API Reference

Abstract type for scalar fields (temperature, composition, etc.)

AdvancedThreadManager

Advanced thread management with CPU affinity, NUMA awareness, and work-stealing.

AsyncCommManager{T}

Advanced asynchronous communication manager for overlapping computation and communication.

CPUParallelizer{T}

Advanced CPU parallelization system with SIMD, NUMA, and task-based parallelism.

CombinerConfig

Configuration structure for field combination process.

DynamicLoadBalancer

Dynamic load balancing system that adapts to computational heterogeneity.

ERK2Cache{T}

Cached data structure for Exponential 2nd Order Runge-Kutta method. Stores precomputed matrix exponentials and φ functions for each spherical harmonic mode.

FieldCombiner{T}

Structure for combining distributed Geodynamo.jl output files using the consistent field structures and parameter system.

HybridParallelizer{T}

Coordinates MPI and threads for maximum CPU parallelization.

MasterParallelizer{T}

Comprehensive parallelization system combining all techniques.

MemoryOptimizer{T}

Advanced memory management with cache optimization and NUMA awareness.

ParallelIOOptimizer{T}

Advanced parallel I/O optimization with asynchronous writes and data staging.

PerformanceMonitor

Comprehensive performance monitoring for parallel efficiency analysis.

SIMDOptimizer{T}

Advanced SIMD vectorization for mathematical operations with AVX/NEON support.

SimulationState{T}

Unified simulation state with comprehensive parallelization and diagnostics.

SpectralToPhysicalConverter{T}

Structure for converting spectral field data to physical space using the Geodynamo.jl infrastructure (PencilArrays + SHTns).

TaskGraph

Represents computation as a directed acyclic graph for optimal scheduling.

TaskNode

Represents a computation task in a dependency graph.

ThreadingAccelerator{T} (Backward Compatibility)

Basic CPU threading acceleration for existing code.

_get_influence_cache(domain::RadialDomain, dr_matrix)

Get or create cached influence functions and matrix for given domain. Note: drmatrix should be a BandedMatrix (defined in linearalgebra.jl)

_get_tau_cache(domain::RadialDomain)

Get or create cached tau polynomials and derivatives for given domain.

add_internal_sources_local!(field::AbstractScalarField{T}, domain::RadialDomain) where T

Add volumetric sources (completely local operation). This works for any scalar field with radial source profile.

analyze_load_balance(pencil::Pencil)

Analyze and report load balance for a given pencil decomposition.

apply_banded_full!(out, B, v)

Apply banded matrix to full vector.

apply_composition_boundary_conditions!(field; time_index=nothing)

Refresh composition boundary values from the BoundaryConditions subsystem and enforce Dirichlet data in spectral space.

apply_enhanced_implicit_step!(state, dt)

Apply enhanced implicit time integration with advanced solvers.

apply_flux_bc_direct!(spec_real, spec_imag, local_lm, lm_idx,
                     field::AbstractScalarField, domain, r_range)

Direct modification of boundary values to approximately satisfy flux BC. This is the simplest but least accurate method.

apply_flux_bc_influence_matrix!(spec_real, spec_imag, local_lm, lm_idx,
                               apply_inner, apply_outer, field::AbstractScalarField,
                               domain, r_range)

Apply flux boundary conditions using the influence matrix method.

apply_flux_bc_spectral_complete!(temp_field, domain)

Complete implementation of flux boundary conditions in spectral space. This modifies the spectral coefficients to satisfy ∂T/∂r = prescribed_flux.

apply_flux_bc_tau!(spec_real, spec_imag, local_lm, lm_idx, 
                   apply_inner, apply_outer, field::AbstractScalarField, 
                   domain, r_range)

Apply flux boundary conditions using the tau method. This is the generalized version that works with any scalar field.

apply_geometric_factors_spectral!(field::AbstractScalarField{T}, domain::RadialDomain) where T

Apply geometric factors (1/r, 1/(r sin θ)) in spectral space. For gradients in spherical coordinates. This is generic.

apply_magnetic_boundary_conditions!(fields; time_index=nothing)

Refresh magnetic boundary data from the BoundaryConditions subsystem and enforce the corresponding Dirichlet values in spectral space.

apply_scalar_flux_bc_spectral!(field::AbstractScalarField{T}, domain::RadialDomain;
                               method::Symbol=:tau) where T

Apply flux boundary conditions to a scalar field in spectral space. Methods available: :tau (most robust), :influence_matrix, :direct (simplest).

apply_tau_correction!(profile::Vector{T}, tau_coeffs, domain::RadialDomain) where T

Add tau correction to the radial profile.

apply_velocity_boundary_conditions!(fields; time_index=nothing)

Refresh velocity boundary data from the BoundaryConditions subsystem and immediately enforce Dirichlet constraints in spectral space.

batch_convert_directory(input_dir::String, output_dir::String = "";
                       pattern::String = "combined_global_time_",
                       precision::Type{T} = Float64,
                       compute_diagnostics::Bool = true) where T

Convert all spectral files matching a pattern in a directory.

batch_magnetic_transforms!(mag_fields::SHTnsMagneticFields{T}) where T

Perform batched transforms for better cache efficiency using shtnskit_transforms.jl

batch_shtnskit_transforms!(specs::Vector{SHTnsSpectralField{T}},
                          physs::Vector{SHTnsPhysicalField{T}}) where T

Batch process multiple transforms using SHTnsKit with PencilArrays.

batch_spectral_to_physical!(specs, physs)

Compatibility wrapper that calls batch_shtnskit_transforms! for batched spectral→physical transforms using SHTnsKit with PencilArrays/MPI.

batch_velocity_transforms!(fields::SHTnsVelocityFields{T}) where T

Perform batched transforms for better cache efficiency using shtnskit_transforms.jl

batch_write_spectral_fields!(nc_file, fields::Dict, config::OutputConfig, field_info::FieldInfo)

Write multiple spectral fields in batched operations for better I/O performance

build_banded_A(T, domain, diffusivity, l) -> BandedMatrix{T}

Construct banded A = ν*(d²/dr² + (2/r)d/dr − l(l+1)/r²) in banded storage.

build_influence_matrix(G_inner, G_outer, dr_matrix, domain)

Construct a 2×2 matrix mapping influence amplitudes to boundary flux errors. Rows correspond to (inner, outer) boundaries; columns to (inner, outer) influence functions.

build_rhs_cnab2!(rhs, un, nl, nl_prev, dt, matrices)

Build RHS for CNAB2 IMEX: rhs = un/dt + (1-θ)·L·un + (3/2)·nl − (1/2)·nl_prev, where θ = matrices.theta and L is the diffusivity-scaled linear operator.

build_theta_derivative_matrix(::Type{T}, config::SHTnsKitConfig) where T

Build sparse matrix for θ-derivatives in spectral space. This matrix couples different l modes with the same m.

calculate_linear_neighbors(rank::Int, dim::Int, proc_dims::Tuple, boundaries::Symbol)

Calculate neighbor ranks for non-Cartesian topologies.

combine_distributed_time(output_dir::String, time::Float64; 
                        config::CombinerConfig = create_combiner_config(),
                        precision::Type{T} = Float64) where T

Main function to combine distributed files for a specific time.

combine_magnetic_spectral!(combiner::FieldCombiner{T}, lm_mapping::Dict) where T

Combine magnetic spectral coefficients from all distributed files.

combine_physical_fields!(combiner::FieldCombiner{T}) where T

Combine physical space temperature field from distributed files.

combine_spectral_fields!(combiner::FieldCombiner{T}) where T

Combine spectral field data from distributed files.

combine_time_series(output_dir::String, time_range::Tuple{Float64,Float64}; 
                   config::CombinerConfig = create_combiner_config(),
                   precision::Type{T} = Float64) where T

Combine multiple time points into a time series.

combine_to_global!(combiner::FieldCombiner{T}) where T

Combine distributed field data into global field structures.

combine_velocity_spectral!(combiner::FieldCombiner{T}, lm_mapping::Dict) where T

Combine velocity spectral coefficients from all distributed files.

compute_all_gradients_spectral!(field::AbstractScalarField{T}, domain::RadialDomain) where T

Compute all gradient components (θ, φ, r) in spectral space. This is the main driver function that works for any scalar field.

compute_boundary_fluxes(profile::Vector{T}, dr_matrix, domain::RadialDomain) where T

