Streams & properties¶

The differentiable Stream pytree passed between units, and the property bridge that gives any stream a two-phase-aware enthalpy, entropy, density, and transport properties via fugacio.thermo.

Stream¶

stream ¶

Material streams: the data passed between flowsheet unit operations.

A Stream carries per-component molar flows together with temperature and pressure and an optional resolved vapor inventory. It is registered as a JAX pytree (both inventories, T, and P are differentiable leaves while the component names are static metadata) so an entire flowsheet built from streams remains end-to-end differentiable. You can take a gradient of any downstream quantity with respect to a feed flow, temperature, or pressure.

Classes:

Name	Description
`Stream`	A process stream of fixed composition basis.

Stream `dataclass` ¶

Stream(
    n: Array,
    t: Array,
    p: Array,
    components: tuple[str, ...],
    vapor_n: Array | None = None,
)

A process stream of fixed composition basis.

Attributes:

Name	Type	Description
`n`	`Array`	Per-component molar flow rates (mol/s), 1-D array aligned with `components`.
`t`	`Array`	Temperature (K).
`p`	`Array`	Pressure (Pa).
`components`	`tuple[str, ...]`	Canonical component names (static metadata).
`vapor_n`	`Array \| None`	Per-component vapor flows for an explicitly resolved state. A negative sentinel means that a PT flash determines the state. This extra inventory preserves saturation quality between units.

Methods:

Name	Description
`check`	Raise for an invalid concrete stream; compiled callers inspect `report`.
`scaled`	Scale material and phase inventories by the same flow fraction.
`reordered`	Reorder a stream's material and phase inventories without changing it.
`from_fractions`	Build a PT stream, optionally selecting a known liquid or vapor branch.
`from_ph`	Build a stream from pressure and molar enthalpy (Pa, J/mol).
`from_ps`	Build a stream from pressure and molar entropy (Pa, J/mol/K).

report `property` ¶

report: SolveReport

Check finite physical inventories, state, and phase bookkeeping.

phase_known `property` ¶

phase_known: Array

Whether explicit vapor component flows determine the phase split.

total `property` ¶

total: Array

Total molar flow rate (mol/s).

z `property` ¶

z: Array

Mole fractions (the flow normalised to sum to one; all zero for an empty stream).

check ¶

check() -> None

Raise for an invalid concrete stream; compiled callers inspect report.

scaled ¶

scaled(fraction: ArrayLike) -> Stream

Scale material and phase inventories by the same flow fraction.

reordered ¶

reordered(components: tuple[str, ...]) -> Stream

Reorder a stream's material and phase inventories without changing it.

Raises:

Type	Description
`ValueError`	If the requested basis has missing or repeated components.

from_fractions `classmethod` ¶

from_fractions(
    components: tuple[str, ...],
    z: Array,
    flow: ArrayLike,
    t: ArrayLike,
    p: ArrayLike,
    *,
    phase: str | None = None,
) -> Stream

Build a PT stream, optionally selecting a known liquid or vapor branch.

Use phase to distinguish saturated liquid and saturated vapor, which have the same temperature and pressure. For a partially vaporized state, use :meth:from_ph or :meth:from_ps.

Raises:

Type	Description
`ValueError`	If `phase` is not liquid, vapor, or None.

from_ph `classmethod` ¶

from_ph(
    components: tuple[str, ...],
    z: Array,
    flow: ArrayLike,
    p: ArrayLike,
    h: ArrayLike,
    *,
    model: Model = None,
) -> Stream

Build a stream from pressure and molar enthalpy (Pa, J/mol).

model sets the property package and its enthalpy reference. The phase split is retained even on a pure fluid's saturation line.

from_ps `classmethod` ¶

from_ps(
    components: tuple[str, ...],
    z: Array,
    flow: ArrayLike,
    p: ArrayLike,
    s: ArrayLike,
    *,
    model: Model = None,
) -> Stream

Build a stream from pressure and molar entropy (Pa, J/mol/K).

Stream properties¶

properties ¶

Stream property bridge: enthalpy, entropy, flows, and transport for a Stream.

Unit operations close material and energy balances, so they need a stream's enthalpy and entropy, not just its composition. This module resolves a stream's (static) component names to the array constants the fugacio.thermo kernels expect (caching that lookup, since names never change during a solve) and exposes the resulting molar and total-flow properties.

Enthalpy and entropy use the stream's resolved phase inventory when present. Otherwise, they run the equilibrium flash at its (T, P) and blend the phase properties. The same calls handle subcooled liquid, superheated vapor, and partially vaporized streams. Properties are differentiable with respect to the stream's flows, temperature, and pressure (the component constants are not differentiated, which is exactly right: they are reference data, not decision variables).

