OpenPinch 0.8.0__tar.gz → 0.8.2__tar.gz

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/execution/README.md

@@ -18,8 +18,9 @@ Resolves synthesis settings from a prepared problem, plans the quality-tier path
 ## Invariants
 - A downstream task needs a successful parent outcome and the parent's in-process solver problem; `_parent_problem` raises `WorkflowContractError`, but `LocalSynthesisExecutor.execute` catches it and returns a failed task outcome carrying the message, while `FakeSynthesisExecutor` lets it propagate [executor.py:LocalSynthesisExecutor._parent_problem] [executor.py:LocalSynthesisExecutor.execute] [fake_executor.py:FakeSynthesisExecutor.execute].
 - Tasks are built inside pool workers only when no parent outcomes exist, no task has a parent and more than one worker is in use [executor.py:_can_build_tasks_in_workers].
-- TDM and ESM models use a fixed approach of 0.1 K; PDM uses the task approach temperature [executor.py:_task_model_approach_temperature].
+- TDM and ESM models use an approach of `max(0.1 K, HENS_MIN_EXCHANGER_APPROACH_SHARE x task approach)` (0.1 K at the default share of 0); PDM uses the task approach temperature [executor.py:_task_model_approach_temperature, LocalSynthesisExecutor._build_problem].
 - A solve counts as successful only when `mSuccess == 1` and `verify()` (if present) passes; failures carry a non-empty error string [executor.py:_solve_built_task, _failed_task_outcome].
+- A successful solve whose solver stopped before converging records `diagnostics["unconverged_termination"]`; it stays a success so downstream tasks can start from it [executor.py:_solve_built_task].
 - Stage-packing scope `"auto"` resolves to `"none"` at execution time [executor.py:_stage_packing_scope]. The scope only decides packing for non-compact PDM tasks and for TDM tasks; PDM tasks with `pdm_mode == "compact"` (tier 0 and the compact routes of tiers 2 to 5) always use the stage-packed model [executor.py:LocalSynthesisExecutor._model_factories_for_task].
 - Outcomes are returned in the order of the input tasks [executor.py:LocalSynthesisExecutor._collect_outcomes].
 - Settings are a frozen dataclass; only `evm_solver_options` is copied on construction, while `pdm_solver_options` and `tdm_solver_options` are shared references [settings.py:SynthesisWorkflowSettings.__post_init__].

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/execution/executor.py

@@ -246,7 +246,10 @@ class LocalSynthesisExecutor:
         parent_outcomes: dict[str, HeatExchangerNetworkSynthesisTaskOutcome],
     ) -> InternalHeatExchangerNetworkProblem:
         parent_problem = self._parent_problem(task, parent_outcomes)
-        dTmin = _task_model_approach_temperature(task)
+        dTmin = _task_model_approach_temperature(
+            task,
+            min_approach_share=problem.master_zone.config.hens.min_exchanger_approach_share,
+        )
         arrays = problem_to_solver_arrays(problem, dTmin)
         stage_selection = _pdm_stage_selection(problem, task)
         decompositions = None