Compute flux (dT/dr) at both boundaries using the derivative matrix. Note: drmatrix should be a BandedMatrix{T} (defined in linearalgebra.jl)

compute_chebyshev_polynomial(n::Int, domain::RadialDomain)

Compute Chebyshev polynomial T_n on the radial grid.

compute_global_diagnostics(combiner::FieldCombiner{T}) where T

Compute global diagnostics for the combined fields.

compute_global_diagnostics(converter::SpectralToPhysicalConverter{T}) where T

Compute global field diagnostics using MPI reductions.

compute_influence_functions_flux(oc_domain::RadialDomain)

Compute influence functions for flux BCs. These are solutions to the homogeneous equation with specific BCs.

compute_inner_tau_function(domain::RadialDomain)

Compute tau function for inner boundary only (zero derivative at outer).

compute_magnetic_helicity(mag_fields::SHTnsMagneticFields{T}) where T

Compute magnetic helicity using enhanced spectral integration

compute_nonlinear!(parallelizer, temp_field, vel_fields, domain)

Advanced CPU computation with SIMD, NUMA, and task-based parallelism.

compute_outer_tau_function(domain::RadialDomain)

Compute tau function for outer boundary only (zero derivative at inner).

compute_phi1_function(A, expA)

Compute φ1(A) = (exp(A) - I) / A efficiently with comprehensive error handling. Uses series expansion for small ||A|| to avoid numerical issues.

compute_phi2_function(A, expA)

Compute φ2(A) = (exp(A) - I - A) / A² efficiently with comprehensive error handling. Uses series expansion for small ||A|| to avoid numerical issues.

compute_phi_gradient_spectral!(field::AbstractScalarField{T}) where T

Compute ∂field/∂φ using spherical harmonic properties (local operation). This is generic and works for any scalar field.

compute_radial_gradient_spectral!(field::AbstractScalarField{T}, domain::RadialDomain) where T

Compute ∂field/∂r using banded matrix derivative operator in spectral space (local operation). This uses the pre-computed derivative matrices from the field for optimal accuracy and efficiency.

compute_scalar_advection_local!(field::AbstractScalarField{T}, vel_fields) where T

Compute -u·∇field in physical space (completely local operation). This works for any scalar field.

compute_scalar_energy(field::AbstractScalarField{T}, oc_domain::RadialDomain) where T

Compute energy ∫ field² dV

compute_scalar_rms(field::AbstractScalarField{T}, oc_domain::RadialDomain) where T

Compute RMS value of scalar field.

compute_spectral_energy_diagnostics!(diagnostics, component, real_part, imag_part, field_info)

Compute spectral energy distribution diagnostics using SHTns configuration

compute_tau_coefficients_both(flux_error_inner::T, flux_error_outer::T, domain::RadialDomain) where T

Compute tau polynomial coefficients for both boundaries. Uses highest two Chebyshev modes as tau functions.

compute_tau_coefficients_inner(flux_error::T, domain::RadialDomain) where T

Compute tau coefficient for inner boundary only. Uses a single tau function that doesn't affect outer boundary.

compute_tau_coefficients_outer(flux_error::T, domain::RadialDomain) where T

Compute tau coefficient for outer boundary only. Uses a single tau function that doesn't affect inner boundary.

compute_theta_gradient_spectral!(field::AbstractScalarField{T}) where T

Compute ∂field/∂θ using spherical harmonic recurrence relations (local operation). This is generic and works for any scalar field.

compute_theta_recurrence_coefficients(::Type{T}, config::SHTnsKitConfig) where T

Pre-compute recurrence coefficients for θ-derivatives. Store as [nlm, 2] matrix: [:, 1] for l-1 coupling, [:, 2] for l+1 coupling

convert_spectral_file(input_filename::String, output_filename::String = "";
                     precision::Type{T} = Float64, 
                     compute_diagnostics::Bool = true) where T

Main function to convert a single spectral data file to physical space.

convert_to_physical!(converter::SpectralToPhysicalConverter{T}) where T

Convert all loaded spectral data to physical space using SHTns transforms.

create_boundary_slice(size_arr::Tuple, dim::Int, side::Symbol, width::Int)

Create array slice for boundary data extraction.

create_combiner_config(; kwargs...)

Create combiner configuration with keyword arguments.

create_computation_pencils(topology, dims, config)

Create specialized pencils for different stages of computation.

create_enhanced_field_variables!(nc_file, field_info::FieldInfo, config::OutputConfig, 
                                available_fields::Vector{String})

Enhanced field variable setup that leverages SHTns configuration

create_enhanced_output_config(state)

Create output configuration with enhanced I/O settings.

create_erk2_cache(config, domain, diffusivity, dt; use_krylov=false, m=20, tol=1e-8)

Create ERK2 cache with precomputed matrix functions for all spherical harmonic modes.

create_erk2_config(; lmax, mmax, nlat, nlon, optimize_for_erk2=true)

Create an SHTnsKit configuration for ERK2 timestepping.

create_etd_cache(config, domain, diffusivity, dt) -> ETDCache

Build per-l exponential cache for the linear operator Al = diffusivity*(d²/dr² + (2/r)d/dr − l(l+1)/r²). Computes exp(dt Al) and phi1(dt A_l) via dense methods. Single-rank recommended.

create_field_combiner(output_dir::String, time::Float64; 
                     precision::Type{T} = Float64) where T

Create a field combiner by reading configuration from distributed files.

create_halo_slice(size_arr::Tuple, dim::Int, side::Symbol, width::Int)

Create array slice for halo region insertion.

create_memory_efficient_output_buffer(data_size::Int, precision::DataType)

Create appropriately sized buffer for output operations

create_parameter_template(filename::String)

Create a template parameter file for users to customize.

create_pencil_array(::Type{T}, pencil::Pencil; init=:zero) where T

Create a PencilArray with specified initialization.

create_pencil_decomposition_shtnskit(nlat, nlon, nr, sht_config, comm, optimize)

Create PencilArrays decomposition optimized for theta-phi parallelization.

create_pencil_fft_plans(pencils, dims)

Create PencilFFTs plans for efficient phi-direction transforms.

create_pencil_topology(shtns_config; optimize=true)

Create enhanced pencil decomposition for SHTns grids. Supports both 1D and 2D decompositions with automatic optimization. Accepts an object with fields nlat, nlon, and nlm (e.g., SHTnsKitConfig).

create_shtns_aware_output_config(shtns_config::SHTnsKitConfig, pencils::NamedTuple; 
                                base_config::OutputConfig = default_config())

Create output configuration that integrates with SHTns configuration and pencil decomposition

create_shtnskit_config(; lmax::Int, mmax::Int=lmax, nlat::Int=lmax+2,
                       nlon::Int=max(2*lmax+1, 4), optimize_decomp::Bool=true) -> SHTnsKitConfig

Create SHTnsKit configuration with MPI parallelization using PencilArrays. This creates proper integration with ../SHTnsKit.jl, PencilArrays, and PencilFFTs.

create_shtnskit_transpose_plans(pencils)

Create transpose plans for efficient pencil reorientations.

create_spectral_converter(filename::String; precision::Type{T} = Float64) where T

Create a spectral to physical converter by reading configuration from a NetCDF file.

create_transpose_plans(pencils)

Create enhanced transpose plans between pencil orientations. Includes caching and communication optimization.

eab2_update!(u, nl, nl_prev, etd, config)

Apply EAB2 update per (l,m): u^{n+1} = E u^n + dtphi1(3/2 nl^n − 1/2 nl^{n−1}).

eab2_update_krylov!(u, nl, nl_prev, domain, diffusivity, config, dt; m=20, tol=1e-8)

EAB2 update using Krylov exp/φ1 actions and banded LU for φ1.

eab2_update_krylov_cached!(u, nl, nl_prev, alu_map, domain, ν, config, dt; m=20, tol=1e-8)

Same as eab2updatekrylov!, but reuses cached banded A and LU per l.

enforce_composition_boundary_values!(field)

Anchor spectral boundary modes to stored Dirichlet values when applicable.

enforce_magnetic_boundary_values!(fields)

Anchor magnetic toroidal/poloidal spectral data to cached Dirichlet boundary values on the inner and outer radial surfaces.

enforce_velocity_boundary_values!(fields)

Anchor toroidal and poloidal spectral coefficients to the currently cached Dirichlet boundary values on the inner and outer radial surfaces.

