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 (build one by name with fugacio.sim.models.package_for). Left unset, the stream's components resolve to a Peng-Robinson fugacio.thermo.CubicPackage. 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 checks that the package describes the stream's components in the stream's order.

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.
`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`	Molar vapour fraction: the retained inventory, else the equilibrium at `(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`	Vapor mass density on the package's vapor branch 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 vapor (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.

resolve_package ¶

resolve_package(
    components: Sequence[str], model: Model = None
) -> PropertyPackage

Pick the property package a unit should use for components.

model wins when given; otherwise the Peng-Robinson default.

Raises:

Type	Description
`TypeError`	if `model` isn't a property package.
`ValueError`	if the package's components don't match the stream's.

molar_enthalpy ¶

molar_enthalpy(
    stream: Stream, *, model: Model = None
) -> Array

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

molar_entropy ¶

molar_entropy(
    stream: Stream, *, model: Model = 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
) -> Array

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

vapor_fraction ¶

vapor_fraction(
    stream: Stream, *, model: Model = None
) -> Array

Molar vapour fraction: the retained inventory, else the equilibrium at (T, P).

enthalpy_flow ¶

enthalpy_flow(
    stream: Stream, *, model: Model = None
) -> Array

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

entropy_flow ¶

entropy_flow(
    stream: Stream, *, model: Model = None
) -> Array

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

volumetric_flow ¶

volumetric_flow(
    stream: Stream, *, model: Model = 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, *, model: Model = None
) -> Array

Vapor mass density on the package's vapor branch 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, *, model: Model = None
) -> Array

Volumetric flow if the stream is all vapor (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,
    model: Model = None,
) -> 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 ¶

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` ¶