Reactors & reactive separations¶

Equilibrium, kinetic (CSTR and PFR), stoichiometric, and batch reactors on a common property package, and reactive separations that solve phase and reaction equilibrium together (reactive flash and reactive MESH columns).

See the reactions & reactors guide and reactive process workflows for worked examples.

Reactors¶

reactors ¶

Reactor unit operations on a common property package.

These blocks turn the reaction thermochemistry and kinetics in fugacio.thermo into flowsheet units that consume and produce Stream objects:

equilibrium_reactor, cstr, and pfr: homogeneous reactors solved by the checked implementation in fugacio.sim.reaction_units.reaction_reactor, with phase-specific package properties, formation-consistent energy balances, and retained reports and profiles;
stoichiometric_reactor: a specified extent or key-reactant conversion on the package's formation-consistent energy basis;
batch_reactor: a constant-volume, ideal-gas batch reactor integrated in time.

Every reactor supports an energy specification: an outlet temperature (the heat to hold it is returned, carrying the heat of reaction) or a heat duty (zero for adiabatic operation, the outlet temperature is then solved). Results are differentiable in the feed, the operating conditions, and the reaction and kinetic parameters. Eager calls raise on failure, and a traced failure has NaN products (outlet, duty, and extents) while its report, balances, and profiles are kept for diagnosis. Pass check=False to get the best iterate instead, with a failed report and nonfinite derivatives.

Classes:

Name	Description
`StoichiometricResult`	Products of a specified-extent reactor.
`BatchResult`	Contents of a closed, constant-volume batch reactor after a reaction time.

Functions:

Name	Description
`equilibrium_reactor`	Reactor whose outlet is the homogeneous chemical-equilibrium composition.
`cstr`	Continuous stirred-tank reactor (perfectly mixed) at steady state.
`pfr`	Plug-flow reactor integrated along its volume with step-doubling error control.
`stoichiometric_reactor`	Reactor with a specified extent or key-reactant conversion (no equilibrium).
`batch_reactor`	Closed, constant-volume, ideal-gas batch reactor integrated over time.
`conversion`	Fractional conversion of a feed component, `(n_in - n_out) / n_in`.

StoichiometricResult ¶

Bases: NamedTuple

Products of a specified-extent reactor.

Attributes:

Name	Type	Description
`outlet`	`Stream`	Product `Stream`.
`duty`	`Array`	Heat added (W), positive into the fluid.
`extent`	`Array`	Extent of each reaction (mol/s).
`generation`	`Array`	Net component generation `extent @ nu` (mol/s).
`report`	`SolveReport`	Specification and energy-solve report.

outlets `property` ¶

outlets: tuple[Stream]

The single outlet, as a flowsheet output tuple.

heat `property` ¶

heat: Array

Heat into the fluid (W).

BatchResult ¶

Bases: NamedTuple

Contents of a closed, constant-volume batch reactor after a reaction time.

Attributes:

Name	Type	Description
`contents`	`Stream`	Final contents as a `Stream` of moles (mol), at the final temperature and ideal-gas pressure.
`heat`	`Array`	Cumulative heat added (J); `Delta U` for an isothermal run, zero when adiabatic.
`extent`	`Array`	Extent of each reaction (mol).

equilibrium_reactor ¶

equilibrium_reactor(
    feed: Stream,
    reactions: Reaction | Sequence[Reaction] | ReactionSet,
    *,
    model: Model = None,
    t_out: ArrayLike | None = None,
    duty: ArrayLike | None = None,
    dp: ArrayLike = 0.0,
    phase: str = "vapor",
    tol: float = 1e-10,
    max_iter: int = 100,
    check: bool = True,
) -> ReactionResult

Reactor whose outlet is the homogeneous chemical-equilibrium composition.

Parameters:

Name	Type	Description	Default
`feed`	`Stream`	Inlet stream; reactions must be defined over `feed.components`.	required
`reactions`	`Reaction \| Sequence[Reaction] \| ReactionSet`	One reaction, several sharing the feed's component order, or a validated `ReactionSet`.	required
`model`	`Model`	Property package; defaults to Peng-Robinson over the feed.	`None`
`t_out`	`ArrayLike \| None`	Isothermal outlet temperature (K); the default is the feed's.	`None`
`duty`	`ArrayLike \| None`	Heat added (W) instead of `t_out`; zero is adiabatic.	`None`
`dp`	`ArrayLike`	Non-negative pressure drop (Pa).	`0.0`
`phase`	`str`	Reacting phase for a newly constructed reaction set.	`'vapor'`
`tol`	`float`	Scaled nonlinear residual tolerance.	`1e-10`
`max_iter`	`int`	Newton iteration cap.	`100`
`check`	`bool`	Raise on a rejected concrete result.	`True`