erk2_stage_residual_stats(buffers) -> NamedTuple

Compute diagnostic statistics for the difference between stage nonlinear terms and the base-step nonlinear terms.

estimate_memory_usage(pencils, field_count::Int, precision::Type)

Estimate memory usage for given pencil configuration.

estimate_memory_usage_shtnskit(nlat, nlon, lmax, field_count, T)

Estimate memory usage for SHTnsKit-based transforms with PencilArrays.

evaluate_chebyshev_derivative(n::Int, r::T, domain::RadialDomain) where T

Evaluate derivative of Chebyshev polynomial at a point.

evaluate_tau_derivative_inner(tau::Vector, domain::RadialDomain)

Evaluate tau function derivative at inner boundary.

evaluate_tau_derivative_outer(tau::Vector, domain::RadialDomain)

Evaluate tau function derivative at outer boundary.

exchange_dimension_halos!(data::Array, pencil::Pencil, dim::Int, 
                          halo_width::Int, boundaries::Symbol, comm::MPI.Comm)

Perform halo exchange along a specific dimension using MPI point-to-point communication.

exp_action_krylov(Aop!, v, dt; m=20, tol=1e-8) -> y ≈ exp(dt A) v

Simple Arnoldi-based approximation of the exponential action.

extract_coefficients_for_shtnskit!(coeffs_buffer, spec_real, spec_imag, r_local, config)

Extract spectral coefficients in format expected by SHTnsKit using pre-allocated buffer.

extract_local_radial_profile!(profile, data, local_lm, nr, r_range)

In-place version to avoid allocations; writes the local radial line into profile for the given local_lm using the provided r_range.

extract_physical_slice_generic!(slice_buffer, phys_data, r_local, config)

Generic extraction for any pencil orientation using pre-allocated buffer.

extract_physical_slice_phi_local!(slice_buffer, phys_data, r_local, config)

Extract physical slice when in phi-local pencil using pre-allocated buffer.

extract_spectral_subset(field::SHTnsSpectralField{T}; l_max::Int = 10) where T

Extract a subset of spectral modes for analysis.

extract_vector_component_generic!(component_buffer, v_data, r_local, config)

Generic extraction for vector components using pre-allocated buffer.

find_distributed_files(output_dir::String, time::Float64, filename_prefix::String = "geodynamo")

Find all distributed files for a specific simulation time.

find_package_root()

Find the root directory of the Geodynamo.jl package.

get_comm()

Get MPI communicator, initializing MPI if needed. Provides thread-safe lazy initialization.

get_dimension_neighbors(pencil::Pencil, dim::Int, boundaries::Symbol) -> (Int, Int)

Get left and right neighbor process ranks for a given dimension. Returns (leftneighbor, rightneighbor) where MPI.MPIPROCNULL indicates no neighbor.

get_eab2_alu_cache!(caches, key, ν, T, domain) -> Dict{Int,Tuple{BandedMatrix{T},BandedLU{T}}}

Retrieve or initialize a cache mapping l -> (Abanded, LU(Abanded)) for EAB2. Reinitializes if ν or nr changed.

get_erk2_cache!(caches, key, diffusivity, config, domain, dt; use_krylov=false)

Retrieve or create ERK2 cache with automatic invalidation when parameters change.

get_flux_value(lm_idx::Int, boundary::Int, field::AbstractScalarField)

Get prescribed flux value for given mode and boundary from scalar field. This is a generic version that works with any scalar field.

get_nprocs()

Get total number of MPI processes.

get_parameters()

Get the current global parameters. If not set, loads default parameters.

get_pencil_orientation(pencil::Pencil{3}) -> Symbol

Get the orientation of a pencil (which dimensions are local).

get_process_dimensions(topology) -> Tuple

Extract process grid dimensions from topology.

get_rank()

Get MPI rank of current process.

get_shtnskit_performance_stats()

Get performance statistics for SHTnsKit transforms with PencilArrays.

hybrid_compute_nonlinear!(parallelizer, temp_field, vel_fields, domain)

Compute nonlinear terms using hybrid MPI+threading parallelism.

index_to_lm_shtnskit(idx, lmax, mmax) -> (l, m)

Convert linear index to (l,m) for SHTnsKit compatibility.

infer_pencils_from_transpose_name(name::Symbol, plan) -> (src_pencil, dest_pencil)

Infer source and destination pencils from transpose operation name and plan. For TransposeOperator, we need to extract pencil info from context since the operator itself doesn't expose src/dest pencils directly.

initialize_enhanced_simulation(::Type{T}=Float64; kwargs...)

Initialize simulation with all parallelization features enabled.

initialize_parameters(config_file::String = "")

Initialize the global parameter system.

initialize_master_simulation(::Type{T}=Float64; kwargs...)

Initialize simulation with comprehensive CPU parallelization.

install_erk2_cache_bundle!(target, bundle)

Copy ERK2 caches from bundle into the target cache dictionary.

list_available_times(output_dir::String, filename_prefix::String = "geodynamo")

List all available simulation times in the output directory.

load_distributed_fields!(combiner::FieldCombiner{T}) where T

Load field data from all distributed files into the combiner structure.

load_erk2_cache_bundle!(target, path) -> metadata

Load caches from path and install them into target, returning metadata.

load_erk2_cache_bundle(path) -> (caches, metadata)

Load ERK2 caches and associated metadata from disk.

load_parameters(config_file::String = "")

Load parameters from a configuration file. If no file is specified, loads from the default config/default_params.jl file.

Arguments

• config_file::String: Path to parameter file (optional)

Returns

• GeodynamoParameters: Loaded parameters

load_parameters_from_file(config_file::String)

Load parameters from a Julia file containing parameter definitions.

load_physical_temperature!(field::SHTnsPhysicalField{T}, nc_file, var_name::String) where T

Load physical space temperature data from NetCDF file.

load_single_file!(combiner::FieldCombiner{T}, filename::String) where T

Load data from a single file (no combination needed).

load_single_spectral_field!(field::SHTnsSpectralField{T}, nc_file, 
                           real_var::String, imag_var::String) where T

Load a single spectral field from NetCDF file.

load_spectral_coefficients!(field::SHTnsSpectralField{T}, nc_file, 
                            real_var_name::String, imag_var_name::String,
                            l_values::Vector{Int}, m_values::Vector{Int}, 
                            r_spectral::Vector{Float64}) where T

Load spectral coefficients from NetCDF file into a spectral field structure.

load_spectral_data!(converter::SpectralToPhysicalConverter{T}, filename::String) where T

Load spectral field data from NetCDF file into Geodynamo field structures.

main_batch_convert(input_dir::String; kwargs...)

Main entry point for batch conversion of files.

main_combine_time(output_dir::String, time::Float64; kwargs...)

Main entry point for combining distributed files for a single time.

main_combine_time_series(output_dir::String, time_range::Tuple{Float64,Float64}; kwargs...)

Main entry point for combining time series.

main_convert_file(filename::String; kwargs...)

Main entry point for converting a single file.

map_spectral_coefficients!(global_tor_real, global_tor_imag, global_pol_real, global_pol_imag,
                          local_tor_real, local_tor_imag, local_pol_real, local_pol_imag,
                          local_l, local_m, lm_mapping)

Map local spectral coefficients to global arrays using (l,m) index mapping.

maybe_log_erk2_stage_residual!(label, buffers, step)

Emit a diagnostic log entry when ERK2 diagnostics are enabled.

modify_for_flux_inner!(spec_real, spec_imag, local_lm, prescribed_flux,
                      dr_matrix, domain, r_range)

Modify coefficients near inner boundary to approximate flux condition. Uses low-order extrapolation.

modify_for_flux_outer!(spec_real, spec_imag, local_lm, prescribed_flux,
                      dr_matrix, domain, r_range)

Modify coefficients near outer boundary to approximate flux condition. Uses low-order extrapolation.

normalize_influence_function!(G::Vector{T}, domain::RadialDomain, which_boundary::Int) where T

Normalize influence function to have unit flux at the specified boundary.

optimize_communication_order(plans::Dict)

Determine optimal order for transpose operations to minimize communication.

optimize_erk2_transforms!(config::SHTnsKitConfig)

Optimize SHTnsKit transforms for ERK2 timestepping with PencilFFTs. This function pre-warms transform plans and optimizes memory layout.

