Configuration & Parameters

GeoDynamo.jl follows a grid → model → simulation setup style. Build a SphericalShellGrid or SphericalBallGrid, pass it to GeodynamoModel with physical and boundary-condition keywords, then advance a Simulation.

GPU Backend

The current :gpu backend is an explicit single-device solver path:

• dense GPU field containers hold scalar, vector, nonlinear-history, and implicit-solve arrays on the selected architecture
• scalar transforms, Stage-2 solenoidal vector transforms, spectral curls, nonlinear projections, CNAB2 right-hand sides, batched radial solves, and the gpu_run! stepping loop have GPU-path implementations
• the CUDA extension routes SHTnsKit scalar and vector transforms to CUDA when the arrays and SHTnsKit configuration are device-backed
• each solver runtime owns a TransformWorkspace; on GPU-marked runtimes its scratch allocations can be sourced from the backend-provided scratch_zeros hook
• with_gpu_backend(...) can temporarily install alternate backend implementations for tests or experimental integrations and restores the previous backend automatically afterward
• full parity with the production CPU SolverState path is still guarded by broken tests while the remaining solver-integration differences are closed
• conducting inner-core magnetic coupling is not yet wired into build_gpu_solver_state; insulating magnetic cases are the supported solver-state path

To use :gpu, load CUDA before creating the solver state:

using GeoDynamo
using CUDA

grid = SphericalShellGrid(GPU(); nr = 64, lmax = 31)
model = GeodynamoModel(grid; include_magnetic = true)
simulation = Simulation(model; Δt = 1e-5, stop_time = 0.02)

If CUDA is not installed or no functional device is available, backend creation fails explicitly instead of silently downgrading to CPU.

SphericalShellGrid(arch=CPU(); lmax, nr, mmax=lmax, nlat=3lmax÷2,
                   nlon=2nlat, nr_inner=max(2, nr÷4),
                   r_inner=0.35, r_outer=1.0)

grid = SphericalShellGrid(lmax = 31, nr = 64)

SphericalBallGrid(arch=CPU(); lmax, nr, mmax=lmax, nlat=3lmax÷2, nlon=2nlat)

grid = SphericalBallGrid(lmax = 31, nr = 48)

GeodynamoModel(grid; T=Float64, Ek=1e-4, Pr=1.0, Pm=1.0, Sc=1.0, Ra=1e6,
               velocity_bcs, temperature_bcs, composition_bcs,
               boundary_conditions=nothing,
               include_magnetic=false, include_composition=false,
               initial_conditions=nothing, kwargs...)

grid  = SphericalShellGrid(lmax = 31, nr = 64)
model = GeodynamoModel(grid; Ra = 1e6, include_magnetic = true)
# Oceananigans-style boundary conditions:
t_bcs = FieldBoundaryConditions(inner = ValueBoundaryCondition(1.0),
                                outer = ValueBoundaryCondition(0.0))
model = GeodynamoModel(grid; Ra = 1e6, boundary_conditions = (temperature = t_bcs,))

mutable struct Simulation{M,C,O}

Quick Reference

Geometry & Resolution

Grid Parameters

SHTnsKit Transform Options

These flags control SHTnsKit v1.1.15 optimizations (set in transforms/spectral.jl):

Check feature availability at runtime:

info = get_shtnskit_version_info()
println("Version: ", info.version)
println("QST transforms: ", info.has_qst_transforms)
println("Energy functions: ", info.has_energy_functions)

See Spherical Harmonics for the complete transform API.

Physical Parameters

Dimensionless Numbers

Magnetic Field Control

Time Integration

Choose a timestepper object in the Simulation constructor:

simulation = Simulation(model; Δt = 1e-5, timestepper = CNAB2())

See Time Integration for detailed scheme documentation.

Boundary Conditions

For complete documentation of all boundary condition types and their physical interpretation, see the dedicated Boundary Conditions page.

Quick Reference

Summary of BC Types

Loading Custom Boundaries

using GeoDynamo

grid = SphericalShellGrid(nr = 64, lmax = 31)
model = GeodynamoModel(grid)
simulation = Simulation(model; Δt = 1e-5, stop_time = 0.02)
state = simulation.model.state

GeoDynamo.bcs.load_boundary_conditions!(state.temperature, GeoDynamo.TEMPERATURE, Dict(
    :inner => (:uniform, 1.0),
    :outer => (:dirichlet, 0.0),
))

GeoDynamo.bcs.load_boundary_conditions!(state.composition, GeoDynamo.COMPOSITION, Dict(
    :inner => (:neumann, 0.0),
    :outer => (:dirichlet, 0.0),
))

Use this helper for programmatic scalar boundaries after the simulation state is created. File-based scalar BC workflows should use the lower-level NetCDF and spectral BC utilities directly.

Boundary Topography

For non-spherical boundaries, these parameters control topography coupling. See Boundary Topography for full theory.

Master Controls

Field-Specific Switches

Stefan Condition (Phase Change)

Topography Data Files

Example Configuration

Via constructor:

grid = SphericalShellGrid(nr = 64, lmax = 31)
model = GeodynamoModel(
    grid;
    topography_enabled = true,
    topography_epsilon = 0.01,
    include_topography_velocity = true,
    include_topography_magnetic = true,
    ocb_topography_file = "config/cmb_topography.nc",
)
simulation = Simulation(model; Δt = 1e-5, stop_time = 0.02)

At runtime:

enable_topography!(epsilon = 0.02, velocity = true, magnetic = true)

Initial Conditions & Restarts

The InitialConditions module provides high-level setup helpers:

Available Functions

Typical Setup

grid = SphericalShellGrid(nr = 64, lmax = 31)
model = GeodynamoModel(grid;
    include_magnetic = true,
    initial_conditions = (
        temperature = AnalyticIC(:conductive),
        velocity = RandomPerturbation(amplitude = 1e-4, lmax = 8),
        magnetic = AnalyticIC(:dipole; amplitude = 1.0),
    ),
)

set!(model; temperature = (r, θ, φ) -> (1 - r) + 1e-3 * sin(θ))
simulation = Simulation(model; Δt = 1e-5, stop_time = 0.02)

Restarts

For reproducible continuation runs:

# Recommended: schedule checkpoints on the simulation.
checkpoint = CheckpointWriter("output"; schedule = TimeInterval(0.5))
simulation = Simulation(model; Δt = 1e-5, stop_time = 1.0,
                        output_writers = (checkpoint,))
run!(simulation)

# Resume later from the restart directory. This is collective and should be
# called under MPI after MPI.Init().
simulation = Simulation(model; Δt = 1e-5, stop_time = 2.0,
                        restart_from = "output")
run!(simulation)

Output Configuration

See Data Output & Restart Files for complete I/O configuration.

Managing Parameters

Creating and Setting

# Create with specific values
grid = SphericalShellGrid(nr = 96, lmax = 47)
model = GeodynamoModel(
    grid;
    Ek = 3e-5,
    Pr = 1.0,
    Pm = 1.0,
    Sc = 1.0,
    Ra = 1e6,
)

simulation = Simulation(model; Δt = 1e-5, stop_time = 0.02)

Saving and Loading

Put the grid, model, and simulation construction in a Julia script such as config/run_highres.jl, then run that script directly or under MPI.

Next Steps