Get MagIC and run it

Download the code

You can download a snapshot of the code from the Git repository using

$ git clone https://github.com/magic-sph/magic.git

In case you already have an account on github.com and uploaded a public SSH key on it, you could then rather use SSH:

$ git clone ssh://git@github.com/magic-sph/magic.git

Setting up the environment variables

Although not mandatory, it is strongly recommended to correctly source the environment variables of the MagIC code. It will ensure a smoother usage of the post-processing python classes and allow to run the auto-test suite. To do that, just go to the root directory of the MagIC code (magic) and source sourceme file that corresponds to your $SHELL environment variable.

In case you use bash, ksh or zsh, just use:

$ source sourceme.sh

In case you use csh or tcsh, rather use

$ source sourceme.csh

You can make sure that the environment variables have been correctly sourced by typing:

$ echo $MAGIC_HOME
$ echo $PYTHONPATH

If you don’t want to source sourceme.[c]sh on each session, you can add the following into your .bash_profile (or .profile or .zprofile or .cshrc):

$ source whereverYouCheckedOut/magic/sourceme.sh

To get started, you then need to compile the code.

Setting up compiler options and compiling

The recommended way of compiling MagIC is to use the build system CMake , if available on your platform. Otherwise, a backup solution is provided via the manual edition of a Makefile.

Generic compiling options

For both build systems (CMake or make), several build options can be toggled using the following available options:

  • ARCH Set it to ‘64’ for 64 bit architecture or to ‘32’ for 32 bit architecture

  • PRECISION Set it to ‘dble’ for double-precision calculations or to ‘sngl’ for single-precision calculations

  • OUT_PREC Set it to ‘dble’ for double-precision in binary outputs or to ‘sngl’ for single precision

  • USE_MPI Set to yes to use MPI, set it to no if you want a serial version of the code .

  • USE_OMP Set it to yes to use the hybrid version of the code, or to no for a pure MPI (or serial) version.

  • USE_PRECOND Set to yes to perform some pre-conditioning of the matrices.

  • USE_FFTLIB This option lets you select the library you want to use for Fast Fourier Transforms. This can be set to ‘JW’, ‘FFTW’ or ‘MKL’. ‘JW’ refers to the built-in library by J ohannes W icht, FFTW refers to the Fastest Fourier Transform in the West, while ‘MKL’ refers to the Intel Math Kernel Library. Use ‘JW’ if you don’t have Intel MKL installed.

  • USE_DCTLIB This option lets you select the library you want to use for Discrete Cosine Transforms. This can be set to ‘JW’, ‘FFTW’ or ‘MKL’.

  • USE_LAPACKLIB This option allows you to select the library you want to use for LU factorisation. This can be set to ‘JW’, ‘MKL’, ‘LIBFLAME’ or ‘LAPACK’. ‘LIBFLAME’ refers to the AMD dense matrix solvers libflame.

  • USE_SHTNS Set to yes to use SHTns library for spherical harmonics transforms. The helper script install-shtns.sh is available in the bin directory to help installing SHTns.

  • CMAKE_BUILD_TYPE Set to Debug to enable the full debug flags.

Warning

MagIC cannot run with openMP alone, therefore a configuration of the form USE_MPI=no, USE_OMP=yes will be overwritten to force USE_OMP=no

Using make (backup solution)

In case CMake is not available on your platform, it is still possible to compile the code directly. Go to the directory where the source files of MagIC are contained

$ cd $MAGIC_HOME/src

Select compiler

Edit the file named Makefile using your favourite editor and set a suitable compiler for your platform using the variable: COMPILER = value. The possible options are intel, gnu or portland compilers.

List of default compilers

Compiler Option

Normal

With MPI

intel

ifort, icc

mpiifort, mpiicc

gnu

gfortran, gcc

mpif90, mpicc

portland

pgf95, pgcc

mpif90, mpicc

Warning

In case you want to use intel but mpiifort and mpiicc are not available, you may also need to adapt the variables COMP_MPFC and COMP_MPCC.

Select compiling options

You can also modify the different compiling options by editing the values of the various parameters defined in the first lines of the Makefile. For instance, in case you want to make use of the built-in libraries and want to disable OpenMP, just define

USE_OMP=no
USE_FFTLIB=JW
USE_LAPACKLIB=JW

MPI_INCPATH

This variable sets the path for your MPI header file mpif.h. This is in general useless if you already use the MPI wrappers such as mpiifort or mpif90 to compile the code. It might be however required to define this path for some compiler configurations: MPI_INCPATH is usually /usr/include or /usr/include/mpi and should be found by the Makefile automatically thanks to the command mpif90 --showme:incdirs. In case this doesn’t work, you may need to specify this variable manually in the Makefile. On supercomputing clusters, this variable is in general not used.

Other compilers

If your available compilers are different from the options provided in the Makefile, then just create a new profile for your desired compiler by changing the options COMP_FC and COMP_CC for serial fortran and C compilers and COMP_MPFC and COMP_MPCC for the possible MPI wrappers.

Once you’ve set up your compiling options compile the code using

$ make -j

The compiler should then produce an executable named magic.exe.

If you want to recompile the code from scratch do

$ make clean

to remove all the files generated by the compiler.

Once the executable is built, you are now ready to run your first production run!

Preparing a production run

After building the executable, use one of the namelists provided in the $MAGIC_HOME/samples directory (called input.nml), adapt it to your physical problem (see here for an exhaustive description of the possible options) and run MagIC as follows:

  • Running a serial version of the code (USE_MPI=no and USE_OMP=no):

    $ ./magic.exe input.nml
    
  • Running the code without OpenMP (USE_MPI=yes and USE_OMP=no) with <n_mpi> MPI ranks:

    $ mpiexec -n <n_mpi> ./magic.exe input.nml
    
  • Running the hybrid code (USE_MPI=yes and USE_OMP=yes) with <n_mpi> MPI ranks and <n_omp> OpenMP threads:

    $ export OMP_NUM_THREAD = <n_omp>
    $ export KMP_AFFINITY=verbose,granularity=core,compact,1
    $ mpiexec -n <n_mpi> ./magic.exe input.nml
    

Note that the n_r_max-1 must be a multiple of <n_mpi>, where n_r_max is the number of radial grid points (see here).