Repository navigation
[AI-Assisted] fix(thermo): preserve cold-start gas/oil/wax equilibrium - #4329
Conversation
Restrict fluid-only Gibbs and duplicate-phase cleanup to fluid calculations. Use conserved wax inventory for WAT and regress cold-start phase stability. Closes #4324
|
Combined flash integration verification completed after the coordinated master merges. Exact constituents: master An isolated combined tree compiled 3,534 production and 2,459 test sources, then passed 165 tests across 21 classes with zero failures, errors or skips on JDK 17. Coverage includes cold-start wax/WAT, solid/fluid cleanup boundaries, TPFlashTest, seeded/trace-water repair, pumps, flow-inventory scaling, reservoir surveillance/balance and well VLP. Both wax exclusions and strict trace-water final validation are retained; no numerical conflicts were found. This is evidence for the intended #4329 -> #4320 sequence, not a merge or Java 8 runtime certification. #4306 remains a separate held repair and was not included. Independent domain review and current-head CI remain required. |
Carry the bounded Maven-resolution retry into the renamed core workflow, retain all eight slow-test shards and four historical check contexts, and preserve both task-log entries. Keep all nine original Java source/test files byte-identical and regenerate engineering coverage. Validation: direct Spotless apply/check, documentation search, engineering coverage check, both pre-commit stages, workflow structure/Bash checks and whitespace checks passed. Isolated current-master+#4329+#4320 integration passed 165 tests across 21 classes with no failures/errors/skips on Java 17. Full exact-head GitHub CI remains pending.
Coordination and merge gates — 2026-10-14
Reviewed published head:
515e21acbb776099836b06fb7318208726e28918.All current-head checks pass (29 successful check runs and one intentional skip). The bounded wax/solid cleanup and inventory-based WAT correction is technically ready for human review. No independent approval is recorded, so green CI alone does not authorize merging.
This isolated thermodynamic-method repair requires the thermodynamics owner and one independent thermodynamics-domain reviewer. No additional independent-maintainer/API approval or NRC is established for this scope.
Integration: First flash lane candidate: #4329 → #4320 → #4332 → qualified #4306 → test/docs-only #4277. The isolated #4329+#4320 trial passed 165 tests; preserve wax/solid and ordinary-fluid cleanup regressions in the final integrated tree.
Closes #4324. Related: #4309 / #4325, #3709, #2937.
Problem and fix
The reported SRK/classic methane/n-heptane/nc14/nc20/nc24 feed already reaches gas–oil–wax equilibrium at 265 K. The subsequent
rescueSpuriousMultiphaseEndpoint()then incorrectly collapses it to one oil phase. Its cached homogeneous-fluid Gibbs comparison does not represent the solid phase's wax fugacity reference. The wax equilibrium solver itself is not the source of this collapse.Restrict that cleanup and the adjacent composition-duplicate cleanup to their intended fluid scope by excluding solid/wax calculations. Identical solid and liquid compositions also do not make them duplicate phases. No EOS, wax parameters, equilibrium iterations, numerical tolerances, or WAT search bounds change.
Read the WAT threshold through the existing inventory-based
getWtFraction(logicalWaxPhaseNumber). This makes this PR independently usable on current master without waiting for the separate public mass-accessor fix in #4325. It does not changeSystemThermo.getPhaseFractionor claim to resolve all of #4309.Reproduction and results
Base: master
373f10eab27749a3fc7f7e9b022c3bcbdc65bc63; runtime OpenJDK 17.0.20.The unchanged baseline fails both cooling regressions and both WAT regressions. With only the WAT inventory read corrected, cold-start WAT still incorrectly reports 153.940887 K at 5 bara and 141.506195 K at 1 bara. Adding the endpoint-scope fix removes those false transitions.
All three starting guesses give identical WAT in each pressure case. Gas/oil/wax persist at 260, 265 and 270 K; 275 K is gas/oil. Independent flashes 0.01 K on each side verify WAT.
The new regression covers 48 temperature/start/initialization combinations at 1 and 5 bara, including fresh starts, previously flashed warm/cold starts and explicit
init(0). It checks normalized phase fractions/compositions, total mass and component inventory, and equal component fugacities. Across the eight distinct P/T states, maximum component mole-fraction residual is 7.19e-9 and maximum log-fugacity mismatch is 9.46e-8.144 independent tangent-plane trials use gas, liquid and wax models, each seeded from the feed and every component. All converge with no instability below the -1e-6 acceptance tolerance. These are model-consistency checks, not experimental qualification or a proof of global stability for arbitrary feeds.
Validation
108 tests across 12 suites passed; zero failures, errors or skips, including:
NamedWaxColdStartTest,WATConsistencyTest(calcWAT returns below the wax-positive TP-flash onset for a characterized synthetic oil #3709),TPFlashTest(including ordinary fluid endpoint cleanup regressions);WaxFlashTest,WaxModelRegressionTest,WaxModelComparisonTest,PhaseWaxTest,WaxCurveCalculatorTest,WaxFractionSimTest;SolidCheckFluidEquilibriumTest,SolidFlash1Test,SystemThermoSolidPhaseCheckTest.Commands and gates:
prepare_maven.pyhelper;./mvnw -q -DskipTests validatepassed../mvnw -q '-Dtest=NamedWaxColdStartTest,WATConsistencyTest,WaxFlashTest,WaxModelRegressionTest,WaxModelComparisonTest,PhaseWaxTest,WaxCurveCalculatorTest,WaxFractionSimTest,TPFlashTest,SolidCheckFluidEquilibriumTest,SolidFlash1Test,SystemThermoSolidPhaseCheckTest' -Djacoco.skip=true -DexcludedTestGroups= testpassed.java com.sun.tools.javac.Main --release 8; actual Java 8 runtime execution remains for CI.python3 devtools/run_spotless.py apply(rerun clean) andcheckpassed.python3 devtools/check_documentation_search.pypassed: 788 Markdown pages and one HTML page audited.pre-commit run --all-files --hook-stage pre-commitand--hook-stage pre-pushpassed.python3 devtools/build_engineering_coverage.pyregenerated only the two changed production-source digests;--checkpassed../mvnw -q -DskipTests -DjavadocExecutable=<temporary-javadoc-launcher> javadoc:javadocpassed. The launcher invokes the installed JDK javadoc module because the runtime lacks the standalone executable; no repository build configuration changed.git diff --cached --checkpassed.Timing spot-checks preserve numerical checksums. After 15,000 warmup flashes, the median of five 10,000-flash ordinary multiphase VLE batches was 48.28 → 48.71 microseconds per flash. At the unchanged 270 K wax state, five 1,000-flash batches gave 2.451 → 2.446 milliseconds per flash in the first matched run; repeated wax medians remained within about 3%. Shared-runner timings varied, especially for gas-only cases, so no overall speedup is claimed. The fix adds only short-circuit flag checks to fluid endpoint cleanup; no extra flashes, EOS evaluations, initialization, cloning or allocation.
Documentation and limits
Updated the wax guide and WAT/cleanup Javadocs with the numerical results, inventory definition and model-validity boundary. Updated wax troubleshooting guidance to inspect raw phase/equilibrium evidence instead of treating monotonic smoothing as validation.
This does not validate or repair solid density/caloric correlations, qualify laboratory WAT, or change equilibrium wax into a deposition model.
AI-assisted. CI PASSED for the reviewed head. Ready for subsystem-owner and independent domain review under repository governance; not merged.