Introduction to EarthBox

EarthBox is a multiphase visco-elasto-plastic marker-in-cell geodynamic modeling program that discretizes the Stokes-continuity and heat transport equations on a staggered grid using conservative finite differences and free-surface stabilization (See Methods). Advective processes are modeled using a 4-th order Runge-Kutta scheme that includes both grid and sub-grid changes in temperature and deviatoric stress. A variety of geologic processes are integrated in the EarthBox modeling system including partial melting, instantaneous melt extraction and transport, gabbroic melt fractionation, melt extrusion, lava flow, submarine hydrothermal cooling, exothermic serpentinization and sediment transport with erosion, deposition, compaction and an isostatically realistic global sea level. EarthBox uses a composite viscous flow law that includes dislocation creep, diffusion creep, Peierls creep, the effects of viscous softening associated with grain size reduction and the effects of partial melting. The frictional-plastic model used by EarthBox includes strain weakening and melt damage associated with melt transport networks above zones of melt focusing (Kneller, 2025) (Fig.).

fig:video-example-model-melt-damage

Video of an EarthBox simulation of magmatic crust formation and subaerial lava flow with melt damage above regions of melt focusing

For quick start instructions see EarthBox Quick Start.

The goals of the EarthBox.jl project are two-fold:

  1. To create an easy-to-use and easy-to-modify geodynamic modeling framework with performance comparable to C++ and Fortran, optimized for multi-threaded shared memory machines.
  2. To provide an extensible system for building libraries of options and model cases.

EarthBox is currently 2D with an experimental 3D multigrid solver that will be integrated into the EarthBox system during a future release. EarthBox is developed using the Julia programming language and includes arm's-length integration with the parallel direct solver MUMPS (Amestoy et al., 2001; Amestoy et al., 2019) that manages the stochastic nature of this powerful parallel direct solver that if not properly addressed can lead to failed simulation runs.

To get started with EarthBox see EarthBox Installation, Building and Executing Models with the EarthBox API, EarthBox Models and EarthBox API Overview.

The fundamental aspects of the marker-in-cell approach for solving incompressible flows with a free-surface used by EarthBox were first published by Harlow and Welch (1965). This approach was later modified for visco-elasto-plastic problems by Gerya and Yuen (2003), Gerya and Yuen (2007), Gerya (2010). EarthBox uses a visco-elasto-plastic thermo-mechanical algorithm that closely follows the algorithm described by Gerya (2010) but with the node-based plasticity approach from Gerya (2019) to improve the convergence of the non-linear visco-elasto-plastic Stokes-continuity solver (see Methods and Main Steps).

EarthBox includes a melting model with linearized melt fraction and instantaneous melt extraction with optional emplacement at the Moho to simulate magma intrusion at mid-ocean ridges (see Melt generation, Transport and Emplacement). Novel aspects of EarthBox's melting model are (1) a simple gabbroic fractionation model based on the proximity of extracted melt to the Moho, (2) a melt extrusion and lava flow model based on cellular automata that allows the modeling of the formation of seaward dipping reflectors (see Melt Extrusion and Lava Flow) and (3) a probabilistic melt-damage model that weakens frictional plastic properties above regions of melt focusing that plays a critical role in stabilizing spreading centers when extrusive processes are included.

Topography can be difficult to accurately track with particle-in-cell models. EarthBox implements an Eulerian-Lagrangian approach whereby a topography marker chain is advected using a 4th order Runge-Kutta scheme and then topographic elevation is interpolated to an Eulerian topography grid. The approach led to highly accurate tracking of the air-rock interface comparable to finite-element Eulerian-Lagrangian codes.

EarthBox provides an option to define global sea level using the isostatic equilibrium between a reference lithospheric column and the average pressure at the base of the model (Kneller et al., 2023). Sediment transport including erosion and deposition with fluvial and marine processes is implemented using the approach of Andrés-Martínez et al. (2019) (see Sediment Transport) but with the added effect of sediment compaction.

EarthBox also includes the effects of hydrothermal circulation on submarine thermal structure that takes into account the effects of sediment overburden (see Hydrothermal Circulation) and how exothermic serpentinization reactions impact thermal conductivity and density (see Serpentinization).

Numerical and analytical benchmarks of EarthBox are presented in the Benchmarks section providing a direct comparison to similar codes such as I2ELVIS that has been used extensively in published geodynamic modeling studies (Gerya and Yuen, 2003; Gerya, 2010; Gerya, 2019). EarthBox includes an integrated benchmarking system allowing the user to quickly reproduce benchmarks, gain confidence in multiple aspects of the code and test the code after modifications are made (see Benchmarks). Some novel aspects of the design of the EarthBox software are as follows:

  • A consistent option scheme utilizing a common option state and Julia's multiple dispatch system making it easy to customize and extend EarthBox and manage complex and diverse model options.
  • Integrated boundary-condition options for the Stokes-continuity and heat equations for specific problem types that take marker recycling into account (see Boundary Condition Models).
  • A self-contained fully integrated benchmarking system allows most aspects of the code to be tested in a fully integrated manner (see Benchmarks).
  • Flexible model building, execution and plotting features allowing the use of an API or YAML input files (see EarthBox API Overview).
  • A multiple model case management system (see Case Management).

EarthBox Quick Start

For more detailed instructions and alternative installation options see EarthBox Installation.

The easiest way to get started with Julia is to use juliaup which involves executing the following command on Linux systems:

curl -fsSL https://install.julialang.org | sh

See Installing Julia for more details.

You can install the registered version of EarthBox via the Julia REPL:

julia> ]
(@v1.x) pkg> add EarthBox

Copy the model collection packaged with EarthBox to your local directory using the REPL:

julia> using EarthBox
julia> get_models()

Next, navigate to models/lithospheric_extension/extension_weak_fault, change the ROOT_OUTPUT_PATH in Model.jl to a desired output location and then run the model using the following command:

julia Model.jl case_name=case1

Alternatively, you can use the REPL to run the model:

julia> include("Model.jl")
julia> Model.run_case(case_name="case1")

Plot model marker output files using:

julia Plot.jl marker_plots case_name=case1 istart=1 iend=10

Alternatively, you can plot marker output files using the REPL:

include("Plot.jl")
Plot.marker_plots(
    model_output_path = "/path/to/model_output",
    istart = 1,
    iend = 10
);