openflume 0.3.1__tar.gz

openflume-0.3.1/.gitignore

@@ -0,0 +1,106 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# Test & coverage
+test-results/
+playwright-report/
+coverage/
+*.lcov
+
+# Logs
+*.log
+npm-debug.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Local env
+.env
+
+# Python venv for scripts/build-cea-tables.py (offline table generator only —
+# never imported at runtime; see docs/combustion.md)
+.venv-cea/
+__pycache__/
+.env.local
+
+# Misc
+*.tgz
+debug_*.ts
+debug-*.ts
+check_*.ts
+check-*.ts
+diag_*.ts
+diag-*.ts
+scratch_*.ts
+scratch-*.ts
+tmp_*.ts
+tmp-*.ts
+# Root-level scratch scripts named with suffixes (e.g. nh3_debug.ts, nh3_probe.mjs)
+/*_debug*.ts
+/*_debug*.mjs
+/*_probe*.ts
+/*_probe*.mjs
+# Preferred home for local scratch work
+/scratch/
+
+# Vite cache
+.vite/
+
+# Validation source documents — re-fetchable via URLs/DOIs in the CATALOG files
+validation/**/*.pdf
+
+# Cloned upstream repo (nested .git) — re-clonable:
+#   git clone github.com/fateh-btpfl/FlowBoilingHTC && git checkout f2e6d83
+# (see validation/references/CATALOG_TIERS.md, tier-5 entry #31)
+validation/references/tier5/FlowBoilingHTC/
+
+# QC render PNGs (~31 MB, regenerable via validation/qc_review/build_gallery.py) —
+# the gallery scripts/HTML under qc_review/ ARE committed
+validation/qc_review/pdf_pages/
+validation/qc_review/plots/
+
+# Python bytecode from validation extraction scripts
+__pycache__/
+
+# Local digitization scratch workspaces (untracked, regenerable): the ~97 MB
+# nbs9264_verify replot/screenshot workspace and the clicker analysis overlays.
+# Canonical digitized CSVs, calibrations, and annotations remain tracked.
+validation/data/digitized/chilldown/nbs9264_verify/
+validation/data/digitized/chilldown/nbs9264_clicker/analysis/
+
+# Regenerable digitization workspace outputs (retain source points/logs/docs)
+validation/data/digitized/chilldown/*/auto/cache/
+validation/data/digitized/chilldown/*/auto/overlays/
+validation/data/digitized/chilldown/*/analysis/previews/
+validation/data/digitized/chilldown/*/analysis/overlays/
+validation/data/digitized/chilldown/*/analysis/*.png
+validation/data/digitized/chilldown/*/analysis/rejected_*/
+validation/data/digitized/chilldown/*/previews/
+validation/data/digitized/chilldown/*/shots/
+validation/data/digitized/chilldown/*/rejected_*/
+validation/data/digitized/chilldown/*/fast_extract/**/cache.npz
+validation/data/digitized/chilldown/*/fast_extract/**/.preprocess_time.json
+validation/data/digitized/chilldown/*/fast_extract/**/diagnostics.png
+validation/data/digitized/chilldown/*/fast_extract/**/overlay.png
+
+# Python package (python/): bundled JS core + license copy are build
+# artifacts of `npm run build:python`; wheels/sdists of `python -m build`.
+python/src/openflume/_js/
+python/LICENSE
+python/dist/
+python/build/
+.venv/
+*.egg-info/
+.pytest_cache/