optimize_fft_performance!(config::SHTnsKitConfig)

Optimize PencilFFTs performance by warming up plans and checking efficiency.

optimize_field_data_layout!(field_data::Dict, field_info::FieldInfo)

Optimize data layout for output based on pencil decomposition

optimize_magnetic_memory_layout!(mag_fields::SHTnsMagneticFields{T}) where T

Optimize memory layout for better cache performance using pencil topology

optimize_process_topology(nprocs::Int, dims::Tuple{Int,Int,Int})

Find optimal 2D process grid for given number of processes and problem dimensions. Minimizes communication volume.

optimize_process_topology_shtnskit(nprocs, nlat, nlon)

Optimize MPI process topology for theta-phi parallelization.

optimize_velocity_memory_layout!(fields::SHTnsVelocityFields{T}) where T

Optimize memory layout for better cache performance using pencil topology

perform_analysis_direct!(phys, spec, config)

Direct analysis without transpose (fallback).

perform_analysis_from_phi_pencil!(phys_phi, spec, config)

Perform analysis from phi-pencil data.

perform_analysis_phi_local!(phys, spec, config)

Perform analysis when physical field is in phi-pencil (phi is local).

perform_analysis_with_transpose!(phys, spec, config, to_phi_plan)

Perform analysis with transpose to phi-pencil.

perform_synthesis_direct!(spec, phys, config)

Direct synthesis without transpose (fallback method).

perform_synthesis_phi_local!(spec, phys, config)

Perform synthesis when physical field is already in phi-pencil (phi is local).

perform_synthesis_to_phi_pencil!(spec, phys_phi, config)

Perform synthesis directly to phi-pencil array.

perform_synthesis_with_transpose!(spec, phys, config, back_plan)

Perform synthesis with transpose to phi-pencil for optimal FFT performance.

phi1_action_krylov(BA, LU_A, v, dt; m=20, tol=1e-8) -> y ≈ φ1(dt A) v

Compute φ1(dt A) v = A^{-1}[(exp(dt A) − I) v]/dt using Krylov exp(action) and banded solve.

print_pencil_axes(pencils)

Print the axes_local tuple for each pencil, showing the local index ranges for all three axes. This helps verify which axes are distributed (those with nontrivial subranges across ranks) and which axis is contiguous locally.

print_pencil_info(pencils)

Print detailed information about pencil decomposition.

print_shtnskit_config_summary(nlat, nlon, lmax, mmax, nlm, nprocs, memory_estimate)

Print configuration summary for SHTnsKit setup.

print_transpose_statistics()

Print accumulated transpose timing statistics.

read_distributed_metadata(filename::String)

Read metadata from a distributed NetCDF file to determine global configuration.

read_file_metadata(filename::String)

Read metadata from NetCDF file to determine grid configuration.

run_enhanced_simulation!(state::SimulationState{T})

Run geodynamo simulation with all parallelization optimizations.

run_master_simulation!(state::SimulationState{T})

Run geodynamo simulation with maximum CPU parallelization optimizations.

save_combined_fields(combiner::FieldCombiner{T}, output_filename::String; 
                    config::CombinerConfig = create_combiner_config()) where T

Save combined fields to NetCDF file using Geodynamo I/O system.

save_combined_time_series(combiners::Vector{FieldCombiner{T}}, output_dir::String, 
                         filename_prefix::String; 
                         config::CombinerConfig = create_combiner_config()) where T

Save combined time series to a single NetCDF file.

save_erk2_cache_bundle(path, caches; metadata=Dict())

Persist a dictionary of ERK2 caches to disk along with optional metadata.

save_parameters(params::GeodynamoParameters, filename::String)

Save parameters to a Julia file.

save_physical_fields(converter::SpectralToPhysicalConverter{T}, output_filename::String) where T

Save converted physical space fields to NetCDF file using parallel I/O.

set_parameters!(params::GeodynamoParameters)

Set the global parameters.

set_velocity_workspace!(ws)

Register a global VelocityWorkspace to be used by velocity kernels when available. Pass nothing to disable and fall back to internal buffers.

setup_shtns_metadata!(nc_file, shtns_config::SHTnsKitConfig, pencils::NamedTuple)

Add SHTns-specific metadata to NetCDF file

shtnskit_physical_to_spectral!(phys::SHTnsPhysicalField{T}, 
                              spec::SHTnsSpectralField{T}) where T

Transform from physical to spectral space using SHTnsKit with PencilArrays.

shtnskit_spectral_to_physical!(spec::SHTnsSpectralField{T},
                              phys::SHTnsPhysicalField{T}) where T

Transform from spectral to physical space using SHTnsKit with PencilArrays/PencilFFTs.

shtnskit_vector_analysis!(vec_phys::SHTnsVectorField{T},
                         tor_spec::SHTnsSpectralField{T}, 
                         pol_spec::SHTnsSpectralField{T}) where T

Vector analysis using SHTnsKit with PencilArrays.

shtnskit_vector_synthesis!(tor_spec::SHTnsSpectralField{T}, 
                          pol_spec::SHTnsSpectralField{T},
                          vec_phys::SHTnsVectorField{T}) where T

Vector synthesis using SHTnsKit spheroidal-toroidal decomposition with PencilArrays.

store_coefficients_from_shtnskit!(spec_real, spec_imag, coeffs_matrix, r_local, config)

Store coefficients from SHTnsKit format back to spectral field.

store_physical_slice_generic!(phys_data, phys_slice, r_local, config)

Generic storage for any pencil orientation.

store_physical_slice_phi_local!(phys_data, phys_slice, r_local, config)

Store physical slice when in phi-local pencil.

store_vector_components_generic!(v_theta, v_phi, vt_field, vp_field, r_local, config)

Store vector components for any pencil orientation.

synchronize_halos!(arr::PencilArray; halo_width::Int=1, boundaries::Symbol=:all)

Synchronize ghost/halo regions for parallel finite difference computations.

Parameters

• arr: PencilArray to synchronize
• halo_width: Width of halo region (number of ghost cells), default 1
• boundaries: Boundary handling (:all, :periodic, :nonperiodic), default :all

Notes

This function implements MPI point-to-point communication to exchange boundary data between neighboring processes in each decomposed dimension. It's essential for maintaining accuracy in finite difference stencil operations near subdomain boundaries.

For spectral methods, explicit halo exchange may not be needed as the global nature of spectral transforms handles boundary coupling through transpose operations.

synchronize_pencil_data!(field)

Synchronize PencilArray data across MPI processes to ensure consistency.

synchronize_pencil_transforms!(field::SHTnsSpectralField{T}) where T

Ensure all pending PencilFFTs operations are completed and data is consistent across processes.

test_halo_exchange(pencil::Pencil, ::Type{T}=Float64; halo_width::Int=1, verbose::Bool=true) where T

Test halo exchange functionality by creating a test array with rank-based values. Returns true if halo exchange is working correctly.

Example

pencils = create_pencil_topology(shtns_config)
test_halo_exchange(pencils.θ, Float64; halo_width=1, verbose=true)

transform_field_and_gradients_to_physical!(field::AbstractScalarField{T}) where T

Transform scalar field and all gradient components to physical space in a single batched operation to minimize communication.

transpose_with_timer!(dest, src, plan, label="")

Perform transpose with optional timing and statistics.

update_derived_parameters!(params::GeodynamoParameters)

Update derived parameters based on primary parameters.

update_global_parameters!()

Update all global parameter variables with values from the current parameter struct.

validate_magnetic_configuration(mag_fields::SHTnsMagneticFields{T}, config::SHTnsKitConfig) where T

Validate magnetic field configuration consistency with SHTns setup

validate_mpi_consistency!(field::SHTnsSpectralField{T}) where T

Check that spectral field data is consistent across MPI processes after time stepping.

validate_output_compatibility(field_info::FieldInfo, shtns_config::SHTnsKitConfig)

Validate that output field information is compatible with SHTns configuration

validate_pencil_decomposition(config::SHTnsKitConfig)

Validate that pencil decomposition is optimal for the problem size and MPI configuration.

validate_velocity_configuration(fields::SHTnsVelocityFields{T}, config::SHTnsKitConfig) where T

Validate velocity field configuration consistency with SHTns setup

write_enhanced_coordinates!(nc_file, field_info::FieldInfo, config::OutputConfig)

