.. role:: mybox
:orphan:
Welcome
#######
.. container:: mybox
.. only:: html
.. raw:: html
**MagIC** is a numerical code that can simulate fluid dynamics in a spherical
shell. MagIC solves for the Navier-Stokes equation including Coriolis force,
optionally coupled with an induction equation for Magneto-Hydro Dynamics (MHD),
a temperature (or entropy) equation and an equation for chemical composition
under both the anelastic and the Boussinesq approximations.
**MagIC** uses Chebyshev polynomials or finite difference in the radial
direction and spherical harmonic decomposition in the azimuthal and latitudinal
directions. MagIC supports several Implicit-Explicit time schemes where the
nonlinear terms and the Coriolis force are treated explicitly, while the
remaining linear terms are treated implicitly.
**MagIC** is written in Fortran and designed to be used on supercomputing
clusters. It thus relies on a hybrid parallelisation scheme using both `OpenMP
`_ and `MPI `_. Postprocessing
functions written in python (requiring `matplotlib `_
and `scipy `_) are also provided to allow a useful data
analysis.
.. figure:: figs/magic_occigen.png
:width: 450px
:align: center
:alt: caption
Walltime of MagIC on `Occigen
`_ versus number of cores
for a Boussinesq dynamo model computed at three different numerical resolutions
:math:`(N_r,\ell_{\text{max}})`.
**MagIC** is a free software. It can be used, modified and redistributed under the
terms of the `GNU GPL v3 licence `_.
Quickly starting using MagIC
============================
.. container:: mybox
* The :ref:`quick-starting guide ` will help you to download,
set up and run your first numerical simulations using **MagIC**.
* The :ref:`description of the input namelists ` will then help
you to define the exact physical setup you may want to simulate.
* The :ref:`description of the output files ` will help you to
understand what are the diagnostic quantities computed by **MagIC**.
* Finally, the :ref:`python functions and classes ` will
allow you to do some advanced post-processing analyses on the outputs of **MagIC**.
Documentation
=============
.. container:: mybox
* The :ref:`table of contents ` gives an overview of the complete documentation.
* The :ref:`formulation of the (M)HD problem ` contains an exhaustive
description of the equations solved by the MagIC code.
* The :ref:`numerical methods section ` contains the description of the
numerical technique.
* The :ref:`search page ` allows to search the documentation.
* The :ref:`fortran API ` contains a generic description of all
Fortran variables, subroutines and modules used in **MagIC**.
You can also download a :download:`PDF version <../magic_manual.pdf>` of this
documentation generated from LaTeX Sphinx.
Contributing to the code
========================
.. container:: mybox
If you want to contribute to **MagIC**, :ref:`the contributor
guide` might be helpful for you.
Giving credit
=============
.. container:: mybox
In case you intend to publish scientific results obtained with **MagIC**
or present them in a conference, we (the developers of MagIC) kindly
ask to be acknowledged with a reference to the website
https://magic-sph.github.io/ or https://github.com/magic-sph/magic.
We also suggest to give appropriate reference to one or several of the following
papers:
* Boussinesq equations: `Wicht (2002, PEPI, 132, 281-302) `_
* Anelastic equations: `Gastine & Wicht (2012, Icarus, 219, 28-442) `_
* Boussinesq benchmark: `Christensen et al. (2001, PEPI, 128, 25-34) `_
* Benchmark for double diffusive convection: `Breuer et al. (2010, GJI, 183, 150-162) `_
* Anelastic benchmark: `Jones et al. (2011, Icarus, 216, 120-135) `_
* In case you use the `SHTns `_ library for the spherical harmonics transforms (MagIC 5.3 or later), please also cite: `Schaeffer (2013, GGG, 14, 751-758) `_
.. seealso:: A (tentative) comprehensive list of the publications that have
been produced to date (May 2019) using **MagIC**
is accessible `here `_.
To date, more than **100 publications** have been-accepted in
more than 10 different peer-reviewed journals: `PEPI
`_
(22), `Icarus `_ (11), `E&PSL
`_ (7), `GJI
`_ (8), `A&A `_ (6),
`GRL `_ (4),
`JFM `_ (6),
`GAFD `_ (3),
`Nature `_ (2), etc.
.. figure:: figs/magic_pubs.png
:width: 600px
:align: center
:alt: caption
Number of peer-reviewed publications produced using **MagIC**