TERRA

Initialize the TERRA API system.

Arguments

• case_path::String: Path to directory containing input/ subdirectory (default: current directory)

Returns

• NamedTuple: Contains num_species and num_dimensions as determined by TERRA from input files

Throws

• ErrorException: If case_path doesn't exist, input file is missing, or Fortran call fails

Runtime and I/O configuration controls.

Abstract root for axial chain handoff policies.

Abstract root for axial chain termination policies.

Typed presentation policy for 0D integration logging and console routing.

Compact API layout information for the Fortran rhs_api / calculate_rhs_api state vectors.

This describes the compact ordering used internally by TERRA: [rho_vib_states, rho_elec_states, rho_species, rho_u..., rho_etot, rho_eeex?, rho_erot?, rho_evib?].

Normalized axial chain profile used by the TERRA chain-of-CSTR interface.

Fields

• z_m::Vector{Float64}: Axial coordinate points (m), strictly increasing
• dx_m::Vector{Float64}: Point-aligned control-volume lengths (m), strictly positive
• te_K::Vector{Float64}: Electron temperature profile (K), strictly positive
• species_u_m_s::Dict{String, Vector{Float64}}: Per-species convective velocities (m/s), strictly positive
• wall_profile::Union{Nothing, ChainWallProfile}: Optional validated wall-profile inputs for wall-loss source terms
• inlet::ChainProfileInlet: Self-contained segment-1 inlet state
• diagnostics::Dict{String, Vector{Float64}}: Optional diagnostics arrays
• generator::Dict{String, Any}: Generator metadata from interchange artifact
• selection::Dict{String, Any}: Selection metadata from interchange artifact
• schema_version::String: Interchange schema version
• source_snapshot::Union{Nothing, Dict{String, Any}}: Optional source provenance snapshot

Controls for the axial-marching chain-of-CSTR solver.

Fields

• handoff_policy::AbstractChainHandoffPolicy: Segment handoff behavior
• termination_policy::AbstractChainTerminationPolicy: Segment termination behavior
• override_tt_K::Union{Nothing, Float64}: Optional translational temperature override (K)
• override_tv_K::Union{Nothing, Float64}: Optional vibrational temperature override (K)
• is_isothermal_teex::Bool: Whether chain segments enforce the profile Te(x) isothermally

Neutral wall-loss closure using a ballistic sticking rate.

Filesystem layout for a prepared TERRA case directory.

Per-cell chain result, including cell-aligned profile inputs and reactor time history.

Metadata for chain-level result organization and segmentation provenance.

Self-contained inlet state used to initialize segment 1 of the chain solver.

Composition payload for the self-contained chain-profile inlet.

Results container for axial-marching chain-of-CSTR simulations.

Fields

• cells::Vector{ChainCellResult}: Solved chain cells (compact retained indexing)
• metadata::ChainMetadata: Chain-level metadata, diagnostics, and index mapping
• success::Bool: Overall chain success flag
• failed_cell::Union{Nothing, Int}: First failing retained-cell index, if any
• message::String: Overall status message

Normalized wall-geometry/profile inputs for chain-driven wall losses.

Top-level configuration for refactored TERRA workflows.

Neutral wall-loss closure using a constant rate.

Integrate each chain segment to the configured final integration time.

Reuse the prior segment state when initializing downstream chain cells.

Ion wall-loss closure using a Bohm-gap style rate.

Logging policy controls for terminal and file-backed runtime diagnostics.

Physics/process model configuration.

Apply the native TERRA ramp limiter update to the integrator.

Solver and discretization controls for the wrapper runtime.

ODE-solver controls managed by the Julia wrapper.

Physics modeling configuration for TERRA simulation.

Fields

• bbh_model::Int: Bound-bound heavy particle model
• esc_model::Int: Escape model
• ar_et_model::Int: Ar-ET model
• eex_noneq::Int: Electron-electronic nonequilibrium flag
• ev_relax_set::Int: Electron-vibrational relaxation set
• et_relax_set::Int: Electron-translational relaxation set
• radiation_length::Float64: Radiation length scale (cm)
• get_electron_density_by_charge_balance::Bool: Electron density by charge balance
• min_sts_frac::Float64: Minimum state-to-state fraction
• is_isothermal_teex::Bool: Isothermal electron-electronic flag
• energy_loss_per_eii::Float64: Average electron energy loss per EII event (× E_ion)