Write coordinates with enhanced precision and metadata from SHTns config

write_grid_file!(config::OutputConfig, field_info::FieldInfo,
                shtns_config::Union{SHTnsKitConfig,Nothing},
                metadata::Dict{String,Any})

Write a separate grid file containing all coordinate and grid information. This is written only once by rank 0 at the start of the simulation.

write_single_spectral_component!(nc_file, component, field_data, config)

Write a single spectral component with enhanced memory handling

write_spectral_data_parallel!(nc_file, real_name, imag_name, real_data, imag_data, field_info)

Write spectral data using parallel I/O strategies based on pencil decomposition

zero_scalar_work_arrays!(field::AbstractScalarField{T}) where T

Efficiently zero all work arrays for a scalar field.

AbstractBoundaryCondition{T}

Abstract base type for all boundary conditions.

BoundaryCache{T}

Cache structure for storing processed boundary data.

BoundaryConditionSet{T}

Complete set of boundary conditions for inner and outer boundaries.

BoundaryData{T}

Common data structure for boundary condition data from any source.

BoundaryLocation

Enumeration for boundary locations.

BoundaryType

Enumeration for boundary condition types.

FieldType

Enumeration for different physical field types.

add_noise_to_boundary(boundary_data::BoundaryData, noise_amplitude::Real, 
                     noise_type::Symbol=:gaussian)

Add noise to existing boundary data.

apply_boundary_conditions!(field, field_type::FieldType, solver_state)

Apply boundary conditions during solver operations.

This function integrates boundary conditions with the timestepping and solving process.

apply_boundary_conditions_to_rhs!(rhs, state, field_type::FieldType)

Apply boundary conditions to right-hand side during timestepping.

This function modifies the RHS vector to enforce boundary conditions during implicit and explicit timestepping methods.

apply_composition_bc_to_rhs!(rhs, comp_field)

Apply composition boundary conditions to RHS vector.

apply_composition_boundaries!(comp_field, boundary_set::BoundaryConditionSet; time::Float64=0.0)

Apply composition boundary conditions from a BoundaryConditionSet to a composition field. This is a convenience wrapper that loads the boundary set and applies it.

apply_composition_boundary_conditions!(comp_field, time_index::Int=1)

Apply composition boundary conditions to the field.

apply_gaussian_smoothing!(data::AbstractMatrix, theta::Vector, phi::Vector, radius::Real)

Apply Gaussian smoothing kernel to 2D data array.

apply_magnetic_bc_to_rhs!(rhs, magnetic_field)

Apply magnetic field boundary conditions to RHS vector.

apply_magnetic_boundary_conditions!(magnetic_field, time_index::Int=1)

Apply magnetic field boundary conditions to the field.

apply_temperature_bc_to_rhs!(rhs, temp_field)

Apply temperature boundary conditions to RHS vector.

apply_temperature_boundaries!(temp_field, boundary_set::BoundaryConditionSet; time::Float64=0.0)

Apply temperature boundary conditions from a BoundaryConditionSet to a temperature field. This is a convenience wrapper that loads the boundary set and applies it.

apply_temperature_boundary_conditions!(temp_field, time_index::Int=1)

Apply temperature boundary conditions to the field.

apply_velocity_bc_to_rhs!(rhs, velocity_field)

Apply velocity boundary conditions to RHS vector.

apply_velocity_boundary_conditions!(velocity_field, time_index::Int=1)

Apply velocity boundary conditions to the field.

bilinear_interpolate(data::Matrix{T}, theta_idx::Tuple{Int, Int}, phi_idx::Tuple{Int, Int},
                    theta_weights::Tuple{T, T}, phi_weights::Tuple{T, T}) where T

Perform bilinear interpolation on a 2D data array. Handles periodic boundary conditions in phi direction.

cache_boundary_data!(cache::BoundaryCache{T}, key::String, data::Array{T}) where T

Cache processed boundary data.

calculate_potential_field_boundary(coeffs::Dict, theta::Vector, phi::Vector, lmax::Int)

Calculate magnetic field from spherical harmonic coefficients of the potential.

check_interpolation_bounds(boundary_data::BoundaryData, target_theta::Vector{T}, 
                          target_phi::Vector{T}) where T

Check if target grid is within the bounds of the source grid and warn if extrapolation is needed.

clear_boundary_cache!(cache::BoundaryCache)

Clear all cached boundary data.

combine_programmatic_patterns(patterns::Vector{Tuple{Symbol, Real}}, config; 
                             parameters::Vector{Dict}=Dict[], description::String="")

Combine multiple programmatic patterns with different amplitudes.

compute_boundary_condition_residual(field, field_type::FieldType)

Compute residual to check how well boundary conditions are satisfied.

Returns a measure of how much the current field violates the boundary conditions. Useful for monitoring solution quality and debugging.

copy_boundary_conditions!(dest_field, src_field, field_type::FieldType)

Copy boundary conditions from one field to another.

create_boundary_data(values::Array{T}, field_type::String; 
                    theta=nothing, phi=nothing, time=nothing,
                    units="", description="", file_path="programmatic") where T

Create a BoundaryData structure from raw data.

create_composition_interpolation_cache(boundary_set::BoundaryConditionSet, config)

Create interpolation cache for composition boundaries.

create_hybrid_composition_boundaries(file_spec::String, prog_spec::Tuple, config; swap_boundaries=false)

Create hybrid composition boundaries (one from file, one programmatic).

create_hybrid_magnetic_boundaries(file_spec::String, prog_spec::Tuple, config; swap_boundaries=false)

Create hybrid magnetic boundaries (one from file, one programmatic).

create_hybrid_temperature_boundaries(file_spec::String, prog_spec::Tuple, config; swap_boundaries=false)

Create hybrid temperature boundaries (one from file, one programmatic).

create_hybrid_velocity_boundaries(file_spec::String, prog_spec::Tuple, config; swap_boundaries=false)

Create hybrid velocity boundaries (one from file, one programmatic).

create_interpolation_cache(boundary_data::BoundaryData, target_theta::Vector{T}, 
                          target_phi::Vector{T}) where T

Create interpolation cache for efficient repeated interpolations.

create_layered_composition_boundary(config, layer_specs::Vector{Tuple{Real, Real, Real}})

Create layered composition boundary conditions.

Arguments

• layer_specs: Vector of (colatitudestart, colatitudeend, composition) tuples

Example

# Create three-layer composition structure
layer_specs = [
    (0.0, π/3, 0.8),     # High composition in top layer
    (π/3, 2π/3, 0.4),    # Medium composition in middle layer  
    (2π/3, π, 0.1)       # Low composition in bottom layer
]

create_layered_temperature_boundary(config, layer_specs::Vector{Tuple{Real, Real, Real}})

Create layered temperature boundary conditions.

Arguments

• layer_specs: Vector of (colatitudestart, colatitudeend, temperature) tuples

Example

# Create three-layer temperature structure
layer_specs = [
    (0.0, π/3, 1000.0),    # High temperature in top layer
    (π/3, 2π/3, 500.0),   # Medium temperature in middle layer  
    (2π/3, π, 100.0)      # Low temperature in bottom layer
]

create_magnetic_interpolation_cache(boundary_set::BoundaryConditionSet, config)

Create interpolation cache for magnetic boundaries.

create_programmatic_boundary(pattern::Symbol, config, amplitude::Real=1.0;
                            parameters::Dict=Dict(), description::String="")

Create programmatically generated boundary conditions.

Available patterns:

• :uniform - Uniform value
• :y11 - Y₁₁ spherical harmonic
• :plume - Gaussian plume pattern
• :hemisphere - Hemispherical pattern
• :dipole - Dipolar pattern (Y₁₀)
• :quadrupole - Quadrupolar pattern
• :custom - User-defined function

create_programmatic_composition_boundaries(inner_spec::Tuple, outer_spec::Tuple, config)

Create fully programmatic composition boundaries.

create_programmatic_magnetic_boundaries(inner_spec::Tuple, outer_spec::Tuple, config)

Create fully programmatic magnetic boundaries.

create_programmatic_magnetic_boundary(pattern::Symbol, config, amplitude::Real=1.0; 
                                    parameters::Dict=Dict())

Create programmatically generated magnetic boundary conditions.

Available patterns:

