fugacio-sim 0.2.0__tar.gz → 0.3.0__tar.gz

{fugacio_sim-0.2.0 → fugacio_sim-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: fugacio-sim
-Version: 0.2.0
+Version: 0.3.0
 Summary: Differentiable steady-state and dynamic process flowsheet simulator (Fugacio).
 Author-email: Owen Carey <37121709+owenthcarey@users.noreply.github.com>
 License-Expression: Apache-2.0
@@ -10,7 +10,7 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Chemistry
 Requires-Python: >=3.11
-Requires-Dist: fugacio-thermo==0.2.0
+Requires-Dist: fugacio-thermo==0.3.0
 Requires-Dist: jax>=0.4.34
 Description-Content-Type: text/markdown
 
@@ -34,6 +34,15 @@ Any `Stream` has a two-phase-aware enthalpy and entropy (via the
 just material balances: `molar_enthalpy`, `molar_entropy`, `enthalpy_flow`,
 `entropy_flow`, `mass_flow`, `molar_mass`.
 
+## Property packages
+
+Every energy-balanced unit, the rigorous column, the two-sided heat exchanger,
+and the equation-oriented engine take a `model=` argument: a
+`fugacio.thermo.PropertyPackage` built with `package_for(components, method)`
+for any method in `METHODS` (`"pr"`, `"srk"`, `"rk"`, `"vdw"`, `"nrtl"`,
+`"uniquac"`, `"unifac"`, `"dortmund"`, `"pcsaft"`, `"iapws"`). Omitting it keeps
+the Peng-Robinson default.
+
 ## Unit operations (rigorous material + energy balances)
 
 - `flash_drum`: isothermal-isobaric vapour/liquid separator.
@@ -43,15 +52,22 @@ just material balances: `molar_enthalpy`, `molar_entropy`, `enthalpy_flow`,
 - `compressor` / `turbine`: isentropic machines with an efficiency.
 - `mix`: adiabatic, energy-balanced mixer (exact material balance).
 - `splitter` / `component_separator`: flow split and idealised component split.
+- `heat_exchanger`: two-sided countercurrent (or parallel) exchanger with
+  rigorous T-Q curves on both sides, zone-wise LMTD, and one closing spec
+  (`duty`, `t_hot_out`, `t_cold_out`, `min_approach`, or `ua`); each side may
+  use its own property package.
 - `bubble_pressure` / `antoine_psat`: lightweight modified-Raoult helpers.
 
 ## Flowsheets with recycle
 
 `tear_solve` closes a recycle by solving the tear fixed point
-`tear = g(tear, theta)` with a Wegstein-accelerated iteration, and
-differentiates the *converged* flowsheet by the implicit function theorem: a
-gradient through the recycle costs one adjoint solve regardless of iteration
-count. `Flowsheet` is a small declarative builder on top of it.
+`tear = g(tear, theta)` by Wegstein acceleration, Broyden, or full Newton
+(`method=`), and differentiates the *converged* flowsheet by the implicit
+function theorem: a gradient through the recycle costs one adjoint solve
+regardless of iteration count. `Flowsheet` is the declarative builder on top of
+it: register feeds and units in any order and `partition` finds the strongly
+connected blocks (Tarjan), orders them, and selects the tear streams; `solve`
+converges every loop and returns all named streams, differentiable in `theta`.
 
 ## Equation-oriented flowsheeting
 
@@ -64,8 +80,9 @@ the converged plant is differentiable by the implicit function theorem,
 `degrees_of_freedom` checks the unknown/equation balance, and
 `optimize_flowsheet_eo` runs nested or full-space simultaneous optimization. The
 blocks mirror the sequential-modular units (`Mixer`, `Splitter`, `Heater`,
-`Valve`, `Pump`, `Compressor`, `Turbine`, `Flash`, `ComponentSeparator`), so the
-two engines agree on any flowsheet both can express.
+`Valve`, `Pump`, `Compressor`, `Turbine`, `Flash`, `ComponentSeparator`), plus
+`HeatExchanger`, `StoichiometricReactor`, and `Column` (an embedded rigorous
+MESH column), so the two engines agree on any flowsheet both can express.
 
 ```python
 import jax.numpy as jnp
@@ -92,9 +109,15 @@ sol["vapor"].total
 - **Shortcut** (Fenske-Underwood-Gilliland): `fenske_min_stages`,
   `underwood_min_reflux`, `gilliland_stages`, `kirkbride_feed_stage`, and the
   `shortcut_column` wrapper.
-- **Rigorous** `solve_column`: a multistage equilibrium-stage column (Wang-Henke
-  bubble-point, constant molar overflow) with EOS K-values on every stage,
-  differentiable through the fixed-point iteration.
+- **Rigorous MESH** `rigorous_column`: simultaneous-correction
+  (Naphtali-Sandholm) column with full stage energy balances on any property
+  package; multiple feeds (`ColumnFeed`), side draws, stage duties, a pressure
+  profile, Murphree efficiency, total/partial/no condenser, kettle/no reboiler,
+  and design specs as equations (`reflux_ratio`, `distillate_rate`,
+  `bottoms_rate`, `boilup_ratio`, `condenser_duty`, `purity`, `recovery`,
+  `component_flow`, `stage_temperature`). `absorber` and `stripper` wrap it.
+- **Constant molar overflow** `solve_column`: the lighter Wang-Henke
+  bubble-point column, kept for quick estimates.
 
 ## Non-ideal separations & diagrams
 
@@ -168,16 +191,21 @@ recycle = tear_solve(one_pass, guess, {"T": 320.0, "P": 20e5, "r": 0.5})
 ```python
 import jax
 import jax.numpy as jnp
-from fugacio.sim import Stream, solve_column
+from fugacio.sim import ColumnFeed, Stream, distillate_rate, purity, reflux_ratio, rigorous_column
 
 feed = Stream.from_fractions(("propane", "n-butane"), jnp.array([0.5, 0.5]), 100.0, 320.0, 10e5)
-col = solve_column(feed, n_stages=12, feed_stage=6, reflux=2.0, distillate_rate=50.0)
-col.distillate.z  # ~[0.97, 0.03] propane overhead
-
-# Exact gradient of distillate purity w.r.t. reflux ratio:
-jax.grad(
-    lambda r: solve_column(feed, 12, 6, r, 50.0).distillate.z[0]
-)(2.0)
+col = rigorous_column([ColumnFeed(feed, 6)], 12, p=10e5,
+                      specs=[reflux_ratio(2.0), distillate_rate(50.0)])
+col.distillate.z                     # propane overhead
+col.reboiler_duty, col.t             # duty from the stage energy balances; T profile
+
+# Impose the purity instead and ask for the reflux it takes, and its energy cost:
+def reboiler_duty(x_target):
+    res = rigorous_column([ColumnFeed(feed, 6)], 12, p=10e5,
+                          specs=[distillate_rate(50.0), purity("distillate", 0, x_target)])
+    return res.reboiler_duty
+
+jax.grad(reboiler_duty)(0.97)        # W per unit mole fraction, exact
 ```
 
 Part of the `fugacio` namespace; installs independently:

{fugacio_sim-0.2.0 → fugacio_sim-0.3.0}/README.md

@@ -18,6 +18,15 @@ Any `Stream` has a two-phase-aware enthalpy and entropy (via the
 just material balances: `molar_enthalpy`, `molar_entropy`, `enthalpy_flow`,
 `entropy_flow`, `mass_flow`, `molar_mass`.
 
+## Property packages
+
+Every energy-balanced unit, the rigorous column, the two-sided heat exchanger,
+and the equation-oriented engine take a `model=` argument: a
+`fugacio.thermo.PropertyPackage` built with `package_for(components, method)`
+for any method in `METHODS` (`"pr"`, `"srk"`, `"rk"`, `"vdw"`, `"nrtl"`,
+`"uniquac"`, `"unifac"`, `"dortmund"`, `"pcsaft"`, `"iapws"`). Omitting it keeps
+the Peng-Robinson default.
+
 ## Unit operations (rigorous material + energy balances)
 
 - `flash_drum`: isothermal-isobaric vapour/liquid separator.
@@ -27,15 +36,22 @@ just material balances: `molar_enthalpy`, `molar_entropy`, `enthalpy_flow`,
 - `compressor` / `turbine`: isentropic machines with an efficiency.
 - `mix`: adiabatic, energy-balanced mixer (exact material balance).
 - `splitter` / `component_separator`: flow split and idealised component split.
+- `heat_exchanger`: two-sided countercurrent (or parallel) exchanger with
+  rigorous T-Q curves on both sides, zone-wise LMTD, and one closing spec
+  (`duty`, `t_hot_out`, `t_cold_out`, `min_approach`, or `ua`); each side may
+  use its own property package.
 - `bubble_pressure` / `antoine_psat`: lightweight modified-Raoult helpers.
 
 ## Flowsheets with recycle
 
 `tear_solve` closes a recycle by solving the tear fixed point
-`tear = g(tear, theta)` with a Wegstein-accelerated iteration, and
-differentiates the *converged* flowsheet by the implicit function theorem: a
-gradient through the recycle costs one adjoint solve regardless of iteration
-count. `Flowsheet` is a small declarative builder on top of it.
+`tear = g(tear, theta)` by Wegstein acceleration, Broyden, or full Newton
+(`method=`), and differentiates the *converged* flowsheet by the implicit
+function theorem: a gradient through the recycle costs one adjoint solve
+regardless of iteration count. `Flowsheet` is the declarative builder on top of
+it: register feeds and units in any order and `partition` finds the strongly
+connected blocks (Tarjan), orders them, and selects the tear streams; `solve`
+converges every loop and returns all named streams, differentiable in `theta`.
 
 ## Equation-oriented flowsheeting
 
@@ -48,8 +64,9 @@ the converged plant is differentiable by the implicit function theorem,
 `degrees_of_freedom` checks the unknown/equation balance, and
 `optimize_flowsheet_eo` runs nested or full-space simultaneous optimization. The
 blocks mirror the sequential-modular units (`Mixer`, `Splitter`, `Heater`,
-`Valve`, `Pump`, `Compressor`, `Turbine`, `Flash`, `ComponentSeparator`), so the
-two engines agree on any flowsheet both can express.
+`Valve`, `Pump`, `Compressor`, `Turbine`, `Flash`, `ComponentSeparator`), plus
+`HeatExchanger`, `StoichiometricReactor`, and `Column` (an embedded rigorous
+MESH column), so the two engines agree on any flowsheet both can express.
 
 ```python
 import jax.numpy as jnp
@@ -76,9 +93,15 @@ sol["vapor"].total
 - **Shortcut** (Fenske-Underwood-Gilliland): `fenske_min_stages`,
   `underwood_min_reflux`, `gilliland_stages`, `kirkbride_feed_stage`, and the
   `shortcut_column` wrapper.
-- **Rigorous** `solve_column`: a multistage equilibrium-stage column (Wang-Henke
-  bubble-point, constant molar overflow) with EOS K-values on every stage,
-  differentiable through the fixed-point iteration.
+- **Rigorous MESH** `rigorous_column`: simultaneous-correction
+  (Naphtali-Sandholm) column with full stage energy balances on any property
+  package; multiple feeds (`ColumnFeed`), side draws, stage duties, a pressure
+  profile, Murphree efficiency, total/partial/no condenser, kettle/no reboiler,
+  and design specs as equations (`reflux_ratio`, `distillate_rate`,
+  `bottoms_rate`, `boilup_ratio`, `condenser_duty`, `purity`, `recovery`,
+  `component_flow`, `stage_temperature`). `absorber` and `stripper` wrap it.
+- **Constant molar overflow** `solve_column`: the lighter Wang-Henke
+  bubble-point column, kept for quick estimates.
 
 ## Non-ideal separations & diagrams
 
@@ -152,16 +175,21 @@ recycle = tear_solve(one_pass, guess, {"T": 320.0, "P": 20e5, "r": 0.5})
 ```python
 import jax
 import jax.numpy as jnp
-from fugacio.sim import Stream, solve_column
+from fugacio.sim import ColumnFeed, Stream, distillate_rate, purity, reflux_ratio, rigorous_column
 
 feed = Stream.from_fractions(("propane", "n-butane"), jnp.array([0.5, 0.5]), 100.0, 320.0, 10e5)
-col = solve_column(feed, n_stages=12, feed_stage=6, reflux=2.0, distillate_rate=50.0)
-col.distillate.z  # ~[0.97, 0.03] propane overhead
-
-# Exact gradient of distillate purity w.r.t. reflux ratio:
-jax.grad(
-    lambda r: solve_column(feed, 12, 6, r, 50.0).distillate.z[0]
-)(2.0)
+col = rigorous_column([ColumnFeed(feed, 6)], 12, p=10e5,
+                      specs=[reflux_ratio(2.0), distillate_rate(50.0)])
+col.distillate.z                     # propane overhead
+col.reboiler_duty, col.t             # duty from the stage energy balances; T profile
+
+# Impose the purity instead and ask for the reflux it takes, and its energy cost:
+def reboiler_duty(x_target):
+    res = rigorous_column([ColumnFeed(feed, 6)], 12, p=10e5,
+                          specs=[distillate_rate(50.0), purity("distillate", 0, x_target)])
+    return res.reboiler_duty
+
+jax.grad(reboiler_duty)(0.97)        # W per unit mole fraction, exact
 ```
 
 Part of the `fugacio` namespace; installs independently:

{fugacio_sim-0.2.0 → fugacio_sim-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fugacio-sim"
-version = "0.2.0"
+version = "0.3.0"
 description = "Differentiable steady-state and dynamic process flowsheet simulator (Fugacio)."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -22,7 +22,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Chemistry",
 ]
 dependencies = [
-    "fugacio-thermo==0.2.0",
+    "fugacio-thermo==0.3.0",
     "jax>=0.4.34",
 ]
 

{fugacio_sim-0.2.0 → fugacio_sim-0.3.0}/src/fugacio/sim/__init__.py

@@ -116,6 +116,27 @@ from fugacio.sim.diagrams import (
     residue_curve_map,
     txy_diagram,
 )
+from fugacio.sim.distillation import (
+    ColumnFeed,
+    ColumnSpec,
+    RigorousColumnResult,
+    SideDraw,
+    StageDuty,
+    absorber,
+    boilup_ratio,
+    bottoms_rate,
+    component_flow,
+    condenser_duty,
+    distillate_rate,
+    purity,
+    reboiler_duty,
+    recovery,
+    reflux_rate,
+    reflux_ratio,
+    rigorous_column,
+    stage_temperature,
+    stripper,
+)
 from fugacio.sim.dynamics import (
     DynamicCSTR,
     DynamicEstimateResult,
@@ -184,7 +205,8 @@ from fugacio.sim.eo import (
     Valve,
     optimize_flowsheet_eo,
 )
-from fugacio.sim.flowsheet import Flowsheet, tear_solve
+from fugacio.sim.flowsheet import TEAR_METHODS, Flowsheet, Partition, tear_solve
+from fugacio.sim.heat_exchanger import HeatExchangerResult, heat_exchanger
 from fugacio.sim.integration import (
     CompositeCurves,
     Exchanger,
@@ -213,9 +235,12 @@ from fugacio.sim.integration import (
     verify_network,
 )
 from fugacio.sim.models import (
+    METHODS,
     UnifacModel,
     eos_model_for,
+    helmholtz_package_for,
     nrtl_model_for,
+    package_for,
     saft_model_for,
     unifac_model_for,
     uniquac_model_for,
@@ -331,12 +356,16 @@ from fugacio.sim.vle import antoine_psat, bubble_pressure
 __all__ = [
     "CEPCI_DEFAULT",
     "CEPCI_REF",
+    "METHODS",
     "PID",
     "STEAM_LEVELS",
+    "TEAR_METHODS",
     "AzeotropeResult",
     "Block",
     "ClosedLoop",
+    "ColumnFeed",
     "ColumnResult",
+    "ColumnSpec",
     "ComponentSeparator",
     "CompositeCurves",
     "Compressor",
@@ -365,6 +394,7 @@ __all__ = [
     "GrandComposite",
     "HeatCascade",
     "HeatExchangerNetwork",
+    "HeatExchangerResult",
     "HeatStream",
     "Heater",
     "HeaterResult",
@@ -383,6 +413,7 @@ __all__ = [
     "OptimalDtMin",
     "OptimizeResult",
     "PIDState",
+    "Partition",
     "PinchResult",
     "Pump",
     "PumpResult",
@@ -393,10 +424,13 @@ __all__ = [
     "ReactiveFlashResult",
     "ReactorResult",
     "ResidueCurve",
+    "RigorousColumnResult",
     "Scales",
     "ShortcutResult",
+    "SideDraw",
     "SpecResult",
     "Splitter",
+    "StageDuty",
     "StateSpace",
     "SteamHeatingResult",
     "SteamTurbineResult",
@@ -412,6 +446,7 @@ __all__ = [
     "Utility",
     "Valve",
     "WorkResult",
+    "absorber",
     "amigo",
     "annualized_capital",
     "antoine_psat",
@@ -422,6 +457,8 @@ __all__ = [
     "bare_module_cost",
     "batch_reactor",
     "bode",
+    "boilup_ratio",
+    "bottoms_rate",
     "bubble_pressure",
     "c2d",
     "capital_cost_target",
@@ -432,10 +469,12 @@ __all__ = [
     "column_diameter",
     "column_diameter_for",
     "column_height",
+    "component_flow",
     "component_separator",
     "composite_curves",
     "compressor",
     "condensate_flash_fraction",
+    "condenser_duty",
     "constant_setpoint",
     "controller",
     "conversion",
@@ -447,6 +486,7 @@ __all__ = [
     "decanter",
     "discounted_payback",
     "discretize",
+    "distillate_rate",
     "dlqr",
     "enthalpy_flow",
     "entropy_flow",
@@ -463,9 +503,11 @@ __all__ = [
     "gilliland_stages",
     "grand_composite_curve",
     "heat_cascade",
+    "heat_exchanger",
     "heat_exchanger_area",
     "heat_stream",
     "heater",
+    "helmholtz_package_for",
     "iae",
     "imc_tuning",
     "installed_capital",
@@ -507,6 +549,7 @@ __all__ = [
     "optimize_flowsheet_eo",
     "overshoot",
     "p_only",
+    "package_for",
     "pfr",
     "pi",
     "pinch_analysis",
@@ -514,13 +557,19 @@ __all__ = [
     "pressure_factor",
     "pump",
     "purchased_cost",
+    "purity",
     "pxy_diagram",
     "quadratic_tracking",
     "reactive_distillation",
     "reactive_flash",
+    "reboiler_duty",
+    "recovery",
+    "reflux_rate",
+    "reflux_ratio",
     "relative_volatility",
     "residue_curve",
     "residue_curve_map",
+    "rigorous_column",
     "rise_time",
     "saft_model_for",
     "saturated_steam_temperature",
@@ -534,12 +583,14 @@ __all__ = [
     "solve_qp",
     "solve_qp_canonical",
     "splitter",
+    "stage_temperature",
     "steam_enthalpy",
     "steam_heating",
     "steam_quality_after_letdown",
     "steam_turbine",
     "step_info",
     "stoichiometric_reactor",
+    "stripper",
     "supertarget",
     "surface_tension",
     "synthesize_network",
@@ -567,4 +618,4 @@ __all__ = [
     "ziegler_nichols",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"