Process flags configuration for TERRA simulation.

Fields

• consider_elec_bbe::Int: Consider electron bound-bound excitation
• consider_elec_bfe::Int: Consider electron bound-free excitation
• consider_elec_bbh::Int: Consider electron bound-bound heavy
• consider_elec_bfh::Int: Consider electron bound-free heavy
• consider_rad::Int: Consider radiation
• consider_rdr::Int: Consider RDR
• consider_chem::Int: Consider chemistry

Combined reactor-state configuration.

Time-frame result for a single reactor solve.

Fields

• t::Float64: Frame timestamp
• species_densities::Vector{Float64}: Species mass densities at this frame
• temperatures::NamedTuple: Temperature state at this frame
• total_energy::Float64: Total energy density at this frame
• source_terms::Union{NamedTuple, Nothing}: Optional source-term snapshot
• diagnostics::Dict{String, Any}: Optional frame-level diagnostics

Concrete 0D initial state prepared from Config and the active TERRA API.

Time-history container for one reactor (one chain cell).

Fields

• t::Vector{Float64}: Saved times
• frames::Vector{ReactorFrame}: Saved per-time reactor frames
• success::Bool: Reactor success flag
• message::String: Reactor status message
• source_terms::Union{NamedTuple, Nothing}: Optional source history payload
• metadata::Dict{String, Any}: Optional reactor metadata

Notes

• Supports HallThruster-like slicing: reactor[i] returns a one-frame ReactorResult.

Compact cache of a reactor end state used for downstream initialization.

Thermal state for the reactor.

Fields

• Tt::Float64: Translational temperature (K)
• Tv::Float64: Vibrational temperature (K)
• Tee::Float64: Electron-electronic temperature (K)
• Te::Float64: Electron temperature (K)

Reinitialize each chain cell from the profile/inlet state without state-cache handoff.

Residence-time (CSTR / flow-through) model controls.

Runtime controls for TERRA wrapper execution.

Wrapper-managed additive source-term configuration.

Spatial-discretization metadata.

Abstract root for per-species wall-interaction closures.

Placeholder policy for future steady-state chain termination support.

Numerical time-integration controls.

Fields

• dt::Float64: Time step (seconds)
• dt_output::Float64: Native-output time step (seconds)
• duration::Float64: Final time (seconds)
• nstep::Int: Maximum number of time steps
• method::Int: Integration method (0=forward Euler, 1=high order explicit, 2=implicit)

Wrapper-managed wall-loss configuration.

_nitrogen_10ev_database_path()

Create a default configuration for the 0D Nitrogen Te=10eV example.

_solve_terra_0d_internal(
    config;
    sources,
    wall_inputs,
    state_cache,
    presentation
)

Solve a 0D TERRA simulation.

_validated_species_composition(
    species,
    mole_fractions,
    total_number_density;
    context,
    density_field
)

Reactor composition inputs for a simulation case.

Fields

• species::Vector{String}: Species names
• mole_fractions::Vector{Float64}: Species mole fractions (must sum to 1)
• total_number_density::Float64: Total number density

calculate_electron_electronic_energy_wrapper(
    teex,
    tvib,
    rho_sp
)

Calculate electron-electronic energy from state variables.

Arguments

• teex::Float64: Electron-electronic temperature (K)
• tvib::Float64: Vibrational temperature (K)
• rho_sp::Vector{Float64}: Species densities (mass/volume)

Returns

• Float64: Electron-electronic energy density

Throws

• ErrorException: If TERRA library is not loaded or not initialized
• ArgumentError: If teex ≤ 0, tvib ≤ 0, or arrays are invalid

calculate_rhs_api_isothermal_teex_wrapper!(
    du,
    u,
    teex_const;
    tex
)

Compute du = rhs_api(u) for a u vector in isothermal Teex mode, using the rhs_api layout.

This calls the Fortran API routine calculate_rhs_api_isothermal_teex, which expects:

• Ordering from get_api_layout_wrapper()
• u[idx_etot] stores the legacy enthalpy remainder rho_rem
• u[idx_eeex] is treated as a dummy; du[idx_eeex] is forced to zero

Optional inputs:

• tex: per-species electronic temperatures passed to the Tvib inversion (length nsp)