openflume-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenFLUME contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openflume-0.3.1/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: openflume
+Version: 0.3.1
+Summary: Python API for the OpenFLUME thermal-fluid network solver (steady and transient, real fluids via CoolProp).
+Project-URL: Homepage, https://github.com/OpenFLUME/OpenFLUME
+Project-URL: Documentation, https://github.com/OpenFLUME/OpenFLUME/blob/main/docs/python.md
+Project-URL: Issues, https://github.com/OpenFLUME/OpenFLUME/issues
+Project-URL: Changelog, https://github.com/OpenFLUME/OpenFLUME/blob/main/CHANGELOG.md
+Author: OpenFLUME contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: CoolProp,GFSSP,aerospace,cryogenics,fluid network,propulsion,solver,thermal-fluid
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: nodejs-wheel-binaries>=22.13
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.24; extra == 'numpy'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# openflume (Python)
+
+Python API for [OpenFLUME](https://github.com/OpenFLUME/OpenFLUME), an open-source
+thermal-fluid network solver for steady and transient analysis of propulsion feed
+systems, cryogenic lines, and tank pressurization, with real-fluid properties from
+CoolProp.
+
+```bash
+pip install openflume            # add [numpy,pandas] for array/DataFrame output
+```
+
+No other installation is needed. The solver core is the same TypeScript code as the
+web app, bundled into the package and run on a Node.js runtime that pip installs as
+a dependency (`nodejs-wheel-binaries`). It is the same solver, with the same
+verification record, not a port.
+
+## Quick start
+
+```python
+import openflume as of
+
+net = of.load("feed_system.fn")  # .fn from the web app, or .json
+print(net.validate())  # [] means runnable
+
+result = net.solve()  # steady or transient per settings.mode
+print(result.converged, result.node("tank")["pressure"])  # SI units: Pa
+```
+
+Start from a bundled example and edit the model as a plain dict:
+
+```python
+net = of.example("Tank blowdown")
+net.settings["endTime"] = 2.0
+net.branch("orifice")["component"]["cd"] = 0.65
+
+tr = net.solve(progress=lambda p: print(f"t = {p['time']:.3f} s", end="\r"))
+t, p = tr.times, tr.series("tank", "pressure")  # numpy arrays if numpy is installed
+df = tr.frame()  # pandas: index time, columns (id, quantity)
+```
+
+Parameter sweeps are ordinary Python:
+
+```python
+base = of.example("Sanity: orifice hand-calc")
+for cd in (0.55, 0.60, 0.65):
+    net = base.copy()
+    net.branch("o")["component"]["cd"] = cd
+    print(cd, net.solve().branch("o")["mdot"])
+```
+
+Fluid properties use the same EOS models as the solver:
+
+```python
+lox = of.Fluid.real("Oxygen")
+lox.density(2e6, 95.0)  # kg/m³
+lox.saturation_temperature([1e5, 5e5, 1e6])
+of.fluids(curated=True)  # CoolProp HEOS catalogue
+of.combustion_gas("lox-rp1", pc=7e6, of=2.6)  # NASA CEA equilibrium tables
+```
+
+Command line:
+
+```bash
+openflume validate model.fn
+openflume solve model.fn -o result.json
+openflume info
+```
+
+## Notes
+
+- **Units** are SI throughout: Pa, K, kg/s, m, m², J/kg.
+- **Always check `result.converged`.** The solver returns its best state either way.
+- **Model format.** `Network.config` is the `NetworkConfig` dict (schema v2) defined in
+  `src/core/schema.ts` and documented in the user manual. `.fn` files round-trip
+  losslessly with the web app.
+- **User code.** Models can embed JavaScript user components (`componentLibrary`). That
+  code runs in the Node process with your user's privileges, so only solve models you
+  trust.
+- **Runtime.** One Node process per `Session` is started on first use and stopped at
+  exit. Set `OPENFLUME_NODE` to use a specific Node.js 22+ executable. For parallel
+  sweeps, use one process (and therefore one session) per worker, e.g. with
+  `concurrent.futures.ProcessPoolExecutor`. Ctrl-C interrupts a running solve.
+
+Full documentation: [docs/python.md](https://github.com/OpenFLUME/OpenFLUME/blob/main/docs/python.md).
+License: MIT.

openflume-0.3.1/README.md

@@ -0,0 +1,85 @@
+# openflume (Python)
+
+Python API for [OpenFLUME](https://github.com/OpenFLUME/OpenFLUME), an open-source
+thermal-fluid network solver for steady and transient analysis of propulsion feed
+systems, cryogenic lines, and tank pressurization, with real-fluid properties from
+CoolProp.
+
+```bash
+pip install openflume            # add [numpy,pandas] for array/DataFrame output
+```
+
+No other installation is needed. The solver core is the same TypeScript code as the
+web app, bundled into the package and run on a Node.js runtime that pip installs as
+a dependency (`nodejs-wheel-binaries`). It is the same solver, with the same
+verification record, not a port.
+
+## Quick start
+
+```python
+import openflume as of
+
+net = of.load("feed_system.fn")  # .fn from the web app, or .json
+print(net.validate())  # [] means runnable
+
+result = net.solve()  # steady or transient per settings.mode
+print(result.converged, result.node("tank")["pressure"])  # SI units: Pa
+```
+
+Start from a bundled example and edit the model as a plain dict:
+
+```python
+net = of.example("Tank blowdown")
+net.settings["endTime"] = 2.0
+net.branch("orifice")["component"]["cd"] = 0.65
+
+tr = net.solve(progress=lambda p: print(f"t = {p['time']:.3f} s", end="\r"))
+t, p = tr.times, tr.series("tank", "pressure")  # numpy arrays if numpy is installed
+df = tr.frame()  # pandas: index time, columns (id, quantity)
+```
+
+Parameter sweeps are ordinary Python:
+
+```python
+base = of.example("Sanity: orifice hand-calc")
+for cd in (0.55, 0.60, 0.65):
+    net = base.copy()
+    net.branch("o")["component"]["cd"] = cd
+    print(cd, net.solve().branch("o")["mdot"])
+```
+
+Fluid properties use the same EOS models as the solver:
+
+```python
+lox = of.Fluid.real("Oxygen")
+lox.density(2e6, 95.0)  # kg/m³
+lox.saturation_temperature([1e5, 5e5, 1e6])
+of.fluids(curated=True)  # CoolProp HEOS catalogue
+of.combustion_gas("lox-rp1", pc=7e6, of=2.6)  # NASA CEA equilibrium tables
+```
+
+Command line:
+
+```bash
+openflume validate model.fn
+openflume solve model.fn -o result.json
+openflume info
+```
+
+## Notes
+
+- **Units** are SI throughout: Pa, K, kg/s, m, m², J/kg.
+- **Always check `result.converged`.** The solver returns its best state either way.
+- **Model format.** `Network.config` is the `NetworkConfig` dict (schema v2) defined in
+  `src/core/schema.ts` and documented in the user manual. `.fn` files round-trip
+  losslessly with the web app.
+- **User code.** Models can embed JavaScript user components (`componentLibrary`). That
+  code runs in the Node process with your user's privileges, so only solve models you
+  trust.
+- **Runtime.** One Node process per `Session` is started on first use and stopped at
+  exit. Set `OPENFLUME_NODE` to use a specific Node.js 22+ executable. For parallel
+  sweeps, use one process (and therefore one session) per worker, e.g. with
+  `concurrent.futures.ProcessPoolExecutor`. Ctrl-C interrupts a running solve.
+
+Full documentation: [docs/python.md](https://github.com/OpenFLUME/OpenFLUME/blob/main/docs/python.md).
+License: MIT.

openflume-0.3.1/hatch_build.py

@@ -0,0 +1,30 @@
+"""Build hook: refuse to produce a wheel/sdist without the bundled JS core.
+
+The Node bridge and coolprop.wasm in src/openflume/_js/ are generated by
+`npm run build:python` at the repository root. Building from an sdist works
+without Node because the sdist already carries them.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+REQUIRED = ("openflume-bridge.mjs", "coolprop.wasm")
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict) -> None:
+        root = Path(self.root)
+        js_dir = root / "src" / "openflume" / "_js"
+        missing = [name for name in REQUIRED if not (js_dir / name).is_file()]
+        if not (root / "LICENSE").is_file():
+            missing.append("../LICENSE copy")
+        if missing:
+            raise RuntimeError(
+                "openflume: bundled JS core not found ("
+                + ", ".join(missing)
+                + "). Run `npm ci && npm run build:python` at the repository "
+                "root before building the Python package."
+            )

openflume-0.3.1/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openflume"
+# Kept equal to ../package.json "version" — tests/test_packaging.py enforces it.
+version = "0.3.1"
+description = "Python API for the OpenFLUME thermal-fluid network solver (steady and transient, real fluids via CoolProp)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "OpenFLUME contributors" }]
+keywords = [
+  "fluid network",
+  "thermal-fluid",
+  "solver",
+  "aerospace",
+  "propulsion",
+  "cryogenics",
+  "CoolProp",
+  "GFSSP",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Physics",
+  "Typing :: Typed",
+]
+dependencies = [
+  # Supplies a Node.js runtime as a regular wheel, so `pip install openflume`
+  # needs nothing else on the machine. OPENFLUME_NODE overrides it.
+  "nodejs-wheel-binaries>=22.13",
+]
+
+[project.optional-dependencies]
+numpy = ["numpy>=1.24"]
+pandas = ["pandas>=2.0"]
+test = ["pytest>=8"]
+
+[project.scripts]
+openflume = "openflume.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/OpenFLUME/OpenFLUME"
+Documentation = "https://github.com/OpenFLUME/OpenFLUME/blob/main/docs/python.md"
+Issues = "https://github.com/OpenFLUME/OpenFLUME/issues"
+Changelog = "https://github.com/OpenFLUME/OpenFLUME/blob/main/CHANGELOG.md"
+
+# The bundled JS core (src/openflume/_js/) is a gitignored build artifact
+# produced by `npm run build:python` at the repository root; `artifacts`
+# re-includes it despite .gitignore, and hatch_build.py refuses to build a
+# package without it.
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openflume"]
+artifacts = ["src/openflume/_js/*"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/openflume",
+  "tests",
+  "hatch_build.py",
+  "README.md",
+  "LICENSE",
+]
+artifacts = ["src/openflume/_js/*", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+ignore = [
+  "RUF001", "RUF002", "RUF003", # ρ, μ, ² etc. in docstrings are intentional
+  "RUF022",                     # __all__ is grouped by topic, not sorted
+]

openflume-0.3.1/src/openflume/__init__.py

@@ -0,0 +1,79 @@
+"""OpenFLUME — thermal-fluid network solver, from Python.
+
+Quick start::
+
+    import openflume as of
+
+    net = of.load("feed_system.fn")        # or of.example("Tank blowdown")
+    errors = net.validate()                # [] means runnable
+    result = net.solve()                   # steady or transient per settings.mode
+    print(result.converged, result.node("tank")["pressure"])
+
+    n2 = of.Fluid.real("Nitrogen")
+    n2.density(101325, 300.0)              # kg/m³
+
+Everything is SI (Pa, K, kg/s, m, J/kg). The solver core is the same
+TypeScript code that runs the web app, executed in a bundled Node.js runtime
+(see :class:`Session`). Models that embed JavaScript user components run that
+code with the privileges of your Python process — only solve models you trust.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+from ._bridge import Session, default_session, find_node, shutdown
+from .errors import (
+    BridgeError,
+    ConfigDecodeError,
+    CoreError,
+    InvalidRequestError,
+    OpenFLUMEError,
+    ParseError,
+    UnknownExampleError,
+    UnsupportedPropertyError,
+    ValidationError,
+)
+from .fluids import Fluid, combustion_gas, combustion_propellants, fluids
+from .network import Network, example, examples, load, solve, validate
+from .results import SteadyResult, TransientResult
+
+try:
+    __version__ = _dist_version("openflume")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0+unknown"
+
+__all__ = [
+    "__version__",
+    # models
+    "Network",
+    "load",
+    "example",
+    "examples",
+    "solve",
+    "validate",
+    # results
+    "SteadyResult",
+    "TransientResult",
+    # fluids
+    "Fluid",
+    "fluids",
+    "combustion_gas",
+    "combustion_propellants",
+    # runtime
+    "Session",
+    "default_session",
+    "shutdown",
+    "find_node",
+    # errors
+    "OpenFLUMEError",
+    "BridgeError",
+    "ConfigDecodeError",
+    "ValidationError",
+    "ParseError",
+    "CoreError",
+    "UnknownExampleError",
+    "InvalidRequestError",
+    "UnsupportedPropertyError",
+]

openflume-0.3.1/src/openflume/__main__.py

@@ -0,0 +1,90 @@
+"""Command line: ``openflume info | validate MODEL | solve MODEL [-o OUT]``.
+
+Also runnable as ``python -m openflume``. Results are written as JSON (the
+core's raw result object); exit status is 0 on success, 1 on validation
+failure or a non-converged solve, 2 on usage/IO errors.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from ._bridge import _encode_nonfinite, default_session, find_node
+from .errors import OpenFLUMEError
+from .network import Network
+
+
+def _cmd_info(_: argparse.Namespace) -> int:
+    info = default_session().start().info
+    print(f"openflume {__version__}")
+    print(f"core      {info.get('version')} (config schema v{info.get('configVersion')})")
+    print(f"node      {info.get('node')} ({find_node()})")
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    errors = Network.load(args.model).validate()
+    for e in errors:
+        print(e)
+    if not errors:
+        print("valid")
+    return 1 if errors else 0
+
+
+def _cmd_solve(args: argparse.Namespace) -> int:
+    net = Network.load(args.model)
+
+    def progress(p: dict) -> None:
+        if p.get("kind") == "transient":
+            print(f"\r  t = {p['time']:.6g} / {p['endTime']:.6g} s", end="", file=sys.stderr)
+        else:
+            print(f"\r  iter {p['iteration']}  residual {p['residual']:.3e}", end="", file=sys.stderr)
+
+    result = net.solve(args.mode, progress=None if args.quiet else progress)
+    if not args.quiet:
+        print(file=sys.stderr)
+        print(repr(result), file=sys.stderr)
+    text = json.dumps(_encode_nonfinite(result.raw), indent=None if args.compact else 2)
+    if args.output:
+        Path(args.output).write_text(text + "\n", encoding="utf-8")
+    else:
+        print(text)
+    return 0 if result.converged else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="openflume", description="OpenFLUME thermal-fluid network solver")
+    parser.add_argument("--version", action="version", version=f"openflume {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("info", help="show package, core and Node.js versions").set_defaults(fn=_cmd_info)
+
+    p_val = sub.add_parser("validate", help="validate a .fn/.json model")
+    p_val.add_argument("model")
+    p_val.set_defaults(fn=_cmd_validate)
+
+    p_solve = sub.add_parser("solve", help="solve a .fn/.json model and print the JSON result")
+    p_solve.add_argument("model")
+    p_solve.add_argument("-o", "--output", help="write the JSON result here instead of stdout")
+    p_solve.add_argument("--mode", choices=["steady", "transient"], help="override settings.mode")
+    p_solve.add_argument("-q", "--quiet", action="store_true", help="no progress on stderr")
+    p_solve.add_argument("--compact", action="store_true", help="single-line JSON")
+    p_solve.set_defaults(fn=_cmd_solve)
+
+    args = parser.parse_args(argv)
+    try:
+        return int(args.fn(args))
+    except OpenFLUMEError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except OSError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())