• :insulating - Insulating boundary (Br = 0, ∂Btan/∂r = 0)
• :perfect_conductor - Perfect conductor (B_tan = 0)
• :dipole - Dipolar magnetic field pattern
• :quadrupole - Quadrupolar magnetic field pattern
• :potential_field - Potential field from spherical harmonic coefficients
• :uniform_field - Uniform magnetic field
• :custom - User-defined magnetic field function

create_programmatic_temperature_boundaries(inner_spec::Tuple, outer_spec::Tuple, config)

Create fully programmatic temperature boundaries.

create_programmatic_velocity_boundaries(inner_spec::Tuple, outer_spec::Tuple, config)

Create fully programmatic velocity boundaries.

create_programmatic_velocity_boundary(pattern::Symbol, config, amplitude::Real=1.0; 
                                    parameters::Dict=Dict())

Create programmatically generated velocity boundary conditions.

Available patterns:

• :no_slip - Zero velocity at boundary (amplitude ignored)
• :stress_free - Zero stress at boundary (amplitude ignored)
• :uniform_rotation - Uniform rotation with angular velocity amplitude
• :differential_rotation - Differential rotation pattern
• :zonal_flow - Zonal (east-west) flow pattern
• :meridional_flow - Meridional (north-south) flow pattern
• :custom - User-defined velocity function

create_temperature_interpolation_cache(boundary_set::BoundaryConditionSet, config)

Create interpolation cache for temperature boundaries.

create_time_dependent_programmatic_boundary(pattern::Symbol, config, time_span::Tuple{Real, Real}, 
                                           ntime::Int; amplitude::Real=1.0, 
                                           parameters::Dict=Dict(), description::String="",
                                           field_type::String="temperature")

Create time-dependent programmatically generated boundary conditions.

create_velocity_interpolation_cache(boundary_set::BoundaryConditionSet, config)

Create interpolation cache for velocity boundaries.

determine_field_type_from_name(field_name::String) -> FieldType

Determine field type from field name string.

enforce_boundary_conditions_in_solution!(solution, state, field_type::FieldType)

Enforce boundary conditions in the solution vector after timestepping.

This function ensures that the solution satisfies the boundary conditions after each timestep, which may be necessary for certain discretization schemes.

enforce_composition_bc_in_solution!(solution, comp_field)

Enforce composition boundary conditions in solution vector.

enforce_magnetic_bc_in_solution!(solution, magnetic_field)

Enforce magnetic field boundary conditions in solution vector.

enforce_magnetic_boundary_constraints!(magnetic_field, bc_type::Symbol)

Enforce magnetic boundary condition constraints based on physics.

Boundary condition types:

• :insulating - Insulating boundary: Jnormal = 0, ∇×Btangential = 0 (B_r ≠ 0)
• :perfect_conductor - Perfect conductor: Btangential = 0, Br free
• :potential_field - Potential field matching at boundary

enforce_temperature_bc_in_solution!(solution, temp_field)

Enforce temperature boundary conditions in solution vector.

enforce_velocity_bc_in_solution!(solution, velocity_field)

Enforce velocity boundary conditions in solution vector.

enforce_velocity_boundary_constraints!(velocity_field, bc_type::Symbol=:no_slip)

Enforce specific velocity boundary constraints based on boundary condition type. Uses proper QST (Q-spheroidal-toroidal) decomposition from SHTnsKit.

Arguments

• velocity_field: Velocity field structure with QST components
• bc_type: Type of boundary condition (:noslip, :stressfree, :custom)

Boundary Condition Mapping:

• No-slip: vr = vθ = v_φ = 0 → Q = S = T = 0 at boundaries
• Stress-free: v_r = 0, tangential stress = 0 → Q = 0, ∂S/∂r = ∂T/∂r = 0
• Impermeable: v_r = 0 → Q = 0 at boundaries (S, T unconstrained)

estimate_interpolation_error(boundary_data::BoundaryData, target_theta::Vector{T}, 
                            target_phi::Vector{T}) where T

Estimate interpolation error based on grid resolution differences.

find_composition_boundary_time_index(boundary_set::BoundaryConditionSet, current_time::Float64)

Find the appropriate time index for the current simulation time.

find_grid_indices(coords::Vector{T}, target::T; is_periodic::Bool=false) where T

Find the two surrounding indices in a coordinate array for interpolation. Handles periodic coordinates (e.g., longitude) if is_periodic=true.

find_temperature_boundary_time_index(boundary_set::BoundaryConditionSet, current_time::Float64)

Find the appropriate time index for the current simulation time.

get_boundary_condition_summary(field, field_type::FieldType)

Get a summary of the current boundary condition state.

get_boundary_data(field, field_type::FieldType)

Get boundary data from field using unified interface with fallback support.

get_boundary_statistics(boundary_data::BoundaryData)

Get statistical information about boundary data.

get_cached_data(cache::BoundaryCache{T}, key::String) where T

Retrieve cached boundary data.

get_comm()

Get MPI communicator (with fallback).

get_composition_boundary_data(comp_field)

Get boundary data from field or fallback cache.

get_composition_time_index(comp_field)

Get current time index from field or fallback cache.

get_current_boundaries(field, field_type::FieldType)

Get current boundary values for any field type.

get_current_composition_boundaries(comp_field)

Get current composition boundary conditions.

get_current_magnetic_boundaries(magnetic_field)

Get current magnetic field boundary conditions.

get_current_simulation_time(solver_state)

Extract current simulation time from solver state.

get_current_temperature_boundaries(temp_field)

Get current temperature boundary conditions.

get_current_velocity_boundaries(velocity_field)

Get current velocity boundary conditions.

get_default_boundary_type(field_type::FieldType, location::BoundaryLocation) -> BoundaryType

Get default boundary condition type for a field at a specific location.

get_default_units(field_type::FieldType) -> String

Get default units for a field type.

get_field_from_state(state, field_type::FieldType)

Extract the appropriate field from simulation state.

get_interpolation_statistics(boundary_data::BoundaryData, interpolated_data::Array{T}) where T

Compute statistics comparing original and interpolated data.

get_interpolation_weights(coords::Vector{T}, target::T, indices::Tuple{Int, Int}) where T

Calculate interpolation weights for linear interpolation.

get_netcdf_file_info(filename::String)

Get information about a NetCDF boundary condition file.

get_nprocs()

Get number of MPI processes (with fallback).

get_rank()

Get MPI rank (with fallback).

get_temperature_boundary_data(temp_field)

Get boundary data from field or fallback cache.

get_temperature_time_index(temp_field)

Get current time index from field or fallback cache.

get_time_index(field, field_type::FieldType)

Get current time index from field using unified interface with fallback support.

infer_velocity_bc_type(boundary::BoundaryData)

Infer boundary condition type (Dirichlet or Neumann) from boundary metadata.

initialize_boundary_conditions!(field, field_type::FieldType, config)

Initialize boundary condition support for a field structure.

Adds the necessary boundary condition fields to existing field structures without breaking compatibility with existing code.

interpolate_boundary_to_grid(boundary_data::BoundaryData, target_theta::Vector{T}, 
                            target_phi::Vector{T}, time_index::Int=1) where T

Interpolate boundary data to a target grid using bilinear interpolation.

interpolate_with_cache(boundary_data::BoundaryData, cache::Dict, time_index::Int=1)

Perform interpolation using pre-computed cache for efficiency.

load_composition_boundaries_from_files(inner_file::String, outer_file::String, config)

Load composition boundary conditions from NetCDF files.

load_composition_boundary_conditions!(comp_field, boundary_specs::Dict)

Load composition boundary conditions from various sources.

Arguments

• comp_field: SHTnsCompositionField structure
• boundary_specs: Dictionary specifying boundary sources

Examples

# NetCDF files for both boundaries
boundary_specs = Dict(
    :inner => "cmb_composition.nc",
    :outer => "surface_composition.nc"
)

# Mixed NetCDF and programmatic
boundary_specs = Dict(
    :inner => "cmb_composition.nc", 
    :outer => (:uniform, 0.1)  # 10% concentration
)

load_magnetic_boundaries_from_files(inner_file::String, outer_file::String, config)

Load magnetic field boundary conditions from NetCDF files.

load_magnetic_boundary_conditions!(magnetic_field, boundary_specs::Dict)

Load magnetic field boundary conditions from various sources.

Arguments

• magnetic_field: SHTnsMagneticField structure
• boundary_specs: Dictionary specifying boundary sources