calculate_rhs_api_wrapper!(dy, y)

Compute dy = rhs_api(y) for a y vector using the rhs_api layout.

y and dy must use the ordering returned by get_api_layout_wrapper().

calculate_sources_wrapper(
    rho_sp,
    rho_etot;
    rho_ex,
    rho_vx,
    rho_u,
    rho_v,
    rho_w,
    rho_erot,
    rho_eeex,
    rho_evib
)

Calculate nonequilibrium source terms.

Arguments

• rho_sp::Vector{Float64}: Species densities (mass/volume)
• rho_etot::Float64: Total energy density
• rho_ex::Matrix{Float64}: Electronic state densities (optional)
• rho_vx::Array{Float64,3}: Vibrational state densities (optional)
• rho_erot::Float64: Rotational energy density (optional)
• rho_eeex::Float64: Electron-electronic energy density (optional)
• rho_evib::Float64: Vibrational energy density (optional)

Returns

• Tuple of derivative arrays corresponding to input arrays

Throws

• ErrorException: If TERRA library is not loaded or not initialized

calculate_temperatures_wrapper(
    rho_sp,
    rho_etot;
    rho_ex,
    rho_vx,
    rho_u,
    rho_v,
    rho_w,
    rho_erot,
    rho_eeex,
    rho_evib
)

Calculate temperatures from thermodynamic state.

Arguments

• rho_sp::Vector{Float64}: Species densities
• rho_etot::Float64: Total energy density
• Additional optional energy components

Returns

• Named tuple with temperatures (tt, trot, teex, tvib, tex, tvx)

Throws

• ErrorException: If TERRA library is not loaded or not initialized

calculate_total_energy_wrapper(
    tt,
    rho_sp;
    rho_ex,
    rho_vx,
    u,
    v,
    w,
    rho_erot,
    rho_eeex,
    rho_evib
)

Calculate total energy from state variables.

Arguments

• tt::Float64: Translational temperature (K)
• rho_sp::Vector{Float64}: Species densities (mass/volume)
• rho_ex::Matrix{Float64}: Electronic state densities (optional)
• rho_vx::Array{Float64,3}: Vibrational state densities (optional)
• u::Float64: x-velocity component (optional)
• v::Float64: y-velocity component (optional)
• w::Float64: z-velocity component (optional)
• rho_erot::Float64: Rotational energy density (optional)
• rho_eeex::Float64: Electron-electronic energy density (optional)
• rho_evib::Float64: Vibrational energy density (optional)

Returns

• Float64: Total energy density

Throws

• ErrorException: If TERRA library is not loaded or not initialized

calculate_vibrational_energy_wrapper(
    tvib,
    rho_sp;
    rho_ex,
    tex,
    teex
)

Calculate vibrational energy from state variables.

Arguments

• tvib::Float64: Vibrational temperature (K)
• rho_sp::Vector{Float64}: Species densities (mass/volume)
• rho_ex::Matrix{Float64}: Electronic state densities (optional)
• tex::Vector{Float64}: Electronic temperatures per species (optional)
• teex::Float64: Electron-electronic temperature (optional)

Returns

• Float64: Vibrational energy density

Throws

• ErrorException: If TERRA library is not loaded or not initialized

calculate_vibrational_temperature_wrapper(
    rho_evib,
    rho_sp;
    rho_ex,
    tex
)

Calculate vibrational temperature from vibrational energy density and species densities.

Arguments

• rho_evib::Float64: Vibrational energy density (erg/cm^3)
• rho_sp::Vector{Float64}: Species mass densities (g/cm^3)
• rho_ex::Union{Matrix{Float64}, Nothing}: Optional electronic state densities (layout: mnex × nsp)
• tex::Union{Vector{Float64}, Nothing}: Optional species electronic temperatures (K)

Returns

• Float64: Vibrational temperature (K)

Throws

• ErrorException: If TERRA library is not loaded or not initialized
• ArgumentError: If inputs are invalid or dimensions exceed library maxima

close_api_output_files_wrapper()

Close the native TERRA output files opened through the API wrappers.

close_terra_library()

Close the TERRA library and free resources.

compute_mixture_pressure(
    rho_sp,
    gas_constants,
    species_names,
    molecular_weights,
    tt,
    te
)

Compute the mixture pressure using translational and electron temperatures.

