MILEVA

Appearance

MILEVAMantle Interaction and Lithospheric Evolution in Viscous Annuli

A finite-volume mantle-convection code in Julia that runs in the 2-D spherical annulus and in the 3-D Yin-Yang spherical shell.

Getting started
Examples
Governing equations
Benchmarks
MILEVA logo, a half globe with the Yin-Yang grid; the cut face plays the temperature of the primordial-material example from 0 to 4.5 Gyr

2-D spherical annulus

The equatorial slice of a spherical shell with the radial measure r² dr, so the core-mantle boundary carries the area ratio of a sphere. Staggered grid, velocities on faces, pressure at centres, full deviatoric stress at variable viscosity.

3-D Yin-Yang shell

Two overlapping latitude-longitude patches coupled by Schwarz iteration, solved with an SCGS-smoothed geometric multigrid V-cycle inside FGMRES.

Markers and composition

Lagrangian markers carry temperature, basalt, depletion, thermochemical piles, grain size and accumulated strain, with a measure-conserving projection and a hand-back of the diffusion increment that is exact up to the `deliveryScaleMax` cap; reseeding conserves marker measure and composition but not exactly energy (the residual shows in `budget_resid`).

Rheology and melting

Diffusion and dislocation creep, Arrhenius and Frank-Kamenetskii laws, yielding and viscoelastoplasticity; partial melting with depletion feedback, eruption and intrusion, heat-pipe cooling.

Large viscosity contrasts

Stokes solvers for viscosity contrasts up to 10¹⁸, tested on the 3-D Yin-Yang shell with FGMRES and a geometric multigrid V-cycle. MUMPS direct and multigrid in 2-D; MPI Yin-Yang decomposition with distributed direct and iterative paths.

Verification

Compared with the published spherical-annulus results of Hernlund & Tackley (2008) and Fleury et al. (2024), and checked against exact identities (Nu = 1 on conduction, a closed energy budget, work equals dissipation).

Examples in motion

Animated hot-temperature isosurface: plumes rising in a 3-D Yin-Yang spherical shell at Ra = 10^6

3-D Yin-Yang plumes, Ra = 10⁶

A hot isosurface: plumes rise from the core-mantle boundary and spread beneath the surface.
3-D plume planforms →
Animated temperature in the 2-D spherical annulus: a hot plume rising from the core-mantle boundary

2-D plume from the CMB

A 300 K anomaly above the core-mantle boundary rises as a plume and spreads beneath the cold boundary layer (Ra = 10⁶, 64 × 512, first 60 Myr).
Plume from the CMB →
Animated temperature in the 2-D spherical annulus over 4.5 Gyr, above a dense primordial layer

Temperature above a primordial layer

The temperature of the primordial-material example: the dense, viscous layer in the lowest 1650 km passes little heat and warms until, between 2.1 and 2.6 Gyr, broad hot domes rise from it (64 × 512, 0 to 4.5 Gyr).
Primordial and recycled material →
Animated temperature in the 2-D spherical annulus: a stagnant lid that fails, sinks and regrows

2-D stagnant lid that fails

An Arrhenius viscosity (contrast 10⁴) holds the cold lid still until its stresses reach an 8 MPa yield stress; it then breaks, sinks into the mantle and regrows (64 × 512, internally heated, 0 to 1500 Myr; 1100 to 1800 K shown).
Stagnant lid →
Animated fraction of primordial material in the 2-D spherical annulus over 4.5 Gyr

Primordial and recycled material

A dense primordial layer, 100 times more viscous than the mantle, fills the lowest 1650 km while convection, melting and crustal recycling go on above it; the colour is the fraction of primordial material (64 × 512, 0 to 4.5 Gyr). Reference case M100dD of Gülcher, Ballmer & Tackley (2021).
Primordial and recycled material →

Grids and geometries

The four MILEVA grids: 2-D spherical annulus, 2-D cylindrical annulus, 3-D spherical chunk and 3-D Yin-Yang sphere
The 2-D spherical and cylindrical annuli, a 3-D spherical chunk and the 3-D Yin-Yang sphere.
Grids and geometries →

What is MILEVA? ​

Mantle Interaction and Lithospheric Evolution in Viscous Annuli is a mantle-convection code written in Julia. It solves the coupled Stokes, energy and composition equations on a staggered finite-volume grid, with velocities on cell faces and pressure at cell centres, and carries temperature and composition on Lagrangian markers.

It runs in two geometries:

  • the 2-D spherical annulus, cfg.geometry = "spherical_annulus" (the default), whose radial measure is r2dr, so boundary areas and volume weights match a sphere;

  • the 3-D Yin-Yang spherical shell, two overlapping latitude-longitude patches coupled by Schwarz iteration.

MILEVA is a flat-include research code: include/mileva.jl loads the sources under config/, utils/, markers/, physics/, solvers/ and parallel/ in dependency order, and main_SphCon.jl holds the time loop. A run is a Julia script that edits the three configuration structs cfg (SimConfig), mat (MaterialProperties) and temp (TemperatureConditions) and calls main_SphCon(cfg, mat, temp).

Capabilities ​

  • Thermochemical Stokes flow with the full deviatoric stress ∇⋅(2ηε˙) at variable viscosity, Boussinesq or anelastic forms; see Governing equations

  • Composite rheology: diffusion and dislocation creep, Arrhenius and Frank-Kamenetskii laws, yielding, viscoelastoplasticity, damage and grain-size evolution; see Rheology

  • Thermal and compositional buoyancy: basalt, depletion, thermochemical piles, phase transitions; see Buoyancy and composition

  • Partial melting with depletion feedback, eruption, intrusion and heat pipe; see Melting and crust production

  • Heat sources and boundaries: radiogenic heating, a fixed, fixed-flux or cooling core; see Heat sources

  • Free surface and isostasy; see Free surface

  • Direct and multigrid solvers, MPI decomposition; see Solvers, Geometric multigrid

  • Conservative markers and an energy budget logged every run; see Markers, Energy budget

Quick start ​

bash
# install dependencies (once)
julia --project=. -e 'using Pkg; Pkg.instantiate()'

# test suite (keep it to a few threads and a bounded heap on a laptop)
JULIA_NUM_THREADS=4 julia --project=. --heap-size-hint=3G tests/run_tests.jl

# isoviscous convection in the spherical annulus, Ra = 1e4, Nr = 64
julia --project=. -t 4 examples/annulus_convection_2d.jl 1e4 64

# verification against Hernlund & Tackley (2008), Ra = 1e4, Nr = 64
# hours of wall time; for a short probe prefix MILEVA_MAXSTEPS=500 (not a result)
julia --project=. benchmarks/hernlund_tackley_annulus.jl HT4 64

Output (VTK frames for ParaView, checkpoints and an in-loop diagnostics.csv) goes to cfg.outputDir. A complete first run, written out line by line, is on the Getting started page; every example is listed in the Examples.

Verification ​

MILEVA's 2-D spherical-annulus operator is verified against the published results of Hernlund & Tackley (2008) and the Annulus column of Fleury et al. (2024), and by conservation tests: Nu = 1 on a conducting state, closure of the energy budget, and the identity between buoyancy work and viscous dissipation. The tables are on the Benchmarks and verification page.

Citing ​

If you use MILEVA, please cite the version described in the repository's CITATION.cff (the public repository link will be added once it is released).