openflume 0.3.1__py3-none-any.whl

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/__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())

openflume/_bridge.py

@@ -0,0 +1,279 @@
+"""Node.js subprocess bridge to the bundled OpenFLUME core.
+
+One long-lived ``node`` process per :class:`Session`, speaking newline-delimited
+JSON over stdio (protocol documented in python/bridge/server.ts). Requests are
+serialized with a lock; the solvers are synchronous so there is no benefit to
+pipelining. Use several sessions (e.g. one per worker process) for parallelism.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import math
+import os
+import shutil
+import subprocess
+import threading
+from collections import deque
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from .errors import BridgeError, from_payload
+
+PROTOCOL_VERSION = 1
+MIN_NODE_MAJOR = 22
+
+_JS_DIR = Path(__file__).resolve().parent / "_js"
+BRIDGE_SCRIPT = _JS_DIR / "openflume-bridge.mjs"
+
+_log = logging.getLogger("openflume.node")
+
+ProgressCallback = Callable[[dict[str, Any]], None]
+
+
+# ── non-finite number codec (mirrors server.ts) ─────────────────────────────
+_NUM_TAG = "$num"
+
+
+def _encode_nonfinite(value: Any) -> Any:
+    if isinstance(value, float):
+        if math.isnan(value):
+            return {_NUM_TAG: "NaN"}
+        if math.isinf(value):
+            return {_NUM_TAG: "Infinity" if value > 0 else "-Infinity"}
+        return value
+    if isinstance(value, dict):
+        return {k: _encode_nonfinite(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_encode_nonfinite(v) for v in value]
+    # numpy scalars / arrays, without importing numpy
+    tolist = getattr(value, "tolist", None)
+    if callable(tolist) and type(value).__module__.startswith("numpy"):
+        return _encode_nonfinite(tolist())
+    return value
+
+
+def _decode_hook(obj: dict[str, Any]) -> Any:
+    if len(obj) == 1 and _NUM_TAG in obj:
+        return float(obj[_NUM_TAG])
+    return obj
+
+
+def dumps(value: Any) -> str:
+    return json.dumps(_encode_nonfinite(value), allow_nan=False, separators=(",", ":"))
+
+
+def loads(text: str) -> Any:
+    return json.loads(text, object_hook=_decode_hook)
+
+
+# ── Node discovery ──────────────────────────────────────────────────────────
+def _wheel_node() -> str | None:
+    try:
+        import nodejs_wheel  # type: ignore[import-not-found]
+    except ImportError:
+        return None
+    root = Path(nodejs_wheel.__file__).resolve().parent
+    candidate = root / "node.exe" if os.name == "nt" else root / "bin" / "node"
+    return str(candidate) if candidate.is_file() else None
+
+
+def find_node() -> str:
+    """Return the Node.js executable to use.
+
+    Order: ``$OPENFLUME_NODE``, the ``nodejs-wheel-binaries`` runtime installed
+    alongside openflume, then ``node`` on ``PATH``.
+    """
+    override = os.environ.get("OPENFLUME_NODE")
+    if override:
+        return override
+    found = _wheel_node() or shutil.which("node")
+    if not found:
+        raise BridgeError(
+            "openflume needs Node.js >= 22. Install the bundled runtime with "
+            "`pip install nodejs-wheel-binaries`, install Node.js on PATH, or set "
+            "OPENFLUME_NODE to a node executable."
+        )
+    return found
+
+
+# ── session ─────────────────────────────────────────────────────────────────
+class Session:
+    """A running instance of the OpenFLUME core.
+
+    Most code never needs this: module-level functions use a shared default
+    session that starts on first use and stops at interpreter exit. Create one
+    explicitly to pick a Node executable, or to isolate state (e.g. one per
+    worker process). Usable as a context manager.
+    """
+
+    def __init__(self, node: str | os.PathLike[str] | None = None) -> None:
+        self._node = os.fspath(node) if node is not None else None
+        self._proc: subprocess.Popen[str] | None = None
+        self._lock = threading.RLock()
+        self._next_id = 0
+        self._stderr_tail: deque[str] = deque(maxlen=50)
+        self.info: dict[str, Any] = {}
+
+    # lifecycle -----------------------------------------------------------------
+    def start(self) -> Session:
+        with self._lock:
+            if self._proc is not None and self._proc.poll() is None:
+                return self
+            if not BRIDGE_SCRIPT.is_file():
+                raise BridgeError(
+                    f"bundled OpenFLUME core missing at {BRIDGE_SCRIPT}; this "
+                    "installation is incomplete (source checkouts need "
+                    "`npm run build:python`)."
+                )
+            node = self._node or find_node()
+            self._stderr_tail.clear()
+            try:
+                self._proc = subprocess.Popen(
+                    [node, "--no-warnings", str(BRIDGE_SCRIPT)],
+                    stdin=subprocess.PIPE,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    text=True,
+                    encoding="utf-8",
+                    bufsize=1,
+                    cwd=str(_JS_DIR),
+                    # Own process group: a terminal Ctrl-C reaches only Python,
+                    # which then kills Node (see _request), instead of Node
+                    # dying first and surfacing as a BridgeError.
+                    start_new_session=os.name != "nt",
+                    creationflags=(
+                        subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0
+                    ),
+                )
+            except OSError as exc:
+                raise BridgeError(f"could not start Node.js ({node}): {exc}") from exc
+            threading.Thread(
+                target=self._pump_stderr, args=(self._proc,), name="openflume-node-stderr", daemon=True
+            ).start()
+            info = self._request("hello", {}, None)
+            if info.get("protocol") != PROTOCOL_VERSION:
+                self.close()
+                raise BridgeError(f"bridge protocol mismatch: expected {PROTOCOL_VERSION}, got {info.get('protocol')}")
+            major = int(str(info.get("node", "0")).split(".")[0] or 0)
+            if major < MIN_NODE_MAJOR:
+                self.close()
+                raise BridgeError(
+                    f"Node.js {info.get('node')} at {node} is too old; openflume needs >= {MIN_NODE_MAJOR}."
+                )
+            self.info = info
+            return self
+
+    def close(self) -> None:
+        """Stop the Node process. The session restarts automatically on next use."""
+        with self._lock:
+            proc, self._proc = self._proc, None
+            if proc is None:
+                return
+            try:
+                if proc.stdin:
+                    proc.stdin.close()
+                proc.wait(timeout=5)
+            except Exception:
+                proc.kill()
+                proc.wait()
+
+    def _kill(self) -> None:
+        proc, self._proc = self._proc, None
+        if proc is not None:
+            proc.kill()
+            proc.wait()
+
+    @property
+    def running(self) -> bool:
+        return self._proc is not None and self._proc.poll() is None
+
+    def __enter__(self) -> Session:
+        return self.start()
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # I/O -----------------------------------------------------------------------
+    def _pump_stderr(self, proc: subprocess.Popen[str]) -> None:
+        assert proc.stderr is not None
+        for line in proc.stderr:
+            line = line.rstrip("\n")
+            self._stderr_tail.append(line)
+            _log.info("%s", line)
+
+    def _died(self) -> BridgeError:
+        code = self._proc.poll() if self._proc else None
+        tail = "\n".join(self._stderr_tail)
+        self._proc = None
+        msg = f"OpenFLUME Node process exited unexpectedly (exit code {code})"
+        return BridgeError(msg + (f":\n{tail}" if tail else ""))
+
+    def call(
+        self, method: str, params: dict[str, Any] | None = None, *, on_progress: ProgressCallback | None = None
+    ) -> Any:
+        """Invoke a bridge method and return its decoded result."""
+        with self._lock:
+            self.start()
+            return self._request(method, params or {}, on_progress)
+
+    def _request(self, method: str, params: dict[str, Any], on_progress: ProgressCallback | None) -> Any:
+        proc = self._proc
+        assert proc is not None and proc.stdin is not None and proc.stdout is not None
+        self._next_id += 1
+        req_id = self._next_id
+        try:
+            proc.stdin.write(dumps({"id": req_id, "method": method, "params": params}) + "\n")
+            proc.stdin.flush()
+        except (BrokenPipeError, OSError):
+            raise self._died() from None
+        try:
+            while True:
+                line = proc.stdout.readline()
+                if not line:
+                    raise self._died()
+                msg = loads(line)
+                if msg.get("id") != req_id:
+                    continue  # stale reply from an interrupted request
+                if "event" in msg:
+                    if on_progress is not None and msg["event"] == "progress":
+                        on_progress(msg.get("data", {}))
+                    continue
+                if "error" in msg:
+                    raise from_payload(msg["error"])
+                return msg.get("result")
+        except KeyboardInterrupt:
+            # The solve is synchronous inside Node and cannot be cancelled
+            # cooperatively; kill it so the session is usable again.
+            self._kill()
+            raise
+        except BaseException:
+            if self._proc is not None and self._proc.poll() is not None:
+                self._proc = None
+            raise
+
+
+_default: Session | None = None
+_default_lock = threading.Lock()
+
+
+def default_session() -> Session:
+    """The shared session used by module-level functions."""
+    global _default
+    with _default_lock:
+        if _default is None:
+            _default = Session()
+        return _default
+
+
+def shutdown() -> None:
+    """Stop the shared default session (it restarts on next use)."""
+    with _default_lock:
+        if _default is not None:
+            _default.close()
+
+
+atexit.register(shutdown)