3.3 Local installation

This is a brief explanation of how to compile and install the required dependencies and ASPECT itself. This installation procedure guarantees fastest runtimes, and largest flexibility, but usually requires more work than the options mentioned in the previous sections. While it is possible to install ASPECT’s dependencies in particular p4est, Trilinos, and deal.II manually, we recommend to use the candi software (see https://github.com/dealii/candi). candi was written as an installation program for deal.II, and includes a number of system specific instructions that will be listed when starting the program. It can be flexibly configured to allow for non-default compilers or libraries (e.g. Intel’s MKL instead of LAPACK) by changing entries in the configuration file candi.cfg, or by providing platform specific installation files.

In case you encounter problems during the installation, please consult our wiki (https://github.com/geodynamics/aspect/wiki) for frequently asked questions and special instructions for MacOS users, before posting your questions on the mailing list.

3.3.1 System prerequisites

candi will show system specific instructions on startup, but its prerequisites are relatively widely used and packaged for most operating systems. You will need compilers for C, C++ and Fortran, the GNU make system, the CMake build system, and the libraries and header files of BLAS, LAPACK and zlib, which is used for compressing the output data. To use more than one process for your computations you will need to install a MPI library, its headers and the necessary executables to run MPI programs. There are some optional packages for additional features, like the HDF5 libraries for additional output formats, PETSc for alternative solvers, and Numdiff for checking ASPECT’s test results with reasonable accuracy, but these are not strictly required, and in some operating systems they are not available as packages but need to be compiled from scratch. Finally, for obtaining a recent development version of ASPECT you will need the git version control system.

An exemplary command to obtain all required packages on Ubuntu 14.04 would be:

3.3.2 Using candi to compile dependencies

In its default configuration candi downloads and compiles a deal.II configuration that is able to run ASPECT, but it also contains a number of packages that are not required (and that can be safely disabled if problems occur during the installation). We require at least the packages p4est, Trilinos (or as an experimental alternative PETSc), and finally deal.II.

At the time of this writing candi will install p4est 2.0, Trilinos 12.10.1, PETSc 3.6.4, and deal.II 8.5.0. We strive to keep the development version of ASPECT compatible with the latest release of deal.II and the current deal.II development version at any time, and we usually support several older versions of p4est, Trilinos, and PETSc.

1. Obtaining candi: Download candi by running
       git clone https://github.com/dealii/candi  
       

   in a directory of your choice.

2. Installing deal.II and its dependencies: Execute candi by running
       cd candi  
       ./candi.sh -p INSTALL_PATH  
       

   (here we assume you replace INSTALL_PATH by the path were you want to install all dependencies and deal.II, typically a directory inside $HOME/bin or a similar place). This step might take a long time, but can be parallelized by adding -jN, where N is the number of CPU cores available on your computer. Further configuration options and parameters are listed at https://github.com/dealii/candi.

3. You may now want to configure your environment to make it aware of the newly installed packages. This can be achieved by adding the line source INSTALL_PATH/configuration/enable.sh to the file responsible for setting up your shell environment⁶ (again we assume you replace INSTALL_PATH by the patch chosen in the previous step). Then close the terminal and open it again to activate the change.
4. Testing your installation: Test that your installation works by compiling the step-32 example that you can find in $DEAL_II_DIR/examples/step-32. Prepare and compile by running cmake . && make and run with mpirun -n 2 ./step-32.

Congratulations, you are now set up for compiling ASPECT itself.

3.3.3 Obtaining ASPECT and initial configuration

The development version of ASPECT can be downloaded by executing the command

If $DEAL_II_DIR points to your deal.II installation, you can configure ASPECT by running

in the ASPECT directory created by the git clone command above. If you did not set $DEAL_II_DIR you have to supply cmake with the location:

An alternative would be to configure ASPECT as an out-of-source build. You would need to create a separate build directory and specify ASPECT’s source directory using cmake PATH_TO_ASPECT_SOURCE from within the build directory. The instructions in the following sections assume an in-source build.

3.3.4 Compiling ASPECT and generating documentation

After downloading ASPECT and having built the libraries it builds on, you can compile it by typing

on the command line (or make -jN if you have multiple processors in your machine, where N is the number of processors). This builds the ASPECT executable which will reside in the main directory and will be named ./aspect. If you intend to modify ASPECT for your own experiments, you may want to also generate documentation about the source code. This can be done using the command

which assumes that you have the doxygen documentation generation tool installed. Most Linux distributions have packages for doxygen. The result will be the file doc/doxygen/index.html that is the starting point for exploring the documentation.