config_to_initial_state(config; state_cache)

Convert nested Config to a reactor-owned initial state in CGS units.

convert_config_units(config, target_unit_system)

Convert nested Config units if needed.

Arguments

• config::Config: Configuration to convert
• target_unit_system::Symbol: Target unit system (:SI or :CGS)

Returns

• Config: Configuration with converted units

convert_density_cgs_to_si(rho_cgs)

Convert species densities from CGS (g/cm³) to SI (kg/m³) units.

convert_density_si_to_cgs(rho_si)

Convert species densities from SI (kg/m³) to CGS (g/cm³) units.

convert_energy_density_cgs_to_si(energy_cgs)

Convert energy density from CGS (erg/cm³) to SI (J/m³) units.

convert_energy_density_si_to_cgs(energy_si)

Convert energy density from SI (J/m³) to CGS (erg/cm³) units.

convert_number_density_cgs_to_si(n_cgs)

Convert number density from CGS (1/cm³) to SI (1/m³) units.

convert_number_density_si_to_cgs(n_si)

Convert number density from SI (1/m³) to CGS (1/cm³) units.

convert_pressure_cgs_to_si(pressure_cgs)

Convert pressure from CGS (dyne/cm²) to SI (Pa) units.

convert_pressure_si_to_cgs(pressure_si)

Convert pressure from SI (Pa) to CGS (dyne/cm²) units.

convert_sources_cgs_to_si(
    drho_sp_cgs,
    drho_etot_cgs;
    drho_erot_cgs,
    drho_eeex_cgs,
    drho_evib_cgs
)

Convert source terms from CGS to SI units.

Arguments

• drho_sp_cgs::Vector{Float64}: Species source terms in CGS units (g/cm³/s)
• drho_etot_cgs::Float64: Energy source term in CGS units (erg/cm³/s)
• Additional optional source terms in CGS units

Returns

• Named tuple with all source terms converted to SI units

convert_state_cgs_to_si(
    rho_sp_cgs,
    rho_etot_cgs;
    rho_erot_cgs,
    rho_eeex_cgs,
    rho_evib_cgs
)

Convert a complete state vector from CGS to SI units from TERRA output.

Arguments

• rho_sp_cgs::Vector{Float64}: Species densities in CGS units (g/cm³)
• rho_etot_cgs::Float64: Total energy density in CGS units (erg/cm³)
• Additional optional energy components in CGS units

Returns

• Named tuple with all quantities converted to SI units

convert_state_si_to_cgs(
    rho_sp_si,
    rho_etot_si,
    number_density_si;
    rho_erot_si,
    rho_eeex_si,
    rho_evib_si
)

Convert a complete state vector from SI to CGS units for TERRA input.

Arguments

• rho_sp_si::Vector{Float64}: Species densities in SI units (kg/m³)
• rho_etot_si::Float64: Total energy density in SI units (J/m³)
• number_density_si::Float64: Total number density in SI units (1/m³)
• Additional optional energy components in SI units

Returns

• Named tuple with all quantities converted to CGS units

create_species_mapping(ht_species, terra_species)

Create species mapping between HallThruster.jl and TERRA conventions.

Arguments

• ht_species::Vector{String}: Species names in HallThruster.jl format
• terra_species::Vector{String}: Species names in TERRA format

Returns

• Dictionary mapping HallThruster.jl species names to TERRA species names

energy_from_enthalpy_isothermal_teex_wrapper(
    rho_enth,
    rho_sp,
    teex_const;
    rho_ex,
    rho_erot,
    rho_eeex,
    rho_evib
)

Convert total enthalpy density to total energy density for 0D isothermal Teex cases.

This calls the Fortran API routine energy_from_enthalpy_isothermal_teex_api, which performs the closed-form enthalpy→energy inversion used by the isothermal Teex API RHS.

Returns

• Named tuple with rho_etot, pressure, and tt (all CGS units; tt in K).

enthalpy_from_energy(
    rho_etot,
    rho_sp,
    gas_constants,
    species_names,
    molecular_weights,
    tt,
    te
)

Convert total energy density into enthalpy density using the ideal-gas closure.

finalize_api_wrapper()

Finalize the TERRA API system and clean up resources.

finalize_terra()

Finalize the TERRA system and clean up resources.

