processforge 0.3.20__tar.gz → 0.3.23__tar.gz

{processforge-0.3.20/src/processforge.egg-info → processforge-0.3.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processforge
-Version: 0.3.20
+Version: 0.3.23
 Summary: A Python-based process simulation framework for chemical engineering applications.
 Author-email: Processforge Team <team@processforge.dev>
 License-Expression: BSD-3-Clause
@@ -31,6 +31,7 @@ Requires-Dist: zarr>=3.0
 Requires-Dist: pint<1.0,>=0.24
 Requires-Dist: coolprop>=7.2.0
 Requires-Dist: typer>=0.12
+Requires-Dist: arrow>=1.3
 Provides-Extra: api
 Requires-Dist: fastapi>=0.110; extra == "api"
 Requires-Dist: uvicorn>=0.29; extra == "api"

{processforge-0.3.20 → processforge-0.3.23}/flowsheets/hydraulic-chain.json

@@ -105,7 +105,7 @@
   "simulation": {
     "mode": "steady",
     "t0": 0.0,
-    "tf": 20.0,
+    "tf": 25.0,
     "dt": 1.0
   }
 }

{processforge-0.3.20 → processforge-0.3.23}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "processforge"
-version = "0.3.20"
+version = "0.3.23"
 description = "A Python-based process simulation framework for chemical engineering applications."
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -37,6 +37,7 @@ dependencies = [
     "pint>=0.24,<1.0",
     "coolprop>=7.2.0",
     "typer>=0.12",
+    "arrow>=1.3",
 ]
 
 [project.optional-dependencies]

{processforge-0.3.20 → processforge-0.3.23}/src/processforge/__init__.py

@@ -18,6 +18,7 @@ from .utils.validate_flowsheet import validate_flowsheet
 from .result import (
     plot_results,
     plot_timeseries,
+    relink_latest_results,
     save_results_zarr,
 )
 from .units.pump import Pump
@@ -29,7 +30,7 @@ from .units.flash import Flash
 from .units.heater import Heater
 from .eo import EOFlowsheet, EOSolver
 
