XSHELLS is a high performance simulation code for the rotating Navier-Stokes equation in spherical shells, optionally coupled to the induction and temperature equation.

Copyright (c) 2010-2018 Centre National de la Recherche Scientifique. written by Nathanael Schaeffer (CNRS, ISTerre, Grenoble, France). XSHELLS is distributed under the open source CeCILL License (GPL compatible) located in the LICENSE file.


  • Designed for speed, it is probably the fastest spherical MHD simulation code.
  • Uses finite differences in radial direction, and spherical harmonic expansion.
  • Low memory footprint; can handle huge spherical harmonic resolutions.
  • Written in C++ with efficiency, extensibility and customizability in mind.
  • Export data to python/matplotlib and paraview.
  • Can time-step various initial value problems in spherical shells or full spheres: geodynamo, spherical Couette flow, precession, inertial waves, torsional Alfvén waves, double-diffusive convection...
  • Can run on a laptop or on massively parallel supercomputers (hybrid parallelization using OpenMP and/or MPI, scales well up to 1 process/shell).
  • CeCILL License (compatible with GNU GPL): everybody is free to use, modify, contribute.


If you accept the open source CeCILL License (GPL compatible french License), you can download XSHELLS.

The SHTns library is required for spherical harmonic transforms.

Briefly, the shell command ./configure will prepare the program for compilation, while ./configure --help will list available options (among which --disable-openmp and --disable-mpi).

Example problems are located in the problems directory. For example, to build executables for the geodynamo benchmark (Christensen et al PEPI 2011):

cp problems/geodynamo/* .
make all

Adjust the parameters found in the xshells.par file, which will be read by program at startup. Depending on what you want you can then run:

  • ./xsbig for the simple OpenMP version
  • ./xsbig_mpi for the pure MPI code
  • ./xsbig_hyb for the hybrid OpenMP-MPI executable.
  • ./xsbig_hyb2 for the radial MPI + in-shell OpenMP executable.
  • ./xsimp for the OpenMP version with Coriolis force handled implicitely (beta).

Read the user manual for more details.


  • A user manual is available online or for download (pdf). The latex source of the manual can be found in the notes directory.
  • In addition, the main source files are documented using Doxygen comments. Run make docs to generate the documentation targeted at developers and contributors.


  • v2.2.2 (20 Mar 2019)

    • Fix configure script to include optimization options correctly.
  • v2.2.1 (8 Mar 2019)

    • Easier configuration and install, including SHTns library configuration and compilation, better intel MKL detection, and better intel KNL support.
  • v2.2 (31 Oct 2018)

    • several optimizations & fixes.
    • diagnostics are now code snippets found in the diagnostics directory, for better code reuse and maintenance; all xshells.hpp files have been updated.
    • all parameters of xshells.par can be overridden by command line arguments.
    • OpenMP 4 tasks are now used when it results in better load balancing.
    • Smarter distribution of shells between MPI processes with solid shells.
    • can now handle energy files with diagnostics added between restarts.
    • can read Parody restart files (and convert them to xshells).
  • v2.1 (16 May 2018)

    • several minor bug fixed.
    • improved python scripts; added to pretty display the energy files.
    • hyper-diffusivity can also be applied on the magnetic field.
  • v2.0 (4 Dec 2017)

    • warning: previous xshells.hpp may not compile as-is.
    • new: time-stepping scheme switched to Predictor-Corrector type allowing 3 to 4 times larger time-steps (change xshells.par accordingly!).
    • new: support for double-diffusive convection.
    • fixed and improved linear mode, which now allows full computation of perturbations around base-fields (optionally including non-linear terms).
    • support for AVX-512 vectorization (e.g. intel KNL).
    • new xsimp handles Coriolis force implicitely (beta).
    • internal changes in banded matrix handling.
    • xspp writes numpy files instead of text files for most slices.
    • improved plotting system: use xsplot to display almost all outputs from xspp.
  • v1.4 (30 Sep 2016)

    • spectral convergence for each field stored in energy file.
    • drop the time_scheme option and the obsolete and poor corrector mode.
    • fix broken linear mode (without magnetic field).
    • improvments to pyxshells module (by E. Kaplan).
    • fix bug in z-averaging (thanks to E. Kaplan).
    • other minor fixes and improvements
  • v1.3 (8 Mar 2016)

    • better spectral convergence (Sconv) check (max of all shells).
    • spectral convergence checks adjusted from xshells.par with variables sconv_lmin and sconv_mmin.
    • variable l-truncation controlled from xshells.par using rsat_ltr.
    • fix sign of rotation vector along y.
    • fix bugs appearing when using MPI and few shells per process.
    • other bugfixes and improvements, especially to plotting scripts.
  • v1.2 (6 Oct 2015)

    • new parallelization mode using OpenMP in the angular directions: compile and run xsbig_hyb2.
    • arbitrary gravity fields allowed.
    • safer default CFL safety factors.
    • real-time spectral convergence check.
    • full linear mode (now supporting non-axisymmetric base fields).
    • user defined bulk forcings (example in problems/tidal).
    • fixes, improvements, optimizations.
  • v1.1 (15 Jul 2015)

    • global rotation no longer required to be along z-axis.
    • real-time diagnostic plotting (using gnuplot).
    • at least 1 radial shell per process required (instead of 2 before).
    • new real-time test for spectral convergence.
    • many fixes, improvements and optimizations.
  • v1.0 (3 Jan 2015)

    • first public release.
    • hybrid OpenMP/MPI parallelization.
    • extensible diagnostic system.