Examples

# Insulating inner, potential field outer
boundary_specs = Dict(
    :inner => (:insulating, 0.0),
    :outer => (:potential_field, "geomagnetic_coefficients.nc")
)

# Perfect conductor boundaries
boundary_specs = Dict(
    :inner => (:perfect_conductor, 0.0),
    :outer => (:perfect_conductor, 0.0)
)

# NetCDF files for both boundaries
boundary_specs = Dict(
    :inner => "cmb_magnetic.nc",
    :outer => "surface_magnetic.nc"
)

load_temperature_boundaries_from_files(inner_file::String, outer_file::String, config)

Load temperature boundary conditions from NetCDF files.

load_temperature_boundary_conditions!(temp_field, boundary_specs::Dict)

Load temperature boundary conditions from various sources.

Arguments

• temp_field: SHTnsTemperatureField structure
• boundary_specs: Dictionary specifying boundary sources

Examples

# NetCDF files for both boundaries
boundary_specs = Dict(
    :inner => "cmb_temperature.nc",
    :outer => "surface_temperature.nc"
)

# Mixed NetCDF and programmatic
boundary_specs = Dict(
    :inner => "cmb_temperature.nc", 
    :outer => (:uniform, 300.0)
)

load_velocity_boundaries_from_files(inner_file::String, outer_file::String, config)

Load velocity boundary conditions from NetCDF files.

load_velocity_boundary_conditions!(velocity_field, boundary_specs::Dict)

Load velocity boundary conditions from various sources.

Arguments

• velocity_field: SHTnsVelocityField structure
• boundary_specs: Dictionary specifying boundary sources

Examples

# No-slip boundaries at both surfaces
boundary_specs = Dict(
    :inner => (:no_slip, 0.0),
    :outer => (:no_slip, 0.0)
)

# Stress-free boundaries
boundary_specs = Dict(
    :inner => (:stress_free, 0.0),
    :outer => (:stress_free, 0.0)
)

# NetCDF file for inner, no-slip for outer
boundary_specs = Dict(
    :inner => "cmb_velocity.nc",
    :outer => (:no_slip, 0.0)
)

log_boundary_condition_status(state, rank::Int=0)

Log the status of all boundary conditions in the simulation state.

magnetic_to_qst_coefficients(B_r, B_theta, B_phi, config)

Convert physical magnetic field components to QST spectral coefficients.

For magnetic fields:

• Q: Radial component coefficients (B_r)
• S: Spheroidal tangential component coefficients
• T: Toroidal tangential component coefficients

print_boundary_data_info(boundary_data::BoundaryData, prefix::String="")

Print detailed information about boundary data.

print_boundary_info(boundary_set::BoundaryConditionSet)

Print comprehensive information about a boundary condition set.

print_boundary_summary(field, field_type::FieldType)

Print a summary of loaded boundary conditions for any field type.

read_netcdf_boundary_data(filename::String; precision::Type{T}=Float64) where T

Read boundary condition data from a NetCDF file.

Returns a BoundaryData structure containing all boundary information.

reset_boundary_conditions!(field, field_type::FieldType)

Reset/clear boundary conditions for a field.

set_programmatic_composition_boundaries!(comp_field, inner_spec::Tuple, outer_spec::Tuple)

Set programmatic composition boundary conditions.

set_programmatic_magnetic_boundaries!(magnetic_field, inner_spec::Tuple, outer_spec::Tuple)

Set programmatic magnetic boundary conditions.

set_programmatic_temperature_boundaries!(temp_field, inner_spec::Tuple, outer_spec::Tuple)

Set programmatic temperature boundary conditions.

set_programmatic_velocity_boundaries!(velocity_field, inner_spec::Tuple, outer_spec::Tuple)

Set programmatic velocity boundary conditions.

shtns_physical_to_spectral(physical_data::Matrix{T}, config) where T

Transform physical boundary data to spectral coefficients using SHTnsKit. This is a common utility function used by both thermal and composition modules.

smooth_boundary_data(boundary_data::BoundaryData, smoothing_radius::Real)

Apply spatial smoothing to boundary data.

spherical_harmonic(l::Int, m::Int, theta::Real, phi::Real)

Compute spherical harmonic Y_l^m(θ, φ).

spherical_harmonic_phi_derivative(l::Int, m::Int, theta::Real, phi::Real)

Compute ∂Y_l^m/∂φ.

spherical_harmonic_theta_derivative(l::Int, m::Int, theta::Real, phi::Real)

Compute ∂Y_l^m/∂θ.

update_boundary_conditions_for_timestep!(state, current_time::Float64)

Update all boundary conditions for the current timestep.

This function should be called at the beginning of each timestep to ensure all fields have up-to-date boundary conditions.

update_composition_time_index!(comp_field, time_index::Int)

Update time index in field or fallback cache.

update_temperature_time_index!(temp_field, time_index::Int)

Update time index in field or fallback cache.

update_time_dependent_boundaries!(field, field_type::FieldType, current_time::Float64)

Update time-dependent boundary conditions for any field type.

update_time_dependent_composition_boundaries!(comp_field, current_time::Float64)

Update time-dependent composition boundary conditions.

update_time_dependent_magnetic_boundaries!(magnetic_field, current_time::Float64)

Update time-dependent magnetic boundary conditions.

update_time_dependent_temperature_boundaries!(temp_field, current_time::Float64)

Update time-dependent temperature boundary conditions.

update_time_dependent_velocity_boundaries!(velocity_field, current_time::Float64)

Update time-dependent velocity boundary conditions.

validate_boundary_compatibility(inner::BoundaryData, outer::BoundaryData, field_name::String)

Validate that inner and outer boundary data are compatible.

validate_boundary_files(field_type::FieldType, boundary_specs::Dict, config)

Validate boundary condition files for any field type.

validate_composition_boundary_files(boundary_specs::Dict, config)

Validate composition boundary condition files.

validate_composition_range(boundary_data::BoundaryData)

Validate that composition values are in the physical range [0, 1].

validate_field_boundary_compatibility(field, field_type::FieldType, boundary_set::BoundaryConditionSet)

Validate that a field structure is compatible with boundary conditions.

validate_interpolation_grids(src_theta::Vector, src_phi::Vector, 
                            tgt_theta::Vector, tgt_phi::Vector)

Validate that source and target grids are compatible for interpolation.

validate_magnetic_boundary_files(boundary_specs::Dict, config)

Validate magnetic field boundary condition files.

validate_netcdf_boundary_file(filename::String, required_vars::Vector{String}=[])

Validate that a NetCDF boundary condition file has the required structure.

validate_temperature_boundary_files(boundary_specs::Dict, config)

Validate temperature boundary condition files.

validate_temperature_range(boundary_data::BoundaryData)

Validate that temperature values are in a reasonable physical range.

validate_velocity_boundary_files(boundary_specs::Dict, config)

Validate velocity boundary condition files.

velocity_to_qst_coefficients(v_r, v_theta, v_phi, config)

Convert physical velocity components (vr, vθ, v_φ) to QST spectral coefficients by using proper SHTnsKit decomposition.

The QST decomposition used by SHTnsKit:

• Q: Radial component coefficients (transforms like scalar field)
• S: Spheroidal horizontal component coefficients (curl-free part)
• T: Toroidal horizontal component coefficients (divergence-free part)

Arguments

• v_r: Radial velocity component [nlat, nlon]
• v_theta: Colatitude velocity component [nlat, nlon]
• v_phi: Azimuthal velocity component [nlat, nlon]
• config: SHTnsKit configuration

Returns

• (Q_coeffs, S_coeffs, T_coeffs): QST spectral coefficients

write_netcdf_boundary_data(filename::String, boundary_data::BoundaryData)

Write boundary condition data to a NetCDF file.

InitialConditions

Module for loading and generating initial conditions for geodynamo simulations. Supports loading from NetCDF files, generating random fields, and setting prescribed analytical patterns.

generate_random_composition!(comp_field, amplitude, modes_range)

Generate random composition initial conditions.

generate_random_initial_conditions!(field, field_type::Symbol;
                                   amplitude=1.0, modes_range=1:10,
                                   seed=nothing)

Generate random initial conditions for any field type.

Arguments

• field: Field structure to initialize
• field_type: Type of field (:temperature, :magnetic, :velocity, :composition)
• amplitude: Overall amplitude of random perturbations
• modes_range: Range of spherical harmonic modes to excite
• seed: Random seed for reproducibility (optional)