-__version__ = "0.3.19"
+__version__ = "0.3.23"
 
 __all__ = [
     "Flowsheet",
@@ -41,6 +42,7 @@ __all__ = [
     "plot_results",
     "plot_timeseries",
     "save_results_zarr",
+    "relink_latest_results",
     "build_run_info",
     "Pump",
     "Valve",

{processforge-0.3.20 → processforge-0.3.23}/src/processforge/cli/__init__.py

@@ -11,6 +11,7 @@ def register_commands(app: typer.Typer) -> None:
     from .validate import validate
     from .run import run
     from .apply import apply
+    from .runs import runs
     from .plan import plan
     from .diagram import diagram
     from .export_fmu import export_fmu
@@ -29,6 +30,10 @@ def register_commands(app: typer.Typer) -> None:
         "apply",
         help="Apply flowsheet using state-based warm start and homotopy fallback",
     )(apply)
+    app.command(
+        "runs",
+        help="List runs for a flowsheet, or show one run's full manifest (pf runs <flowsheet> [<run_id>])",
+    )(runs)
     app.command(
         "plan",
         help="Validate a flowsheet, run DOF analysis, structural diff, container health check, and generate a Mermaid diagram",

{processforge-0.3.20 → processforge-0.3.23}/src/processforge/cli/apply.py

@@ -31,13 +31,15 @@ def _persist_run(archive, fs, results, run_info, config, base_name, snapshot_id)
     # Always persist a Zarr copy of the standardized outputs (fields + artifacts)
     # inside the archive, mirroring `pf run`.
     try:
-        from ..result import save_results_zarr
+        from ..result import relink_latest_results, save_results_zarr
 
+        run_results_dir = os.path.join(archive.path, "results", run_id)
         save_results_zarr(
             results,
-            os.path.join(archive.path, "results.zarr"),
+            os.path.join(run_results_dir, "results.zarr"),
             run_info,
         )
+        relink_latest_results(archive.path, run_id)
     except Exception as e:
         logger.warning(f"Failed to write results.zarr: {type(e).__name__}: {e}")
 
@@ -131,11 +133,14 @@ def apply(
             return
         stream_drifts = [d for d in drifted if d.startswith("streams.")]
         unit_drifts = [d for d in drifted if d.startswith("units.")]
+        other_drifts = [d for d in drifted if not d.startswith(("streams.", "units."))]
         logger.warning("Drift detected:")
         if stream_drifts:
             logger.warning(f"  Stream drift : {stream_drifts}")
         if unit_drifts:
             logger.warning(f"  Unit drift   : {unit_drifts}")
+        if other_drifts:
+            logger.warning(f"  Config drift : {other_drifts}")
 
     # Build flowsheet; attach saved state for warm-start unless topology changed
     fs = EOFlowsheet(config, backend=backend)

{processforge-0.3.20 → processforge-0.3.23}/src/processforge/cli/common.py

@@ -145,6 +145,13 @@ def load_state_manager(outputs_dir: str, base_name: str) -> tuple[ProcessStateAr
 # Provider checking
 # ---------------------------------------------------------------------------
 
+# Retry/poll settings for containerized provider health checks. A container
+# spun up by ``pf init`` may take a few seconds to become ready; poll rather
+# than failing immediately so ``pf run`` waits for readiness with visible text.
+HEALTH_MAX_ATTEMPTS = 6
+HEALTH_RETRY_DELAY = 5  # seconds between attempts
+
+
 def is_local_provider_url(url: str | None) -> bool:
     """Return True if *url* points at a locally-managed provider.
 
@@ -184,6 +191,85 @@ def _ping_provider_health(url: str, timeout: int = 5) -> tuple[bool, "dict | str
         return False, str(exc)
 
 
+def _check_container_provider(
+    name: str,
+    ptype: str,
+    url: str,
+    flowsheet_path: str,
+    *,
+    fail_fast: bool,
+    errors: list[str],
+) -> None:
+    """Probe a containerized provider's ``/health`` endpoint with a retry/poll.
+
+    Polls up to ``HEALTH_MAX_ATTEMPTS`` times (``HEALTH_RETRY_DELAY`` apart) so a
+    container that is still booting after ``pf init`` gets a chance to become
+    ready before we give up. Logs a visible ``[OK]``/``[ERR]`` line (matching the
+    ``pf plan`` convention) so ``pf run`` never silently waits.
+    """
+    import time
+
+    ok, info = False, "not probed"
+    for attempt in range(1, HEALTH_MAX_ATTEMPTS + 1):
+        ok, info = _ping_provider_health(url, timeout=5)
+        if ok:
+            break
+        if attempt < HEALTH_MAX_ATTEMPTS:
+            logger.info(
+                f"  Waiting for '{name}' container to become healthy at {url}… "
+                f"(attempt {attempt}/{HEALTH_MAX_ATTEMPTS})"
+            )
+            time.sleep(HEALTH_RETRY_DELAY)
+
+    if ok:
+        payload = info if isinstance(info, dict) else {}
+        status = payload.get("status", "?")
+        provider_type = payload.get("provider_type", "?")
+        logger.info(
+            f"  [OK] {name} [{ptype}] {url} — status={status} provider_type={provider_type}"
+        )
+        return
+
+    msg = (
+        f"  [ERR] {name} [{ptype}] {url} — unreachable after "
+        f"{HEALTH_MAX_ATTEMPTS} attempt(s): {info}. "
+        f"Run: pf init {flowsheet_path}"
+    )
+    logger.error(msg)
+    if fail_fast:
+        raise SystemExit(1)
+    errors.append(f"Provider '{name}' unreachable at {url}: {info}")
+
+
+def _check_pip_provider(
+    name: str,
+    ptype: str,
+    flowsheet_path: str,
+    *,
+    fail_fast: bool,
+    errors: list[str],
+) -> None:
+    """Verify a pip-installable provider's module is importable."""
+    from ..providers.registry import _PROVIDER_CATALOG
+
+    catalog = _PROVIDER_CATALOG.get(ptype, {})
+    module = catalog.get("module", "")
+    try:
+        importlib.util.find_spec(module)
+        logger.info(f"  [OK] {name} [{ptype}] (pip — importable)")
+    except (ModuleNotFoundError, ValueError):
+        dep = catalog.get("optional_dep")
+        hint = f"pip install 'processforge[{dep}]'" if dep else "built-in"
+        msg = (
+            f"  [WARN] {name} [{ptype}] — not installed. "
+            f"Run: pf init {flowsheet_path}  (install with: {hint})"
+        )
+        logger.warning(msg)
+        if fail_fast:
+            raise SystemExit(1)
+        errors.append(f"Provider '{name}' not installed ({hint})")
+
+
 def check_providers(
     config: dict,
     flowsheet_path: str,
@@ -193,56 +279,41 @@ def check_providers(
 ) -> None:
     """Verify all declared providers are reachable or importable.
 
+    For containerized providers this pings the container's ``/health`` endpoint
+    (with a short retry/poll so a still-booting container can become ready) and
+    logs a visible ``[OK]``/``[ERR]`` line — so ``pf run`` shows a clear health
+    check instead of silently waiting. Pip-installable providers are checked for
+    importability and reported the same way.
+
     Parameters
     ----------
     fail_fast:
         If ``True`` (default), raise ``SystemExit`` on the first failure.
         If ``False``, accumulate errors and raise once at the end.
     verbose:
-        If ``True``, log per-provider success messages.
+        Accepted for compatibility; the health check is always logged.
     """
-    from ..providers.registry import is_containerized, _PROVIDER_CATALOG
+    from ..providers.registry import is_containerized
 
     providers = config.get("providers", {})
     errors: list[str] = []
 
+    if providers:
+        logger.info("=== Provider / Container Health ===")
+
     for name, cfg in providers.items():
         ptype = cfg.get("type", "")
         if is_containerized(ptype):
             url = _resolve_provider_url(cfg, ptype)
-            try:
-                urllib.request.urlopen(f"{url}/health", timeout=5)
-                if verbose:
-                    logger.info(f"Provider '{name}' — reachable at {url}")
-            except (urllib.error.URLError, OSError, TimeoutError) as exc:
-                msg = (
-                    f"Provider '{name}' unreachable at {url}. "
-                    f"Run: pf init {flowsheet_path}"
-                )
-                if fail_fast:
-                    logger.error(msg)
-                    raise SystemExit(1)
-                logger.error(msg)
-                errors.append(msg)
+            _check_container_provider(
+                name, ptype, url, flowsheet_path,
+                fail_fast=fail_fast, errors=errors,
+            )
         else:
-            catalog = _PROVIDER_CATALOG.get(ptype, {})
-            module = catalog.get("module", "")
-            try:
-                importlib.util.find_spec(module)
-                if verbose:
-                    logger.info(f"Provider '{name}' — importable (pip)")
-            except (ModuleNotFoundError, ValueError):
-                dep = catalog.get("optional_dep")
-                hint = f"pip install 'processforge[{dep}]'" if dep else "built-in"
-                msg = (
-                    f"Provider '{name}' not installed. "
-                    f"Run: pf init {flowsheet_path}  (install with: {hint})"
-                )
-                if fail_fast:
-                    logger.error(msg)
-                    raise SystemExit(1)
-                logger.error(msg)
-                errors.append(msg)
+            _check_pip_provider(
+                name, ptype, flowsheet_path,
+                fail_fast=fail_fast, errors=errors,
+            )
 
     if errors:
         raise SystemExit(1)

{processforge-0.3.20 → processforge-0.3.23}/src/processforge/cli/run.py

@@ -19,6 +19,7 @@ from .common import (
     output_root,
     require_existing_file,
     validate_runtime_flowsheet,
+    _resolve_provider_url,
 )
 
 
@@ -38,6 +39,39 @@ def _run_id() -> str:
     return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + "_" + os.urandom(3).hex()
 
 
+def _log_active_providers(config: dict) -> None:
+    """Log a one-line summary of the provider(s) a run will dispatch to.
+
+    Highlights containerized providers (which do their real work inside a Docker
+    container and can take a while) so the user sees what is running instead of
+    a silent wait. Pip-installable providers are mentioned for completeness.
+    """
+    from ..providers.registry import is_containerized
+
+    providers = config.get("providers", {})
+    if not providers:
+        return
+
+    containers = []
+    pips = []
+    for name, cfg in providers.items():
+        ptype = cfg.get("type", "")
+        if is_containerized(ptype):
+            url = _resolve_provider_url(cfg, ptype)
+            containers.append(f"{name} [{ptype}] @ {url}")
+        else:
+            pips.append(f"{name} [{ptype}]")
+
+    if containers:
+        logger.info("=== Active providers (containerized) ===")
+        for entry in containers:
+            logger.info(f"  → {entry}")
+    if pips:
+        logger.info("=== Active providers (local) ===")
+        for entry in pips:
+            logger.info(f"  → {entry}")
+
+
 def run(
     flowsheet: str = typer.Argument(help="Path to the flowsheet JSON file"),
     export_images: bool = typer.Option(
@@ -53,6 +87,10 @@ def run(
     # Check provider availability (assumes any containers are already running)
     check_providers(config, flowsheet)
 
+    # Surface which containerized provider(s) this run will dispatch to, so the
+    # command line isn't silent while the container does the heavy compute.
+    _log_active_providers(config)
+
     base_name = flowsheet_basename(flowsheet)
     outputs_dir = output_root()
 
@@ -158,13 +196,15 @@ def run(
     # Cantera) and for both local and remote docker runs — remote artifacts
     # reference their S3 remote_uris.
     try:
-        from ..result import save_results_zarr
+        from ..result import relink_latest_results, save_results_zarr
 
+        run_results_dir = os.path.join(archive.path, "results", run_id)
         save_results_zarr(
             results,
-            os.path.join(archive.path, "results.zarr"),
+            os.path.join(run_results_dir, "results.zarr"),
             run_info,
         )
+        relink_latest_results(archive.path, run_id)
     except Exception as e:
         logger.warning(f"Failed to write results.zarr: {type(e).__name__}: {e}")
 

processforge-0.3.23/src/processforge/cli/runs.py

@@ -0,0 +1,88 @@
+"""``pf runs`` — list runs for a flowsheet, or show one run's full manifest."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import arrow
+import typer
+from loguru import logger
+
+from .common import flowsheet_basename, output_root
+from ..persistence.archive import ProcessStateArchive
+
+
+def _humanize_timestamp(ts: str) -> str:
+    """Render a stored timestamp as a human-readable relative string.
+
+    Falls back to the raw string for values that aren't parseable ISO-8601
+    (e.g. ``20260101T000000Z`` used in some test fixtures).
+    """
+    try:
+        return arrow.get(ts).humanize()
+    except (arrow.parser.ParserError, ValueError, TypeError):
+        return ts
+
+
+def runs(
+    flowsheet: str = typer.Argument(..., help="Path to the flowsheet JSON"),
+    run_id: str = typer.Argument(
+        None,
+        help="Show this run's full manifest instead of listing all runs",
+    ),
+):
+    """List runs stored in a flowsheet's ``.pfarchive`` (or show one run)."""
+    base = flowsheet_basename(flowsheet)
+    archive_path = os.path.join(output_root(), f"{base}.pfarchive")
+
+    if not os.path.isdir(archive_path):
+        logger.error(
+            f"No archive found for '{flowsheet}' at {archive_path}. "
+            "Run 'pf run' first."
+        )
+        raise typer.Exit(code=1)
+
+    archive = ProcessStateArchive(archive_path)
+    latest = archive.latest_run()
+    latest_id = latest.run_id if latest is not None else None
+
+    if run_id is not None:
+        if run_id not in archive.list_runs():
+            logger.error(f"Run '{run_id}' not found in {archive_path}/runs.")
+            raise typer.Exit(code=1)
+        manifest = archive.load_run(run_id)
+        typer.echo(json.dumps(manifest.model_dump(), indent=2, default=str))
+        typer.echo("\nArtifacts on disk:")
+        for unit_name, out in manifest.units.items():
+            for art in out.artifacts:
+                present = os.path.exists(art.local_path) if art.local_path else False
+                remote = bool(art.remote_uris)
+                status = (
+                    "local✓" if present else ("remote-only" if remote else "missing")
+                )
+                loc = art.local_path or "no local path"
+                typer.echo(f"  [{unit_name}] {art.name}: {status} ({loc})")
+        return
+
+    run_ids = archive.list_runs()
+    if not run_ids:
+        typer.echo(f"No runs found for '{flowsheet}'.")
+        return
+
+    header = f"{'RUN ID':<28} {'TIMESTAMP':<22} LATEST"
+    typer.echo(header)
+    typer.echo("-" * len(header))
+    for rid in run_ids:
+        manifest = archive.load_run(rid)
+        if manifest is None:
+            continue
+        marker = "*" if rid == latest_id else " "
+        typer.echo(
+            f"{rid:<28} {_humanize_timestamp(manifest.timestamp):<22} {marker}"
+        )
+    typer.echo("")
+    typer.echo(
+        "'*' marks the latest run. "
+        "'pf runs <flowsheet> <run_id>' prints the full manifest."
+    )

{processforge-0.3.20 → processforge-0.3.23}/src/processforge/output_collector.py

@@ -14,8 +14,10 @@ canonical, unit-aware record persisted by :class:`ProcessStateArchive`:
 """
 from __future__ import annotations
 
+from datetime import datetime, timezone
 from typing import Optional
 
+import arrow
 from loguru import logger
 
 from .types import (
@@ -75,6 +77,20 @@ def collect_stream_outputs(provider, stream_results: dict) -> dict[str, StreamOu
     return out
 
 
+def _timestamp_from_run_id(run_id: str) -> str:
+    """Derive an ISO-8601 timestamp from a run_id's compact UTC prefix.
+
+    Run ids are ``<YYYYMMDDTHHMMSSZ>_<suffix>`` (see ``pf run`` / ``pf apply``),
+    so the start time is recoverable from the id itself. Falls back to the
+    current UTC time for ids that don't follow that convention.
+    """
+    prefix = run_id.split("_", 1)[0]
+    try:
+        return arrow.get(prefix).isoformat()
+    except (arrow.parser.ParserError, ValueError):
+        return datetime.now(timezone.utc).isoformat()
+
+
 def build_run_manifest(
     *,
     run_id: str,
@@ -91,6 +107,7 @@ def build_run_manifest(
         run_id=run_id,
         mode=mode,
         flowsheet=flowsheet_name,
+        timestamp=_timestamp_from_run_id(run_id),
         units=dict(engine_outputs),
         streams=streams,
         provenance=provenance or {},

{processforge-0.3.20 → processforge-0.3.23}/src/processforge/providers/container_client.py

@@ -177,6 +177,15 @@ class ContainerProviderClient(AbstractProvider):
             else {"type": unit_config.provider or self._ptype, "url": self._url}
         )
 
+        # Fall back to context set via set_run_context() (the CLI propagates the
+        # shared run_id/flowsheet_hash there). SolverUnit calls run_simulation()
+        # without these arguments, so without the fallback the container receives
+        # null and artifacts get uploaded under the wrong key.
+        if run_id is None:
+            run_id = self._run_id or None
+        if flowsheet_hash is None:
+            flowsheet_hash = self._flowsheet_hash or None
+
         body = {
             "unit_config": self._serialize_unit_config(unit_config),
             "materials": self._serialize_materials(self._materials),
@@ -190,6 +199,10 @@ class ContainerProviderClient(AbstractProvider):
             f"ContainerProviderClient: POST {self._url}/run "
             f"sim_type='{unit_config.sim_type}' run_id='{run_id}'"
         )
+        logger.info(
+            f"Waiting for '{self._ptype}' container at {self._url} to finish "
+            f"simulation — this may take a while…"
+        )
 
         payload = json.dumps(body).encode()
         req = urllib.request.Request(

{processforge-0.3.20 → processforge-0.3.23}/src/processforge/providers/coolprop_provider.py

@@ -56,11 +56,20 @@ class CoolPropProvider(AbstractProvider):
                 logger.warning(f"Component '{comp}' not found in CoolProp. Cp contribution is 0.")
 
         Ks = {}
+        from CoolProp.CoolProp import AbstractState
+
         for comp in z.keys():
             try:
-                fugL = self.CP.PropsSI("fugL", "T", T, "P", P, comp)
-                fugV = self.CP.PropsSI("fugV", "T", T, "P", P, comp)
-                Ks[comp] = fugL / fugV if fugV != 0 else 1.0
+                st = AbstractState("PR", comp)
+                st.specify_phase(self.CP.iphase_liquid)
+                st.update(self.CP.PT_INPUTS, P, T)
+                phi_L = st.fugacity_coefficient(0)
+                st.unspecify_phase()
+                st.specify_phase(self.CP.iphase_gas)
+                st.update(self.CP.PT_INPUTS, P, T)
+                phi_V = st.fugacity_coefficient(0)
+                st.unspecify_phase()
+                Ks[comp] = phi_L / phi_V if phi_V != 0 else 1.0
             except Exception:
                 logger.warning(f"Could not calculate K-value for '{comp}'. Using fallback K=1.0.")
                 Ks[comp] = 1.0

{processforge-0.3.20 → processforge-0.3.23}/src/processforge/result.py

@@ -272,6 +272,34 @@ def save_results_zarr(results, fname="results.zarr", run_info: RunInfo | dict |
     return store_path
 
 
+def relink_latest_results(archive_path: str, run_id: str) -> None:
+    """Point ``<archive>/results.zarr`` at the latest per-run zarr.
+
+    Each run now writes its zarr to ``<archive>/results/<run_id>/results.zarr``
+    (see `save_results_zarr`). To keep backward compatibility with tooling that
+    reads a single ``results.zarr`` at the archive root, we make that path a
+    symlink to the newest run. Falls back to a copy on platforms/filesystems
+    without symlink support (or when the existing target is a real directory).
+    """
+    latest = os.path.join(archive_path, "results", run_id, "results.zarr")
+    if not os.path.exists(latest):
+        return
+    link_path = os.path.join(archive_path, "results.zarr")
+
+    # Remove any existing target (real dir or stale/broken symlink) without
+    # following the link.
+    if os.path.islink(link_path):
+        os.unlink(link_path)
+    elif os.path.exists(link_path):
+        shutil.rmtree(link_path)
+
+    try:
+        os.symlink(latest, link_path)
+    except (OSError, NotImplementedError):
+        # Non-POSIX / restricted filesystem: keep a physical copy instead.
+        shutil.copytree(latest, link_path)
+
+
 def save_results_zarr_s3(results, s3_uri: str, run_info: RunInfo | dict | None = None):
     """Write simulation results directly to an S3-backed Zarr store.