processforge 0.2.38__tar.gz → 0.2.40__tar.gz

{processforge-0.2.38/src/processforge.egg-info → processforge-0.2.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processforge
-Version: 0.2.38
+Version: 0.2.40
 Summary: A Python-based process simulation framework for chemical engineering applications.
 Author-email: Processforge Team <team@processforge.dev>
 License-Expression: BSD-3-Clause
@@ -29,6 +29,7 @@ Requires-Dist: graphviz>=0.20
 Requires-Dist: pandas>=2.2
 Requires-Dist: zarr>=3.0
 Requires-Dist: coolprop>=7.2.0
+Requires-Dist: typer>=0.12
 Provides-Extra: eo
 Requires-Dist: pyomo>=6.7; extra == "eo"
 Provides-Extra: eo-casadi

{processforge-0.2.38 → processforge-0.2.40}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "processforge"
-version = "0.2.38"
+version = "0.2.40"
 description = "A Python-based process simulation framework for chemical engineering applications."
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -35,6 +35,7 @@ dependencies = [
     "pandas>=2.2",
     "zarr>=3.0",
     "coolprop>=7.2.0",
+    "typer>=0.12",
 ]
 
 [project.optional-dependencies]

{processforge-0.2.38 → processforge-0.2.40}/src/processforge/__init__.py

@@ -29,7 +29,7 @@ from .units.flash import Flash
 from .units.heater import Heater
 from .eo import EOFlowsheet, EOSolver
 
-__version__ = "0.1.0"
+__version__ = "0.2.40"
 
 __all__ = [
     "Flowsheet",

processforge-0.2.40/src/processforge/cli/__init__.py

@@ -0,0 +1,44 @@
+"""CLI subpackage — one module per ``pf`` subcommand."""
+
+from __future__ import annotations
+
+import typer
+
+
+def register_commands(app: typer.Typer) -> None:
+    """Register all subcommands on *app*."""
+    from .init import init
+    from .validate import validate
+    from .run import run
+    from .apply import apply
+    from .plan import plan
+    from .diagram import diagram
+    from .export_fmu import export_fmu
+    from .export_modelica import export_modelica
+
+    app.command(
+        "init",
+        help="Initialise .processforge/ project directory and provider environment",
+    )(init)
+    app.command(
+        "validate",
+        help="Check providers and environment are ready for a flowsheet",
+    )(validate)
+    app.command("run", help="Run a process simulation")(run)
+    app.command(
+        "apply",
+        help="Apply flowsheet using state-based warm start and homotopy fallback",
+    )(apply)
+    app.command(
+        "plan",
+        help="Validate a flowsheet, run DOF analysis, structural diff, and generate a Mermaid diagram",
+    )(plan)
+    app.command("diagram", help="Generate a flowsheet diagram")(diagram)
+    app.command(
+        "export-modelica",
+        help="Transpile flowsheet to Modelica .mo and compile via OMPython",
+    )(export_modelica)
+    app.command(
+        "export-fmu",
+        help="Export flowsheet as FMI 2.0 co-simulation FMU",
+    )(export_fmu)

processforge-0.2.40/src/processforge/cli/apply.py

@@ -0,0 +1,207 @@
+"""``pf apply`` — state-based warm start with homotopy fallback."""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Literal
+
+import typer
+from loguru import logger
+
+from ..eo import EOFlowsheet
+from ..provenance import build_run_info
+from ..result import save_results_zarr
+from ..state import StateManager
+from .common import (
+    build_divergence_report,
+    build_run_metadata,
+    check_providers,
+    load_state_manager,
+    log_residual_breakdown,
+    output_root,
+    require_existing_file,
+    save_snapshot,
+    validate_runtime_flowsheet,
+    write_divergence_report,
+)
+from .display import print_structural_diff
+
+
+def apply(
+    flowsheet: str = typer.Argument(help="Path to the flowsheet JSON file"),
+    backend: Literal["scipy", "pyomo", "casadi"] | None = typer.Option(
+        None,
+        "--backend",
+        help="Override the flowsheet's simulation.backend",
+    ),
+    tolerance: float = typer.Option(
+        1e-6,
+        "--tolerance",
+        help="Newton solver convergence tolerance (default: 1e-6)",
+    ),
+    max_iter: int = typer.Option(
+        50,
+        "--max-iter",
+        help="Max Newton iterations (default: 50)",
+    ),
+    skip_homotopy: bool = typer.Option(
+        False,
+        "--skip-homotopy",
+        help="Disable homotopy fallback; cold-start only",
+    ),
+) -> None:
+    """Apply flowsheet: drift detection, warm-start, homotopy fallback, convergence guardrails."""
+    require_existing_file(flowsheet)
+    config = validate_runtime_flowsheet(flowsheet)
+
+    # Check provider availability
+    check_providers(config, flowsheet)
+
+    base_name = os.path.splitext(os.path.basename(flowsheet))[0]
+
+    sim_cfg = config.get("simulation", {})
+    mode = sim_cfg.get("mode", "steady")
+    if mode != "steady":
+        logger.error("pf apply is only supported for steady-state EO flowsheets.")
+        raise SystemExit(1)
+
+    outputs_dir = output_root()
+    os.makedirs(outputs_dir, exist_ok=True)
+    sm, state = load_state_manager(outputs_dir, base_name)
+
+    # Structural diff: detect topology changes
+    topology_changed = False
+    if state is not None:
+        diff = sm.detect_structural_diff(config, state)
+        print_structural_diff(diff)
+        topology_changed = bool(diff.get("added") or diff.get("removed"))
+        if topology_changed:
+            logger.warning(
+                "Topology changed (units added/removed). "
+                "Homotopy requires identical topology — falling back to cold start."
+            )
+
+    # Parameter drift (only meaningful when topology is unchanged)
+    drifted: list[str] = []
+    current_metadata = build_run_metadata(config, tolerance, max_iter, backend or "scipy")
+    if state is not None and not topology_changed:
+        mismatches = sm.validate_metadata(current_metadata, state)
+        if mismatches:
+            logger.warning(f"Metadata mismatch: {mismatches}")
+        drifted = sm.detect_drift(config, state)
+        if not drifted:
+            logger.info("No drift detected. System is already at the desired state.")
+            return
+        stream_drifts = [d for d in drifted if d.startswith("streams.")]
+        unit_drifts = [d for d in drifted if d.startswith("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}")
+
+    # Build flowsheet; attach saved state for warm-start unless topology changed
+    fs = EOFlowsheet(config, backend=backend)
+    fs.saved_state = state if not topology_changed else None
+    fs.solver_tol = tolerance
+    fs.solver_max_iter = max_iter
+
+    logger.info("=== Running Apply (Steady-State EO) ===")
+    t0 = time.perf_counter()
+    results = fs.run()
+    elapsed = time.perf_counter() - t0
+
+    logger.info(
+        f"Direct solve completed in {elapsed:.2f}s (converged={fs.converged})."
+    )
+
+    if fs.converged:
+        snapshot_id = save_snapshot(
+            sm, config, fs.x_converged, fs.var_names,
+            metadata=current_metadata,
+            parent_snapshot_id=state.snapshot_id if state is not None and not topology_changed else None,
+            label="converged state",
+        )
+        run_info = build_run_info(config, x0=fs.x0, var_names=fs.var_names)
+        zarr_path = os.path.join(outputs_dir, f"{base_name}_results.zarr")
+        save_results_zarr(results, zarr_path, run_info=run_info)
+        logger.info("=== Apply Summary ===")
+        logger.info("  Status       : CONVERGED")
+        logger.info(f"  Final ||F||  : {fs.solver_stats.get('final_norm', '?'):.3e}")
+        logger.info(f"  Iterations   : {fs.solver_stats.get('iterations', '?')}")
+        logger.info(f"  Backend      : {fs.backend}")
+        logger.info(f"  Snapshot ID  : {snapshot_id}")
+        logger.info(f"  Results zarr : {zarr_path}")
+        logger.info(f"  Elapsed (s)  : {elapsed:.2f}")
+        return
+
+    # Direct solve failed — try homotopy (only when topology is same and state exists)
+    if state is not None and not topology_changed and drifted and not skip_homotopy:
+        logger.warning("Direct solve failed. Attempting homotopy continuation...")
+        from ..eo.solver import EOSolver, solve_with_homotopy
+        from ..eo.flowsheet import EOFlowsheet as _EO
+        from ..providers.manager import teardown_providers
+
+        solver = EOSolver(backend=fs.backend, tol=tolerance, max_iter=max_iter)
+        tmp_fs = _EO(config, backend=backend)
+        manager = tmp_fs._build()
+        try:
+            x_hom, hom_converged, hom_stats = solve_with_homotopy(
+                tmp_fs, manager, solver, state, drifted
+            )
+        finally:
+            teardown_providers(tmp_fs._provider_map)
+
+        if hom_converged:
+            logger.info(
+                f"Homotopy converged: ||F||={hom_stats.get('final_norm', '?'):.3e}, "
+                f"iterations={hom_stats.get('iterations', '?')}"
+            )
+            save_snapshot(
+                sm, config, x_hom, fs.var_names,
+                metadata=current_metadata,
+                parent_snapshot_id=state.snapshot_id if state is not None and not topology_changed else None,
+                label="homotopy solution",
+            )
+            run_info = build_run_info(config, x0=fs.x0, var_names=fs.var_names)
+            save_results_zarr(
+                results,
+                os.path.join(outputs_dir, f"{base_name}_results.zarr"),
+                run_info=run_info,
+            )
+            logger.info("Homotopy apply succeeded. New snapshot saved.")
+            return
+
+        # Both failed — auto-revert and write divergence report
+        logger.error("Homotopy also failed to converge.")
+        prev_id = state.snapshot_id if state is not None else "unknown"
+        sm.rollback(1)
+        logger.warning(f"Reverted .pfstate to snapshot before {prev_id}.")
+        breakdown = log_residual_breakdown(fs)
+        divergence = build_divergence_report(
+            drifted_params=drifted,
+            solver_stats=hom_stats,
+            x_last=x_hom,
+            var_names=fs.var_names,
+            breakdown=breakdown,
+        )
+    else:
+        # Cold start also failed; no rollback (nothing to revert to)
+        if not drifted and state is None:
+            logger.error("Cold-start solve failed to converge (no prior snapshot).")
+        elif skip_homotopy:
+            logger.error("Cold-start solve failed to converge (--skip-homotopy).")
+        else:
+            logger.error("Cold-start solve failed to converge.")
+        breakdown = log_residual_breakdown(fs)
+        divergence = build_divergence_report(
+            drifted_params=[],
+            solver_stats=fs.solver_stats,
+            x_last=getattr(fs, "x_converged", []),
+            var_names=getattr(fs, "var_names", []),
+            breakdown=breakdown,
+        )
+
+    write_divergence_report(outputs_dir, base_name, divergence)
+    raise SystemExit(1)

processforge-0.2.40/src/processforge/cli/common.py

@@ -0,0 +1,280 @@
+"""Shared CLI helpers — provider checks, state loading, metadata, divergence reports."""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import importlib
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+from .. import __version__ as _pf_version
+from ..utils.validate_flowsheet import validate_flowsheet
+from ..state import StateManager
+
+if TYPE_CHECKING:
+    from ..state import SnapshotState
+
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+
+def output_root() -> str:
+    """Root directory for run outputs (zarr, provider artifacts).
+
+    Defaults to ``outputs`` for local runs; the Docker image sets
+    ``PROCESSFORGE_OUTPUT_DIR=/data`` so outputs land on the mounted volume.
+    """
+    return os.environ.get("PROCESSFORGE_OUTPUT_DIR", "outputs")
+
+
+def require_existing_file(path: str, label: str = "Flowsheet file") -> None:
+    """Fail fast with a consistent message when an input path is missing."""
+    if not os.path.exists(path):
+        logger.error(f"{label} '{path}' not found.")
+        raise SystemExit(1)
+
+
+# ---------------------------------------------------------------------------
+# Flowsheet validation
+# ---------------------------------------------------------------------------
+
+def validate_runtime_flowsheet(path: str) -> dict:
+    """Validate flowsheet config and attach source path for runtime providers."""
+    try:
+        config = validate_flowsheet(path)
+    except Exception as e:
+        logger.error(f"Failed to validate flowsheet file '{path}': {e}")
+        logger.debug("Validation traceback:", exc_info=True)
+        raise SystemExit(1)
+
+    # Added after schema validation so additionalProperties:false doesn't reject it.
+    config["_config_path"] = path
+    return config
+
+
+def validate_snapshot_config(state: "SnapshotState", base_name: str) -> None:
+    """Warn if a loaded snapshot config has missing required fields."""
+    from ..types import FlowsheetConfig
+
+    snap_cfg = state.config
+    try:
+        FlowsheetConfig.from_dict(snap_cfg)
+    except (TypeError, KeyError) as exc:
+        logger.warning(
+            f"Snapshot '{state.snapshot_id}' for '{base_name}' has an "
+            f"incompatible config schema: {exc}. "
+            f"Delete 'outputs/{base_name}.pfstate' and re-run to create a "
+            f"fresh snapshot."
+        )
+
+
+# ---------------------------------------------------------------------------
+# Metadata
+# ---------------------------------------------------------------------------
+
+def build_run_metadata(config: dict, solver_tol: float, solver_max_iter: int, backend: str) -> dict:
+    """Build run metadata for checkpoint storage."""
+    config_bytes = json.dumps(config, sort_keys=True).encode("utf-8")
+    flowsheet_hash = hashlib.sha256(config_bytes).hexdigest()[:16]
+    return {
+        "version": _pf_version,
+        "flowsheet_hash": flowsheet_hash,
+        "solver_settings": {
+            "tol": solver_tol,
+            "max_iter": solver_max_iter,
+            "backend": backend,
+        },
+    }
+
+
+def extract_providers(flowsheet_path: str) -> dict:
+    """Read flowsheet JSON and return the raw providers dict."""
+    try:
+        with open(flowsheet_path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        logger.error(f"Failed to read flowsheet '{flowsheet_path}': {e}")
+        raise SystemExit(1)
+    providers = config.get("providers", {})
+    if not providers:
+        logger.warning(f"No providers declared in '{flowsheet_path}'.")
+    return providers
+
+
+# ---------------------------------------------------------------------------
+# State management
+# ---------------------------------------------------------------------------
+
+def load_state_manager(outputs_dir: str, base_name: str) -> tuple[StateManager, "SnapshotState | None"]:
+    """Create a StateManager and load the snapshot (if it exists)."""
+    state_path = os.path.join(outputs_dir, f"{base_name}.pfstate")
+    sm = StateManager(state_path)
+    state = sm.load_state()
+    return sm, state
+
+
+# ---------------------------------------------------------------------------
+# Provider checking
+# ---------------------------------------------------------------------------
+
+def _resolve_provider_url(cfg: dict, ptype: str) -> str:
+    """Build the provider URL, falling back to the default port."""
+    from ..providers.registry import get_provider_default_port
+
+    url = cfg.get("url")
+    if not url:
+        port = get_provider_default_port(ptype) or 9000
+        url = f"http://localhost:{port}"
+    return url
+
+
+def check_providers(
+    config: dict,
+    flowsheet_path: str,
+    *,
+    fail_fast: bool = True,
+    verbose: bool = False,
+) -> None:
+    """Verify all declared providers are reachable or importable.
+
+    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.
+    """
+    from ..providers.registry import is_containerized, _PROVIDER_CATALOG
+
+    providers = config.get("providers", {})
+    errors: list[str] = []
+
+    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)
+        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)
+
+    if errors:
+        raise SystemExit(1)
+
+
+# ---------------------------------------------------------------------------
+# Divergence reports
+# ---------------------------------------------------------------------------
+
+def log_residual_breakdown(fs: Any) -> list[dict]:
+    """Log the top residual violators from a failed solve and return the breakdown."""
+    breakdown = getattr(fs, "residual_breakdown", [])
+    if breakdown:
+        logger.error("Top residual violators:")
+        for entry in breakdown:
+            logger.error(
+                f"  [{entry['index']:4d}] {entry['var_name']:<35s}  |F| = {entry['residual']:.4e}"
+            )
+    else:
+        logger.debug("No residual breakdown available from solver.")
+    return breakdown
+
+
+def build_divergence_report(
+    *,
+    drifted_params: list[str],
+    solver_stats: dict,
+    x_last: Any,
+    var_names: list[str],
+    breakdown: list[dict],
+) -> dict:
+    """Construct the divergence report dict for failed solves."""
+    x_last_list = x_last.tolist() if hasattr(x_last, "tolist") else (x_last if isinstance(x_last, list) else [])
+    var_names_list = var_names if var_names else []
+
+    if not x_last_list:
+        logger.debug("x_last unavailable — divergence report will have empty x_last field.")
+    if not var_names_list:
+        logger.debug("var_names unavailable — divergence report will have empty var_names field.")
+
+    return {
+        "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "drifted_params": drifted_params,
+        "final_norm": solver_stats.get("final_norm"),
+        "solver_stats": solver_stats,
+        "x_last": x_last_list,
+        "var_names": var_names_list,
+        "top_violators": breakdown,
+    }
+
+
+def write_divergence_report(outputs_dir: str, base_name: str, divergence: dict) -> None:
+    """Write the divergence report JSON and log its path."""
+    div_path = os.path.join(outputs_dir, f"{base_name}_divergence.json")
+    with open(div_path, "w", encoding="utf-8") as f:
+        json.dump(divergence, f, indent=2)
+    logger.error(f"Divergence report written to {div_path}")
+
+
+# ---------------------------------------------------------------------------
+# State saving (with error handling)
+# ---------------------------------------------------------------------------
+
+def save_snapshot(
+    sm: StateManager,
+    config: dict,
+    x_converged: Any,
+    var_names: list[str],
+    *,
+    metadata: dict,
+    parent_snapshot_id: str | None,
+    label: str = "snapshot",
+) -> str:
+    """Save a state snapshot, logging a clear message on failure."""
+    try:
+        return sm.save_state(
+            config, x_converged, var_names,
+            metadata=metadata,
+            parent_snapshot_id=parent_snapshot_id,
+        )
+    except Exception as exc:
+        logger.error(f"Failed to save {label}: {exc}")
+        logger.warning("Results were computed but state was not persisted.")
+        raise SystemExit(1)

processforge-0.2.40/src/processforge/cli/diagram.py

@@ -0,0 +1,57 @@
+"""``pf diagram`` — generate a flowsheet diagram."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Literal
+
+import typer
+from loguru import logger
+
+from ..utils.flowsheet_diagram import draw_flowsheet
+from .common import require_existing_file
+
+
+def diagram(
+    flowsheet: str = typer.Argument(help="Path to the flowsheet JSON file"),
+    output_dir: str = typer.Option(
+        "diagrams",
+        "--output-dir",
+        "-o",
+        help="Output directory (default: diagrams)",
+    ),
+    format: Literal["png", "svg", "pdf"] = typer.Option(
+        "png",
+        "--format",
+        "-f",
+        help="Output format (default: png)",
+    ),
+) -> None:
+    """Generate a flowsheet diagram from a JSON file."""
+    require_existing_file(flowsheet)
+
+    try:
+        with open(flowsheet, "r", encoding="utf-8") as f:
+            flowsheet_schema = json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        logger.error(f"Failed to read flowsheet '{flowsheet}': {e}")
+        raise SystemExit(1)
+
+    output_dir = output_dir or "diagrams"
+    fmt = format or "png"
+
+    base_name = os.path.splitext(os.path.basename(flowsheet))[0]
+
+    try:
+        output_path = draw_flowsheet(
+            flowsheet_schema,
+            output_directory=output_dir,
+            output_filename=base_name,
+            file_format=fmt,
+        )
+    except Exception as e:
+        logger.error(f"Failed to generate diagram: {type(e).__name__}: {e}")
+        raise SystemExit(1)
+
+    logger.info(f"Diagram saved to {output_path}")