TERRA

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_mode::Symbol: Segment handoff mode (:reinitialize or :full_state)
• termination_mode::Symbol: Segment termination mode (:final_time or :steady_state)
• 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

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.

Physics/process model configuration.

Integrate the 0D system over time using the Fortran rhs_api layout.

This uses terra_ode_system! and constructs a y vector that matches the ordering returned by get_api_layout().

Notes:

• Vibrational STS is not yet supported in this wrapper (vibrational mode energy is supported).
• For isothermal Teex cases, the stored energy slot in u is rho_rem (legacy semantics), and the working y passed to Fortran is reconstructed each call.
• Wrapper-managed additive source terms are prepared from config.sources or an explicit sources override.

Apply the native TERRA ramp limiter update to the integrator.

Arguments

• integrator: DifferentialEquations.jl integrator being stepped

Returns

• Nothing

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

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

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

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.

Convert nested Config to initial state vectors for TERRA.

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)

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

Runtime and I/O configuration controls.

Wrapper-managed additive source-term configuration.

Spatial-discretization metadata.

Per-species wall-interaction closure for wrapper-managed wall losses.

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.

_solve_terra_0d_internal(
    config;
    sources,
    wall_inputs,
    state_cache
)

Solve a 0D TERRA simulation.

This is the main high-level interface for running TERRA simulations. It handles all the complexity of data conversion, Fortran interfacing, and result processing.

Arguments

• config::Config: Configuration for the simulation

Returns

• ReactorResult: Results of the simulation

Throws

• ErrorException if TERRA not initialized or simulation fails

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.

Arguments

• rho_sp::AbstractVector{<:Real}: Species mass densities in CGS units
• gas_constants::AbstractVector{<:Real}: Species-specific gas constants
• species_names::AbstractVector{<:AbstractString}: Species identifiers used to detect electrons
• molecular_weights::AbstractVector{<:Real}: Species molecular weights
• tt::Real: Translational (heavy-particle) temperature
• te::Real: Electron temperature applied to electron species

Returns

• Float64: Mixture pressure consistent with TERRA conventions

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.

Arguments

• rho_etot::Float64: Total energy density (CGS units)
• rho_sp::AbstractVector{<:Real}: Species mass densities
• gas_constants::AbstractVector{<:Real}: Species-specific gas constants
• species_names::AbstractVector{<:AbstractString}: Species names used to detect electrons
• molecular_weights::AbstractVector{<:Real}: Species molecular weights
• tt::Real: Translational temperature applied to heavy species
• te::Real: Electron temperature applied to electron species

Returns

• Tuple{Float64, Float64}: Enthalpy density and corresponding pressure

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.

Arguments

• None

Returns

• Nothing

generate_input_files(config)
generate_input_files(config, case_path)

Generate TERRA input files from configuration with proper directory structure.

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

• case_path/input/ (input files)
• case_path/output/ (output files)
• case_path/output/sources/ (source term outputs)
• case_path/output/states/ (state outputs)

Arguments

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

Returns

• true if files generated successfully

Throws

• ErrorException if file generation fails

generate_prob_setup_file(config, filepath)

Generate prob_setup.inp file from configuration.

generate_sources_setup_file(config, filepath)

Generate sources_setup.inp file from configuration.

generate_tau_scaling_file(config, filepath)

Generate tau_scaling.inp file from configuration.

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_api_wrapper(; case_path)

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

initialize_terra(config)
initialize_terra(config, case_path)

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.

Arguments

• None

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.

Arguments

• initial_dt: Baseline time step used after the ramp is complete
• understep_ratio: Optional ratio controlling the initial under-stepping
• history_steps: Optional number of accepted steps to maintain the ramp

Returns

• DiscreteCallback: Callback implementing the ramp behaviour

native_ramp_condition(u, t, integrator)

Condition function for the native ramp callback (always triggers).

Arguments

• u: Current state vector (unused)
• t: Current simulation time (unused)
• integrator: DifferentialEquations.jl integrator (unused)

Returns

• true

native_ramp_initialize(cb, u, t, integrator)

Initializer for the native ramp callback.

Arguments

• cb: Callback instance containing the ramp limiter
• u: Current state vector (unused)
• t: Current simulation time (unused)
• integrator: DifferentialEquations.jl integrator instance

Returns

• Nothing

nitrogen_10ev_config(; isothermal)

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

Returns

• Config: Configuration matching the example case

Throws

• ErrorException if TERRA_LIB_PATH is unset/invalid or if required database paths do not exist

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

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

This function provides a convenient way to run the reference test case that matches the TERRA example in /terra/examples/0D_Nitrogen_Te_10eV. Requires the TERRA_LIB_PATH environment variable to point to the TERRA shared library.

Arguments

• case_path::String: Case directory path (optional, creates temp directory if not provided)

Returns

• ReactorResult: Results of the simulation

Example

results = nitrogen_10ev_example()

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:

• handoff_mode = :reinitialize
• handoff_mode = :full_state
• termination_mode = :final_time

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

terra_ode_system!(du, u, p, t)

ODE system that calls the Fortran rhs_api directly (via calculate_rhs_api).

Assumptions about the state u:

• Non-isothermal (config.models.physics.is_isothermal_teex == false): u matches the Fortran rhs_api y layout and stores total energy density at layout.idx_etot.
• Isothermal Teex (== true): u[layout.idx_etot] stores the remainder energy rho_rem = rho_h - rho_eeex - rho_e * R_e * Teex. The rho_eeex slot is treated as a dummy (its derivative is forced to zero). The Fortran call uses a working vector with rho_eeex recomputed from the prescribed Teex, and with rho_etot reconstructed from rho_rem by converting total enthalpy back to energy.

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/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_results(results)

Validate simulation results for physical consistency.

Arguments

• results::ReactorResult: Simulation results to validate

Returns

• true if results pass validation, false otherwise

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_runtime(
    config;
    database_path,
    case_path,
    unit_system,
    validate_species_against_terra,
    print_source_terms,
    write_native_outputs,
    print_integration_output
)

Return a copy of config 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.