Returns:

Type	Description
`ReactionResult`	A `fugacio.sim.reaction_units.ReactionResult` with the outlet, duty,
`ReactionResult`	extents, balances, and report.

cstr ¶

cstr(
    feed: Stream,
    reactions: Reaction | Sequence[Reaction] | ReactionSet,
    volume: ArrayLike,
    rate_laws: Any = None,
    *,
    model: Model = None,
    t_out: ArrayLike | None = None,
    duty: ArrayLike | None = None,
    dp: ArrayLike = 0.0,
    phase: str = "vapor",
    rate_basis: str = "concentration",
    tol: float = 1e-10,
    max_iter: int = 100,
    check: bool = True,
) -> ReactionResult

Continuous stirred-tank reactor (perfectly mixed) at steady state.

Solves F_out = F_in + V (r . Nu) with outlet-condition rates on the package's phase concentrations, jointly with the energy balance when a duty is specified.

Parameters:

Name	Type	Description	Default
`feed`	`Stream`	Inlet stream (`feed.n` are molar flows, mol/s).	required
`reactions`	`Reaction \| Sequence[Reaction] \| ReactionSet`	Reaction(s) over `feed.components`, or a `ReactionSet`.	required
`volume`	`ArrayLike`	Reacting-phase volume (m^3).	required
`rate_laws`	`Any`	One rate law per reaction; omit for a ReactionSet.	`None`
`model`	`Model`	Property package; defaults to Peng-Robinson over the feed.	`None`
`t_out`	`ArrayLike \| None`	Isothermal temperature (K); the default is the feed's.	`None`
`duty`	`ArrayLike \| None`	Heat added (W) instead of `t_out`; zero is adiabatic.	`None`
`dp`	`ArrayLike`	Non-negative pressure drop (Pa).	`0.0`
`phase`	`str`	Reacting phase for a newly constructed reaction set.	`'vapor'`
`rate_basis`	`str`	Kinetic input convention for a newly constructed set.	`'concentration'`
`tol`	`float`	Scaled nonlinear residual tolerance.	`1e-10`
`max_iter`	`int`	Newton iteration cap.	`100`
`check`	`bool`	Raise on a rejected concrete result.	`True`

Returns:

Type	Description
`ReactionResult`	A `fugacio.sim.reaction_units.ReactionResult`.

pfr ¶

pfr(
    feed: Stream,
    reactions: Reaction | Sequence[Reaction] | ReactionSet,
    volume: ArrayLike,
    rate_laws: Any = None,
    *,
    model: Model = None,
    t_out: ArrayLike | None = None,
    duty: ArrayLike | None = None,
    dp: ArrayLike = 0.0,
    phase: str = "vapor",
    rate_basis: str = "concentration",
    steps: int = 64,
    tol: float = 1e-10,
    max_iter: int = 100,
    check: bool = True,
) -> ReactionResult

Plug-flow reactor integrated along its volume with step-doubling error control.

Parameters:

Name	Type	Description	Default
`feed`	`Stream`	Inlet stream (`feed.n` are molar flows, mol/s).	required
`reactions`	`Reaction \| Sequence[Reaction] \| ReactionSet`	Reaction(s) over `feed.components`, or a `ReactionSet`.	required
`volume`	`ArrayLike`	Reacting-phase volume (m^3).	required
`rate_laws`	`Any`	One rate law per reaction; omit for a ReactionSet.	`None`
`model`	`Model`	Property package; defaults to Peng-Robinson over the feed.	`None`
`t_out`	`ArrayLike \| None`	Isothermal temperature (K); the default is the feed's.	`None`
`duty`	`ArrayLike \| None`	Heat added (W) instead of `t_out`, distributed uniformly; zero is adiabatic.	`None`
`dp`	`ArrayLike`	Non-negative pressure drop (Pa), linear along the reactor.	`0.0`
`phase`	`str`	Reacting phase for a newly constructed reaction set.	`'vapor'`
`rate_basis`	`str`	Kinetic input convention for a newly constructed set.	`'concentration'`
`steps`	`int`	Coarse mesh size; a refined mesh estimates the integration error.	`64`
`tol`	`float`	Scaled nonlinear residual tolerance.	`1e-10`
`max_iter`	`int`	Newton iteration cap for implicit steps.	`100`
`check`	`bool`	Raise on a rejected concrete result.	`True`

