[AI-Assisted] fix(compressor): report consistent speed-solve results and convergence

.github/skills/neqsim-compressor-antisurge-recycle/SKILL.md

@@ -21,6 +21,24 @@ This skill provides patterns for anti-surge protection, minimum-speed recycle co
 
 Standards: **API 617 / API 619**, **IEC 60534 / ISA-75**, **ISO 50001 / ISO 14064** (energy & carbon emissions).
 
+## Compressor pressure-target solves
+
+For `Compressor.setSolveSpeed(true)`, check `isSpeedSolveConverged()` after `run()`
+before accepting an optimization point. Read actual pressure from the outlet
+stream and the signed pressure error in bar from `getSpeedSolvePressureResidual()`.
+`getOutletPressure()` retains the requested setpoint, including after failure.
+The returned state uses the fixed-speed forward calculation, including anti-surge
+flow changes; these can leave the requested pressure unmet. `setLimitSpeed(false)`
+allows extrapolation, so pressure convergence does not establish mechanical
+feasibility. Check speed and operating-envelope constraints separately.
+`ProductionOptimizer` treats `Compressor.SpeedSolveException` as an infeasible
+trial and continues searching without evaluating stale outputs; unrelated
+exceptions propagate. Its hard `compressorSpeedSolve` constraint also rejects
+returned unconverged results even with capacity analysis enabled. Keep this gate
+when integrating chart-based compressor models into optimizers.
+See [compressor curves](../../../docs/process/equipment/compressor_curves.md#speed-calculation-from-operating-point)
+and `CompressorSpeedSolveConsistencyTest` for the tested contract.
+
 ## Key Java Class: `MinimumSpeedRecycleControllerStructure`
 
 `neqsim.process.controllerdevice.structure.MinimumSpeedRecycleControllerStructure` coordinates pressure control between compressor speed and recycle-valve opening when the compressor reaches its minimum speed.

docs/development/TASK_LOG.md

@@ -48,6 +48,12 @@ requirement`, or `confidential compressor route`.
 **Solution:** `LoopedPipeNetwork.calculateHeadLossCompressor`, `MappedCompressorAcceptanceTest`, and the SURF integration guide.
 **Notes:** A bounded chart speed search requested 100 bara and returned an internally consistent 11.647013866 bara forward state with `solved() == false`, while the network labelled it a valid chart result and retained 53.131953657 kW. Require the existing equipment convergence contract, an enabled chart, finite non-negative power, and positive finite outlet pressure/temperature before accepting mapped evidence. Reuse the existing infeasible-edge path to invalidate power and clear previous thermal state. Four regressions first establish a valid state, then exercise an unsolved result, chart disablement, non-finite power, and non-finite temperature. Keep the common network boundary in PR #4328 and the compressor's speed-search implementation in PR #4326; no system-specific solver or new constraint framework is introduced.
 
+### 2026-10-14 — Preserve compressor convergence requirements during optimization
+**Type:** E (Feature)
+**Keywords:** compressor, speed solve, invalid chart, optimizer, infeasible trials, lift curves, CI, 4326
+**Solution:** `Compressor.SpeedSolveException`, `ProductionOptimizer` candidate rejection and hard convergence gate, and conditional chart-setup process runs in `FlowRateOptimizer`.
+**Notes:** Reproduced all three failing optimizer cases on PR #4326 before repair. A no-valid-map trial is rejected without reading stale objectives or downstream constraints; unrelated exceptions still propagate. Capacity analysis and optional output validation cannot bypass the pressure-target convergence requirement. Repeated table setup reuses existing charts without rerunning an invalid preceding probe. Updated compressor/optimization guides, the compressor skill and the generated coverage inventory; regression tests cover stale outputs, hard convergence, recovery and chart reuse.
+
 ### 2026-10-14 — Repair shared CI failures and preserve workflow diagnostics
 **Type:** G (Workflow)
 **Keywords:** PR 4315, hermetic tests, evidence-source-cues, slow shards, required checks, Surefire, CI

docs/process/equipment/compressor_curves.md

@@ -1099,7 +1099,41 @@ accepted speed is retained once the pressure residual is within 0.001 bar.
 The reported speed, chart head, efficiency and power therefore describe the same
 iterate. Re-running an unchanged inlet and target does not take an additional
 Newton step after convergence, which could otherwise move a capacity-limited
-operating point across its limit. Configured speed limits still apply.
+operating point across its limit.
+
+The outlet stream is always calculated from the returned speed using the same
+chart-forward calculation as fixed-speed operation, including guide-vane and
+anti-surge effects. An unreachable pressure target must not be interpreted as a
+successful operating point just because `run()` returns:
+
+- `isSpeedSolveConverged()` reports whether the final outlet pressure is within
+  0.001 bar of the requested target.
+- `getSpeedSolvePressureResidual()` returns achieved minus requested pressure in
+  bar, or `NaN` when no speed-solve result is available for the latest run.
+- `solved()` and `isSimulationValid()` are false when an enabled chart speed solve
+  misses its target; `getSimulationValidationErrors()` explains the failure.
+- Read achieved pressure from `getOutletStream().getPressure("bara")`.
+  `getOutletPressure()` retains the requested setpoint in its configured unit,
+  so repeated runs continue to solve the same target, including after failure.
+
+With `setLimitSpeed(true)`, the search is limited to the configured minimum and
+maximum speeds. A result at a speed limit is still marked non-converged if it
+does not deliver the target. With `setLimitSpeed(false)` (the default), speed
+extrapolation remains allowed for compatibility. Pressure convergence alone
+does not establish that speed, surge, stonewall or power constraints are met;
+check those constraints separately before accepting an operating point.
+
+If the search does not converge, the solver uses its best finite evaluated speed
+and reports the actual forward result with a warning. This is not proof that
+the target is globally unreachable on a non-monotonic map. A search with no valid
+chart operating point raises `Compressor.SpeedSolveException` (an
+`IllegalStateException`) instead of publishing a target-pressure result.
+`ProductionOptimizer` rejects this specific failed trial and continues searching;
+unrelated calculation exceptions still propagate. Its `compressorSpeedSolve`
+hard constraint also rejects an unmet target when capacity analysis is enabled or
+optional output validation is disabled. It does not evaluate objectives or
+downstream constraints on a failed trial's stale outlet state. Diagnostics reset
+at the start of every run, including fixed-speed runs.
 
 When you need to determine the compressor speed required to achieve a specific operating point (flow and head), NeqSim provides a robust algorithm that works both within the defined curve range and with extrapolation beyond it.
 

docs/process/optimization/flow-rate-optimization.md

@@ -31,6 +31,18 @@ This is essential for:
 
 ## Key Features
 
+Compressor pressure-target failures are infeasible operating points. The shared
+`ProductionOptimizer` handles `Compressor.SpeedSolveException` without aborting
+the search and records a hard `compressorSpeedSolve` constraint. It also rejects
+a returned compressor result whose pressure target did not converge, even when
+capacity analysis is enabled. Objectives and downstream constraints are not read
+from a failed calculation; unrelated exceptions remain visible to callers.
+
+Automatic chart setup reruns the process only when it generates a chart. This
+avoids redundant process solves between capacity, lift-curve and performance
+tables, including when a preceding sweep ended on an invalid chart trial. The
+next table evaluates its own requested operating points.
+
 | Feature | Description |
 |---------|-------------|
 | **Pressure boundary search** | Find max flow at given inlet/outlet pressures |