processforge 0.3.25__tar.gz → 0.3.26__tar.gz

{processforge-0.3.25/src/processforge.egg-info → processforge-0.3.26}/PKG-INFO

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

{processforge-0.3.25 → processforge-0.3.26}/pyproject.toml

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

{processforge-0.3.25 → processforge-0.3.26}/src/processforge/__init__.py

@@ -30,7 +30,7 @@ from .units.flash import Flash
 from .units.heater import Heater
 from .eo import EOFlowsheet, EOSolver
 
-__version__ = "0.3.25"
+__version__ = "0.3.26"
 
 __all__ = [
     "Flowsheet",

{processforge-0.3.25 → processforge-0.3.26}/src/processforge/cli/apply.py

@@ -6,46 +6,10 @@ import os
 import time
 from typing import Literal
 
-import hashlib
-import json
-import os
 import typer
-from datetime import datetime, timezone
 from loguru import logger
 
-
-def _persist_run(archive, fs, results, run_info, config, base_name, snapshot_id):
-    """Build a standardized RunManifest and persist it to the archive."""
-    run_id = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + "_" + os.urandom(3).hex()
-    flowsheet_hash = hashlib.sha256(
-        json.dumps(config, sort_keys=True, default=str).encode("utf-8")
-    ).hexdigest()[:16]
-    manifest = fs.collect_outputs(
-        run_id, config.get("simulation", {}).get("mode", "steady"),
-        base_name, provenance=run_info.model_dump(),
-    )
-    manifest.snapshot_id = snapshot_id
-    stream_results = {k: v for k, v in results.items() if not hasattr(v, "fields")}
-    archive.save_run(manifest, stream_results=stream_results)
-
-    # Always persist a Zarr copy of the standardized outputs (fields + artifacts)
-    # inside the archive, mirroring `pf run`.
-    try:
-        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(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}")
-
-    logger.info(f"Run saved    : {run_id}")
-    return run_id
-
+from .persist import make_run_id, persist_run
 from ..eo import EOFlowsheet
 from ..provenance import build_run_info
 from .common import (
@@ -158,14 +122,15 @@ def apply(
             label="converged state",
         )
         run_info = build_run_info(config, x0=fs.x0, var_names=fs.var_names)
-        saved_run_id = _persist_run(sm, fs, results, run_info, config, base_name, snapshot_id)
+        run_id = make_run_id()
+        persist_run(sm, fs, run_id, results, run_info, config, base_name, snapshot_id)
         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      : {display_backend(config, fs.backend)}")
         logger.info(f"  Snapshot ID  : {snapshot_id}")
-        logger.info(f"  Run ID       : {saved_run_id}")
+        logger.info(f"  Run ID       : {run_id}")
         logger.info(f"  Elapsed (s)  : {elapsed:.2f}")
         return
 
@@ -180,25 +145,31 @@ def apply(
         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
-            )
+            homotopy_result = solve_with_homotopy(tmp_fs, manager, solver, state, drifted)
+            if homotopy_result.converged:
+                # Assemble the real (converged) outputs from the homotopy
+                # solution while the providers are still alive. The `results`
+                # from the earlier failed direct solve must NOT be persisted.
+                tmp_fs.assemble_from_solution(
+                    manager, homotopy_result.x_solution, True, homotopy_result.stats
+                )
         finally:
             teardown_providers(tmp_fs._provider_map)
 
-        if hom_converged:
+        if homotopy_result.converged:
             logger.info(
-                f"Homotopy converged: ||F||={hom_stats.get('final_norm', '?'):.3e}, "
-                f"iterations={hom_stats.get('iterations', '?')}"
+                f"Homotopy converged: ||F||={homotopy_result.stats.get('final_norm', '?'):.3e}, "
+                f"iterations={homotopy_result.stats.get('iterations', '?')}"
             )
-            save_snapshot(
-                sm, config, x_hom, fs.var_names,
+            snapshot_id = save_snapshot(
+                sm, config, homotopy_result.x_solution, 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)
-            _persist_run(sm, fs, results, run_info, config, base_name, snapshot_id)
+            run_id = make_run_id()
+            persist_run(sm, tmp_fs, run_id, tmp_fs.results, run_info, config, base_name, snapshot_id)
             logger.info("Homotopy apply succeeded. New snapshot saved.")
             return
 
@@ -210,8 +181,8 @@ def apply(
         breakdown = log_residual_breakdown(fs)
         divergence = build_divergence_report(
             drifted_params=drifted,
-            solver_stats=hom_stats,
-            x_last=x_hom,
+            solver_stats=homotopy_result.stats,
+            x_last=homotopy_result.x_solution,
             var_names=fs.var_names,
             breakdown=breakdown,
         )

processforge-0.3.26/src/processforge/cli/persist.py

@@ -0,0 +1,99 @@
+"""Shared run-persistence helpers for the ``pf run`` / ``pf apply`` CLIs.
+
+Both commands build a :class:`~processforge.types.RunManifest`, save it to the
+:class:`~processforge.persistence.archive.ProcessStateArchive`, and write a Zarr
+copy of the standardized outputs. That logic was previously duplicated (with
+slightly different bugs in each copy); it now lives here in one place.
+"""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import json
+import os
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from ..persistence.archive import ProcessStateArchive
+    from ..types import RunInfo
+
+_RUN_ID_TS_FMT = "%Y%m%dT%H%M%SZ"
+
+
+def make_run_id() -> str:
+    """Build a unique, sortable run id: ``<UTC timestamp>_<6 hex bytes>``."""
+    return (
+        datetime.datetime.now(datetime.timezone.utc).strftime(_RUN_ID_TS_FMT)
+        + "_"
+        + os.urandom(3).hex()
+    )
+
+
+def flowsheet_hash(config: dict) -> str:
+    """Short (16-hex) sha256 of a flowsheet config for run/index correlation."""
+    return hashlib.sha256(
+        json.dumps(config, sort_keys=True, default=str).encode("utf-8")
+    ).hexdigest()[:16]
+
+
+def persist_run(
+    archive: "ProcessStateArchive",
+    fs: Any,
+    run_id: str,
+    results: dict,
+    run_info: "RunInfo | dict",
+    config: dict,
+    base_name: str,
+    snapshot_id: str | None = None,
+) -> str:
+    """Persist a run's manifest + Zarr outputs into *archive*.
+
+    Args:
+        archive: The :class:`ProcessStateArchive` for this flowsheet.
+        fs: The flowsheet object that produced *results* (must expose
+            ``collect_outputs``). Either ``EOFlowsheet`` or ``Flowsheet``.
+        run_id: Unique run id (use :func:`make_run_id`).
+        results: The solve's stream/unit result dict (the *converged* one).
+        run_info: Provenance from
+            :func:`processforge.provenance.build_run_info`.
+        config: Validated flowsheet config (for the simulation mode).
+        base_name: Flowsheet basename used for archive paths.
+        snapshot_id: Optional snapshot id to stamp on the manifest (so a run
+            can be linked back to the state it was derived from).
+
+    Returns:
+        The run id that was persisted.
+    """
+    mode = config.get("simulation", {}).get("mode", "steady")
+    run_info_dump = (
+        run_info.model_dump() if hasattr(run_info, "model_dump") else run_info
+    )
+    manifest = fs.collect_outputs(
+        run_id, mode, base_name, provenance=run_info_dump
+    )
+    if snapshot_id is not None:
+        manifest.snapshot_id = snapshot_id
+
+    stream_results = {k: v for k, v in results.items() if not hasattr(v, "fields")}
+    archive.save_run(manifest, stream_results=stream_results)
+
+    # Always persist a Zarr copy of the standardized outputs (fields + artifacts)
+    # inside the archive, mirroring `pf run`.
+    try:
+        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(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}")
+
+    logger.info(f"Run saved    : {run_id}")
+    return run_id

{processforge-0.3.25 → processforge-0.3.26}/src/processforge/cli/run.py

@@ -1,7 +1,6 @@
 """``pf run`` — run a process simulation from a flowsheet JSON file."""
 from __future__ import annotations
 
-import hashlib
 import os
 from datetime import datetime, timezone
 
@@ -21,22 +20,7 @@ from .common import (
     validate_runtime_flowsheet,
     _resolve_provider_url,
 )
-
-
-def _flowsheet_hash(config: dict) -> str:
-    return hashlib.sha256(
-        json_dumps(config).encode("utf-8")
-    ).hexdigest()[:16]
-
-
-def json_dumps(obj) -> str:
-    import json
-
-    return json.dumps(obj, sort_keys=True, default=str)
-
-
-def _run_id() -> str:
-    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + "_" + os.urandom(3).hex()
+from .persist import flowsheet_hash, make_run_id, persist_run
 
 
 def _log_active_providers(config: dict) -> None:
@@ -99,8 +83,8 @@ def run(
     is_dynamic = mode == "dynamic"
 
     # Standardized run id, shared with container-side artifact uploads.
-    run_id = _run_id()
-    flowsheet_hash = _flowsheet_hash(config)
+    run_id = make_run_id()
+    flowsheet_hash_value = flowsheet_hash(config)
 
     if is_dynamic:
         # Load .pfarchive snapshot as t=0 if available.
@@ -164,17 +148,12 @@ def run(
     # are keyed by the same run_id/flowsheet_hash as this archive run.
     for provider in getattr(fs, "_provider_map", {}).values():
         if hasattr(provider, "set_run_context"):
-            provider.set_run_context(run_id, flowsheet_hash)
+            provider.set_run_context(run_id, flowsheet_hash_value)
 
     # Build + persist the standardized run manifest.
     archive_path = os.path.join(outputs_dir, f"{base_name}.pfarchive")
     archive = ProcessStateArchive(archive_path)
-    manifest = fs.collect_outputs(run_id, mode, base_name, provenance=run_info.model_dump())
-    stream_results = {
-        k: v for k, v in results.items()
-        if not hasattr(v, "fields")  # exclude EngineOutput objects
-    }
-    archive.save_run(manifest, stream_results=stream_results)
+    persist_run(archive, fs, run_id, results, run_info, config, base_name)
 
     # Persist a StateManager snapshot so `pf plan` (and `pf apply`) can diff
     # against this run as a baseline. Without it, `pf plan` always reports
@@ -191,27 +170,11 @@ def run(
         except Exception as e:
             logger.warning(f"Failed to save state snapshot: {type(e).__name__}: {e}")
 
-    # Always persist a Zarr copy of the standardized outputs (fields + artifacts)
-    # inside the archive. Works for every provider (OpenMC, CoolProp, FESTIM,
-    # Cantera) and for both local and remote docker runs — remote artifacts
-    # reference their S3 remote_uris.
-    try:
-        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(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}")
-
     logger.info(f"Backend      : {display_backend(config, getattr(fs, 'backend', 'dynamic'))}")
     logger.info(f"Run saved    : {os.path.join(archive_path, 'runs', run_id + '.json')}")
 
     # Summarize standardized outputs.
+    manifest = archive.load_run(run_id)
     for unit_name, out in manifest.units.items():
         for f in out.fields:
             logger.info(f"  [{unit_name}] {f.name} = {f.quantity.value} {f.quantity.unit}")

{processforge-0.3.25 → processforge-0.3.26}/src/processforge/eo/flowsheet.py

@@ -93,24 +93,58 @@ class EOFlowsheet:
                     )
                 except Exception:  # noqa: BLE001
                     self.residual_breakdown = []
-            results = manager.extract_results(x_sol)
-
-            # Run standalone SolverUnit instances (no inlet/outlet streams —
-            # they delegate entirely to their provider's run_simulation()).
-            from processforge.units.solver_unit import SolverUnit
-            for unit_name, unit in self._unit_objects.items():
-                if isinstance(unit, SolverUnit):
-                    logger.info(f"EOFlowsheet: running standalone SolverUnit '{unit_name}'")
-                    unit_result = unit._run_impl({})
-                    results[unit_name] = unit_result
-                    self.engine_outputs[unit_name] = unit_result
+            results = self.assemble_from_solution(manager, x_sol, converged, stats)
 
             logger.info("EOFlowsheet: simulation complete.")
-            self.results = results
             return results
         finally:
             teardown_providers(self._provider_map)
 
+    def assemble_from_solution(
+        self,
+        manager: "GlobalJacobianManager",
+        x_sol: "np.ndarray",
+        converged: bool,
+        stats: dict,
+    ) -> dict:
+        """Populate run outputs from an already-computed solution vector.
+
+        Used both by :meth:`run` (after the Newton solve) and by callers such as
+        the homotopy fallback in ``pf apply``, where a solved ``x`` is produced
+        externally and must be turned into the same standardized ``results`` that
+        :meth:`run` would have returned. This keeps the post-solve assembly in
+        exactly one place.
+
+        Args:
+            manager: The live Jacobian manager used to build ``x_sol``.
+            x_sol: The converged (or best-effort) solution vector.
+            converged: Whether the solve was judged converged.
+            stats: Solver statistics dict (e.g. ``final_norm``, ``iterations``).
+
+        Returns:
+            The stream/unit result dict (also stored on ``self.results``).
+        """
+        self.x_converged = x_sol
+        self.converged = converged
+        self.solver_stats = stats
+
+        results = manager.extract_results(x_sol)
+
+        # Run standalone SolverUnit instances (no inlet/outlet streams —
+        # they delegate entirely to their provider's run_simulation()).
+        from processforge.units.solver_unit import SolverUnit
+
+        self.engine_outputs = {}
+        for unit_name, unit in self._unit_objects.items():
+            if isinstance(unit, SolverUnit):
+                logger.info(f"EOFlowsheet: running standalone SolverUnit '{unit_name}'")
+                unit_result = unit._run_impl({})
+                results[unit_name] = unit_result
+                self.engine_outputs[unit_name] = unit_result
+
+        self.results = results
+        return results
+
     # ------------------------------------------------------------------
     # Standardized output collection
     # ------------------------------------------------------------------

{processforge-0.3.25 → processforge-0.3.26}/src/processforge/eo/solver.py

@@ -6,12 +6,14 @@ from typing import TYPE_CHECKING, Optional
 
 import numpy as np
 from loguru import logger
+from pydantic import BaseModel, ConfigDict
 
 from .backends import ScipyBackend, PyomoBackend, CasADiBackend
 from .backends.base import AbstractEOBackend
 from ..types import SnapshotState
 
 if TYPE_CHECKING:
+    from .flowsheet import EOFlowsheet
     from .jacobian import GlobalJacobianManager
 
 
@@ -29,9 +31,18 @@ _BACKENDS: dict[str, type[AbstractEOBackend]] = {
 }
 
 
+class HomotopyResult(BaseModel):
+    """Typed outcome of :func:`solve_with_homotopy`."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    x_solution: np.ndarray
+    converged: bool
+    stats: dict
+
+
 class EOSolver:
-    """
-    Selects and runs the EO backend specified by ``backend`` name.
+    """Selects and runs the EO backend specified by ``backend`` name.
 
     Args:
         backend: One of ``"scipy"``, ``"pyomo"``, ``"casadi"``.
@@ -117,22 +128,40 @@ def compute_residual_breakdown(
 
 
 def solve_with_homotopy(
-    fs, manager, solver, state, drifted
-) -> "tuple[np.ndarray, bool, dict]":
-    """Try standard solve; if fails, fall back to step-wise homotopy."""
+    flowsheet: "EOFlowsheet",
+    manager: "GlobalJacobianManager",
+    solver: "EOSolver",
+    state: "SnapshotState | dict",
+    drifted: list[str],
+) -> "HomotopyResult":
+    """Try a standard solve; if it fails, fall back to step-wise homotopy.
+
+    Args:
+        flowsheet: The current-config :class:`EOFlowsheet` (used for its config
+            and backend).
+        manager: The live Jacobian manager for the current config.
+        solver: The :class:`EOSolver` instance driving each continuation step.
+        state: The prior converged snapshot (object or dict) used as the warm
+            start.
+        drifted: Dotted config paths that changed between the snapshot and the
+            current flowsheet.
+
+    Returns:
+        A :class:`HomotopyResult` holding the best solution vector found, whether
+        it converged, and the associated solver statistics.
+    """
     old_config = state.config if isinstance(state, SnapshotState) else state["config"]
-    current_config = fs.config
+    current_config = flowsheet.config
 
-    def update_config_value(cfg, path, value):
-        from copy import deepcopy
-        parts = path.split('.')
+    def update_config_value(cfg: dict, path: str, value: float) -> None:
+        parts = path.split(".")
         d = cfg
         for p in parts[:-1]:
             d = d[p]
         d[parts[-1]] = float(value)
-        
-    def get_config_value(cfg, path):
-        parts = path.split('.')
+
+    def get_config_value(cfg: dict, path: str):
+        parts = path.split(".")
         d = cfg
         for p in parts[:-1]:
             if p not in d:
@@ -144,10 +173,14 @@ def solve_with_homotopy(
     _DEFAULT_SIGNALS = {
         "openmc": ConvergenceSignal(signal_key="k_eff", target=1.0, tolerance=0.01),
     }
-    provider = current_config.get("units", {}).get(
-        list(current_config.get("units", {}).keys())[0], {}
-    ).get("provider", "openmc") if current_config.get("units") else None
-    
+    provider = (
+        current_config.get("units", {})
+        .get(list(current_config.get("units", {}).keys())[0], {})
+        .get("provider", "openmc")
+        if current_config.get("units")
+        else None
+    )
+
     active_signal = None
     if convergence_signal:
         provider_filter = convergence_signal.get("provider")
@@ -155,103 +188,109 @@ def solve_with_homotopy(
             active_signal = ConvergenceSignal(**convergence_signal)
     elif provider in _DEFAULT_SIGNALS:
         active_signal = _DEFAULT_SIGNALS[provider]
-    
+
     if active_signal:
         logger.info(
             f"Homotopy convergence signal: {active_signal.signal_key} "
             f"target={active_signal.target}"
         )
 
-    import numpy as np
-
     if not isinstance(state, SnapshotState):
-        x0 = np.array(state["x"])
+        warm_start = np.array(state["x"])
     else:
-        x0 = np.array(state.x)
+        warm_start = np.array(state.x)
 
-    x_sol, converged, stats = solver.solve(manager, x0)
+    x_solution, converged, stats = solver.solve(manager, warm_start)
     if converged:
         logger.info("Standard solver converged with previous state's warm guess.")
-        return x_sol, converged, stats
-        
+        return HomotopyResult(x_solution=x_solution, converged=converged, stats=stats)
+
     logger.warning("Standard solve failed. Invoking Homotopy 'step-wise apply' solver...")
-    
-    drifts = []
-    for d in drifted:
-        old_val = get_config_value(old_config, d)
-        new_val = get_config_value(current_config, d)
+
+    interpolated_drifts: list[tuple[str, float, float]] = []
+    for drift in drifted:
+        old_val = get_config_value(old_config, drift)
+        new_val = get_config_value(current_config, drift)
         if isinstance(old_val, (int, float)) and isinstance(new_val, (int, float)):
-            drifts.append((d, old_val, new_val))
-            
-    if not drifts:
+            interpolated_drifts.append((drift, float(old_val), float(new_val)))
+
+    if not interpolated_drifts:
         logger.error("No continuous numerical parameters to interpolate. Homotopy fails.")
-        return x_sol, False, stats
+        return HomotopyResult(x_solution=x_solution, converged=False, stats=stats)
 
-    x_current = x0.copy()
+    x_current = warm_start.copy()
     best_x = x_current.copy()
-    best_residual = float('inf')
+    best_residual = float("inf")
     best_step = 0
-    
+
     from copy import deepcopy
+
     interpolated_config = deepcopy(old_config)
     steps = 10
-    
+
     from .flowsheet import EOFlowsheet
     from processforge.providers.manager import teardown_providers
-    
+
     for step in range(1, steps + 1):
         alpha = step / steps
         logger.info(f"--- Homotopy Step {step}/{steps} (alpha={alpha:.1f}) ---")
-        
-        for d, old_val, new_val in drifts:
-            val = old_val + alpha * (new_val - old_val)
-            update_config_value(interpolated_config, d, val)
-        
-        step_fs = EOFlowsheet(interpolated_config, backend=fs.backend)
+
+        for path, old_val, new_val in interpolated_drifts:
+            value = old_val + alpha * (new_val - old_val)
+            update_config_value(interpolated_config, path, value)
+
+        step_flowsheet = EOFlowsheet(interpolated_config, backend=flowsheet.backend)
         try:
-            step_manager = step_fs._build()
+            step_manager = step_flowsheet._build()
             step_x0 = x_current.copy()
-            step_fs.x0 = step_x0
-            step_fs.var_names = step_fs._build_var_names(step_manager)
-            
-            step_solver = EOSolver(backend=fs.backend, tol=solver.tol, max_iter=solver.max_iter)
-            x_current, step_converged, s_stats = step_solver.solve(step_manager, step_x0)
-            
-            current_residual = s_stats.get('final_norm', float('inf'))
-            
+            step_flowsheet.x0 = step_x0
+            step_flowsheet.var_names = step_flowsheet._build_var_names(step_manager)
+
+            step_solver = EOSolver(
+                backend=flowsheet.backend, tol=solver.tol, max_iter=solver.max_iter
+            )
+            x_current, step_converged, step_stats = step_solver.solve(step_manager, step_x0)
+
+            current_residual = step_stats.get("final_norm", float("inf"))
+
             if active_signal and active_signal.target is not None:
                 signal_key = active_signal.signal_key
                 signal_target = active_signal.target
                 signal_tol = active_signal.tolerance
-                all_scalars = {}
-                for unit_name, unit_scalars in step_manager.scalars.items():
+                all_scalars: dict[str, float] = {}
+                for unit_scalars in step_manager.scalars.values():
                     all_scalars.update(unit_scalars)
                 signal_val = all_scalars.get(signal_key)
                 if signal_val is not None:
                     rel_error = abs(signal_val - signal_target) / signal_target
-                    logger.info(f"  {signal_key}={signal_val:.4f}, target={signal_target}, rel_error={rel_error:.4f}")
+                    logger.info(
+                        f"  {signal_key}={signal_val:.4f}, target={signal_target}, "
+                        f"rel_error={rel_error:.4f}"
+                    )
                     if rel_error < signal_tol:
                         logger.info(f"  Converged via convergence signal at step {step}")
                         best_x = x_current.copy()
                         best_residual = current_residual
                         best_step = step
                         break
-            
+
             if not step_converged:
-                logger.error(f"Homotopy failed to converge at step {step} (alpha={alpha:.1f})")
+                logger.error(
+                    f"Homotopy failed to converge at step {step} (alpha={alpha:.1f})"
+                )
                 if best_step > 0:
                     logger.info(f"Reverting to best checkpoint at step {best_step}")
                     x_current = best_x.copy()
-                return x_current, False, s_stats
-            
+                return HomotopyResult(x_solution=x_current, converged=False, stats=step_stats)
+
             if current_residual < best_residual:
                 best_residual = current_residual
                 best_x = x_current.copy()
                 best_step = step
-                
+
         finally:
-            teardown_providers(step_fs._provider_map)
-            
+            teardown_providers(step_flowsheet._provider_map)
+
     logger.info("Homotopy step-wise solve successfully reached target config.")
-    x_sol, conv, stats = solver.solve(manager, x_current)
-    return x_sol, conv, stats
+    x_solution, converged, stats = solver.solve(manager, x_current)
+    return HomotopyResult(x_solution=x_solution, converged=converged, stats=stats)