This function should be called when TERRA is no longer needed to properly clean up memory and resources.

Returns

• Nothing

generate_input_files(config)
generate_input_files(config, case_path)

Generate TERRA input files from configuration with the prepared case layout.

This function creates the directory structure required by the Fortran wrapper:

• case_path/input/
• case_path/output/
• case_path/output/sources/
• case_path/output/states/

Arguments

• config::Config: TERRA configuration
• case_path::String: Case directory path (default: config.runtime.case_path)

Returns

• true if files generated successfully

get_api_layout()

Query the Fortran API for the current y/dy layout.

get_api_layout_wrapper()

Get the API layout for the y/dy vectors used by the Fortran rhs_api.

This calls the Fortran get_api_layout() routine and returns sizes, flags, and species/state metadata needed to construct an ODE state in the rhs_api ordering on the Julia side.

get_max_number_of_atomic_electronic_states_wrapper()

Get the maximum number of electronic states per atomic species supported by TERRA.

Returns

• Int32: Maximum number of atomic electronic states

Throws

• ErrorException: If TERRA library is not loaded

get_max_number_of_molecular_electronic_states_wrapper()

Get the maximum number of electronic states per molecular species supported by TERRA.

Returns

• Int32: Maximum number of molecular electronic states

Throws

• ErrorException: If TERRA library is not loaded

get_max_number_of_species_wrapper()

Get the maximum number of species supported by TERRA.

Returns

• Int32: Maximum number of species

Throws

• ErrorException: If TERRA library is not loaded

get_max_vibrational_quantum_number_wrapper()

Get the maximum vibrational quantum number supported by TERRA.

Returns

• Int32: Maximum vibrational quantum number (mnv from Fortran parameters)

Throws

• ErrorException: If TERRA library is not loaded

get_molecular_weights(species)

Get molecular weights for common species (g/mol).

Arguments

• species::Vector{String}: Species names

Returns

• Vector{Float64}: Molecular weights in g/mol

get_number_of_active_species_wrapper()

Get the active number of species (nsp) from TERRA.

Returns

• Int32: Active species count

get_number_of_dimensions_wrapper()

Get the number of spatial dimensions (nd) from TERRA.

Returns

• Int32: Number of spatial dimensions

get_runtime_flags()

Get runtime setup flags from TERRA (for verification).

get_species_gas_constants_wrapper()

Retrieve per-species gas constants from TERRA.

Values are returned in CGS units (erg/(g·K)) to maintain consistency with the rest of the wrapper.

get_species_names_wrapper()

Get species names from TERRA.

Returns

• Vector{String}: Array of species names

Throws

• ErrorException: If TERRA library is not loaded

get_terra_lib_path()

Get the path to the loaded TERRA library.

Returns

• String: Path to the loaded library

Throws

• ErrorException: If no library is loaded

has_electronic_sts_wrapper()

Report whether the current TERRA setup includes electronic state-to-state data.

has_vibrational_sts_wrapper()

Report whether the current TERRA setup includes vibrational state-to-state data.

initialize_terra(config; ...)
initialize_terra(
    config,
    case_path;
    lifecycle_console,
    preserve_active_runtime
)

Initialize the TERRA system.

This function must be called before any TERRA calculations can be performed. It sets up the Fortran library, initializes internal data structures, and prepares the system for simulation. The TERRA shared library is obtained from the TERRA_LIB_PATH environment variable when it is not already loaded.

Arguments

• config::Config: Configuration for initialization
• case_path::String: Case directory path (optional, defaults to config.runtime.case_path)

Returns

• true if initialization successful

Throws

• ErrorException if initialization fails

is_api_initialized_wrapper()

Return whether the TERRA Fortran API reports itself initialized.

Returns

• Bool: True if Fortran side is initialized, false otherwise

is_terra_initialized()

Check if TERRA is properly initialized.

Returns

• true if TERRA is initialized and ready for use

is_terra_loaded()

Check if the TERRA library is currently loaded.

Returns

• Bool: True if library is loaded, false otherwise

load_chain_profile(path)

Load a chain profile JSON artifact into normalized AxialChainProfile.

Arguments

• path::AbstractString: Path to chain_profile_v4.json

Returns

• AxialChainProfile

Throws

• ArgumentError on file, schema, or data validation failures

load_results_chain(filename)