Which thermodynamic method evaluates those properties is set by the model argument, a fugacio.thermo.PropertyPackage. Left unset, the stream's components resolve to a Peng-Robinson fugacio.thermo.CubicPackage (the historical default, still selectable through the eos / kij arguments). Pass an NRTL/UNIFAC gamma-phi package, a PC-SAFT package, or a reference-fluid package instead and every unit operation downstream uses it for its energy balance as well as its phase split. resolve_package performs that resolution and also upgrades a bare equilibrium model (EOSModel, GammaPhiModel, SAFTModel) to the matching package by attaching the components' ideal-gas heat capacities.

Sizing-grade physical properties are surfaced too: phase densities and volumetric flows (liquid_density, vapor_volumetric_flow), viscosities, thermal conductivities, and surface tension, all evaluated at the stream's state through the curated correlations and mixture rules in fugacio.thermo. A stream-aware Souders-Brown helper (column_diameter_for) wires them straight into the equipment-sizing correlations of fugacio.sim.economics.

Functions:

Name	Description
`default_package`	The cubic-EOS package a stream falls back to when no `model` is given.
`as_package`	Upgrade an equilibrium model to a property package for `components`.
`resolve_package`	Pick the property package a unit should use for `components`.
`molar_enthalpy`	Molar enthalpy of the stream (J/mol), relative to the package's reference.
`molar_entropy`	Molar entropy of the stream (J/mol/K), relative to the package's reference.
`molar_volume`	Two-phase-aware molar volume of the stream (m^3/mol).
`vapor_fraction`	Equilibrium molar vapour fraction of the stream at its `(T, P)`.
`enthalpy_flow`	Total enthalpy flow of the stream (W = J/s).
`entropy_flow`	Total entropy flow of the stream (W/K).
`volumetric_flow`	Actual volumetric flow of the stream at its state (m^3/s).
`molar_mass`	Mole-fraction-averaged molar mass of the stream (g/mol).
`mass_flow`	Total mass flow of the stream (kg/s).
`liquid_density`	Saturated-liquid mass density at the stream's `T` and composition (kg/m^3).
`vapor_density`	Vapour mass density from the EOS at the stream's `(T, P)` (kg/m^3).
`liquid_volumetric_flow`	Volumetric flow if the stream is all liquid (m^3/s).
`vapor_volumetric_flow`	Volumetric flow if the stream is all vapour (m^3/s).
`liquid_viscosity`	Liquid-mixture viscosity at the stream's `T` (Pa*s), Grunberg-Nissan.
`vapor_viscosity`	Dilute-gas mixture viscosity at the stream's `T` (Pa*s), Wilke.
`liquid_thermal_conductivity`	Liquid-mixture thermal conductivity at the stream's `T` (W/m/K), DIPPR9H.
`vapor_thermal_conductivity`	Gas-mixture thermal conductivity at the stream's `T` (W/m/K), Wassiljewa.
`surface_tension`	Liquid-mixture surface tension at the stream's `T` (N/m).
`column_diameter_for`	Souders-Brown column/drum diameter sized from the actual stream states (m).

default_package ¶

default_package(
    components: Sequence[str],
    *,
    eos: CubicEOS = PR,
    kij: Array | None = None,
) -> CubicPackage

The cubic-EOS package a stream falls back to when no model is given.

as_package ¶

as_package(
    model: Any, components: Sequence[str]
) -> PropertyPackage

Upgrade an equilibrium model to a property package for components.

A PropertyPackage is returned unchanged. An EOSModel, GammaPhiModel, or SAFTModel (which know equilibrium but not energy) is completed with the components' ideal-gas heat capacities into the matching package, so the existing model factories in fugacio.sim.models can feed any unit.

Raises:

Type	Description
`TypeError`	if `model` is none of the supported kinds.

resolve_package ¶

resolve_package(
    components: Sequence[str],
    model: Model = None,
    *,
    eos: CubicEOS = PR,
    kij: Array | None = None,
) -> PropertyPackage

Pick the property package a unit should use for components.

model wins when given (upgraded through as_package if it is a bare equilibrium model); otherwise the cubic default built from eos / kij.

Raises:

Type	Description
`ValueError`	if the package's component count does not match the stream's.

molar_enthalpy ¶

molar_enthalpy(
    stream: Stream,
    *,
    model: Model = None,
    eos: CubicEOS = PR,
    kij: Array | None = None,
) -> Array

Molar enthalpy of the stream (J/mol), relative to the package's reference.

molar_entropy ¶

molar_entropy(
    stream: Stream,
    *,
    model: Model = None,
    eos: CubicEOS = PR,
    kij: Array | None = None,
) -> Array