Returns:

Type	Description
`ReactionResult`	A `fugacio.sim.reaction_units.ReactionResult` with axial profiles.

stoichiometric_reactor ¶

stoichiometric_reactor(
    feed: Stream,
    reactions: Reaction | Sequence[Reaction],
    *,
    extent: ArrayLike | None = None,
    conversion: ArrayLike | None = None,
    t_out: ArrayLike | None = None,
    duty: ArrayLike | None = None,
    dp: ArrayLike = 0.0,
    model: Model = None,
) -> StoichiometricResult

Reactor with a specified extent or key-reactant conversion (no equilibrium).

Provide exactly one of extent (per reaction, mol/s) or conversion (a single reaction's fractional conversion of its limiting reactant, in [0, 1]). The outlet is n = n_feed + extent @ nu and every outlet flow must stay non-negative. Energy uses the package's sensible and residual enthalpies plus ideal-gas formation enthalpies: with t_out (default: the feed temperature) the duty follows; with duty (zero is adiabatic) the outlet temperature follows from a PH flash.

Raises:

Type	Description
`ValueError`	For conflicting or missing specifications, a conversion outside `[0, 1]`, a negative outlet flow, or a reference-fluid package.
`ConvergenceError`	If an eager adiabatic energy solve fails.

batch_reactor ¶

batch_reactor(
    feed: Stream,
    reactions: Reaction | Sequence[Reaction],
    rate_laws: Any,
    volume: ArrayLike,
    time: ArrayLike,
    *,
    t_out: ArrayLike | None = None,
    adiabatic: bool = False,
    steps: int = 200,
) -> BatchResult

Closed, constant-volume, ideal-gas batch reactor integrated over time.

Here feed.n are the initial moles (mol). Marches dN_i/dt = V (r . Nu)_i with concentrations c_i = N_i / V by explicit RK4. The vessel is closed and rigid, so the first law conserves internal energy, not enthalpy: an adiabatic run integrates (sum_i N_i Cv_i) dT/dt = -V sum_j r_j Delta U_j with Cv = Cp - R and Delta U_j = Delta H_j - R T sum_i nu_ji, and an isothermal run returns the heat Q = Delta U. The final pressure is the ideal-gas N R T / V.

Raises:

Type	Description
`ValueError`	If the number of rate laws doesn't match the reactions.

conversion ¶

conversion(
    feed: Stream, outlet: Stream, component_index: int
) -> Array

Fractional conversion of a feed component, (n_in - n_out) / n_in.

Reactive separations¶

reactive ¶

Reactive separations: simultaneous chemical reaction and phase equilibrium.

Real separation equipment often runs with a reaction happening inside it: the whole point of reactive distillation is to push a reaction past its equilibrium limit by continuously pulling products into a different phase. This module provides the common-package units:

reactive_flash: an isothermal flash in which the liquid simultaneously reaches chemical equilibrium (one or more reactions) and phase equilibrium (vapour-liquid). The extents of reaction and the V/L split are solved together, reusing the validated gamma-phi flash and the ideal-gas reaction thermochemistry. Works for any net mole change.
reactive_column: energy-balanced MESH with a common property package and volumetric rates on a declared liquid or vapor phase.

The reaction equilibrium constant K(T) comes from the ideal-gas formation data in fugacio.thermo.reactions; at vapour-liquid equilibrium the component fugacities are equal across phases, so the ideal-gas-referenced equilibrium is written consistently in terms of the liquid activities a_i = x_i gamma_i f_i^{0,L}/P_ref. Every result is a differentiable Stream (or profile of them): conversions, product purities, and stage profiles carry gradients with respect to the feed, operating conditions, the activity-model parameters, and the kinetic/thermochemical parameters.

Classes:

Name	Description
`ReactiveFlashResult`	Outcome of a simultaneous reaction + vapour-liquid flash.

Functions:

Name	Description
`reactive_flash`	Solve isothermal chemical equilibrium coupled to a package PT flash.
`reactive_column`	Solve reactive MESH distillation with formation-consistent stage energy.

ReactiveFlashResult ¶

Bases: NamedTuple

Outcome of a simultaneous reaction + vapour-liquid flash.

Attributes:

Name	Type	Description
`vapor`	`Stream`	Vapour product `Stream`.
`liquid`	`Stream`	Liquid product `Stream`.
`beta`	`Array`	Vapour fraction (mol vapour / mol after reaction).
`extent`	`Array`	Equilibrium extent of each reaction (mol/s), shape `(n_reactions,)`.
`duty`	`Array`	External heat input, including formation energy exactly once (W).
`generation`	`Array`	Component generation (mol/s).
`report`	`SolveReport`	Chemical solve and final phase-solve acceptance.
`phase_report`	`SolveReport`	Actual final PT flash iteration report.

outlets `property` ¶

outlets: tuple[Stream, Stream]

(vapor, liquid), as a flowsheet output tuple.

heat `property` ¶

heat: Array

Heat into the fluid (W), including formation energy once.

reactive_flash ¶

reactive_flash(
    feed: Stream,
    reactions: Reaction | Sequence[Reaction] | ReactionSet,
    t: ArrayLike,
    p: ArrayLike,
    model: Model,
    *,
    tol: float = 1e-09,
    max_iter: int = 100,
    check: bool = True,
) -> ReactiveFlashResult

Solve isothermal chemical equilibrium coupled to a package PT flash.

All property and thermochemical parameters pass explicitly through the implicit solve, including under JIT, JVP, and VJP. The reaction quotient uses the liquid fugacity when liquid is present, otherwise the vapor fugacity. Absent phases never determine chemical equilibrium. Formation enthalpy is included once in the reported heat input (W).

Parameters:

Name	Type	Description	Default
`feed`	`Stream`	Inlet material and thermal state.	required
`reactions`	`Reaction \| Sequence[Reaction] \| ReactionSet`	One reaction, a sequence, or a validated ReactionSet.	required
`t`	`ArrayLike`	Drum temperature (K).	required
`p`	`ArrayLike`	Drum pressure (Pa).	required
`model`	`Model`	Common property package or compatible equilibrium model.	required
`tol`	`float`	Chemical-equilibrium residual tolerance.	`1e-09`
`max_iter`	`int`	Root iteration cap.	`100`
`check`	`bool`	Raise for failed concrete solves; compiled callers inspect report.	`True`

Returns:

Type	Description
`ReactiveFlashResult`	Products preserving phase inventories, reaction extents, heat input,
`ReactiveFlashResult`	generation, and the actual chemical solve report. Process-case audits
`ReactiveFlashResult`	independently assess product equilibrium, stability, and balances.

reactive_column ¶

reactive_column(
    feeds: Sequence[ColumnFeed],
    n_stages: int,
    reactions: ReactionSet,
    reaction_volumes: ArrayLike,
    **kwargs: Any,
) -> RigorousColumnResult

Solve reactive MESH distillation with formation-consistent stage energy.

Arguments follow rigorous_column. Volumes are reacting-phase m^3; a scalar selects interior stages and a vector explicitly selects each stage. This rigorous entry point closes stage energy balances for any reaction stoichiometry.

Checked common-package reactors¶

reaction_units ¶

Checked, property-package-consistent steady-state reaction calculations.

Reacting units use one declared homogeneous phase. Their energy includes formation enthalpies exactly once. A phase change is a rejected homogeneous reactor calculation; a reactive flash or reactive MESH column handles coupled reaction and phase separation explicitly.

Classes:

Name	Description
`ReactionResult`	Reaction products, actual numerical reports, balances, and retained profiles.

Functions:

Name	Description
`reaction_parameter_validity`	Check finite reaction parameters and element conservation under JAX too.
`reaction_reactor`	Solve a homogeneous equilibrium reactor, CSTR, or PFR with a common package.

ReactionResult ¶

Bases: NamedTuple

Reaction products, actual numerical reports, balances, and retained profiles.

Extents and generation are in mol/s; duty is W, positive into the fluid. integration_error is a dimensionless step-doubling error ratio for PFRs (accepted at <= 1), zero for algebraic reactors. Profiles use the refined axial grid, including the inlet. Acceptance checks homogeneous phase compatibility in addition to balance closure, but a finite PT flash isn't an independent global phase-stability proof. Case runs add the existing stream stability audit.

Methods:

Name	Description
`check`	Raise with the retained report for a rejected concrete calculation.

Attributes:

Name	Type	Description
`outlets`	`tuple[Stream]`	The single outlet, as a flowsheet output tuple.
`heat`	`Array`	Heat into the fluid (W).
`converged`	`Array`	Whether numerical, physical-domain, and integration checks passed.

outlets `property` ¶

outlets: tuple[Stream]

The single outlet, as a flowsheet output tuple.

heat `property` ¶

heat: Array

Heat into the fluid (W).

converged `property` ¶

converged: Array

Whether numerical, physical-domain, and integration checks passed.

check ¶

check() -> None

Raise with the retained report for a rejected concrete calculation.

reaction_parameter_validity ¶

reaction_parameter_validity(system: ReactionSet) -> Array

Check finite reaction parameters and element conservation under JAX too.

reaction_reactor ¶

reaction_reactor(
    feed: Stream,
    system: ReactionSet,
    *,
    kind: str = "equilibrium",
    model: Model = None,
    volume: float | Array = 1.0,
    t_out: float | Array | None = None,
    duty: float | Array | None = None,
    dp: float | Array = 0.0,
    steps: int = 64,
    integration_rtol: float = 1e-05,
    integration_atol: float = 1e-08,
    tol: float = 1e-10,
    max_iter: int = 100,
    check: bool = True,
) -> ReactionResult

Solve a homogeneous equilibrium reactor, CSTR, or PFR with a common package.

Parameters:

Name	Type	Description	Default
`feed`	`Stream`	Inlet material and phase state.	required
`system`	`ReactionSet`	Validated reactions, kinetic laws, phase, and rate basis.	required
`kind`	`str`	`equilibrium`, `cstr`, or `pfr`.	`'equilibrium'`
`model`	`Model`	Property package; defaults to Peng-Robinson.	`None`
`volume`	`float \| Array`	Reacting-phase volume (m^3), required positive for kinetic units.	`1.0`
`t_out`	`float \| Array \| None`	Isothermal temperature. Omission retains inlet T if duty is omitted.	`None`
`duty`	`float \| Array \| None`	Specified heat input (W); zero selects adiabatic operation. Mutually exclusive with t_out. PFR heat is distributed uniformly.	`None`
`dp`	`float \| Array`	Nonnegative pressure loss (Pa); PFR pressure decreases linearly.	`0.0`
`steps`	`int`	Coarse PFR mesh size; a 2*steps mesh supplies the returned solution.	`64`
`integration_rtol`	`float`	Relative step-doubling and energy error scale.	`1e-05`
`integration_atol`	`float`	Absolute step-doubling scale in normalized coordinates.	`1e-08`
`tol`	`float`	Scaled nonlinear residual tolerance.	`1e-10`
`max_iter`	`int`	Newton iteration cap.	`100`
`check`	`bool`	Raise on a rejected concrete result; traced callers inspect report.	`True`

Returns:

Type	Description
`ReactionResult`	A ReactionResult retaining failed primals and nonfinite failed derivatives.
`ReactionResult`	PFRs compare coarse/refined extents and temperatures, independently audit
`ReactionResult`	energy, and reject negative inventory without clipping the final solution.

Reactors & reactive separations¶

Reactors¶

reactors ¶

StoichiometricResult ¶

outlets property ¶

heat property ¶

BatchResult ¶

equilibrium_reactor ¶

cstr ¶

pfr ¶

stoichiometric_reactor ¶

batch_reactor ¶

conversion ¶

Reactive separations¶

reactive ¶

ReactiveFlashResult ¶

outlets property ¶

heat property ¶

reactive_flash ¶

reactive_column ¶

Checked common-package reactors¶

reaction_units ¶

ReactionResult ¶

outlets property ¶

heat property ¶

converged property ¶

check ¶

reaction_parameter_validity ¶

reaction_reactor ¶

outlets `property` ¶

heat `property` ¶

outlets `property` ¶

heat `property` ¶

outlets `property` ¶

heat `property` ¶

converged `property` ¶