Load chain simulation results from a JSON file generated by save_results.

Arguments

• filename::String: Input JSON filename

Returns

• ChainSimulationResult

load_terra_library!(path)

Set the path to the TERRA shared library and load it.

Arguments

• path::String: Path to the TERRA shared library file

Throws

• ErrorException: If the library cannot be loaded

load_terra_library!()

Load the TERRA shared library using the TERRA_LIB_PATH environment variable.

Throws an error if the environment variable is not set or does not point to an existing file.

mass_densities_to_mole_fractions(
    mass_densities,
    molecular_weights
)

Convert mass densities to mole fractions.

Arguments

• mass_densities::Vector{Float64}: Species mass densities (g/cm³)
• molecular_weights::Vector{Float64}: Species molecular weights (g/mol)

Returns

• Vector of mole fractions

mole_fractions_to_mass_densities(
    mole_fractions,
    molecular_weights,
    total_number_density
)

Convert mole fractions to mass densities.

Arguments

• mole_fractions::Vector{Float64}: Species mole fractions
• molecular_weights::Vector{Float64}: Species molecular weights (g/mol)
• total_number_density::Float64: Total number density (1/cm³)

Returns

• Vector of mass densities (g/cm³)

native_ramp_callback(
    initial_dt;
    understep_ratio,
    history_steps
)

Create the native TERRA step-size ramp callback.

nitrogen_10ev_example(; ...)
nitrogen_10ev_example(case_path; isothermal)

Run the 0D Nitrogen Te=10eV example case.

open_api_output_files_wrapper()

Open native TERRA Tecplot-style output files for the current API session.

Requires a successful call to initialize_api_wrapper so the case path is tracked.

pack_state_vector!(
    y,
    layout,
    rho_sp,
    rho_etot;
    rho_ex,
    rho_vx,
    rho_u,
    rho_v,
    rho_w,
    rho_erot,
    rho_eeex,
    rho_evib
)

In-place variant of pack_state_vector.

pack_state_vector(
    layout,
    rho_sp,
    rho_etot;
    rho_ex,
    rho_vx,
    rho_u,
    rho_v,
    rho_w,
    rho_erot,
    rho_eeex,
    rho_evib
)

Pack state components into the y vector ordering used by Fortran rhs_api.

resolve_terra_library_path()

Resolve the TERRA shared library path from the TERRA_LIB_PATH environment variable.

Returns

• String: Validated absolute path to the TERRA shared library

Throws

• ErrorException: If the environment variable is unset or points to a missing file

save_results(results, filename)

Save chain simulation results to a JSON file.

Arguments

• results::ChainSimulationResult: Chain results to save
• filename::String: Output JSON filename

Returns

• true if save successful

save_results(results, filename)

Save TERRA results to file.

Arguments

• results::ReactorResult: Results to save
• filename::String: Output filename (CSV format)

Returns

• true if save successful

set_api_finalize_mpi_wrapper(enable)

Control whether finalizeapi() will call MPIFinalize on the Fortran side. Default is true; tests may disable it to allow reinitialization in one process.

set_electronic_boltzmann_wrapper(rho_sp, tex, trot, tvib)

Set electronic state densities to Boltzmann distribution.

Arguments

• rho_sp::Vector{Float64}: Species densities (mass/volume)
• tex::Float64: Electronic temperature (K)
• trot::Float64: Rotational temperature (K)
• tvib::Float64: Vibrational temperature (K)

Returns

• Matrix{Float64}: Electronic state densities in Boltzmann distribution

Throws

• ErrorException: If TERRA library is not loaded or not initialized
• ArgumentError: If temperatures ≤ 0 or arrays are invalid

set_vibrational_boltzmann_wrapper(rho_ex, tex, trot, tvib)

Set vibrational state densities to a Boltzmann distribution given rho_ex.

Arguments

• rho_ex::Matrix{Float64}: Electronic state densities (mass/volume)
• tex::Float64: Electronic temperature (K)
• trot::Float64: Rotational temperature (K)
• tvib::Float64: Vibrational temperature (K)

Returns

• Array{Float64,3}: Vibrational state densities (0:mnv, mmnex, mnsp)

Throws

• ErrorException: If TERRA library is not loaded or not initialized
• ArgumentError: If temperatures ≤ 0 or arrays are invalid

set_wrapper_debug!(flag)