@@ -407,6 +410,14 @@ def _solve_built_task(
                 return task, _failed_task_outcome(task, reason), internal_problem
 
         network = internal_problem.extract_network(run_id=task.run_id)
+        # An unconverged solve stays a success so downstream tasks can start
+        # from it; demote_infeasible_outcomes keeps it out of the ranking.
+        solver_run = getattr(solved, "solver_run", None)
+        diagnostics = (
+            {}
+            if getattr(solver_run, "converged", True)
+            else {"unconverged_termination": str(solver_run.termination_condition)}
+        )
         return (
             task,
             HeatExchangerNetworkSynthesisTaskOutcome(
@@ -415,6 +426,7 @@ def _solve_built_task(
                 network=network,
                 objective_value=network.total_annual_cost,
                 solver_status=_solver_status(internal_problem),
+                diagnostics=diagnostics,
             ),
             internal_problem,
         )
@@ -507,12 +519,20 @@ def _model_objective(method: HeatExchangerNetworkDesignMethod) -> str:
 
 def _task_model_approach_temperature(
     task: HeatExchangerNetworkSynthesisTask,
+    *,
+    min_approach_share: float = 0.0,
 ) -> float:
+    """Return the model's minimum approach temperature.
+
+    The pinch design step uses the task's approach. The thermal derivative and
+    evolution steps minimise cost down to 0.1 K, or to ``min_approach_share``
+    (``HENS_MIN_EXCHANGER_APPROACH_SHARE``) times the task's approach if larger.
+    """
     if task.method in {
         HeatExchangerNetworkDesignMethod.ThermalDerivative,
         HeatExchangerNetworkDesignMethod.NetworkEvolution,
     }:
-        return 0.1
+        return max(0.1, min_approach_share * float(task.approach_temperature))
     return float(task.approach_temperature)
 
 

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/models/README.md

@@ -25,6 +25,7 @@ Concrete GEKKO-based equation models for heat exchanger network synthesis, plus
 - `ThermalProfile` is frozen; its arrays must share one non-zero length and `side` must be "hot" or "cold". Smoothing applies only to symbolic arguments; plain numbers are exact. [thermal_profiles.py:ThermalProfile.__post_init__] [thermal_profiles.py:smooth_max0]
 - Stage packing applies only when `integers` is true, `S > 1` and some stage has positive capacity. [stage_packing.py:add_recovery_stage_packing_constraints]
 - PDM construction needs "above" and "below" decompositions; stage-wise construction needs an explicit stage count or a parent solution. [problem.py:InternalHeatExchangerNetworkProblem._build_pdm] [problem.py:InternalHeatExchangerNetworkProblem._build_stage_wise]
+- The amalgamated PDM case is built, not solved, so it takes the termination condition of the first required side whose solve did not converge; otherwise it keeps its own solver run. [problem.py:InternalHeatExchangerNetworkProblem._carry_unconverged_side_solve]
 - `get_solution` converts `ValueError` into `None` with `solution_failure_reason` set. [problem.py:InternalHeatExchangerNetworkProblem.get_solution]
 - Stage reduction keeps stages whose share of peak recovery meets a threshold (0.1, 5, 8, 10 percent for at most 3, 5, 8, 10 stages and 0 percent for more than 10; PDM and TDM solves only) and returns the original case unless the reduced model solves and verifies. [problem.py:InternalHeatExchangerNetworkProblem._utilisation_threshold] [problem.py:InternalHeatExchangerNetworkProblem.remove_unused_stages]
 

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/models/_base/README.md

@@ -31,6 +31,7 @@ The parent imports `alpha`, `approach`, `execution`, `parameters` and `piecewise
 ## Side Effects
 - Creates a local (non-remote) GEKKO model and configures its solver. [execution.py:setup_model]
 - `optimise` always removes the GEKKO run directory afterwards; `cleanup_model` is safe to repeat. [execution.py:optimise] [execution.py:cleanup_model]
+- A solve that stopped before converging (`solver_run.converged` false) keeps `mSuccess` and its values, but is logged as a warning (`[Unconverged]`) rather than `[Success]`. [execution.py:_solve_and_post_process]
 - `get_alpha_values` builds and solves a second GEKKO model and cleans it up. [alpha.py:get_alpha_values]
 - Writes solver results, logs and many attributes onto the model passed in (`mSuccess`, `solver_run`, `area_*`, `LMTD_*`, `z_allowed`). [execution.py:_solve_and_post_process] [area.py:set_utility_lmtd_and_areas]
 - Lazy imports of `OpenPinch.analysis.heat_exchanger_networks.solver.piecewise` inside segmented-stream branches. [area.py:_apply_segment_recovery_areas] [piecewise.py:_utility_cost_expression]

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/models/_base/execution.py

@@ -96,6 +96,16 @@ def _solve_and_post_process(model, print_output: bool) -> None:
                 model.name,
                 model.m._path,
             )
+        elif not model.solver_run.converged:
+            # The values are kept (evolution can start from them), but the
+            # objective is not a converged optimum to compare against.
+            model.mSuccess = model.m.options.SOLVESTATUS
+            logger.warning(
+                "[Unconverged] [model: %s] [path: %s] [termination: %s]",
+                model.name,
+                model.m._path,
+                model.solver_run.termination_condition,
+            )
         else:
             model.mSuccess = model.m.options.SOLVESTATUS
             logger.info(

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/models/_stagewise/README.md

@@ -19,7 +19,7 @@ Private helper modules for `StageWiseModel` (`../stagewise.py`), which delegates
 - Supported goals: "hot utility", "cold utility", "total utility", "utility costs", "heat recovery", "dQ/dA obj", "total cost", "variable total cost"; others raise `ValueError`. [objectives.py:set_obj]
 - Solver area terms use Chen's LMTD approximation; multiperiod total cost uses one shared area per unit bounded below by each period's requirement. [objectives.py:_chen_mean] [objectives.py:_set_multiperiod_total_cost_objective]
 - `verify` checks cost and area consistency only for the two total-cost goals; once those pass it also runs the reporting-layer network feasibility check. [verification.py:verify]
-- Evolution candidates are usable only if solved and `verify()` passes; the best is adopted only if its TAC is below the original and it verifies. [evolution.py:_is_usable_evolution_candidate] [evolution.py:_update_with_best_model]
+- Evolution candidates are usable only if solved, converged (`solver_run.converged`) and `verify()` passes; the best is adopted only if it verifies and, when the starting solve converged, its TAC is below the original. When the starting solve did not converge its TAC is not a benchmark: the best usable candidate is adopted, and the workflow's final ranking compares it with the seed network on verified costs. [evolution.py:_is_usable_evolution_candidate] [evolution.py:_benchmark_model] [evolution.py:_update_with_best_model]
 - With more than one add or remove branch, or a patience limit, evolution keeps at most `beam_width` branches ranked by TAC then topology signature, solves each topology once, and orders parallel results by (branch, kind, rank) so serial and parallel runs agree. [evolution.py:get_net_benefit_evolution] [evolution.py:_solve_evolution_candidates]
 - With one add branch, one remove branch and no patience, the original single-path search runs. [evolution.py:get_net_benefit_evolution]
 - Evolution children are relaxed (`integers=False`, `tol=1e-3`) and use the root model's solver. [evolution.py:_build_and_solve_evolution]
@@ -28,7 +28,7 @@ Private helper modules for `StageWiseModel` (`../stagewise.py`), which delegates
 
 ## Side Effects
 - Evolution builds and solves child `StageWiseModel` instances (GEKKO models), in a `ThreadPoolExecutor` when `max_parallel` exceeds one and `supported_workers` allows it. [evolution.py:_solve_evolution_candidates]
-- `get_net_benefit_evolution` ends by calling `owner.cleanup()` on both search paths (only the early return when `owner.mSuccess != 1` skips it), and `_update_with_best_model` overwrites the owner's variables, `z_allowed`, alpha and cost attributes, then re-runs post-processing. [evolution.py:get_net_benefit_evolution] [evolution.py:_update_with_best_model]
+- `get_net_benefit_evolution` ends by calling `owner.cleanup()` on both search paths (only the early return when `owner.mSuccess != 1` skips it), and `_update_with_best_model` overwrites the owner's variables, `z_allowed`, alpha, cost attributes and `solver_run`, then re-runs post-processing. [evolution.py:get_net_benefit_evolution] [evolution.py:_update_with_best_model]
 - `verify` lazily imports and runs `extract_heat_exchanger_network` and `verify_network_feasibility`. [verification.py:_check_network_feasibility]
 - Post-processing runs the post-optimisation alpha solve via `get_alpha_values`. [postprocess.py:_get_multiperiod_post_process]
 - Evolution and verification log mostly at debug level; exceptions in a candidate solve are caught and logged. [evolution.py:_solve_evolution_candidate]

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/models/_stagewise/evolution.py

@@ -82,8 +82,13 @@ def get_net_benefit_evolution(
     initial_z = getattr(owner, "z_allowed", None)
     if initial_z is not None:
         seen_signatures.add(_topology_signature_from_z(owner, initial_z))
-    frontier = [_EvolutionBranchState(model=owner, best_tac=float(owner.TAC))]
-    best_model = owner
+    best_model = _benchmark_model(owner)
+    frontier = [
+        _EvolutionBranchState(
+            model=owner,
+            best_tac=float(owner.TAC) if best_model is owner else float("inf"),
+        )
+    ]
 
     for unit in range(max_depth):
         logger.debug(
@@ -142,7 +147,7 @@ def get_net_benefit_evolution(
                 )
                 continue
             next_frontier.append(branch_period)
-            if candidate.TAC < best_model.TAC:
+            if best_model is None or candidate.TAC < best_model.TAC:
                 best_model = candidate
         # Keep the best branches by TAC, ties broken on topology signature, so
         # the frontier never grows past the beam width.
@@ -154,14 +159,14 @@ def get_net_benefit_evolution(
             logger.debug("No viable evolution model found.")
             break
 
-        if best_model is not owner:
+        if best_model is not None and best_model is not owner:
             logger.debug(
                 "New best evolution model %s with TAC %.6f",
                 best_model.name,
                 best_model.TAC,
             )
 
-    if best_model.mSuccess and best_model.TAC < owner.TAC:
+    if best_model is not None and best_model is not owner:
         _update_with_best_model(owner, best_model)
     else:
         logger.debug("No evolution improvement found over original model.")
@@ -178,7 +183,7 @@ def _get_source_net_benefit_evolution(
     """Run the original OpenHENS single-path add/remove evolution search."""
 
     model = owner
-    best_model = owner
+    best_model = _benchmark_model(owner)
     for unit in range(max_depth):
         logger.debug(
             "Evolution step %s/%s - Current TAC: %s",
@@ -205,7 +210,7 @@ def _get_source_net_benefit_evolution(
         if model is None:
             logger.debug("No viable model found; ending evolution.")
             break
-        if model.TAC < best_model.TAC:
+        if best_model is None or model.TAC < best_model.TAC:
             best_model = model
             logger.debug(
                 "New best model: %s found with TAC: %.6f",
@@ -213,7 +218,7 @@ def _get_source_net_benefit_evolution(
                 best_model.TAC,
             )
 
-    if best_model.mSuccess and best_model.TAC < owner.TAC:
+    if best_model is not None and best_model is not owner:
         _update_with_best_model(owner, best_model)
     else:
         logger.debug("No improvement found over original model.")
@@ -221,6 +226,27 @@ def _get_source_net_benefit_evolution(
     return owner
 
 
+def _benchmark_model(owner):
+    """Return the starting model when its TAC is a fair benchmark, else None.
+
+    A solve that stopped before converging (for example at IPOPT's iteration
+    limit) is still reported as successful, but its objective can be far below
+    the cost of any real network. Evolution then keeps its best verified
+    candidate, and the workflow's final ranking compares it with the seed
+    network on verified costs.
+    """
+
+    solver_run = getattr(owner, "solver_run", None)
+    if getattr(solver_run, "converged", True):
+        return owner
+    logger.warning(
+        "Starting model %s did not converge; evolution candidates are not "
+        "compared with its TAC.",
+        getattr(owner, "name", None),
+    )
+    return None
+
+
 def _select_source_best_candidate(
     owner,
     current_model,
@@ -507,6 +533,8 @@ def _update_with_best_model(owner, best_model) -> None:
         owner.area_cu_shared = copy.deepcopy(best_model.area_cu_shared)
     owner.hu_area_cost_total = copy.deepcopy(best_model.hu_area_cost_total)
     owner.cu_area_cost_total = copy.deepcopy(best_model.cu_area_cost_total)
+    if hasattr(best_model, "solver_run"):
+        owner.solver_run = best_model.solver_run
     owner.get_post_process()
 
 
@@ -688,6 +716,9 @@ def _is_usable_evolution_candidate(candidate) -> bool:
         return False
     if not candidate.mSuccess:
         return False
+    # A solve stopped at a limit keeps mSuccess, but its TAC is not reliable.
+    if not getattr(getattr(candidate, "solver_run", None), "converged", True):
+        return False
     verify = getattr(candidate, "verify", None)
     if not callable(verify):
         return True

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/models/problem.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import Any, Literal, Mapping, Sequence
 
 from ....contracts.synthesis.result import HeatExchangerNetworkSynthesisResult
@@ -248,6 +248,7 @@ class InternalHeatExchangerNetworkProblem:
             below_case=self.below,
             above_case=self.above,
         )
+        self._carry_unconverged_side_solve()
         self.case.get_post_process()
         if print_output:
             self.case.output_to_cmd_line()
@@ -259,6 +260,23 @@ class InternalHeatExchangerNetworkProblem:
             }
         )
 
+    def _carry_unconverged_side_solve(self) -> None:
+        # The amalgamated model is built, not solved, so its own solver run
+        # says nothing about the sides' convergence.
+        for side in (self.above, self.below):
+            side_run = getattr(side, "solver_run", None)
+            if side.side_required and not getattr(side_run, "converged", True):
+                case_run = getattr(self.case, "solver_run", None)
+                self.case.solver_run = (
+                    side_run
+                    if case_run is None
+                    else replace(
+                        case_run,
+                        termination_condition=side_run.termination_condition,
+                    )
+                )
+                return
+
     def remove_unused_stages(self, case) -> StageWiseModel:
         """Apply the source stage-utilisation reduction after PDM/TDM solves."""
 

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/results/README.md

@@ -6,7 +6,7 @@ Turns executed task outcomes into the canonical synthesis result, resolves seed
 ## Interface
 - `SynthesisWorkflowResult` (`assembly.py`): frozen dataclass of tasks, outcomes, accepted result and run time.
 - `build_synthesis_result` (`assembly.py`): demotes infeasible outcomes, accepts the best one and builds the result with its manifest.
-- `demote_infeasible_outcomes` (`assembly.py`): marks solver successes that fail `verify_network_feasibility` as failed.
+- `demote_infeasible_outcomes` (`assembly.py`): marks solver successes that fail `verify_network_feasibility`, or that carry `diagnostics["unconverged_termination"]`, as failed.
 - `resolve_seed_networks` (`seeds.py`): returns explicit seed networks or the cached upstream design network.
 - `ranked_networks` (`selection.py`): unique ranked outcomes of a result.
 - `network_for_rank` (`selection.py`): network at a one-based rank, without mutation.
@@ -14,7 +14,7 @@ Turns executed task outcomes into the canonical synthesis result, resolves seed
 
 ## Invariants
 - The accepted outcome is the successful outcome with the lowest `outcome_ranking_key`, whichever method produced it; ties are broken by task id [assembly.py:_accepted_outcome].
-- Infeasible outcomes are demoted before acceptance, keeping their network and a reason; `WorkflowContractError` is raised only when no success remains [assembly.py:demote_infeasible_outcomes, _accepted_outcome].
+- Infeasible and unconverged outcomes are demoted before acceptance, keeping their network and a reason; `WorkflowContractError` is raised only when no success remains [assembly.py:demote_infeasible_outcomes, _accepted_outcome].
 - The accepted network must be present, and its run id, task id, period id, method are overwritten from settings and task, and the stage count is kept from the network when it has one [assembly.py:build_synthesis_result].
 - Manifest approach temperatures are those the tasks actually ran, falling back to the settings values [assembly.py:build_synthesis_result].
 - Manifest `method_sequence` lists each method once, in outcome order (PDM, TDM, EVM, though tiers above 1 also run some EVM tasks before TDM), without outcomes that failed because Couenne is missing; `settings.method_sequence` does not affect it [assembly.py:_executed_method_sequence].

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/results/assembly.py

@@ -179,10 +179,23 @@ def demote_infeasible_outcomes(
 
     One infeasible outcome no longer aborts the synthesis: it keeps its network
     and reasons for diagnostics, and the result is selected from the feasible
-    outcomes. Selection raises only when none is left.
+    outcomes. Selection raises only when none is left. A solve that stopped
+    before converging is demoted too: it stayed a success only so downstream
+    tasks could start from it, and its objective is not a converged optimum.
     """
     demoted = []
     for outcome in outcomes:
+        termination = outcome.diagnostics.get("unconverged_termination")
+        if outcome.status == "success" and termination is not None:
+            demoted.append(
+                outcome.model_copy(
+                    update={
+                        "status": "failed",
+                        "error": f"solver stopped before converging ({termination})",
+                    }
+                )
+            )
+            continue
         failures = (
             verify_network_feasibility(outcome.network)
             if outcome.status == "success"

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/solver/README.md

@@ -7,7 +7,7 @@ Everything between a prepared problem and the equation models: solver arrays bui
 - `problem_to_solver_arrays`, `PreparedSolverArrays`, `SEGMENT_PROFILE_VERSION`, `annual_cost_scales` (`arrays.py`): prepared-problem to padded, period-indexed arrays, axis maps, identities and unit conventions.
 - `PiecewiseThermalProfile`, `profile_from_solver_arrays`, `utility_thermal_profile`, `duty_aligned_area_contributions`, `add_piecewise_temperature_mapping`, `add_piecewise_cost_mapping`, `add_piecewise_temperature_contribution_mapping` (`piecewise.py`): segment profiles, duty-aligned area slices, and model constraints mapping duty to temperature, cost or contribution.
 - `build_pinch_design_decomposition`, `PinchDesignDecomposition`, `PinchDesignTarget`, `PinchLocation`, `StageSelection` (`pinch_design_decomposition.py`): per-period pinch targets and clipped active-stream fields for the PDM.
-- `SolverRun`, `create_gekko_model`, `cleanup_gekko_model`, `require_solver_backend`, `configure_gekko_solver`, `solve_gekko_model`, `suppress_gekko_numpy_array_copy_deprecation`, `PYOMO_SOLVERS`, `GEKKO_SOLVERS`, `DEFAULT_IPOPT_GEKKO_OPTIONS` (`backend.py`): solver selection, option files and normalised solves.
+- `SolverRun`, `create_gekko_model`, `cleanup_gekko_model`, `require_solver_backend`, `configure_gekko_solver`, `solve_gekko_model`, `suppress_gekko_numpy_array_copy_deprecation`, `PYOMO_SOLVERS`, `GEKKO_SOLVERS`, `CONVERGED_TERMINATION_CONDITIONS`, `DEFAULT_IPOPT_GEKKO_OPTIONS` (`backend.py`): solver selection, option files and normalised solves.
 - `require_synthesis_dependency`, `require_declared_synthesis_dependencies`, `require_solver_binary`, `SYNTHESIS_DEPENDENCIES`, `SynthesisDependency`, `SYNTHESIS_EXTRA`, `MissingSynthesisDependencyError`, `MissingSynthesisSolverError` (`dependencies.py`): optional package and executable guards.
 
 ## Invariants
@@ -20,8 +20,11 @@ Everything between a prepared problem and the equation models: solver arrays bui
 - Exchanger duty beyond a profile raises, except for solver noise within a relative allowance that is dropped [piecewise.py:duty_aligned_area_contributions].
 - The PDM decomposition works on a deep copy of the master zone, and its stage boundary count satisfies `K = S + 1` [pinch_design_decomposition.py:_zone_with_hen_dt_contribution, PinchDesignDecomposition].
 - Shifted pinch temperature is the selected pinch (cold pinch when the hot utility target is zero, otherwise hot pinch) in K [pinch_design_decomposition.py:_shifted_pinch_temperature].
+- A stream is active on a side of the pinch only if it reaches more than `tol` past its pinch temperature, so a stream that starts or ends at the pinch is not kept on the far side as a sliver [pinch_design_decomposition.py:_clip_stream_temperatures].
 - Solver names must be in `PYOMO_SOLVERS | GEKKO_SOLVERS`; solver options are validated [backend.py:require_solver_backend, _normalise_solver_options].
 - Pyomo solves that need an option file are serialised by a process-wide lock [backend.py:_solver_working_directory].
+- `create_gekko_model` returns a GEKKO subclass that records each Pyomo solve's termination condition on `SolverRun.termination_condition`. GEKKO reports a solve that stopped at an iteration or time limit as successful; `SolverRun.converged` is false for any condition outside `CONVERGED_TERMINATION_CONDITIONS`, and true when none was recorded (GEKKO-native solvers) [backend.py:create_gekko_model, SolverRun.converged].
+- That subclass and its Pyomo converter are built on first use (importing `backend` does not import gekko) and published once as module attributes of `backend`, so models from `create_gekko_model` pickle for process pool workers [backend.py:_termination_recording_class, __getattr__].
 
 ## Side Effects
 - Pyomo solves with an option file (solver options supplied) change the process working directory under a per-process thread lock, restoring it afterwards [backend.py:_solver_working_directory].

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/solver/arrays.py

@@ -178,6 +178,7 @@ def problem_to_solver_arrays(
                 "dt_cont_multipliers",
                 None,
             ),
+            "HENS_MIN_EXCHANGER_APPROACH_SHARE": hens.min_exchanger_approach_share,
             "HENS_SYNTHESIS_QUALITY_TIER": hens.synthesis_quality_tier,
             "HENS_PDM_STAGE_PAIR_LIMIT": hens.pdm_stage_pair_limit,
             "HENS_TDM_PARENT_LIMIT": hens.tdm_parent_limit,

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/solver/backend.py

@@ -38,6 +38,12 @@ DEFAULT_IPOPT_GEKKO_OPTIONS: dict[str, Any] = {
     "max_iter": 1000,
     "print_level": 5,
 }
+# Pyomo termination conditions of a converged solve. GEKKO's Pyomo extension
+# only warns on the others (an iteration or time limit, for example) and still
+# reports the solve as successful.
+CONVERGED_TERMINATION_CONDITIONS = frozenset(
+    {"optimal", "locallyOptimal", "globallyOptimal", "feasible"}
+)
 GEKKO_NUMPY_ARRAY_COPY_DEPRECATION = (
     r"__array__ implementation doesn't accept a copy keyword.*"
 )
@@ -55,17 +61,78 @@ class SolverRun:
     failure_reason: str | None = None
     solver_options: dict[str, Any] | None = None
     option_file: str | None = None
+    termination_condition: str | None = None
+
+    @property
+    def converged(self) -> bool:
+        """False when the solver stopped before converging, for example at its
+        iteration limit. Solves without a recorded condition count as converged."""
+
+        return (
+            self.termination_condition is None
+            or self.termination_condition in CONVERGED_TERMINATION_CONDITIONS
+        )
 
 
 def create_gekko_model(*, remote: bool = False) -> Any:
-    """Create a GEKKO model after the optional dependency has been requested."""
+    """Create a GEKKO model after the optional dependency has been requested.
+
+    The model records the Pyomo termination condition of each solve, which
+    GEKKO itself only prints.
+    """
 
-    gekko = require_synthesis_dependency(
+    require_synthesis_dependency(
         "gekko",
         package="gekko",
         purpose="GEKKO heat exchanger network equation model construction",
     )
-    return gekko.GEKKO(remote=remote)
+    return _termination_recording_class("_TerminationRecordingGEKKO")(remote=remote)
+
+
+def __getattr__(name: str) -> type:
+    # Pickle looks classes up by module and name, so unpickling a model in a
+    # process pool worker resolves the lazily built classes here.
+    if name in _TERMINATION_RECORDING_CLASS_NAMES:
+        return _termination_recording_class(name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+_TERMINATION_RECORDING_CLASS_NAMES = frozenset(
+    {"_TerminationRecordingGEKKO", "_TerminationRecordingPyomoConverter"}
+)
+_TERMINATION_RECORDING_CLASS_LOCK = threading.Lock()
+
+
+def _termination_recording_class(name: str) -> type:
+    """Return a GEKKO subclass published as a module attribute of this module.
+
+    The classes are built on first use, so importing this module does not
+    import gekko, and published once, so models pickle by reference to them.
+    """
+
+    with _TERMINATION_RECORDING_CLASS_LOCK:
+        if name not in globals():
+            _define_termination_recording_classes()
+    return globals()[name]
+
+
+def _define_termination_recording_classes() -> None:
+    from gekko import GEKKO
+    from gekko.gk_solver_extension_pyomo import PyomoConverter
+
+    class _TerminationRecordingPyomoConverter(PyomoConverter):
+        def handle_status(self, status_dict, status, status_string) -> None:
+            if isinstance(status, self.TerminationCondition):
+                self._gekko_model._openpinch_termination_condition = str(status)
+            super().handle_status(status_dict, status, status_string)
+
+    class _TerminationRecordingGEKKO(GEKKO):
+        def solver_extension_pyomo(self, disp=True):
+            self.solve_with_converter(_TerminationRecordingPyomoConverter, disp)
+
+    for cls in (_TerminationRecordingPyomoConverter, _TerminationRecordingGEKKO):
+        cls.__qualname__ = cls.__name__
+        globals()[cls.__name__] = cls
 
 
 def cleanup_gekko_model(model: Any) -> None:
@@ -208,6 +275,7 @@ def solve_gekko_model(
 
     extension = getattr(model.options, "SOLVER_EXTENSION", None)
     _restore_run_directory(model)
+    model._openpinch_termination_condition = None
     start = time.time()
     failure_reason = None
     try:
@@ -232,6 +300,7 @@ def solve_gekko_model(
         failure_reason=failure_reason,
         solver_options=getattr(model, "_openpinch_solver_options", None),
         option_file=getattr(model, "_openpinch_solver_option_file", None),
+        termination_condition=model._openpinch_termination_condition,
     )
 
 

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_exchanger_networks/solver/pinch_design_decomposition.py

@@ -474,13 +474,15 @@ def _clip_stream_temperatures(
 ) -> tuple[tuple[int, ...], tuple[int, ...]]:
     hot_thresholds = shifted_pinch_temperature + np.asarray(hot_contributions)
     cold_thresholds = shifted_pinch_temperature - np.asarray(cold_contributions)
+    # The problem table rounds the pinch to tol, so a stream that starts or ends
+    # at the pinch can look a sliver past it. It is not active on that side.
     if pinch_location == "above":
         z_i_active = tuple(
-            1 if value > threshold else 0
+            1 if value > threshold + tol else 0
             for value, threshold in zip(T_h_in, hot_thresholds)
         )
         z_j_active = tuple(
-            1 if value > threshold else 0
+            1 if value > threshold + tol else 0
             for value, threshold in zip(T_c_out, cold_thresholds)
         )
         for index, is_active in enumerate(z_i_active):
@@ -497,11 +499,11 @@ def _clip_stream_temperatures(
                 T_c_out[index] = 0.0
     else:
         z_i_active = tuple(
-            1 if value < threshold else 0
+            1 if value < threshold - tol else 0
             for value, threshold in zip(T_h_out, hot_thresholds)
         )
         z_j_active = tuple(
-            1 if value < threshold else 0
+            1 if value < threshold - tol else 0
             for value, threshold in zip(T_c_in, cold_thresholds)
         )
         for index, is_active in enumerate(z_i_active):

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_pumps/common/README.md

@@ -33,7 +33,7 @@ multi-stage vapour-compression objective, and residual utility accounting.
 - A cascade stage whose work is at most `NEGLIGIBLE_STAGE_WORK_FRACTION` of the machine's work is not charged stage capital. [shared.py:_single_cost_unit]
 - The feasibility penalty is `rho * sum(r + r^2)` with violations relative to `Q_hpr_target`. Vapour results price it at the no-heat-pump annual cost, at least 1 $/y; Carnot results scale it by `max(Q_hpr_target, 1) * max(price ratio, 1)` in power-equivalent units, with violations measured against `max(Q_hpr_target, 1)`, with no annual-cost scale or floor. [shared.py:_cycle_penalty] [shared.py:hpr_penalty_cost_scale] [optimisation_adapter.py:build_hpr_accounting]
 - Errors raised after a cycle has solved are re-raised, not ranked as infeasible candidates. [multi_vc_objective.py:_evaluate_multi_vc_objective] [shared.py:post_solve_error]
-- Ambient air and cooling water are applied through `cascade_with_air` on the condenser and evaporator cascades; cooling water applies on the evaporator side only. [shared.py:evaluate_vapour_hpr_result]
+- Ambient air and cooling water are applied through `cascade_with_air` on the condenser and evaporator cascades; cooling water applies on the evaporator side only. Air is left out when `args.ambient_air_enabled` is false (`HPR_AMBIENT_AIR_ENABLED`). [shared.py:_cascade_air_duties]
 - `calc_carnot_heat_pump_cop` and `calc_carnot_heat_engine_eta` take absolute temperatures (K); `satisfies_second_law` takes degC and adds 273.15 internally, and `compute_entropic_mean_temperature` takes degC by default and returns K. [shared.py:calc_carnot_heat_pump_cop] [shared.py:satisfies_second_law]
 - Residual loads below `max(tol, 1e-7 * largest)` are treated as rounding noise and set to zero; duplicate residual temperatures with conflicting values raise `ValueError`. [postprocessing.py:_residual_noise_floor] [postprocessing.py:_deduplicate_residual_profile_rows]
 - `common` imports the parent's `optimisation_adapter` and `performance_maps.targeting` for accounting and backend names. [shared.py] [preprocessing.py]

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_pumps/common/_shared/README.md

@@ -21,7 +21,7 @@ What the parent and siblings import from this package:
 ## Invariants
 - Air and cooling water never create a utility demand: the duties they take or give are limited by the smallest cascade flow on the affected side, and cannot be negative. [air.py:cascade_with_air]
 - The cascade is supplied with `T` descending and `H_net` clipped to non-negative before use. [air.py:cascade_with_air]
-- Air supplies heat before it takes heat, and cooling water acts only on what air leaves. [air.py:cascade_with_air]
+- Air supplies heat before it takes heat, and cooling water acts only on what air leaves. With `air=False` no air is placed and cooling water acts on the whole cascade. [air.py:cascade_with_air]
 - A sink at or above the top of the cascade takes no heat. [air.py:_sink_duty]
 - Ambient and cooling-water levels are shifted by `dt_env_cont`, `dt_cooling_water` and `dtcont_hp`, with `dtcont_hp` applied in the opposite sense on the source and sink sides. [air.py:ambient_source_temperature]
 - Carnot condenser and evaporator levels closer than `dt_phase_change` are merged and their duties summed before streams are built. [streams.py:_get_carnot_hpr_cycle_cascade_profile]

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_pumps/common/_shared/air.py

@@ -99,6 +99,7 @@ def cascade_with_air(
     T_air_sink: float,
     T_cooling_water: float | None = None,
     utility_bands: Sequence[tuple[float, float]] = (),
+    air: bool = True,
 ) -> CascadeWithAir:
     """Place free ambient air in a feasible cascade and return external duties.
 
@@ -113,7 +114,8 @@ def cascade_with_air(
     saves the dearer hot utility, then takes heat from what flows on.
     Cooling water at ``T_cooling_water`` then takes heat the same way from
     what is left. A level inside one of ``utility_bands``, each ``(upper, lower)``,
-    moves to the end of that band, so the band counts as at the level.
+    moves to the end of that band, so the band counts as at the level. With
+    ``air`` false no air is placed and only cooling water acts.
     """
     T = np.asarray(T, dtype=float)
     H_net = np.maximum(np.asarray(H_net, dtype=float), 0.0)
@@ -132,7 +134,7 @@ def cascade_with_air(
     # Air heat enters at the source level and can only meet deficits below it;
     # it also lowers every flow above that level, which must stay non-negative.
     Q_air_source = 0.0
-    if T_air_source > T_grid[-1]:
+    if air and T_air_source > T_grid[-1]:
         above = T_grid >= T_air_source
         at = float(np.interp(T_air_source, T_grid[::-1], H_grid[::-1]))
         absorbed_below = at - float(H_grid[T_grid <= T_air_source].min())
@@ -140,7 +142,7 @@ def cascade_with_air(
         Q_air_source = max(min(flow_limit, absorbed_below), 0.0)
 
     remaining = H_grid - np.where(_at_or_above(T_grid, T_air_source), Q_air_source, 0.0)
-    Q_air_sink = _sink_duty(T_grid, remaining, T_air_sink)
+    Q_air_sink = _sink_duty(T_grid, remaining, T_air_sink) if air else 0.0
     remaining = remaining - np.where(_at_or_below(T_grid, T_air_sink), Q_air_sink, 0.0)
     Q_cooling_water = (
         0.0

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_pumps/common/preprocessing.py

@@ -118,6 +118,7 @@ def construct_HPRTargetInputs(
         max_pressure_ratio=hpr.max_pressure_ratio,
         T_env=environment.temperature,
         dt_env_cont=hpr.dt_env_cont,
+        ambient_air_enabled=hpr.ambient_air_enabled,
         dt_phase_change=thermal.dt_phase_change,
         eta_penalty=hpr.eta_penalty,
         rho_penalty=hpr.rho_penalty,

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_pumps/common/shared.py

@@ -428,6 +428,7 @@ def _cascade_air_duties(
             and getattr(args, "background_is_utility", False)
             else ()
         ),
+        air=getattr(args, "ambient_air_enabled", True),
     )
 
 

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_pumps/targeting/README.md

@@ -18,7 +18,7 @@ One module per heat pump and refrigeration (HPR) cycle topology. Each defines ho
 - Carnot objective vectors hold condenser fractions, evaporator fractions and heat-split fractions, all bounded to [0, 1]; the initial point starts every heat split at 1 [_carnot_common.py:carnot_opt_setup].
 - Parallel Carnot and parallel vapour compression equalise `n_cond` and `n_evap` to the larger value on `args`, and callers rely on that after the solve [_carnot_common.py:normalise_carnot_stage_counts, parallel_vapour_compression.py:optimise_parallel_heat_pump_placement].
 - Condenser temperatures are capped and evaporator temperatures floored through `common.shared` helpers before use [cascade_vapour_compression.py:_parse_cascade_hp_state_variables, parallel_vapour_compression.py:_parse_parallel_hp_state_temperatures].
-- Air is a partner for refrigeration heat sink and heat pump heat source only [_carnot_common.py:parse_carnot_state_variables].
+- Air is a partner for refrigeration heat sink and heat pump heat source only, and adds no availability when `ambient_air_enabled` is false [_carnot_common.py:parse_carnot_state_variables].
 - The Carnot warm start is clipped into the refrigerant's subcritical condensing range and seed duties are encoded against availability at the seed temperatures [cascade_vapour_compression.py:_get_cascade_hp_opt_setup, parallel_vapour_compression.py:_get_parallel_hp_opt_setup, vapour_compression_mvr.py:_get_vc_mvr_opt_setup].
 - Cascade process-control counts depend on mode: a heat pump has `n_cond` heat controls and `n_evap - 1` cool controls, a refrigerator the reverse, with its heat controls on `T_cond[1:]` because the top stage takes the remaining heat [cascade_vapour_compression.py:_cascade_process_control_counts].
 - VC+MVR state arrays are ordered [MVR stages, VC stages]; the MVR lift is at most `MAX_MVR_STAGE_LIFT` (20 K) [vapour_compression_mvr.py:_unpack_vc_mvr_state, vapour_compression_mvr.py:_parse_vc_mvr_state_variables].

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/analysis/heat_pumps/targeting/_carnot_common.py

@@ -101,7 +101,11 @@ def parse_carnot_state_variables(
     # Air can be a refrigerator's heat sink and a heat pump's heat source, but
     # never a heat pump's load or a refrigerator's duty. Where it is a partner
     # it adds generous availability; the cascade decides how much air is used.
-    air_allowance = float(args.Q_heat_max + args.Q_cool_max)
+    air_allowance = (
+        float(args.Q_heat_max + args.Q_cool_max)
+        if getattr(args, "ambient_air_enabled", True)
+        else 0.0
+    )
     heat_air = 0.0 if args.is_heat_pumping else air_allowance
     cool_air = air_allowance if args.is_heat_pumping else 0.0
     H_cold_available = args.H_cold + args.z_amb_cold * heat_air

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/application/_problem/accessors/design.py

@@ -340,6 +340,12 @@ class _DesignAccessor:
         """Run the default HEN synthesis workflow.
 
         It runs quality tier 0 unless ``HENS_SYNTHESIS_QUALITY_TIER`` is set.
+
+        ``approach_temperatures`` sets the pinch design step's approach. The
+        later thermal derivative and evolution steps choose each exchanger's
+        approach by total annual cost, down to 0.1 K, or down to
+        ``HENS_MIN_EXCHANGER_APPROACH_SHARE`` (in ``options``) times the
+        requested approach if that is larger.
         """
         from ....analysis.heat_exchanger_networks.service import (
             _heat_exchanger_network_enhanced_synthesis_method_service,

{openpinch-0.8.0 → openpinch-0.8.2}/OpenPinch/contracts/hpr.py

@@ -293,6 +293,7 @@ class HeatPumpTargetInputs(BaseModel):
     max_multi_start: int
     T_env: float
     dt_env_cont: float
+    ambient_air_enabled: bool = True
     eta_ii_hpr_carnot: float
     eta_ii_he_carnot: float
     refrigerant_ls: List[str]