# Zero-Dimensional Reactor Networks

(jl-type-reactor)=
::::{describe} Reactor
Wrapper around a Cantera reactor CLib handle.  Construct one of the concrete
helpers ([`IdealGasReactor`](#jl-function-idealgasreactor), [`Reactor`](#jl-type-reactor), [`ConstPressureReactor`](#jl-function-constpressurereactor),
[`IdealGasConstPressureReactor`](#jl-function-idealgasconstpressurereactor)) rather than this type directly.

```julia
Reactor(gas; name="")
```

General constant-volume reactor.
::::

(jl-function-idealgasreactor)=
::::{describe} IdealGasReactor(gas; name="")
Zero-dimensional constant-volume reactor with an ideal-gas energy equation.
::::

(jl-function-constpressurereactor)=
::::{describe} ConstPressureReactor(gas; name="")
Constant-pressure reactor.
::::

(jl-function-idealgasconstpressurereactor)=
::::{describe} IdealGasConstPressureReactor(gas; name="")
Constant-pressure reactor with an ideal-gas energy equation.
::::

(jl-function-mass)=
::::{describe} mass(r::Reactor)
Mass of the reactor contents [kg].
::::

(jl-function-reactor-phase)=
::::{describe} reactor_phase(r::Reactor) -> Solution
The `Solution` actually integrated by the reactor. This is the reactor's own
clone of the phase it was constructed from (see [`IdealGasReactor`](#jl-function-idealgasreactor) and
friends), and reflects its current state, unlike the original `Solution`
passed to the constructor.
::::

(jl-function-set-energy-enabled-bang)=
::::{describe} set_energy_enabled!(r::Reactor, flag::Bool)
Enable/disable the energy equation in the reactor.
::::

(jl-function-set-chemistry-enabled-bang)=
::::{describe} set_chemistry_enabled!(r::Reactor, flag::Bool)
Enable/disable chemistry in the reactor.
::::

(jl-function-set-initial-volume-bang)=
::::{describe} set_initial_volume!(r::Reactor, vol)
Set the initial reactor volume [m^3].
::::

(jl-function-reservoir)=
::::{describe} Reservoir(gas; name="")
A reactor with a fixed thermodynamic state, used as a boundary (source or sink)
for [`FlowDevice`](#jl-type-flowdevice)s and [`Wall`](#jl-type-wall)s.  Its state never changes during
integration.
::::

(jl-function-area)=
::::{describe} area(r::Reactor) -> Float64
Wall/surface area associated with the reactor [m^2].

```julia
area(w::Wall)
```

Wall area [m^2].
::::

(jl-function-set-area-bang)=
::::{describe} set_area!(r::Reactor, a)
Set the wall/surface area of the reactor [m^2].

```julia
set_area!(w::Wall, a)
```

Set the wall area [m^2].
::::

(jl-function-reactorsurface)=
::::{describe} ReactorSurface(surf, reactor; name="")
A surface on which heterogeneous reactions take place, coupling the surface
phase `surf` (a [`Solution`](#jl-type-solution) for an interface phase) to a bulk `reactor`.
::::

(jl-function-mass-flow-rate)=
::::{describe} mass_flow_rate(r::Reactor)
Mass flow rate through the reactor [kg/s].

```julia
mass_flow_rate(d::FlowDevice)
```

Mass flow rate through the flow device [kg/s].
::::

(jl-function-set-mass-flow-rate-bang)=
::::{describe} set_mass_flow_rate!(r::Reactor, mdot)
Set the mass flow rate through the reactor [kg/s].

```julia
set_mass_flow_rate!(mfc, mdot)
```

Set the (constant) mass flow rate of a [`MassFlowController`](#jl-type-massflowcontroller) [kg/s].
::::

(jl-function-add-sensitivity-reaction-bang)=
::::{describe} add_sensitivity_reaction!(r, i)
Mark reaction `i` (1-based) as a sensitivity parameter for reactor `r`.  The
reactor must already be part of a [`ReactorNet`](#jl-type-reactornet).
::::

(jl-function-n-sens-params)=
::::{describe} n_sens_params(r::Reactor)
Number of sensitivity parameters associated with the reactor.
::::

(jl-type-reactornet)=
::::{describe} ReactorNet(reactors::Vector{Reactor})
```julia
ReactorNet(reactor::Reactor)
```

Create a reactor network for time integration.  The network keeps references to
its reactors so they are not finalized while integration is in progress.
::::

(jl-function-advance-bang)=
::::{describe} advance!(net, t)
Advance the network state to absolute time `t` [s].
::::

(jl-function-step-bang)=
::::{describe} step!(net) -> Float64
Take one internal timestep and return the new time [s].
::::

(jl-function-set-initial-time-bang)=
::::{describe} set_initial_time!(net::ReactorNet, t)
Set the initial integration time [s].
::::

(jl-function-set-max-time-step-bang)=
::::{describe} set_max_time_step!(net::ReactorNet, dt)
Set the maximum internal timestep [s].
::::

(jl-function-set-tolerances-bang)=
::::{describe} set_tolerances!(net; rtol=1e-9, atol=1e-15)
Set the relative and absolute integrator tolerances.
::::

(jl-function-rtol)=
::::{describe} rtol(net::ReactorNet)
Relative error tolerance of the network integrator.
::::

(jl-function-atol)=
::::{describe} atol(net::ReactorNet)
Absolute error tolerance of the network integrator.
::::

(jl-function-set-sensitivity-tolerances-bang)=
::::{describe} set_sensitivity_tolerances!(net; rtol=1e-6, atol=1e-6)
Set the relative and absolute tolerances used for sensitivity analysis.
::::

(jl-function-sensitivity)=
::::{describe} sensitivity(net, component, p, reactor) -> Float64
Normalized sensitivity of `component` (e.g. `"temperature"` or a species name)
in `reactor` with respect to sensitivity parameter `p` (1-based).  `reactor` may
be a [`Reactor`](#jl-type-reactor) belonging to the network or its 1-based position.
::::

(jl-function-n-components)=
::::{describe} n_components(net) -> Int
Number of state variables (equations) integrated by the network.

```julia
n_components(d::Domain1D)
```

Number of solution components in the domain.
::::

(jl-function-state)=
::::{describe} state(net) -> Vector{Float64}
Current network state vector, of length [`n_components`](#jl-function-n-components).
::::

(jl-function-component-name)=
::::{describe} component_name(net::ReactorNet, i::Integer)
Name of state-vector component `i` (1-based).

```julia
component_name(d::Domain1D, n::Integer)
```

Name of component `n` (1-based).
::::

(jl-function-component-names)=
::::{describe} component_names(net) -> Vector{String}
Names of all state-vector components, aligned with [`state`](#jl-function-state).

```julia
component_names(d::Domain1D)
```

Vector of all component names in the domain.
::::

(jl-type-connector)=
::::{describe} Connector
Abstract supertype of objects that link two reactors in a network
([`Wall`](#jl-type-wall), [`MassFlowController`](#jl-type-massflowcontroller), [`Valve`](#jl-type-valve),
[`PressureController`](#jl-type-pressurecontroller)).
::::

(jl-type-flowdevice)=
::::{describe} FlowDevice <: Connector
Abstract supertype of flow devices that move mass between reactors.
::::

(jl-function-connector-type)=
::::{describe} connector_type(c::Connector)
Connector type string.
::::

(jl-function-set-name-bang)=
::::{describe} set_name!(c::Connector, nm::AbstractString)
Set the connector name.
::::

(jl-type-wall)=
::::{describe} Wall(left, right; A=1.0, U=0.0, K=0.0, Q=nothing, velocity=nothing,
```julia
expansion_rate_coeff=nothing, emissivity=nothing, name="")
```

A wall separating reactors `left` and `right`.  `A` is the wall area [m^2], `U`
the heat-transfer coefficient [W/m^2/K], `K` the expansion-rate coefficient
[m/s/Pa].  `Q` (heat flux) and `velocity` may be `Func1` objects; `emissivity`
enables radiative transfer.
::::

(jl-function-expansion-rate)=
::::{describe} expansion_rate(w::Wall)
Rate of volumetric expansion of the left reactor [m^3/s].
::::

(jl-function-heat-rate)=
::::{describe} heat_rate(w::Wall)
Rate of heat transfer through the wall (left to right) [W].
::::

(jl-function-set-heat-transfer-coeff-bang)=
::::{describe} set_heat_transfer_coeff!(w::Wall, U)
Set the wall heat-transfer coefficient [W/m^2/K].
::::

(jl-function-set-thermal-resistance-bang)=
::::{describe} set_thermal_resistance!(w::Wall, Rth)
Set the wall thermal resistance [m^2*K/W].
::::

(jl-function-set-expansion-rate-coeff-bang)=
::::{describe} set_expansion_rate_coeff!(w::Wall, k)
Set the wall expansion-rate coefficient [m/s/Pa].
::::

(jl-function-set-emissivity-bang)=
::::{describe} set_emissivity!(w::Wall, epsilon)
Set the wall emissivity for radiative heat transfer (0..1).
::::

(jl-function-set-heat-flux-bang)=
::::{describe} set_heat_flux!(w::Wall, q)
Set the wall heat flux as a time-dependent `Func1` (or handle) [W/m^2].
::::

(jl-function-set-velocity-bang)=
::::{describe} set_velocity!(w::Wall, f)
Set the wall velocity as a time-dependent `Func1` (or handle) [m/s].
::::

(jl-function-device-coefficient)=
::::{describe} device_coefficient(d::FlowDevice)
Device coefficient of the flow device (meaning depends on the device type).
::::

(jl-function-set-device-coefficient-bang)=
::::{describe} set_device_coefficient!(d::FlowDevice, c)
Set the device coefficient of the flow device.
::::

(jl-function-set-pressure-function-bang)=
::::{describe} set_pressure_function!(d::FlowDevice, f)
Set the pressure function of the flow device as a `Func1` (or handle).
::::

(jl-function-set-time-function-bang)=
::::{describe} set_time_function!(d::FlowDevice, g)
Set the time function of the flow device as a `Func1` (or handle).
::::

(jl-function-set-primary-bang)=
::::{describe} set_primary!(d::FlowDevice, primary::FlowDevice)
Set the primary flow device (used by [`PressureController`](#jl-type-pressurecontroller)).
::::

(jl-type-massflowcontroller)=
::::{describe} MassFlowController(upstream, downstream; mdot=0.0, name="")
A flow device that maintains a specified mass flow rate `mdot` [kg/s] from
`upstream` to `downstream`, independent of the pressure difference.
::::

(jl-type-valve)=
::::{describe} Valve(upstream, downstream; K=0.0, name="")
A flow device whose mass flow rate is proportional to the pressure difference,
`mdot = K * (P_upstream - P_downstream)`, with valve coefficient `K`.
::::

(jl-type-pressurecontroller)=
::::{describe} PressureController(upstream, downstream; primary=nothing, K=0.0, name="")
A flow device that regulates the pressure difference across it relative to a
`primary` flow device: `mdot = primary.mdot + K * (P_upstream - P_downstream)`.
::::

(jl-type-func1)=
::::{describe} Func1
A wrapper around a Cantera `Func1` function object.  A `Func1` is
callable: `f(t)` evaluates it at `t`.  Instances combine with `+`, `-`, `*` and
`/` to build compound functions and support symbolic [`derivative`](#jl-function-derivative).

# Examples
```julia
f = Func1("sin", 2.0)   # t -> sin(2t)
f(pi/4)                 # == sin(pi/2)
g = Func1("polynomial3", [1.0, 2.0, 3.0, 4.0])  # t^3 + 2t^2 + 3t + 4
h = Func1("constant", 2.0) + Func1("constant", 3.0)
```

```julia
Func1(type::String, coeff::Real=1.0)
```

Construct a basic functor of the given `type` (e.g. `"sin"`, `"cos"`, `"exp"`,
`"log"`, `"pow"`, `"constant"`).  For `"sin"` with coefficient `w`, evaluating
at `t` returns `sin(w*t)`.

```julia
Func1(type::String, coeffs::AbstractVector)
```

Construct an advanced functor parametrized by an array of coefficients, e.g.
`"polynomial3"` (coefficients from highest to lowest degree) or `"Fourier"`.
::::

(jl-function-constant-function)=
::::{describe} constant_function(c) -> Func1
Convenience constructor for the constant functor `t -> c`.
::::

(jl-function-evaluate)=
::::{describe} evaluate(f::Func1, t) -> Float64
Evaluate the functor at `t`.
::::

(jl-function-derivative)=
::::{describe} derivative(f::Func1) -> Func1
Return a new `Func1` representing the symbolic derivative of `f`.
::::

(jl-function-func-type)=
::::{describe} func_type(f::Func1) -> String
The functor's type string (e.g. `"sin"`, `"sum"`).
::::