fugacio-thermo 0.0.1__tar.gz

fugacio_thermo-0.0.1/.gitignore

@@ -0,0 +1,32 @@
+# Byte-compiled / build artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.import_linter_cache/
+.jax_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Docs build
+site/
+# Material social-cards plugin cache (downloaded fonts + generated card layers)
+.cache/
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/

fugacio_thermo-0.0.1/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: fugacio-thermo
+Version: 0.0.1
+Summary: Differentiable thermodynamics and physical-property engine for the Fugacio stack.
+Author-email: Owen Carey <37121709+owenthcarey@users.noreply.github.com>
+License-Expression: Apache-2.0
+Keywords: activity-coefficients,chemical-engineering,jax,phase-equilibrium,thermodynamics
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.11
+Requires-Dist: jax>=0.4.34
+Description-Content-Type: text/markdown
+
+# fugacio-thermo
+
+Differentiable thermodynamics and physical-property engine for the
+[Fugacio](https://github.com/fugacio/fugacio) stack. Every model is written
+in [JAX](https://github.com/jax-ml/jax), so any output (a fugacity coefficient,
+a saturation pressure, a flash result) is differentiable with respect to
+temperature, pressure, composition, *and* model parameters. The iterative solvers
+(cubic-EOS root, flash, saturation, bubble/dew) carry hand-written
+implicit-function-theorem rules, so gradients flow exactly through them rather
+than through unrolled iterations.
+
+## What's inside
+
+- **Curated open component database** (`DATABASE`, `get`, `component_arrays`):
+  critical constants, acentric factors, Antoine coefficients, and ideal-gas heat
+  capacities for common species.
+- **Ideal-gas properties**: `cp_ig`, `enthalpy_ig`, `entropy_ig`, `gibbs_ig`
+  (plus mixture variants).
+- **Cubic equations of state**: van der Waals, Redlich-Kwong, SRK, Peng-Robinson
+  (`VDW`, `RK`, `SRK`, `PR`), with mixing rules, a differentiable compressibility
+  solver, fugacity coefficients (`ln_phi_mixture`, `ln_phi_pure`), and molar
+  volume.
+- **Real-fluid energy properties**: residual/departure functions
+  (`residual_enthalpy`, `residual_entropy`, `residual_gibbs`, `residual_cp`),
+  real-fluid molar properties (`molar_enthalpy`, `molar_entropy`, `molar_gibbs`,
+  `molar_cp`, `stable_phase`), two-phase `mixture_enthalpy` / `mixture_entropy`,
+  and energy-specified flashes `flash_ph` (isenthalpic) and `flash_ps`
+  (isentropic), the backbone of adiabatic units, valves, compressors, and
+  turbines.
+- **Activity-coefficient models**: Margules, van Laar, Wilson, NRTL, UNIQUAC, and
+  predictive regular-solution / Flory-Huggins, available both as functions and
+  as differentiable `ActivityModel` objects (`nrtl`, `uniquac`, ...) whose
+  parameters are themselves gradient leaves.
+- **Group contribution**: predictive `unifac_activity` and `joback_estimate`
+  (pure-component constants from a structure).
+- **Molecular PC-SAFT**: the perturbed-chain SAFT equation of state
+  (`SaftParameters`, `saft_parameters_for`, `alpha_residual`, `SAFTModel`) with a
+  curated Gross-Sadowski parameter bank, Wertheim TPT1 association for
+  hydrogen-bonding fluids, fugacity / density / residual properties by autodiff,
+  the equilibrium routines `flash_pt_saft`, `bubble_pressure_saft`,
+  `dew_pressure_saft`, `psat_saft`, and `stability_saft`, and differentiable
+  parameter regression (`fit_saft_pure`, `fit_saft_kij`).
+- **Reference state**: pure-liquid reference fugacity (`liquid_reference_fugacity`),
+  the `poynting_factor`, saturation fugacity coefficient, and `henry_constant`.
+- **EOS phase equilibrium**: `rachford_rice`, `flash_pt`, `psat_eos`,
+  `bubble_pressure_eos`, `dew_pressure_eos`, and Michelsen `stability_analysis`.
+- **Non-ideal (gamma-phi) VLE**: `flash_pt_gamma`, `bubble_pressure_gamma`,
+  `dew_pressure_gamma`, and the temperature duals, the route that captures
+  azeotropes and strongly polar mixtures.
+- **Liquid-liquid & three-phase equilibria**: isoactivity `flash_lle` with
+  `tie_line` / `binodal_curve`, three-phase `flash_vlle`, the binary
+  `heterogeneous_azeotrope` solver, and a general tangent-plane stability test
+  (`stability_analysis_general`, `liquid_stability`).
+- **Unified model interface**: `EOSModel`, `GammaPhiModel`, and `SAFTModel` expose
+  the same `flash_pt` / bubble / dew calls, so the rest of the stack switches
+  thermodynamic method (cubic, γ–φ, or molecular PC-SAFT) by swapping one
+  (differentiable) object.
+- **Parameter regression & prediction**: a self-contained `levenberg_marquardt`
+  over arbitrary parameter pytrees with residual builders
+  (`bubble_pressure_residuals`, `activity_residuals`, `lle_residuals`), ready
+  fitters (`fit_nrtl_binary`, `fit_uniquac_binary`), and UNIFAC-to-binary
+  prediction (`predict_nrtl_from_unifac`, `predict_uniquac_from_unifac`) for
+  mixtures without fitted parameters.
+- **Reactions, equilibrium & kinetics**: stoichiometry and standard-state
+  thermochemistry (`Reaction`, `reaction_properties`, `delta_g_rxn`,
+  `equilibrium_constant`), chemical-reaction `equilibrium` (single or simultaneous,
+  ideal-gas or EOS-`phi` basis), and differentiable rate laws (`PowerLaw`,
+  `MassActionReversible`, `LHHW`, `Arrhenius`).
+- **Validation harness**: first-principles consistency checks (Gibbs-Duhem,
+  equifugacity, the `(d ln phi / dP)_T` identity), an AD-vs-finite-difference
+  checker, and optional differential-testing oracles: CoolProp / `chemicals`
+  (pure-fluid properties), `thermo` / Clapeyron.jl (activity coefficients and
+  PC-SAFT), and Cantera (reaction equilibrium and standard-state thermochemistry).
+
+## Example: a differentiable flash
+
+```python
+import jax
+import jax.numpy as jnp
+from fugacio.thermo import PR, component_arrays, flash_pt
+
+arr = component_arrays(["methane", "propane", "n-pentane"])
+z = jnp.array([0.5, 0.3, 0.2])
+
+result = flash_pt(PR, 320.0, 20e5, z, arr["tc"], arr["pc"], arr["omega"])
+result.beta      # vapour fraction (~0.75)
+result.x, result.y  # liquid / vapour compositions
+
+# Gradient of the vapour fraction w.r.t. pressure, straight through the solver:
+dbeta_dP = jax.grad(
+    lambda p: flash_pt(PR, 320.0, p, z, arr["tc"], arr["pc"], arr["omega"]).beta
+)
+dbeta_dP(20e5)
+```
+
+## Example: a non-ideal (gamma-phi) bubble point
+
+```python
+import jax.numpy as jnp
+from fugacio.thermo import bubble_pressure_gamma, component_arrays, nrtl
+
+arr = component_arrays(["ethanol", "water"])
+# NRTL with 1/T interaction coefficients (K); alpha = 0.3.
+model = nrtl(
+    a=jnp.zeros((2, 2)),
+    b=jnp.array([[0.0, 670.0], [310.0, 0.0]]),
+    alpha=jnp.array([[0.0, 0.3], [0.3, 0.0]]),
+)
+P, y = bubble_pressure_gamma(model, 350.0, jnp.array([0.3, 0.7]),
+                             arr["tc"], arr["pc"], arr["omega"])
+# P, y are differentiable w.r.t. T, x, *and* the NRTL parameters.
+```
+
+Part of the `fugacio` namespace; installs independently:
+`pip install fugacio-thermo`.

fugacio_thermo-0.0.1/README.md

@@ -0,0 +1,115 @@
+# fugacio-thermo
+
+Differentiable thermodynamics and physical-property engine for the
+[Fugacio](https://github.com/fugacio/fugacio) stack. Every model is written
+in [JAX](https://github.com/jax-ml/jax), so any output (a fugacity coefficient,
+a saturation pressure, a flash result) is differentiable with respect to
+temperature, pressure, composition, *and* model parameters. The iterative solvers
+(cubic-EOS root, flash, saturation, bubble/dew) carry hand-written
+implicit-function-theorem rules, so gradients flow exactly through them rather
+than through unrolled iterations.
+
+## What's inside
+
+- **Curated open component database** (`DATABASE`, `get`, `component_arrays`):
+  critical constants, acentric factors, Antoine coefficients, and ideal-gas heat
+  capacities for common species.
+- **Ideal-gas properties**: `cp_ig`, `enthalpy_ig`, `entropy_ig`, `gibbs_ig`
+  (plus mixture variants).
+- **Cubic equations of state**: van der Waals, Redlich-Kwong, SRK, Peng-Robinson
+  (`VDW`, `RK`, `SRK`, `PR`), with mixing rules, a differentiable compressibility
+  solver, fugacity coefficients (`ln_phi_mixture`, `ln_phi_pure`), and molar
+  volume.
+- **Real-fluid energy properties**: residual/departure functions
+  (`residual_enthalpy`, `residual_entropy`, `residual_gibbs`, `residual_cp`),
+  real-fluid molar properties (`molar_enthalpy`, `molar_entropy`, `molar_gibbs`,
+  `molar_cp`, `stable_phase`), two-phase `mixture_enthalpy` / `mixture_entropy`,
+  and energy-specified flashes `flash_ph` (isenthalpic) and `flash_ps`
+  (isentropic), the backbone of adiabatic units, valves, compressors, and
+  turbines.
+- **Activity-coefficient models**: Margules, van Laar, Wilson, NRTL, UNIQUAC, and
+  predictive regular-solution / Flory-Huggins, available both as functions and
+  as differentiable `ActivityModel` objects (`nrtl`, `uniquac`, ...) whose
+  parameters are themselves gradient leaves.
+- **Group contribution**: predictive `unifac_activity` and `joback_estimate`
+  (pure-component constants from a structure).
+- **Molecular PC-SAFT**: the perturbed-chain SAFT equation of state
+  (`SaftParameters`, `saft_parameters_for`, `alpha_residual`, `SAFTModel`) with a
+  curated Gross-Sadowski parameter bank, Wertheim TPT1 association for
+  hydrogen-bonding fluids, fugacity / density / residual properties by autodiff,
+  the equilibrium routines `flash_pt_saft`, `bubble_pressure_saft`,
+  `dew_pressure_saft`, `psat_saft`, and `stability_saft`, and differentiable
+  parameter regression (`fit_saft_pure`, `fit_saft_kij`).
+- **Reference state**: pure-liquid reference fugacity (`liquid_reference_fugacity`),
+  the `poynting_factor`, saturation fugacity coefficient, and `henry_constant`.
+- **EOS phase equilibrium**: `rachford_rice`, `flash_pt`, `psat_eos`,
+  `bubble_pressure_eos`, `dew_pressure_eos`, and Michelsen `stability_analysis`.
+- **Non-ideal (gamma-phi) VLE**: `flash_pt_gamma`, `bubble_pressure_gamma`,
+  `dew_pressure_gamma`, and the temperature duals, the route that captures
+  azeotropes and strongly polar mixtures.
+- **Liquid-liquid & three-phase equilibria**: isoactivity `flash_lle` with
+  `tie_line` / `binodal_curve`, three-phase `flash_vlle`, the binary
+  `heterogeneous_azeotrope` solver, and a general tangent-plane stability test
+  (`stability_analysis_general`, `liquid_stability`).
+- **Unified model interface**: `EOSModel`, `GammaPhiModel`, and `SAFTModel` expose
+  the same `flash_pt` / bubble / dew calls, so the rest of the stack switches
+  thermodynamic method (cubic, γ–φ, or molecular PC-SAFT) by swapping one
+  (differentiable) object.
+- **Parameter regression & prediction**: a self-contained `levenberg_marquardt`
+  over arbitrary parameter pytrees with residual builders
+  (`bubble_pressure_residuals`, `activity_residuals`, `lle_residuals`), ready
+  fitters (`fit_nrtl_binary`, `fit_uniquac_binary`), and UNIFAC-to-binary
+  prediction (`predict_nrtl_from_unifac`, `predict_uniquac_from_unifac`) for
+  mixtures without fitted parameters.
+- **Reactions, equilibrium & kinetics**: stoichiometry and standard-state
+  thermochemistry (`Reaction`, `reaction_properties`, `delta_g_rxn`,
+  `equilibrium_constant`), chemical-reaction `equilibrium` (single or simultaneous,
+  ideal-gas or EOS-`phi` basis), and differentiable rate laws (`PowerLaw`,
+  `MassActionReversible`, `LHHW`, `Arrhenius`).
+- **Validation harness**: first-principles consistency checks (Gibbs-Duhem,
+  equifugacity, the `(d ln phi / dP)_T` identity), an AD-vs-finite-difference
+  checker, and optional differential-testing oracles: CoolProp / `chemicals`
+  (pure-fluid properties), `thermo` / Clapeyron.jl (activity coefficients and
+  PC-SAFT), and Cantera (reaction equilibrium and standard-state thermochemistry).
+
+## Example: a differentiable flash
+
+```python
+import jax
+import jax.numpy as jnp
+from fugacio.thermo import PR, component_arrays, flash_pt
+
+arr = component_arrays(["methane", "propane", "n-pentane"])
+z = jnp.array([0.5, 0.3, 0.2])
+
+result = flash_pt(PR, 320.0, 20e5, z, arr["tc"], arr["pc"], arr["omega"])
+result.beta      # vapour fraction (~0.75)
+result.x, result.y  # liquid / vapour compositions
+
+# Gradient of the vapour fraction w.r.t. pressure, straight through the solver:
+dbeta_dP = jax.grad(
+    lambda p: flash_pt(PR, 320.0, p, z, arr["tc"], arr["pc"], arr["omega"]).beta
+)
+dbeta_dP(20e5)
+```
+
+## Example: a non-ideal (gamma-phi) bubble point
+
+```python
+import jax.numpy as jnp
+from fugacio.thermo import bubble_pressure_gamma, component_arrays, nrtl
+
+arr = component_arrays(["ethanol", "water"])
+# NRTL with 1/T interaction coefficients (K); alpha = 0.3.
+model = nrtl(
+    a=jnp.zeros((2, 2)),
+    b=jnp.array([[0.0, 670.0], [310.0, 0.0]]),
+    alpha=jnp.array([[0.0, 0.3], [0.3, 0.0]]),
+)
+P, y = bubble_pressure_gamma(model, 350.0, jnp.array([0.3, 0.7]),
+                             arr["tc"], arr["pc"], arr["omega"])
+# P, y are differentiable w.r.t. T, x, *and* the NRTL parameters.
+```
+
+Part of the `fugacio` namespace; installs independently:
+`pip install fugacio-thermo`.

fugacio_thermo-0.0.1/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "fugacio-thermo"
+version = "0.0.1"
+description = "Differentiable thermodynamics and physical-property engine for the Fugacio stack."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [
+    { name = "Owen Carey", email = "37121709+owenthcarey@users.noreply.github.com" },
+]
+keywords = [
+    "thermodynamics",
+    "chemical-engineering",
+    "jax",
+    "phase-equilibrium",
+    "activity-coefficients",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Chemistry",
+]
+dependencies = [
+    "jax>=0.4.34",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fugacio"]