.. _secContribute: 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: .. topic:: Contribute * **Do you want to contribute to the code?** Just clone the code and start modyfing it. Make sure that your modifications :ref:`don't alter the code `, try to :ref:`document your changes ` as much as you can and follow the recommended :ref:`Fortran coding style `. * **Do you want to improve the documentation?** Feel free to document some missing features. The documentation is stored in the directory :code:`$MAGIC_HOME/doc/sphinx` and relies on the documenting tool `Sphinx `_. Some recommendations regarding documentation can be found :ref:`below `. * **Did you find a bug?** Issues and feature requests should be raised in the `github tracker `_. .. _secAutoTest: 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 :code:`$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: .. code-block:: bash ./magic_wizard.py It supports the following options: .. code-block:: bash -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: .. tabularcolumns:: |c|p{14cm}| +---------+-----------------------------------------------------------+ | 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 | * Hydrodynamic anelastic benchmark | | | (`Jones et al., 2011 | | | `_) | | | (``hydro_bench_anel``) | +---------+-----------------------------------------------------------+ | 3 | * Heat flux perturbation (``fluxPerturbation``) | | | * Isothermal model with :math:`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``) | +---------+-----------------------------------------------------------+ .. _secModernFortran: 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 `_: .. code-block:: 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 :code:`dimension(len)` for declaring array but rather :code:`real(cp) :: data(len)` 5. Always use the default precisions when introducing new variables :code:`(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. .. _secDocSphinx: 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 .. code-block:: bash $ cd $MAGIC_HOME/doc/sphinx and build the html documentation .. code-block:: bash $ make html The complete documentation will then be built in a local directory named :code:`$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: .. code-block:: bash $ make latexpdf The resulting pdf is then generated in a local directory named :code:`$MAGIC_HOME/doc/sphinx/.build/latex`. It is pretty straightforward to contribute to the documentation by simply adding some contents to the different :code:`rst` files. Informations about `reStructuredText `_ syntax can be found on `www.sphinx-doc.org `_, while helpful CheatSheet are accessible `here `_ or `there `_.