GitHub

Initial Conditions

Looking for the how-to guide?

This page is the auto-generated reference for the internal InitialConditions module. For setting up initial conditions with the public API (set!, RandomPerturbation, AnalyticIC, direct values), see the Initial Conditions guide.

The InitialConditions module provides the low-level helpers behind the public IC API.

At a Glance

GeoDynamo.InitialConditions
├── Scalar Fields
│   ├── set_temperature_ic!
│   ├── set_composition_ic!
│   └── randomize_scalar_field!
│
├── Vector Fields
│   └── randomize_vector_field!
│
├── Magnetic Field
│   └── randomize_magnetic_field!
│
└── File I/O
    ├── load_initial_conditions!
    └── save_initial_conditions
Usage (public API)
grid = SphericalShellGrid(nr = 64, lmax = 31)
model = GeodynamoModel(grid; include_magnetic = true)

set!(model;
     temperature = AnalyticIC(:conductive),
     magnetic    = RandomPerturbation(amplitude = 1e-5, lmax = 8))

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

Initial Condition API

GeoDynamo.InitialConditions.load_initial_conditions! — Function
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
source
GeoDynamo.InitialConditions.generate_random_initial_conditions! — Function
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)
source
GeoDynamo.InitialConditions.set_analytical_initial_conditions! — Function
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)
source
GeoDynamo.InitialConditions.save_initial_conditions — Function
save_initial_conditions(field, field_type::Symbol, file_path::String)

Save a field's spectral coefficients to an IC NetCDF file that load_initial_conditions! can read back.

The file stores dense (spectral_mode, r) real/imag matrices per component (one for scalars, toroidal + poloidal for vectors) plus a field_type attribute used to validate the field on load. All ranks participate in the gather; rank 0 writes the file.

source
GeoDynamo.InitialConditions.randomize_scalar_field! — Function
randomize_scalar_field!(field; amplitude, lmax, domain=nothing)

Superimpose random spectral perturbations up to degree lmax ONTO a scalar spectral field (temperature/composition). The perturbation is added to the field's existing content (no clearing first), so a previously set base state — e.g. a set!(:conductive) mean gradient — is preserved.

domain is accepted for API symmetry but currently unused.

source
GeoDynamo.InitialConditions.randomize_vector_field! — Function
randomize_vector_field!(field; amplitude, lmax, domain=nothing)

Superimpose random perturbations up to degree lmax ONTO velocity-like toroidal/poloidal fields. The perturbation is added to the existing spectral content (no clearing first), so a prior base state is preserved.

domain is accepted for API symmetry but currently unused.

source
GeoDynamo.InitialConditions.randomize_magnetic_field! — Function
randomize_magnetic_field!(field; amplitude, lmax, domain=nothing)

Superimpose random perturbations ONTO magnetic toroidal/poloidal fields. The perturbation is added to the existing spectral content (no clearing first), so a prior base state is preserved.

domain is accepted for API symmetry but currently unused.

source
GeoDynamo.InitialConditions — Module
InitialConditions

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

source
GeoDynamo.InitialConditions.set_analytical_magnetic! — Method
set_analytical_magnetic!(mag_field, pattern, amplitude; domain=nothing, parameters...)

Set analytical magnetic field patterns (:dipole, :uniform_field).

For :uniform_field, pass direction = :z (default, axial) or direction = :x. domain (the radial grid) lets the uniform profile be built against the PHYSICAL radius so the synthesized field is exactly uniform; without it the profile uses the normalized radial coordinate and is only approximately uniform.

Uses PencilArray structure with datareal/dataimag arrays.

source