Pedersen-faithful gamma delumping with MW basis and conservation modes - #2337
Open
dupuypablo wants to merge 14 commits into
Open
Pedersen-faithful gamma delumping with MW basis and conservation modes#2337dupuypablo wants to merge 14 commits into
dupuypablo wants to merge 14 commits into
Conversation
…sen Ch. 5.6 common slate) Adds a CharacterizationOptions.inheritReferenceProperties flag (default true) so that fluids characterized to a shared reference inherit an identical pseudo-component property slate (MW, Tc, Pc, omega, density, ...) and differ only in mole fractions - the Pedersen et al. Chapter 5.6 'Common EoS' slate. The bare two-arg characterizeToReference stays grid-only (backward compatible). Adds CharacterizeToReferenceCommonSlateTest.
Faithful common-slate characterization that keeps multiple fluids separate while forcing them to share one mole-fraction weighted pseudo-component set. Per shared cut: MW (Eq. 5.59), Tc/Pc/omega (Eqs. 5.55-5.58) are weighted means X_i = sum_j Wgt(j) z_i^j X_i^j / sum_j Wgt(j) z_i^j; density reconstructed from weighted MW + weighted molar volume (Peneloux basis, Eq. 5.6). Inputs unchanged; clones returned in input order keeping each fluid's own lump mole fractions. Distinct from characterizeToReference (snap to one reference, PR #2318) and combineReservoirFluids (Ch. 5.5 merge into one fluid). Adds CharacterizeToCommonSlateTest (6 tests).
Splits each coarse source pseudocomponent into N SCN sub-fractions before distributeToProfiles, conserving parent moles and mass exactly. Sub-fractions redistribute across reference cuts so per-cut MW and density are recomputed self-consistently instead of being frozen by atomic PC-to-cut mapping. Gated by new CharacterizationOptions.delumpBeforeRecharacterization (default false, preserving today's behaviour). Resolution via delumpResolution (default 12). Recommended faithful path: delump=true + inheritReferenceProperties=false.
…eToReference Place reference cut boundaries as carbon-number equal-mass cut points on the reference's delumped imaginary composition (Pedersen Ch. 5.6, Eqs. 5.58-5.59, reference-only NFLUID=1) instead of boiling-point midpoints. Each equal-mass cut is clamped into the gap between adjacent reference pseudo-components so the one-to-one property-inheritance ordering is preserved even for unequal-mass references. Gated by new CharacterizationOptions.sharedImaginaryBoundaries (default false, reusing delumpResolution as the fine grid). delumpResolution<=1 falls back to midpoint boundaries. Backward compatible.
… equal-mass boundaries Document the new PseudoComponentCombiner API surface added in this PR: characterizeToCommonSlate (Pedersen Ch. 5.6, Eqs. 5.55-5.60 with worked math), the inheritReferenceProperties / delumpBeforeRecharacterization / delumpResolution / sharedImaginaryBoundaries options, and a three-workflow comparison table. Fixes the stale normalizeComposition default (false, not true) and the incorrect combineReservoirFluids example signature. Requested by PR reviewer.
Replace the arbitrary fixed +/-40% molar-mass window in PseudoComponentCombiner.delumpContributions with a neighbour-aware, Whitson-gamma delumping faithful to Pedersen Chapter 5: - Bound each lump's sub-fraction range by its neighbours' carbon-number midpoints (Eq. 5.27 inverted); first/last lumps use a one-sided rule, so sub-fractions never cross into a neighbour's interval or fabricate mass outside the lump. - Shape the mole split with a shifted Whitson gamma fitted by the method of moments on the molar-mass axis (local per-lump or global scope), sliced via the regularized incomplete gamma function; exponential Eq. 5.15 fallback. - Assign molar mass via Eq. 5.27 and normal boiling point via the non-linear Katz-Firoozabadi correlation (Eq. 5.28), anchored to the parent Tb, instead of a linear Tb-proportional-to-MW spread. - Add user-selectable conservation (DelumpConservation BOTH/MOLES/MASS) and binning basis (DelumpBinningBasis MOLAR_MASS/BOILING_POINT) and gamma scope (DelumpGammaScope NEIGHBOURS/GLOBAL) options; BOTH conserves parent moles and mass to 1e-9. - The shared-imaginary equal-mass boundary path reuses the same delumping. Add PseudoComponentDelumpDistributionTest (synthetic 3-lump fluid) asserting neighbour-bounded ranges, unimodal gamma molar distribution, the Katz-Firoozabadi MW-Tb relation, and per-lump mole/mass conservation, plus a package-private delumpForTesting seam. Update the characterization mathematics docs to describe the gamma/MW/conservation scheme.
# Conflicts: # CHANGELOG_AGENT_NOTES.md # docs/pvtsimulation/fluid_characterization_mathematics.md # src/main/java/neqsim/thermo/characterization/CharacterizationOptions.java # src/main/java/neqsim/thermo/characterization/PseudoComponentCombiner.java # src/test/java/neqsim/thermo/characterization/CharacterizeToCommonSlateTest.java
EvenSol
approved these changes
Jun 22, 2026
… characterization Adds an opt-in ReferenceBoundaryMode.CENTROID_SPAN to CharacterizationOptions so each reference cut key becomes the centroid of its own span (recurrence b_i = 2*key_i - b_(i-1), anchored at b_0 = key_0 - 0.5*(key_1 - key_0), walked light->heavy, each boundary clamped strictly between adjacent keys with midpoint fallback). Linear in molar mass, so only active on the MOLAR_MASS basis; boiling-point falls back to midpoint. Default stays MIDPOINT (no behaviour change). Includes JUnit test, docs, and changelog.
This was referenced Aug 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces the arbitrary fixed ±40 % molar-mass window in
PseudoComponentCombiner.delumpContributionswith a neighbour-aware, Whitson-gamma delumping faithful to Pedersen Chapter 5.Changes
M = 14C − 4); first/last lumps use a one-sided rule. Sub-fractions never cross into a neighbour's range or fabricate mass outside the lump.NEIGHBOURSorGLOBALscope), sliced with the regularized incomplete gamma function; exponential Eq. 5.15 fallback when the gamma is degenerate.Tb, replacing the oldTb ∝ MWlinear spread. Density and critical constants inherited from the parent.CharacterizationOptions:DelumpConservation {BOTH, MOLES, MASS}(defaultBOTH, conserves parent moles and mass to 1e-9),DelumpBinningBasis {MOLAR_MASS, BOILING_POINT}(defaultMOLAR_MASS),DelumpGammaScope {NEIGHBOURS, GLOBAL}(defaultNEIGHBOURS).Tests
PseudoComponentDelumpDistributionTeston a synthetic 3-lump fluid asserts: (a) neighbour-bounded ranges, (b) unimodal gamma molar distribution, (c) the Katz-Firoozabadi MW–Tb relation, (d) per-lump mole/mass conservation to 1e-9. Added a package-privatedelumpForTestingseam.Docs
docs/pvtsimulation/fluid_characterization_mathematics.md(options table, builder example, and a rewritten delumping subsection).