Physics & Fields

SHTnsVelocityFields{T}

Velocity state in the toroidal-poloidal formulation used by GeoDynamo.

This bundles the physical velocity/vorticity fields, their spectral toroidal and poloidal coefficients, nonlinear work arrays, and the radial derivative operators needed by the velocity update kernels.

create_shtns_velocity_fields(T, config, domain, pencils=nothing, pencil_spec=nothing;
                             geometry=:shell, params)

Allocate and initialize the velocity field container used by solver runtimes.

When params is not supplied, defaults are derived from config/domain — but the geometry cannot be inferred from the grid (the ball's off-center radial grid has r_1 > 0), so callers building ball fields without explicit params must pass geometry = :ball.

The returned object includes physical-space velocity/vorticity fields, spectral toroidal-poloidal coefficients, nonlinear history buffers, and cached radial operators.

compute_kinetic_energy(velocity_fields, domain)

Compute the global kinetic energy of the current velocity state from its spectral toroidal-poloidal coefficients.

compute_reynolds_stress(velocity_fields)

Compute the volume-averaged Reynolds-stress tensor components from the current physical velocity field.

SHTnsMagneticFields{T}

Magnetic-field state for the GeoDynamo MHD solver.

This stores the physical magnetic/current fields, toroidal-poloidal spectral coefficients for the outer and inner core, induction-term work arrays, and the radial derivative operators used by magnetic update kernels.

create_shtns_magnetic_fields(T, config, outer_domain, inner_domain; pencils=nothing, pencil_spec=nothing)

Allocate and initialize the magnetic field container used by GeoDynamo.

compute_magnetic_energy(magnetic_fields, domain)

Compute the global magnetic energy from the spectral toroidal-poloidal representation.

compute_ohmic_dissipation(magnetic_fields)

Estimate the global Ohmic dissipation from the current-density work arrays.

SHTnsTemperatureField{T}

Temperature field state used by GeoDynamo’s thermal evolution equations.

It contains the physical temperature, its gradient, spectral coefficients, nonlinear work arrays, boundary/source data, and cached radial/spectral operators.

create_shtns_temperature_field(T, config, domain; pencils=nothing, pencil_spec=nothing)

Allocate and initialize the temperature field container for a simulation.

compute_nusselt_number(temperature_field, domain)

Compute a shell-averaged Nusselt number from the radial heat flux at the inner and outer boundaries.

compute_thermal_energy(temperature_field)

Compute the global thermal energy from the spectral temperature coefficients.

get_temperature_statistics(temperature_field, domain)

Return a named set of basic temperature statistics such as extrema, RMS level, surface fluxes, and Nusselt number.

SHTnsCompositionField{T}

Composition field state used by the compositional transport equation.

This mirrors the temperature-field layout so scalar transport code can share operators and diagnostics while keeping composition-specific boundary/source data separate.

create_shtns_composition_field(::Type{T}, config,
                               outer_core_domain::RadialDomain,
                               pencils=nothing, pencil_spec=nothing) where T

Create a composition field structure with all necessary arrays for spectral computation.

Arguments

• T: Numeric type (e.g., Float64)
• config: SHTnsKitConfig with transform parameters (lmax, mmax, nlat, nlon)
• outer_core_domain: Radial domain information for outer core
• pencils: Optional pencil decomposition (defaults to config.pencils)
• pencil_spec: Optional spectral pencil (defaults to pencils.spec)

Returns

• SHTnsCompositionField{T}: Fully initialized composition field structure

Example

config = create_shtns_config(lmax=32, mmax=32, nlat=64, nlon=128)
domain = create_radial_domain(nr=64, ri=0.35, ro=1.0)
𝔽 = create_shtns_composition_field(Float64, config, domain)

Notes

Default boundary conditions are no-flux (NEUMANN) at both boundaries, appropriate for typical compositional convection problems.

compute_composition_rms(composition_field, domain)

Compute a global RMS measure of the composition field from its spectral coefficients.

compute_composition_energy(composition_field, domain)

Compute a volume-averaged compositional energy from the current physical field.

get_composition_statistics(composition_field, domain)

Return a named collection of basic composition statistics such as extrema, RMS level, and integrated energy.

RadialDomain

Specification of the radial discretization for the spherical shell.

Radial Grid

The simulation domain is a spherical shell between inner radius ri (e.g., inner core boundary) and outer radius ro (e.g., core-mantle boundary). The radial direction is discretized using Chebyshev collocation for spectral accuracy.

Fields

• N: Number of radial points
• local_range: Indices of radial points local to this MPI process
• r: Radial coordinate values [1, N]
• dr_matrices: Radial derivative matrices (1st, 2nd order, etc.)
• radial_laplacian: Matrix for radial part of Laplacian
• integration_weights: Quadrature weights for radial integration

SHTnsTorPolField{T}

Vector field in toroidal-poloidal spectral representation.

The Toroidal-Poloidal Decomposition

Any solenoidal (divergence-free) vector field can be written as: v = ∇ × (T r̂) + ∇ × ∇ × (P r̂)

where T and P are scalar functions called the toroidal and poloidal potentials.

Why This Representation?

1. Automatically satisfies ∇·v = 0 (mass conservation for incompressible flow)
2. Decouples certain physical processes in the equations
3. Reduces storage: 2 scalars instead of 3 vector components
4. Natural for spherical geometry and spectral methods

Fields

• toroidal: Toroidal potential T(l,m,r) in spectral space
• poloidal: Poloidal potential P(l,m,r) in spectral space

create_radial_domain(nr=nothing; radius_ratio=nothing, radial_bandwidth=nothing) -> RadialDomain

Create a radial domain for a spherical shell geometry.

Arguments

• nr: Number of radial points (required)
• radius_ratio: Inner/outer radius ratio (defaults to 0.35)
• radial_bandwidth: Bandwidth for finite differences (defaults to 4)

Returns

A RadialDomain with Chebyshev-like radial spacing optimized for spectral accuracy.

create_shtns_physical_field(T, config, outer_core_domain, pencil) -> SHTnsPhysField{T}

Create a new physical space field initialized to zero.

Arguments

• T: Element type (typically Float64)
• config: SHTnsKit configuration providing grid dimensions
• outer_core_domain: RadialDomain (for consistency with spectral field API)
• pencil: PencilArrays Pencil defining the data distribution

Returns

A new SHTnsPhysField with all grid values initialized to zero.

create_shtns_vector_field(T, config, outer_core_domain, pencils) -> SHTnsVectorField{T}

Create a new vector field with three physical space components.

Arguments

• T: Element type
• config: SHTnsKit configuration
• outer_core_domain: RadialDomain specification
• pencils: Either a NamedTuple with :theta/:θ, :phi/:φ, :r keys, or a tuple (pencilθ, pencilφ, pencil_r)

Returns

A new SHTnsVectorField with all components initialized to zero. Each component uses a potentially different pencil orientation for optimal computation of different operations.

GradientWorkspace{T}

Shared workspace for transient gradient spectral fields. Reused across scalar field computations that run sequentially (temperature, composition). These arrays are zeroed and recomputed every timestep, so sharing is safe.

create_gradient_workspace(::Type{T}, config, domain, pencil_spec=nothing) where T

Allocate the shared spectral scratch fields used to compute scalar gradients. Temperature and composition reuse this workspace sequentially so the solver does not need separate transient gradient buffers for each scalar field.

clear_mode_index_cache!()

Clear cached (l, m) -> linear index lookup tables. Useful in long-lived sessions that create many temporary transform configurations.

clear_scalar_field_caches!()

Clear process-global scalar field caches that retain transform and boundary helper state.

VelocityWorkspace{T}

Reusable radial work buffers for velocity boundary-condition and derivative operations. Keeping these arrays alive across timesteps avoids repeated allocation in the hottest velocity-side boundary kernels.

create_velocity_workspace(::Type{T}, nr; nthreads=max(Threads.nthreads(), Threads.maxthreadid())) where T

Create a thread-local VelocityWorkspace sized for nr radial points. One buffer set is allocated per thread so velocity boundary kernels can reuse scratch storage without synchronization.

compute_surface_flux(field, r_level, config)

Compute the horizontally integrated scalar flux through the radial shell at r_level. This is the low-level thermal diagnostic used by Nusselt-number and boundary-flux post-processing.

set_temperature_ic!(temp_field, domain; perturbation_amplitude=1e-3)

Seed the temperature field with the standard conductive mean profile plus small low-degree perturbations. This is the default programmatic initializer used by examples and tests that want a nontrivial thermal state without loading an external restart.

set_boundary_conditions!(temp_field; inner_bc_type=DIRICHLET,
                         outer_bc_type=DIRICHLET,
                         inner_value=one(T), outer_value=zero(T))

Assign uniform thermal boundary-condition types and the mean-mode boundary values for a temperature field. Higher modes are reset to zero boundary values so the thermal boundary state stays consistent with a spherically symmetric prescribed profile.

set_internal_heating!(temp_field, domain; heating_type=:uniform, amplitude=one(T))

Populate the radial internal-heating profile used by the temperature equation. The helper provides a few common analytic profiles so tests and examples can configure volumetric heating without constructing the source vector manually.

set_composition_ic!(field, ic_type, domain)

Initialize the composition field from one of the built-in analytic profiles. The helper is intended for tests and simple setups that want a uniform, linear, or randomly perturbed compositional state without reading a restart file.

set_composition_boundary_conditions!(field, bc_inner, bc_outer,
                                     value_inner=zero(T), value_outer=zero(T))

Assign simple programmatic boundary conditions to the composition field. Use :fixed for Dirichlet concentration values or :no_flux for impermeable Neumann boundaries at the inner and outer shell surfaces.

create_velocity_green_matrices(config, domain, diffusivity;
                                theta, T)

Create Green's function matrices for the influence matrix method (poloidal pressure). These use Dirichlet BCs (identity rows) at both boundaries, matching Fortran velbcGre.

solve_velocity_implicit_step!(solution, rhs, matrices, component;
                               velocity_bc_code=1, domain=nothing,
                               rot_omega=0.0, current_field=nothing)

Solve the implicit velocity system with boundary conditions embedded in the matrix. Before solving, sets the RHS boundary values appropriately.

This matches the Fortran DD_2DCODE approach where each rank has full radial profiles for its subset of (l,m) modes:

1. Loop over local lm modes
2. Set RHS boundary rows to BC values (typically 0)
3. Solve banded system with BC rows in matrix
4. Solution automatically satisfies BCs

Arguments

• solution: Output spectral field
• rhs: Input RHS spectral field (modified in place for BCs)
• matrices: SHTnsImplicitMatrices with BCs embedded
• component: :toroidal or :poloidal
• velocity_bc_code: Velocity BC type (1-4)
• domain: RadialDomain (needed for rotating IC boundary)
• rot_omega: Inner core rotation rate (for no-slip toroidal l=1,m=0)
• current_field: Current velocity field (for incremental form of rotating IC BC)

solve_temperature_implicit_step!(solution, rhs, matrices; ...)

Solve the implicit temperature system with boundary conditions embedded in the matrix and boundary values supplied as mode-indexed RHS vectors.

solve_composition_implicit_step!(solution, rhs, matrices; ...)

Solve the implicit composition system with boundary conditions embedded in the matrix and boundary values supplied as mode-indexed RHS vectors.

solve_magnetic_implicit_step!(solution, rhs, matrices, component;
                               mag_bc_inner=nothing, prev_bc_inner=nothing)

Solve the implicit magnetic system with boundary conditions embedded in the matrix. Before solving, sets the RHS boundary values appropriately.

This matches the Fortran DD_2DCODE approach where each rank has full radial profiles for its subset of (l,m) modes:

1. Loop over local lm modes
2. Set RHS boundary rows to 0 (insulating BCs)
3. Solve banded system with BC rows in matrix
4. Solution automatically satisfies BCs

Arguments

• solution: Output spectral field
• rhs: Input RHS spectral field (modified in place for BCs)
• matrices: SHTnsImplicitMatrices with BCs embedded
• component: :toroidal or :poloidal
• mag_bc_inner: Optional inner boundary values for toroidal (conducting IC case)
• prev_bc_inner: Previous step inner BC values (for incremental form)