Examples

# Random temperature field
generate_random_initial_conditions!(temp_field, :temperature, amplitude=0.1)

# Random magnetic field with specific modes
generate_random_initial_conditions!(mag_field, :magnetic,
                                   amplitude=0.01, modes_range=1:20, seed=42)

generate_random_magnetic!(mag_field, amplitude, modes_range)

Generate random magnetic initial conditions.

generate_random_temperature!(temp_field, amplitude, modes_range)

Generate random temperature initial conditions.

generate_random_velocity!(vel_field, amplitude, modes_range)

Generate random velocity initial conditions.

load_composition_initial_conditions!(comp_field, file_path::String)

Load composition initial conditions from NetCDF file.

load_initial_conditions!(field, field_type::Symbol, file_path::String)

Load initial conditions from NetCDF file for any field type.

Arguments

• field: Field structure (temperature, magnetic, velocity, or composition type)
• field_type: Field type (:temperature, :magnetic, :velocity, :composition)
• file_path: Path to NetCDF file containing initial conditions

File Format

NetCDF files should contain:

• For scalar fields: spectral coefficients array
• For vector fields: toroidal and poloidal spectral coefficients
• Coordinate arrays: lm indices, radial grid

load_magnetic_initial_conditions!(mag_field, file_path::String)

Load magnetic initial conditions from NetCDF file.

load_temperature_initial_conditions!(temp_field, file_path::String)

Load temperature initial conditions from NetCDF file.

load_velocity_initial_conditions!(vel_field, file_path::String)

Load velocity initial conditions from NetCDF file.

randomize_magnetic_field!(field; amplitude, lmax, domain=nothing)

Populate magnetic toroidal/poloidal fields with random perturbations.

randomize_scalar_field!(field; amplitude, lmax, domain=nothing)

Populate a scalar spectral field (temperature/composition) with random perturbations up to degree lmax. If a radial domain is provided and includes r=0, ball regularity is enforced.

randomize_vector_field!(field; amplitude, lmax, domain=nothing)

Populate velocity-like toroidal/poloidal fields with random perturbations up to degree lmax.

save_initial_conditions(field, field_type::Symbol, file_path::String)

Save current field state as initial conditions to NetCDF file.

This function is useful for saving generated or computed initial conditions for later use in simulations.

set_analytical_composition!(comp_field, pattern, amplitude; parameters...)

Set analytical composition patterns.

set_analytical_initial_conditions!(field, field_type::Symbol, pattern::Symbol;
                                  amplitude=1.0, parameters...)

Set analytical initial conditions based on predefined patterns.

Patterns

• :conductive - Conductive temperature profile
• :dipole - Dipolar magnetic field
• :convective - Small convective velocity pattern
• :stratified - Stratified composition profile

Examples

# Conductive temperature profile
set_analytical_initial_conditions!(temp_field, :temperature, :conductive)

# Earth-like dipolar magnetic field
set_analytical_initial_conditions!(mag_field, :magnetic, :dipole, amplitude=1.0)

set_analytical_magnetic!(mag_field, pattern, amplitude; parameters...)

Set analytical magnetic field patterns.

set_analytical_temperature!(temp_field, pattern, amplitude; parameters...)

Set analytical temperature patterns.

set_analytical_velocity!(vel_field, pattern, amplitude; parameters...)

Set analytical velocity patterns.

apply_shell_composition_boundaries!(comp_field, boundary_set; time=0)

apply_shell_temperature_boundaries!(temp_field, boundary_set; time=0)

Wrapper around core boundary application for shell geometry.

create_shell_composition_field(T, cfg::ShellConfig; nr=Geodynamo.i_N)

create_shell_hybrid_composition_boundaries(inner_spec, outer_spec, cfg::ShellConfig; precision=Float64)

Create composition boundaries for shell geometry. Dispatches to appropriate function based on spec types:

• Both Tuple: fully programmatic boundaries
• String + Tuple: hybrid (one from file, one programmatic)
• Both String: both from files

create_shell_hybrid_temperature_boundaries(inner_spec, outer_spec, cfg::ShellConfig; precision=Float64)

Create temperature boundaries for shell geometry. Dispatches to appropriate function based on spec types:

• Both Tuple: fully programmatic boundaries
• String + Tuple: hybrid (one from file, one programmatic)
• Both String: both from files

create_shell_magnetic_fields(T, cfg::ShellConfig; nr_oc=Geodynamo.i_N, nr_ic=Geodynamo.i_Nic)

create_shell_pencils(cfg::ShellConfig; optimize=true)

Create a shell-oriented pencil decomposition using the core topology helper.

create_shell_physical_field(T, cfg::ShellConfig, domain::Geodynamo.RadialDomain, pencil)

create_shell_radial_domain(nr=i_N) -> RadialDomain

Create a radial domain suitable for a spherical shell using the global parameter d_rratio for inner radius ratio. This is a thin wrapper over Geodynamo.create_radial_domain.

create_shell_spectral_field(T, cfg::ShellConfig, domain::Geodynamo.RadialDomain, pencil)

create_shell_temperature_field(T, cfg::ShellConfig; nr=Geodynamo.i_N)

create_shell_vector_field(T, cfg::ShellConfig, domain::Geodynamo.RadialDomain, pencils)

create_shell_velocity_fields(T, cfg::ShellConfig; nr=Geodynamo.i_N)

apply_ball_composition_regularity!(comp_field)

apply_ball_temperature_regularity!(temp_field)

Convenience to enforce scalar regularity on the temperature spectral field. Call after assembling or updating temp_field.spectral.

ball_physical_to_spectral!(phys::Geodynamo.SHTnsPhysicalField,
                           spec::Geodynamo.SHTnsSpectralField)

Wrapper for transforms in a solid sphere that enforces scalar regularity at r=0 after analysis. Use this for scalar fields (temperature, composition, etc.).

ball_vector_analysis!(vec::Geodynamo.SHTnsVectorField,
                      tor::Geodynamo.SHTnsSpectralField,
                      pol::Geodynamo.SHTnsSpectralField)

Wrapper for vector analysis in a solid sphere; enforces vector regularity at r=0 after transforming to spectral toroidal/poloidal.

create_ball_composition_field(T, cfg::BallConfig; nr=Geodynamo.i_N)

create_ball_hybrid_composition_boundaries(inner_spec, outer_spec, cfg::BallConfig; precision=Float64)

create_ball_hybrid_temperature_boundaries(inner_spec, outer_spec, cfg::BallConfig; precision=Float64)

create_ball_magnetic_fields(T, cfg::BallConfig; nr=Geodynamo.i_N)

Create magnetic fields for a solid sphere. Since a "core" split is not used in a ball, we pass the same domain for both oc and ic to reuse the core implementation.

create_ball_pencils(cfg::BallConfig; optimize=true)

create_ball_physical_field(T, cfg::BallConfig, domain::Geodynamo.RadialDomain, pencil)

create_ball_radial_domain(nr=i_N) -> RadialDomain

Create a radial domain for a solid sphere (inner radius = 0). Uses a cosine-stretched grid similar to the shell for compatibility, but sets the inner radius to zero and adjusts the coordinate columns to match expectations of downstream operators.

create_ball_spectral_field(T, cfg::BallConfig, domain::Geodynamo.RadialDomain, pencil)

create_ball_temperature_field(T, cfg::BallConfig; nr=Geodynamo.i_N)

create_ball_vector_field(T, cfg::BallConfig, domain::Geodynamo.RadialDomain, pencils)

create_ball_velocity_fields(T, cfg::BallConfig; nr=Geodynamo.i_N)

enforce_ball_scalar_regularity!(spec::Geodynamo.SHTnsSpectralField)

Enforce scalar regularity at r=0 for solid sphere: for l>0, the scalar amplitude must vanish at r=0. Sets inner radial plane to zero for all nonzero l modes (both real and imaginary parts).

enforce_ball_vector_regularity!(tor_spec::Geodynamo.SHTnsSpectralField,
                                pol_spec::Geodynamo.SHTnsSpectralField)

Enforce vector-field regularity at r=0 for solid sphere. For smooth fields, both toroidal and poloidal potentials behave like r^{l+1}, so they vanish at r=0 for all l ≥ 1. Zeros the inner radial plane for l≥1.