Enable or disable verbose wrapper debug logging.

solve_terra_chain_steady(config, profile_path; marching)

Load a profile from disk and solve the steady axial chain of CSTR segments.

solve_terra_chain_steady(config, profile; marching)

Solve a steady axial chain of CSTR segments using the TERRA 0D solver.

This implementation supports:

• ReinitializeHandoff()
• FullStateHandoff()
• FinalTimeTermination()

Arguments

• config::Config: Base TERRA config for models, sources, solver controls, and inlet state
• profile::AxialChainProfile: Axial chain profile

Keyword Arguments

• marching::AxialMarchingConfig: Axial marching controls

Returns

• ChainSimulationResult

species_density_matrix(result)

Return species densities as an n_species x n_times matrix.

temperature_history(result)

Return saved temperature histories as (tt, te, tv).

terra_ode_system!(du, u, p, t)

ODE system that calls the Fortran rhs_api directly.

total_energy_history(result)

Return saved total-energy history.

unpack_state_vector(y, layout)

Unpack a compact y vector into component arrays.

This returns rho_sp for all active species (including charge-balanced electrons when enabled), plus rho_ex and rho_vx when the corresponding STS modes are active.

validate_array_dimensions(config)

Validate that configuration arrays match TERRA Fortran expectations.

Arguments

• config::Config: Configuration to validate

Returns

• true if validation passes

Throws

• ErrorException if array dimensions exceed TERRA limits

validate_axial_chain_profile(profile)

Validate an AxialChainProfile against the chain-profile contract.

Arguments

• profile::AxialChainProfile: Profile to validate

Returns

• true if validation passes

Throws

• ArgumentError if the profile is invalid

validate_axial_marching_config(marching)

Validate an AxialMarchingConfig for the current chain solver capabilities.

Arguments

• marching::AxialMarchingConfig: Marching controls to validate

Returns

• true if validation passes

Throws

• ArgumentError if unsupported modes are requested

validate_config_against_terra(config)

Validate configuration parameters against loaded TERRA library capabilities.

This function checks that the configuration is compatible with the loaded TERRA library, including array dimensions and species availability.

Arguments

• config::Config: Configuration to validate

Returns

• true if validation passes

Throws

• ErrorException if validation fails or library not loaded

validate_species_against_terra_database(config)

Validate species against TERRA database (requires loaded library).

This function uses the fortran_wrapper to query the TERRA database for available species and validates the configuration species against it.

Arguments

• config::Config: Configuration to validate

Returns

• true if validation passes

Throws

• ErrorException if species validation fails or library not loaded

validate_species_data(
    species_names,
    terra_species,
    densities
)

Validate species data consistency between Julia and TERRA.

Arguments

• species_names::Vector{String}: Species names from configuration
• terra_species::Vector{String}: Species names from TERRA
• densities::Vector{Float64}: Species densities

Returns

• true if validation passes, throws error otherwise

validate_species_in_database(config)

Validate that all species in configuration exist in the TERRA database.

Arguments

• config::Config: Configuration to validate

Returns

• true if validation passes

Throws

• ErrorException if any species are not found in database

with_case_path(config, case_path)

Return a copy of config with an updated case path.

with_logging(
    config;
    console_mode,
    progress_mode,
    native_stream_mode,
    integration_detail_mode,
    chain_detail_mode,
    log_dir
)

Return a copy of config with an updated logging block.

with_logging(
    logging;
    console_mode,
    progress_mode,
    native_stream_mode,
    integration_detail_mode,
    chain_detail_mode,
    log_dir
)

Return a copy of logging with updated logging controls.

with_runtime(
    config;
    database_path,
    case_path,
    unit_system,
    validate_species_against_terra,
    print_source_terms,
    write_native_state_files,
    logging
)

Return a copy of config with an updated runtime block.

with_runtime(
    runtime;
    database_path,
    case_path,
    unit_system,
    validate_species_against_terra,
    print_source_terms,
    write_native_state_files,
    logging
)

Return a copy of runtime with an updated runtime block.

with_time(config; dt, dt_output, duration, nstep, method)

Return a copy of config with updated time-integration controls.

write_api_outputs_wrapper(istep, time, dt, state; dist, dx)

Write a snapshot of the current API state to the native TERRA output files, using the y layout expected by rhs_api.