torch-flash 0.2.0

Differentiable phase-equilibrium flash calculations built on PyTorch

torch-flash is a typed, differentiable thermodynamics and phase-equilibrium library built on PyTorch. Homogeneous-state properties are independent of equilibrium solvers: a supplied composition, temperature, and pressure can be evaluated directly and differentiated for optimization, machine learning, or coupled simulation.

The current model coverage, assumptions, and limitations are documented in Model scope.

Installation

python -m pip install torch-flash

Optional package capabilities are available through the groups, intel, and gpu extras:

python -m pip install "torch-flash[groups]"
python -m pip install "torch-flash[intel]"
python -m pip install "torch-flash[gpu]"

The intel and gpu dependencies are currently published for Linux and Windows. GPU use additionally requires a compatible CUDA runtime and device.

Development, documentation, notebook, external-comparison, and benchmark dependencies remain in their dedicated Pixi environments:

pixi install -e test
pixi run -e test test-cov

For maintainers, pixi.toml is the dependency source of truth and the package version is synchronized across release metadata through Pixi tasks:

pixi run sync-deps
pixi run sync-deps-check
pixi run bump-version 0.1.3 --dry-run
pixi run bump-version 0.1.3

See the contribution guide for the dependency-export boundary, synchronized version files, and release checks.

Quick start

import torch

from torch_flash import (
    ChemicalState,
    component_set,
    configure,
    peng_robinson_1978,
    phase_properties,
    state_derivatives,
    two_phase_flash,
)

runtime = configure(device="cpu", dtype=torch.float64)
model = peng_robinson_1978(component_set(("methane", "n_butane")))
state = ChemicalState(
    temperature=runtime.tensor(270.0),       # K
    pressure=runtime.tensor(3.0e6),          # Pa
    composition=runtime.tensor([0.5, 0.5]),  # mole fractions
)

# Evaluate the supplied homogeneous state without solving an equilibrium.
properties = phase_properties(model, state, phase="stable")
print(properties.compressibility_factor)
print(properties.fugacities, properties.log_fugacities)
print(properties.chemical_potentials)
print(properties.molar_helmholtz_energy, properties.molar_gibbs_energy)
print(properties.reduced_helmholtz_energy, properties.reduced_gibbs_energy)

# Derivatives are evaluated with PyTorch automatic differentiation.
derivatives = state_derivatives(model, state)
print(derivatives.dfugacity_dpressure)
print(derivatives.dchemical_potential_dtemperature)

# Stability-tested two-phase TP flash.
equilibrium = two_phase_flash(model, state)
print(equilibrium.phase_fractions)
print(equilibrium.phase_kinds, equilibrium.phase_regime)
for phase in equilibrium.phases:
    print(phase.composition)

Thermodynamic inputs and outputs use SI units. Float64 is strongly recommended for phase-equilibrium calculations. Device, dtype, CPU-thread, and deterministic-execution policies are set before model construction; see Runtime configuration.

Capabilities

• SRK, PR76, and PR78 cubic equations of state, with attractive and co-volume binary interactions, PPR78 group-contribution BIPs, and Pedersen or Péneloux/Whitson volume translation (Soave, 1972; Peng and Robinson, 1976; Jaubert and Mutelet, 2004).
• NRTL, Wilson, original VLE-UNIFAC, and Huron–Vidal mixing rules (Renon and Prausnitz, 1968; Huron and Vidal, 1979; Hansen et al., 1991).
• SRK-CPA association models with configurable site schemes, cross-association rules, hydrocarbon/water parameters, and heavy-cut adapters (Kontogeorgis et al., 1996).
• Native GERG-2008 and EOS-CG-2021 multiparameter Helmholtz mixture models (Kunz and Wagner, 2012; Neumann et al., 2023).
• Fugacity, chemical potential, compressibility, molar volume, Helmholtz and Gibbs energies, caloric and response properties, and PyTorch derivatives at a specified state.
• Tangent-plane stability, two-phase TP flash, fixed-phase-count multiphase flash, phase identification, bubble/dew calculations, phase-envelope continuation, and a binary critical-point solver (Michelsen, 1982).
• Model-neutral pseudo-component splitting, characterization, lumping, and model-specific property adapters.
• Differentiable LBC and corresponding-states viscosity models.
• Trainable interaction parameters and Helmholtz coefficients for reparameterization against user data.

The package does not currently provide automatic global phase-count discovery, reactive equilibrium, or a general multicomponent critical-locus arclength solver. Fixed-phase-count multiphase calculations require physically meaningful initialization. Detailed model-specific boundaries are stated in Model scope.

Parameter databases

Component properties and bundled model parameterizations are stored in versioned YAML with canonical component names, declared SI units, model identity, and source metadata. Models may use packaged parameter sets, custom YAML files, typed parameter objects, or user-supplied tensors:

from torch_flash import (
    available_parameter_sets,
    component_set,
    cubic_eos,
    cubic_interaction_parameters,
    multiparameter_eos,
)

components = component_set(("methane", "n_decane"))
interactions = cubic_interaction_parameters(
    components,
    "binary-interaction.segovia-2017-methane-n-decane",
)
pr78 = cubic_eos(
    components,
    "cubic.pr-1978",
    kij=interactions.kij,
    lij=interactions.lij,
)
gerg = multiparameter_eos("gerg2008", ("CO2", "CH4"))
print(available_parameter_sets(model_kind="cubic"))

Parsed database documents are cached; model instances and their tensors are not shared. Custom schemas, canonical naming, units, cache controls, and trainable-parameter conventions are described in Component and model parameter databases.

Documentation

• Rendered documentation
• Getting started
• Theoretical background
• Model scope and numerical assumptions
• Python API
• Parameter and component databases
• Runtime configuration
• High-performance PyTorch setup and benchmarks
• Verification and validation evidence
• Scientific references and data provenance
• Licensing and redistribution policy
• Contributing

Generative-AI disclosure

Following the transparency and responsibility principles in the CNPq Policy for Integrity in Scientific Activity, generative-AI tools—OpenAI Codex and GPT models—assisted code implementation, refactoring, and documentation. Human contributors remain responsible for scientific choices, source verification, tests, review, and released artifacts. Contributions produced with AI assistance are held to the same review and reproducibility requirements as all other work.

License

Source code is distributed under the GNU Lesser General Public License v2.1. Third-party notices and data-specific terms are recorded in THIRD_PARTY_NOTICES.md.

Institutional Support

torch-flash receives institutional support from the Laboratório Nacional de Computação Científica (LNCC), a research unit of the Ministério da Ciência, Tecnologia e Inovação (MCTI), Brazil, and is partially developed at the Universidade do Estado de Santa Catarina (UDESC). The project is developed by the ThermoPhase — Fluid and Complex Systems Research Group.