Physical acceptance and provenance

acceptance

Physical acceptance shared by checked flashes, process audits, and tools.

A small numerical residual alone doesn't establish a physical solution. These checks separately grade input validity, component closure, present-phase normalization, equifugacity, energy/entropy closure, finite-start tangent-plane stability, and parameter applicability. Stability search success isn't a proof of a global minimum; the search scope is always reported.

Classes:

Name	Description
AcceptancePolicy	Explicit physical tolerances and optional extrapolation/stability choices.
PhysicalReport	JAX-compatible independent acceptance criteria and their observed errors.
CheckedFlash	PT flash value plus physical acceptance; failed values have invalid derivatives.
CheckedEnergyFlash	PH/PS state plus independent physical and specified-property acceptance.
PhysicalAcceptanceError	A concrete state failed a physical criterion, with its report attached.

Functions:

Name	Description
require_accepted	Raise for rejected host states; compiled callers inspect report.accepted.
accepted_value	Retain a failed primal for diagnosis while invalidating its derivative.
equilibrium_residual	Present-phase log-fugacity residual, ignoring only exactly absent components.
phase_stability	Search both liquid and vapor trial phases against the returned common tangent.
assess_flash	Independently assess a returned PT/PH/PS state, including maliciously supplied states.
flash_pt_checked	Solve PT, assess physics, and attach derivative validity to the returned values.
flash_ph_checked	PH flash with energy, equilibrium, stability, and applicability acceptance.
flash_ps_checked	PS flash with entropy, equilibrium, stability, and applicability acceptance.

AcceptancePolicy dataclass

AcceptancePolicy(
    material_tolerance: float = 1e-08,
    equilibrium_tolerance: float = 1e-07,
    energy_relative_tolerance: float = 1e-07,
    stability_tolerance: float = 1e-07,
    stability_iterations: int = 160,
    check_stability: bool = True,
    allow_extrapolation: bool = False,
)

Explicit physical tolerances and optional extrapolation/stability choices.

PhysicalReport

Bases: NamedTuple

JAX-compatible independent acceptance criteria and their observed errors.

Methods:

Name	Description
to_dict	Strict JSON with unchecked criteria represented explicitly.

to_dict

to_dict() -> dict[str, Any]

Strict JSON with unchecked criteria represented explicitly.

CheckedFlash

Bases: NamedTuple

PT flash value plus physical acceptance; failed values have invalid derivatives.

CheckedEnergyFlash

Bases: NamedTuple

PH/PS state plus independent physical and specified-property acceptance.

PhysicalAcceptanceError

PhysicalAcceptanceError(
    report: PhysicalReport,
    context: str = "thermodynamic state",
)

Bases: RuntimeError

A concrete state failed a physical criterion, with its report attached.

require_accepted

require_accepted(
    report: PhysicalReport,
    context: str = "thermodynamic state",
) -> None

Raise for rejected host states; compiled callers inspect report.accepted.

accepted_value

accepted_value(value: Array, accepted: Array) -> Array

Retain a failed primal for diagnosis while invalidating its derivative.

equilibrium_residual

equilibrium_residual(
    pkg: PropertyPackage,
    t: Array | float,
    p: Array | float,
    result: FlashResult,
    z: Array,
) -> Array

Present-phase log-fugacity residual, ignoring only exactly absent components.

phase_stability

phase_stability(
    pkg: PropertyPackage,
    t: Array | float,
    p: Array | float,
    z: Array,
    result: FlashResult,
    *,
    iterations: int = 160,
    tolerance: float = 1e-07,
) -> tuple[Array, Array]

Search both liquid and vapor trial phases against the returned common tangent.

Starts include the feed, returned phases, and every component enrichment. Exactly absent components stay absent. Acceptance requires stationary trials and nonnegative observed TPD. A negative TPD rejects even if a trial stalled.

assess_flash

assess_flash(
    pkg: PropertyPackage,
    t: Array | float,
    p: Array | float,
    z: Array,
    result: FlashResult,
    *,
    numerical: SolveReport | None = None,
    target: Array | float | None = None,
    prop: str = "enthalpy",
    policy: AcceptancePolicy = DEFAULT_POLICY,
) -> PhysicalReport

