Contributing to the code

MagIC is an open-source code, we thus value any possible contribution! There are several ways to directly contribute to the code:

Contribute

  • Do you want to contribute to the code? Just clone the code and start modyfing it. Make sure that your modifications don’t alter the code, try to document your changes as much as you can and follow the recommended Fortran coding style.

  • Do you want to improve the documentation? Feel free to document some missing features. The documentation is stored in the directory $MAGIC_HOME/doc/sphinx and relies on the documenting tool Sphinx. Some recommendations regarding documentation can be found below.

  • Did you find a bug? Issues and feature requests should be raised in the github tracker.

Checking the consistency of the code

It is frequently required to check the consistency of the code, especially after the implementation of new features. For this reason, we developed the python test suite magic_wizard.py, located in the directory $MAGIC_HOME/samples/, which tests the compilation of the code and it’s results against a set of standard solutions in sample directories to check if the code produces the correct output.

You can run it as follows:

./magic_wizard.py <options>

It supports the following options:

-h,  --help              Show usage overview
     --level LEV               Run only tests from level LEV
     --use-debug-flags         Compile MagIC with the debug flags
     --use-mpi                 Use MPI
     --use-openmp              Use the hybrid version of MagIC
     --use-mkl                 Use the MKL for FFTs and Lapack calls
     --use-shtns               Use SHTns for Legendre transforms
     --use-precond USE_PRECOND Use matrix preconditioning
     --nranks NRANKS           Specify the number of MPI ranks
     --nthreads NTHREADS       Specify the number of threads (hybrid version)
     --mpicmd MPICMD           Specify the mpi executable (mpiexec, mpirun, srun)

Note

Make sure that your environment variables FC and CC are correctly defined otherwise the script will use the default system compilers.

The --level LEV option defines the priority level of check and validation of the code. It has the following levels of checking:

Level

Cases to check (subdirectories)

0

  • Boussinesq dynamo benchmark (BM1) (Christensen et al., 2001) - start from zero (dynamo_benchmark)

  • Variable transport properties (viscosity, thermal diffusivity and electrical diffusivity) in an anelastic convective model (varProps)

  • Test of a case that uses finite differences - restart from a case that used Chebyshev polynomials (finite_differences)

  • Boussinesq dynamo benchmark (BM2) (Christensen et al., 2001) - start from a saturated state (boussBenchSat)

  • Double-diffusive convection benchmark (Breuer et al., 2010) - start from a saturated state (doubleDiffusion)

  • Axisymmetric spherical Couette flow - this auto-test checks the axisymmetric version of MagIC (couetteAxi)

  • Test Precession (precession)

  • Whole sphere benchmark (Marti et al., 2014) - start from a saturated state (full_sphere)

1

  • Test reading and writing of restart files (testRestart)

  • Test different grid truncations (testTruncations)

  • Test mapping on to a new grid (testMapping)

  • Test different outputs produced (testOutputs)

  • Test different radial outputs - *R.TAG (testRadialOutputs)

2

3

  • Heat flux perturbation (fluxPerturbation)

  • Isothermal model with \(N_{\rho}=3\) (isothermal_nrho3)

  • Boussinesq Dynamo benchmark for conducting and rotating inner core (dynamo_benchmark_condICrotIC)

  • Anelastic dynamo with variable conductivity (varCond)

4

  • Test the writing of CMB and coeff files (testCoeffOutputs)

  • Test the writing of RMS force balance (testRMSOutputs)

  • Test the writing of Graphic and Movie files (testGraphMovieOutputs)

  • Test the writing of TO and Geos outputs (testTOGeosOutputs)

Advices when contributing to the code

  • Before commiting your modifications always make sure that the auto-tests pass correctly.

  • Try to follow the same coding style rules as in the rest of the code:

    1. Never use TABS but always SPACES instead

    2. Use 3 spaces for indentation

      Note

      These two rules can be easily set in your $HOME/.vimrc file if you use vim:

      au FileType fortran set shiftwidth=3
au FileType fortran set tabstop=3
au FileType fortran set expandtab

    3. Never use capital letters for variable declaration or Fortran keywords

    4. Never use dimension(len) for declaring array but rather real(cp) :: data(len)

    5. Always use the default precisions when introducing new variables (cp)

These rules try to follow the general recommendations on modern fortran programming that can be found on www.fortran90.org or in the book Modern Fortran - style and usage by N. S. Clerman and W. Spector.

Building the documentation and contributing to it

The documentation is generated using Sphinx. To build it you’ll thus need to install this python module on your machine. This is in general directly available on most of the Linux distributions under the name python-sphinx. Once installed, just go to the documentation directory

$ cd $MAGIC_HOME/doc/sphinx

and build the html documentation

$ make html

The complete documentation will then be built in a local directory named $MAGIC_HOME/doc/sphinx/.build/html.

If LaTeX is installed on your work station, it is also possible to build the corresponding manual of the documentation in the pdf format:

$ make latexpdf

The resulting pdf is then generated in a local directory named $MAGIC_HOME/doc/sphinx/.build/latex.

It is pretty straightforward to contribute to the documentation by simply adding some contents to the different rst files. Informations about reStructuredText syntax can be found on www.sphinx-doc.org, while helpful CheatSheet are accessible here or there.