processforge 0.2.34__tar.gz → 0.2.40__tar.gz

{processforge-0.2.34 → processforge-0.2.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processforge
-Version: 0.2.34
+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,8 +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: pi>=0.1.2
-Requires-Dist: pip>=26.1.2
+Requires-Dist: typer>=0.12
 Provides-Extra: eo
 Requires-Dist: pyomo>=6.7; extra == "eo"
 Provides-Extra: eo-casadi
@@ -66,38 +65,58 @@ A lightweight Python framework for process simulation, coupling hydraulic, therm
 
 ## Install
 
+Install the `pf` command-line tool with [uv](https://docs.astral.sh/uv/):
+
 ```bash
-uv add processforge
+uv tool install processforge
 ```
 
 For CoolProp-backed units:
 
 ```bash
-uv add "processforge[coolprop]"
+uv tool install "processforge[coolprop]"
 ```
 
 Optional solver backends:
 
 ```bash
-uv add "processforge[eo]"
-uv add "processforge[eo-casadi]"
-uv add "processforge[modelica]"
+uv tool install "processforge[eo]"
+uv tool install "processforge[eo-casadi]"
+uv tool install "processforge[modelica]"
 ```
 
 ## Quick start
 
-Use `plan` to validate and preview changes, then `apply` to solve and store a snapshot. For flowsheets without Tank units, use `apply` to solve with the EO solver. 
+1. **Install the tool**
 
-```bash
-pf init
-pf plan flowsheets/hydraulic-chain.json
-pf apply flowsheets/hydraulic-chain.json
-```
-For flowsheets with Tank units, use `run` to solve with the SM solver. For direct run mode (for dynamic flowsheets with Tank units), use `run`:
+   ```bash
+   uv tool install processforge
+   ```
 
-```bash
-pf run flowsheets/hydraulic-chain.json
-```
+2. **Download an example flowsheet**
+
+   ```bash
+   curl -O https://raw.githubusercontent.com/urjanova/processforge/master/flowsheets/hydraulic-chain.json
+   ```
+
+3. **Initialize, plan, and apply**
+
+   ```bash
+   pf init
+   pf plan hydraulic-chain.json
+   pf apply hydraulic-chain.json
+   ```
+
+   `plan` validates the flowsheet (schema, DOF, units) without running the solver; `apply` solves it and stores a snapshot.
+
+4. **Look at the output**
+
+   `pf apply` writes results under `outputs/`:
+   - `*_results.zarr` — simulation results store
+   - `*_validation.xlsx` — validation report
+   - `*.pfstate/` — versioned snapshot store with a `latest` pointer
+
+   For flowsheets with Tank units (dynamic), use `pf run` instead of `pf apply` to solve with the SM solver.
 
 ## Python API
 

processforge-0.2.40/README.md

@@ -0,0 +1,82 @@
+# Processforge
+
+![processforge-logo](images/processforge-logo.svg)
+
+A lightweight Python framework for process simulation, coupling hydraulic, thermal, and reactor workflows.
+
+## Install
+
+Install the `pf` command-line tool with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install processforge
+```
+
+For CoolProp-backed units:
+
+```bash
+uv tool install "processforge[coolprop]"
+```
+
+Optional solver backends:
+
+```bash
+uv tool install "processforge[eo]"
+uv tool install "processforge[eo-casadi]"
+uv tool install "processforge[modelica]"
+```
+
+## Quick start
+
+1. **Install the tool**
+
+   ```bash
+   uv tool install processforge
+   ```
+
+2. **Download an example flowsheet**
+
+   ```bash
+   curl -O https://raw.githubusercontent.com/urjanova/processforge/master/flowsheets/hydraulic-chain.json
+   ```
+
+3. **Initialize, plan, and apply**
+
+   ```bash
+   pf init
+   pf plan hydraulic-chain.json
+   pf apply hydraulic-chain.json
+   ```
+
+   `plan` validates the flowsheet (schema, DOF, units) without running the solver; `apply` solves it and stores a snapshot.
+
+4. **Look at the output**
+
+   `pf apply` writes results under `outputs/`:
+   - `*_results.zarr` — simulation results store
+   - `*_validation.xlsx` — validation report
+   - `*.pfstate/` — versioned snapshot store with a `latest` pointer
+
+   For flowsheets with Tank units (dynamic), use `pf run` instead of `pf apply` to solve with the SM solver.
+
+## Python API
+
+```python
+from processforge import EOFlowsheet, validate_flowsheet
+config = validate_flowsheet("flowsheets/hydraulic-chain.json")
+fs = EOFlowsheet(config, backend="scipy")
+results = fs.run()
+```
+
+## Usage and Docker
+Processforge is also available as Docker images, and can be run in the cloud. See the [usage guide](docs/usage.md) for CLI commands, workflows, Docker, and cloud notes.
+
+## Flowsheets
+The core of Processforge is the flowsheet JSON format, which defines materials, units, and recycle rules. See below for more information on the formats and example flowsheets.
+- [docs/flowsheets.md](docs/flowsheets.md) : flowsheet JSON format, materials, units, and recycle rules
+- [flowsheets/](flowsheets/) : example flowsheets shipped with the repo
+
+
+## License
+
+BSD 3-Clause License

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

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

{processforge-0.2.34 → 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)