processforge 0.2.3__tar.gz → 0.2.5__tar.gz

{processforge-0.2.3/src/processforge.egg-info → processforge-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processforge
-Version: 0.2.3
+Version: 0.2.5
 Summary: A Python-based process simulation framework for chemical engineering applications.
 Author-email: Process Forge Team <team@processforge.dev>
 License-Expression: BSD-3-Clause

{processforge-0.2.3 → processforge-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "processforge"
-version = "0.2.3"
+version = "0.2.5"
 description = "A Python-based process simulation framework for chemical engineering applications."
 readme = "README.md"
 license = "BSD-3-Clause"

{processforge-0.2.3 → processforge-0.2.5}/src/processforge/__init__.py

@@ -11,6 +11,7 @@ Provides steady-state and dynamic process simulation capabilities including:
 """
 
 from .flowsheet import Flowsheet
+from .provenance import build_run_info
 from .solver import Solver
 from .thermo import get_enthalpy_molar, get_Cp_molar, get_K_values, rachford_rice
 from .validate import validate_flowsheet
@@ -45,6 +46,7 @@ __all__ = [
     "plot_results",
     "plot_timeseries",
     "save_results_zarr",
+    "build_run_info",
     "Pump",
     "Valve",
     "Strainer",

{processforge-0.2.3 → processforge-0.2.5}/src/processforge/eo/flowsheet.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 from copy import deepcopy
 
+import numpy as np
 from loguru import logger
 
 from .jacobian import GlobalJacobianManager
@@ -64,12 +65,19 @@ class EOFlowsheet:
         """
         Build and solve the EO system.
 
+        After this method returns, ``self.x0`` holds the initial-guess vector
+        and ``self.var_names`` holds a human-readable label for each element —
+        both can be passed directly to
+        :func:`processforge.provenance.build_run_info` for reproducibility.
+
         Returns:
             Stream result dict in the same format as ``Flowsheet.run()``:
             ``{stream_name: {"T": ..., "P": ..., "flowrate": ..., "z": {...}}}``
         """
         manager = self._build()
         x0 = self._warm_start(manager)
+        self.x0: "np.ndarray" = x0.copy()
+        self.var_names: list[str] = self._build_var_names(manager)
         solver = EOSolver(backend=self.backend)
         x_sol, converged, stats = solver.solve(manager, x0)
         if not converged:
@@ -172,6 +180,26 @@ class EOFlowsheet:
             comps.update(stream.get("z", {}).keys())
         return sorted(comps)
 
+    # ------------------------------------------------------------------
+    # Provenance helpers
+    # ------------------------------------------------------------------
+
+    def _build_var_names(self, manager: "GlobalJacobianManager") -> list[str]:
+        """Return a human-readable label for every scalar in the x vector.
+
+        Variable order mirrors ``GlobalJacobianManager`` layout:
+        ``T``, ``P``, ``flowrate``, then one entry per component ``z_<comp>``
+        for each registered stream in registration order.
+        """
+        suffixes = ["T", "P", "flowrate"] + [
+            f"z_{c}" for c in manager.components
+        ]
+        names: list[str] = []
+        for stream_name in manager._streams:
+            for suffix in suffixes:
+                names.append(f"{stream_name}/{suffix}")
+        return names
+
     # ------------------------------------------------------------------
     # Warm-start
     # ------------------------------------------------------------------

processforge-0.2.5/src/processforge/provenance.py

@@ -0,0 +1,123 @@
+"""Provenance and metadata utilities for ProcessForge runs."""
+from __future__ import annotations
+
+import platform
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+import numpy as np
+
+_KEY_PACKAGES = [
+    "numpy",
+    "scipy",
+    "zarr",
+    "coolprop",
+    "loguru",
+    "pandas",
+    "openpyxl",
+    "matplotlib",
+    "jsonschema",
+    "graphviz",
+]
+
+
+def _git_hash() -> str:
+    """Return the current git commit hash, or 'unknown' if not in a git repo."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return "unknown"
+
+
+def _package_versions(packages: list[str]) -> dict[str, str]:
+    """Return installed versions for each package (or 'unknown')."""
+    from importlib.metadata import PackageNotFoundError, version
+
+    versions: dict[str, str] = {}
+    for pkg in packages:
+        try:
+            versions[pkg] = version(pkg)
+        except PackageNotFoundError:
+            versions[pkg] = "unknown"
+    return versions
+
+
+def build_run_info(
+    config: dict,
+    x0: np.ndarray | None = None,
+    var_names: list[str] | None = None,
+) -> dict:
+    """Build a run_info metadata dict for provenance tracking.
+
+    Args:
+        config:    The validated flowsheet configuration dict.
+        x0:        Initial guess vector (EO mode) or flattened feed-stream
+                   initial conditions (dynamic mode).
+        var_names: Human-readable label for each element of x0 (e.g.
+                   ``"feed/T"``, ``"feed/P"``, ``"product/z_H2O"``).
+
+    Returns:
+        A dict suitable for passing to ``save_results_zarr`` as *run_info*.
+        Keys:
+          - ``git_hash``             – current HEAD commit SHA
+          - ``timestamp``            – ISO-8601 UTC timestamp
+          - ``python_version``       – full ``sys.version`` string
+          - ``platform``             – ``platform.platform()`` string
+          - ``processforge_version`` – installed processforge version
+          - ``mode``                 – ``"steady"`` or ``"dynamic"``
+          - ``backend``              – EO backend name (steady-state only)
+          - ``pkg_versions``         – dict of {package: version}
+          - ``x0``                   – numpy float64 array or ``None``
+          - ``var_names``            – list of str labels or ``None``
+    """
+    from . import __version__ as _pf_version
+
+    sim_cfg = config.get("simulation", {})
+    return {
+        "git_hash": _git_hash(),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "python_version": sys.version,
+        "platform": platform.platform(),
+        "processforge_version": _pf_version,
+        "mode": sim_cfg.get("mode", "steady"),
+        "backend": sim_cfg.get("backend", "scipy"),
+        "pkg_versions": _package_versions(_KEY_PACKAGES),
+        "x0": np.asarray(x0, dtype=float) if x0 is not None else None,
+        "var_names": list(var_names) if var_names is not None else None,
+    }
+
+
+def build_dynamic_x0(config: dict) -> tuple[np.ndarray, list[str]]:
+    """Flatten feed-stream initial conditions into a reproducibility vector.
+
+    For dynamic simulations there is no single ``x0`` passed to a global
+    solver; instead the starting state is fully determined by the feed streams
+    in the config.  This helper packs those values into a flat numpy array so
+    the same schema used for EO runs can be applied here.
+
+    Returns:
+        (x0_array, var_names) where ``x0_array[i]`` corresponds to
+        ``var_names[i]`` (e.g. ``"feed/T"``, ``"feed/z_H2O"``).
+    """
+    values: list[float] = []
+    names: list[str] = []
+
+    for stream_name, stream in config.get("streams", {}).items():
+        for prop in ("T", "P", "flowrate"):
+            val = stream.get(prop, 0.0)
+            values.append(float(val))
+            names.append(f"{stream_name}/{prop}")
+        for comp, frac in sorted(stream.get("z", {}).items()):
+            values.append(float(frac))
+            names.append(f"{stream_name}/z_{comp}")
+
+    return np.asarray(values, dtype=float), names

{processforge-0.2.3 → processforge-0.2.5}/src/processforge/result.py

@@ -39,8 +39,63 @@ def _store_stream(stream_group, stream_data):
         stream_group.create_dataset(key, data=arr, shape=arr.shape)
 
 
-def save_results_zarr(results, fname="results.zarr"):
-    """Persist simulation results in a Zarr directory."""
+def _store_run_info(root, run_info: dict) -> None:
+    """Persist provenance metadata in a ``run_info`` Zarr sub-group.
+
+    Layout::
+
+        run_info/
+            .attrs  → git_hash, timestamp, python_version, platform,
+                       processforge_version, mode, backend
+            pkg_versions/
+                .attrs  → {package: version, ...}
+            initial_guess/
+                x0          – float64 array  (length = n_vars)
+                .attrs      → var_names  (JSON list of string labels)
+    """
+    ri_group = root.create_group("run_info")
+
+    scalar_keys = [
+        "git_hash",
+        "timestamp",
+        "python_version",
+        "platform",
+        "processforge_version",
+        "mode",
+        "backend",
+    ]
+    ri_group.attrs.update(
+        {k: str(run_info[k]) for k in scalar_keys if k in run_info}
+    )
+
+    pkg_versions = run_info.get("pkg_versions") or {}
+    if pkg_versions:
+        pkg_group = ri_group.create_group("pkg_versions")
+        pkg_group.attrs.update({k: str(v) for k, v in pkg_versions.items()})
+
+    x0 = run_info.get("x0")
+    if x0 is not None:
+        x0_arr = np.asarray(x0, dtype=float)
+        ig_group = ri_group.create_group("initial_guess")
+        ig_group.create_dataset("x0", data=x0_arr, shape=x0_arr.shape)
+        var_names = run_info.get("var_names")
+        if var_names:
+            ig_group.attrs["var_names"] = list(var_names)
+
+
+def save_results_zarr(results, fname="results.zarr", run_info=None):
+    """Persist simulation results in a Zarr directory.
+
+    Args:
+        results:  Stream result dict as returned by ``Flowsheet.run()``
+                  or ``EOFlowsheet.run()``.
+        fname:    Output path for the Zarr store directory.
+        run_info: Optional provenance dict from
+                  :func:`processforge.provenance.build_run_info`.  When
+                  supplied, a ``run_info`` sub-group is written inside the
+                  store containing the git hash, package versions, and
+                  initial-guess vector for full reproducibility.
+    """
     store_path = os.path.abspath(fname)
     if os.path.exists(store_path):
         if os.path.isdir(store_path):
@@ -55,6 +110,8 @@ def save_results_zarr(results, fname="results.zarr"):
     for stream_name, stream_data in results.items():
         stream_group = root.create_group(stream_name)
         _store_stream(stream_group, stream_data)
+    if run_info is not None:
+        _store_run_info(root, run_info)
     logger.info(f"Saved Zarr results to {store_path}")
     return store_path
 
@@ -190,7 +247,7 @@ def _build_dataframe_row(group, stream_name, idx, comp_names, include_time):
 def _load_dataframe_from_zarr(store_path):
     store = zarr.storage.LocalStore(store_path)
     root = zarr.open(store=store, mode="r")
-    streams = sorted(root.group_keys())
+    streams = sorted(k for k in root.group_keys() if k != "run_info")
     rows = []
     components = set()
     mode = root.attrs.get("mode", "steady")

{processforge-0.2.3 → processforge-0.2.5}/src/processforge/simulate.py

@@ -7,6 +7,7 @@ from loguru import logger
 from .utils.validate_flowsheet import validate_flowsheet
 from .flowsheet import Flowsheet
 from .eo import EOFlowsheet
+from .provenance import build_dynamic_x0, build_run_info
 from .result import (
     generate_validation_excel,
     plot_results,
@@ -40,15 +41,20 @@ def _cmd_run(args):
     if is_dynamic:
         fs = Flowsheet(config)
         logger.info("=== Dynamic Results ===")
+        results = fs.run()
+        x0, var_names = build_dynamic_x0(config)
+        run_info = build_run_info(config, x0=x0, var_names=var_names)
     else:
         backend = sim_cfg.get("backend", "scipy")
         fs = EOFlowsheet(config, backend=backend)
         logger.info("=== Steady-State EO Results ===")
+        results = fs.run()
+        run_info = build_run_info(config, x0=fs.x0, var_names=fs.var_names)
 
-    results = fs.run()
     zarr_path = save_results_zarr(
         results,
         os.path.join("outputs", f"{base_name}_results.zarr"),
+        run_info=run_info,
     )
     validation_path = os.path.join("outputs", f"{base_name}_validation.xlsx")
     generate_validation_excel(

{processforge-0.2.3 → processforge-0.2.5}/src/processforge/units/pump.py

@@ -49,7 +49,7 @@ class Pump(PumpEOMixin):
 
         # Approximate temperature rise (adiabatic inefficiency)
         Cp = 4180.0  # J/kg-K for water
-        dT = (power * (1 - self.efficiency)) / (mass_flow * Cp)
+        dT = (power * (1 - self.efficiency)) / (mass_flow * Cp) if mass_flow > 0 else 0.0
         outlet["T"] = inlet["T"] + dT
 
         outlet["power"] = power

{processforge-0.2.3 → processforge-0.2.5/src/processforge.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processforge
-Version: 0.2.3
+Version: 0.2.5
 Summary: A Python-based process simulation framework for chemical engineering applications.
 Author-email: Process Forge Team <team@processforge.dev>
 License-Expression: BSD-3-Clause

{processforge-0.2.3 → processforge-0.2.5}/src/processforge.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ flowsheets/archive/hydraulic_chain.json
 src/processforge/__init__.py
 src/processforge/_schema.py
 src/processforge/flowsheet.py
+src/processforge/provenance.py
 src/processforge/result.py
 src/processforge/simulate.py
 src/processforge/solver.py