perf(VTPR): cache T-only UNIFAC tables + densify group arrays (~6-7x for multicomponent flash) - #3276

Summary

Fixes the catastrophic slowdown of VTPR mixture flashes with component count (issue #3275). A 6-component natural-gas two-phase PT flash went from ~2.7 s to ~0.43 s (~6×); a single-phase flash from ~0.5 s to ~0.07 s (~7×). Results are bit-for-bit identical — this is pure memoization + a data-structure change, no math change.

Root cause

Profiling showed ~84 % of the flash in UNIFAC::UNIFACMixture::set_temperature, which rebuilt the entire temperature-dependent UNIFAC table on every call using std::map<pair,double> lookups, and was invoked O(N²) times per flash iteration through the fugacity-composition-derivative Jacobian. The temperature-cache guard was present but commented out.

Changes

1. Cache the T-only tables (Ψ interaction table + pure-component reference ln Γ). A flash holds T fixed across its density-solve iterations and its O(N²) composition-derivative evaluations, so these are recomputed only when T changes (re-enabled the guard).

2. Cache the mixture group residual ln Γ (m_lnGammag) on (T, composition). gE_R_RT evaluates ln_gamma_R for every component at the same (T, composition), invoking set_temperature from each, so this O(G³) block was rebuilt N× per gE evaluation. It is invalidated whenever the composition changes — set_mole_fractions is the sole writer of the group surface fractions it depends on, so the cache is invalidated exactly when its input changes. This is safe across a phase split: every liquid/vapour trial composition routes through set_mole_fractions, and SatL/SatV are separate instances with independent caches.

3. Replace the std::map group structures with dense arrays indexed by a compact group index built once in set_pure_data. The compact index preserves the ascending-sgi ordering of the previous std::map iteration, so summation order — and therefore results — are unchanged.

Results

VTPR/HEOS ratio at N=6 drops from ~57× to ~5×, and VTPR is now faster than HEOS for N ≤ 3. Total instruction count 3.24 B → 760 M.

Correctness / tests

• Bit-identical verified before/after on methanol-water (bubble P 24669.872 Pa exact) and a 6-component NG mixture (bubble/dew match exactly at every T) — the NG case exercises asymmetric Ψ and many group pairs, ruling out an index transposition.
• Adds the first VTPR mixture test (CoolProp-Tests-VTPRMixture.cpp, [VTPR][cubic][mixture]). CoolProp bundles no UNIFAC parameters, so it embeds a minimal methanol-water UNIFAC dataset, writes it to a temp dir, and loads it via VTPR_UNIFAC_PATH; the asserted bubble pressure is a regression value guarding the group-activity math. Config is restored on scope exit.
• [cubic] (3694 assertions) passes; preflight green (clang-format, build, tests, cppcheck, clang-tidy, semgrep).

Remaining (separate follow-up)

The dominant remaining cost is the finite-difference temperature derivatives in ln_gamma_R (itau > 0), which evaluate at perturbed T (tau ± dtau) and so miss the T-cache. Replacing them with analytical τ-derivatives of ln Γ would remove it and is a distinct piece of work.

Closes #3275.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Improvements

  • Enhanced UNIFAC mixture calculations with more efficient dense data structures and compact-group indexing.
  • Improved responsiveness to composition/temperature changes using updated caching and table-validity handling.

• Testing

  • Added a new VTPR methanol–water integration test (bubble-point regression and blind PT flash), using an embedded/local UNIFAC dataset.
  • Expanded the Catch2 test runner build to include an additional UNIFAC-related test translation unit.

Update: added temperature-keyed cache for the finite-difference τ-derivative path (commit c9e5bab)

The finite-difference temperature derivatives in ln_gamma_R (itau>0, needed by the const-P fugacity Jacobian) evaluate the group tables at perturbed temperatures (tau ± dtau). Those repeat across the per-component loop and the density-solve iterations at fixed (T, composition), but the single-slot cache thrashed on every perturbation. Replaced it with a temperature-keyed cache of the fully-computed group tables — a hit restores them with a few small vector copies instead of a rebuild. Cleared on composition/group change (and, since the Jacobian is analytical, composition changes only per trial phase, so the perturbed-T tables are reused across the whole density solve). A size cap bounds memory.

Still bit-for-bit identical (methanol-water and 6-component NG bubble/dew match exactly). Adds ~1.3× on top of the previous work → ~8× cumulative vs the original (6-component NG two-phase flash ~2.7 s → ~0.33 s).

The remaining follow-up is now genuinely just the analytical τ-derivatives (an accuracy improvement over the finite differences, which would also remove the perturbed-T evaluations entirely) — a distinct, non-bit-identical piece of work.