Molar entropy of the stream (J/mol/K), relative to the package's reference.

molar_volume ¶

molar_volume(
    stream: Stream,
    *,
    model: Model = None,
    eos: CubicEOS = PR,
    kij: Array | None = None,
) -> Array

Two-phase-aware molar volume of the stream (m^3/mol).

vapor_fraction ¶

vapor_fraction(
    stream: Stream,
    *,
    model: Model = None,
    eos: CubicEOS = PR,
    kij: Array | None = None,
) -> Array

Equilibrium molar vapour fraction of the stream at its (T, P).

enthalpy_flow ¶

enthalpy_flow(
    stream: Stream,
    *,
    model: Model = None,
    eos: CubicEOS = PR,
    kij: Array | None = None,
) -> Array

Total enthalpy flow of the stream (W = J/s).

entropy_flow ¶

entropy_flow(
    stream: Stream,
    *,
    model: Model = None,
    eos: CubicEOS = PR,
    kij: Array | None = None,
) -> Array

Total entropy flow of the stream (W/K).

volumetric_flow ¶

volumetric_flow(
    stream: Stream,
    *,
    model: Model = None,
    eos: CubicEOS = PR,
    kij: Array | None = None,
) -> Array

Actual volumetric flow of the stream at its state (m^3/s).

molar_mass ¶

molar_mass(stream: Stream) -> Array

Mole-fraction-averaged molar mass of the stream (g/mol).

mass_flow ¶

mass_flow(stream: Stream) -> Array

Total mass flow of the stream (kg/s).

liquid_density ¶

liquid_density(stream: Stream) -> Array

Saturated-liquid mass density at the stream's T and composition (kg/m^3).

vapor_density ¶

vapor_density(
    stream: Stream, *, eos: CubicEOS = PR
) -> Array

Vapour mass density from the EOS at the stream's (T, P) (kg/m^3).

liquid_volumetric_flow ¶

liquid_volumetric_flow(stream: Stream) -> Array

Volumetric flow if the stream is all liquid (m^3/s).

vapor_volumetric_flow ¶

vapor_volumetric_flow(
    stream: Stream, *, eos: CubicEOS = PR
) -> Array

Volumetric flow if the stream is all vapour (m^3/s).

liquid_viscosity ¶

liquid_viscosity(stream: Stream) -> Array

Liquid-mixture viscosity at the stream's T (Pa*s), Grunberg-Nissan.

vapor_viscosity ¶

vapor_viscosity(stream: Stream) -> Array

Dilute-gas mixture viscosity at the stream's T (Pa*s), Wilke.

liquid_thermal_conductivity ¶

liquid_thermal_conductivity(stream: Stream) -> Array

Liquid-mixture thermal conductivity at the stream's T (W/m/K), DIPPR9H.

vapor_thermal_conductivity ¶

vapor_thermal_conductivity(stream: Stream) -> Array

Gas-mixture thermal conductivity at the stream's T (W/m/K), Wassiljewa.

surface_tension ¶

surface_tension(stream: Stream) -> Array

Liquid-mixture surface tension at the stream's T (N/m).

column_diameter_for ¶

column_diameter_for(
    vapor: Stream,
    liquid: Stream | None = None,
    *,
    k_drum: ArrayLike = 0.07,
    flooding: ArrayLike = 0.8,
) -> Array

Souders-Brown column/drum diameter sized from the actual stream states (m).

The vapour density, molar mass, and flow come from vapor; the liquid density from liquid (defaulting to the vapour stream's composition at its own temperature, the saturated-liquid view of the same material, a sensible drum approximation).

Streams & properties¶

Stream¶

stream ¶

Stream dataclass ¶

report property ¶

phase_known property ¶

total property ¶

z property ¶

check ¶

scaled ¶

reordered ¶

from_fractions classmethod ¶

from_ph classmethod ¶

from_ps classmethod ¶

Stream properties¶

properties ¶

default_package ¶

as_package ¶

resolve_package ¶

molar_enthalpy ¶

molar_entropy ¶

molar_volume ¶

vapor_fraction ¶

enthalpy_flow ¶

entropy_flow ¶

volumetric_flow ¶

molar_mass ¶

mass_flow ¶

liquid_density ¶

vapor_density ¶

liquid_volumetric_flow ¶

vapor_volumetric_flow ¶

liquid_viscosity ¶

vapor_viscosity ¶

liquid_thermal_conductivity ¶

vapor_thermal_conductivity ¶

surface_tension ¶

column_diameter_for ¶

Stream `dataclass` ¶

report `property` ¶

phase_known `property` ¶

total `property` ¶

z `property` ¶

from_fractions `classmethod` ¶

from_ph `classmethod` ¶

from_ps `classmethod` ¶