# Utilities and Constants

(jl-type-solutionarray)=
::::{describe} SolutionArray(gas::Solution, n::Integer)
```julia
SolutionArray(gas::Solution)
```

A collection of `n` thermodynamic states of `gas` (or an empty, growable array).
States are stored as temperature, pressure, and mass fractions, and are restored
into `gas` on demand to evaluate properties.

```julia
states = SolutionArray(gas)
for t in times
    advance!(net, t)
    append!(states, gas)          # snapshot the current gas state
end
temperature(states)               # Vector of T for every stored state
write_csv(states, "history.csv")
```
::::

(jl-function-restore-bang)=
::::{describe} restore!(sa::SolutionArray, i::Integer)
Restore stored state `i` (1-based) into the backing `Solution` and return it.
::::

(jl-function-set-state-bang)=
::::{describe} set_state!(sa, i; T, P, X=nothing, Y=nothing)
Set stored state `i` (1-based). Provide composition as mole fractions `X` or
mass fractions `Y` (string or vector); if neither is given the composition is
left unchanged.
::::

(jl-function-extract)=
::::{describe} extract(sa, f) -> Vector
Evaluate the scalar property function `f` (e.g. `density`, `enthalpy_mass`) for
every stored state and return the results as a vector.
::::

(jl-function-write-csv)=
::::{describe} write_csv(sa::SolutionArray, path)
Write the stored states to a CSV file with columns `T`, `P`, and one column per
species mass fraction.
::::

(jl-constant-one-atm)=
::::{describe} one_atm
One standard atmosphere [Pa].
::::

(jl-constant-gas-constant)=
::::{describe} gas_constant
Universal gas constant in Cantera's molar convention [J/kmol/K].
::::

(jl-constant-avogadro)=
::::{describe} avogadro
Avogadro's number [1/kmol].
::::

(jl-function-cantera-version)=
::::{describe} cantera_version() -> String
Version string of the linked Cantera library.
::::

(jl-function-git-commit)=
::::{describe} git_commit() -> String
Git commit of the linked Cantera library.
::::

(jl-function-add-data-directory)=
::::{describe} add_data_directory(dir)
Add `dir` to the list of directories searched for Cantera input files.
::::

(jl-function-suppress-thermo-warnings)=
::::{describe} suppress_thermo_warnings(flag=true)
Suppress (or re-enable) Cantera's thermodynamic warnings.
::::

(jl-function-reset-storage)=
::::{describe} reset_storage()
Reset all Cantera CLib storage, invalidating every existing handle.
::::

(jl-type-canteraerror)=
::::{describe} CanteraError(msg)
Exception raised when an underlying Cantera CLib call reports an error.  The
message is the exception text produced by the C++ Cantera core.
::::