Independently assess a returned PT/PH/PS state, including maliciously supplied states.

When no iteration report is supplied, numerical status grades the state residual and reports zero iterations. It doesn't invent an iteration log. An absent phase needn't be normalized; every present phase must be.

flash_pt_checked

flash_pt_checked(
    pkg: PropertyPackage,
    t: Array | float,
    p: Array | float,
    z: Array,
    *,
    policy: AcceptancePolicy = DEFAULT_POLICY,
    **options: Any,
) -> CheckedFlash

Solve PT, assess physics, and attach derivative validity to the returned values.

flash_ph_checked

flash_ph_checked(
    pkg: PropertyPackage,
    p: Array | float,
    h: Array | float,
    z: Array,
    *,
    policy: AcceptancePolicy = DEFAULT_POLICY,
    **options: Any,
) -> CheckedEnergyFlash

PH flash with energy, equilibrium, stability, and applicability acceptance.

flash_ps_checked

flash_ps_checked(
    pkg: PropertyPackage,
    p: Array | float,
    s: Array | float,
    z: Array,
    *,
    policy: AcceptancePolicy = DEFAULT_POLICY,
    **options: Any,
) -> CheckedEnergyFlash

PS flash with entropy, equilibrium, stability, and applicability acceptance.

provenance

Hashable parameter evidence and explicit applicability assessments.

Evidence is static JAX metadata; parameter arrays remain differentiable leaves. Curated and predictive parameters aren't automatically measured or qualified. Unknown validation bounds are reported as unknown, never as infinite coverage.

Classes:

Name	Description
PairEvidence	Origin of one interaction pair, in the package's component order.
PackageEvidence	Immutable provenance, model assumptions, and observed parameter bounds.
ApplicabilityReport	Array-valued condition checks; unknown ranges remain separately visible.

Functions:

Name	Description
assess_applicability	Check declared ranges without inferring empirical validity from convergence.
database_evidence	Describe actual factory choices, distinguishing missing pairs from zero assumptions.

PairEvidence dataclass

PairEvidence(
    components: tuple[str, str], kind: str, source: str
)

Origin of one interaction pair, in the package's component order.

PackageEvidence dataclass

PackageEvidence(
    method: str = "custom",
    components: tuple[str, ...] = (),
    pairs: tuple[PairEvidence, ...] = (),
    assumptions: tuple[str, ...] = (),
    sources: tuple[tuple[str, str], ...] = (),
    temperature_range: tuple[float, float] | None = None,
    pressure_range: tuple[float, float] | None = None,
    composition_range: tuple[float, float] | None = None,
    qualification_id: str | None = None,
    missing_components: tuple[str, ...] = (),
)

Immutable provenance, model assumptions, and observed parameter bounds.

Bounds describe the data used for parameter estimation, not a proof of model validity. A qualification ID identifies a separate validation artifact.

Methods:

Name	Description
to_dict	JSON-compatible provenance, with unknown bounds represented by null.

to_dict

to_dict() -> dict[str, Any]

JSON-compatible provenance, with unknown bounds represented by null.

ApplicabilityReport

Bases: NamedTuple

Array-valued condition checks; unknown ranges remain separately visible.

Methods:

Name	Description
to_dict	Concrete condition report, including unknown bounds and assumptions.

Attributes:

Name	Type	Description
accepted	Array	Parameters exist and no declared bound is exceeded.

accepted property

accepted: Array

Parameters exist and no declared bound is exceeded.

to_dict

to_dict() -> dict[str, Any]

Concrete condition report, including unknown bounds and assumptions.

assess_applicability

assess_applicability(
    evidence: PackageEvidence,
    t: Array | float,
    p: Array | float,
    z: Array,
) -> ApplicabilityReport

Check declared ranges without inferring empirical validity from convergence.

database_evidence

database_evidence(
    components: tuple[str, ...],
    method: str,
    *,
    allow_ideal: bool = False,
    use_database_kij: bool = False,
    explicit_kij: bool = False,
) -> PackageEvidence

Describe actual factory choices, distinguishing missing pairs from zero assumptions.