[Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models

[EvenSol]

Goal

Build a validated refinery-simulation capability in NeqSim that is useful for real engineering studies while preserving NeqSim's strengths as an open, programmable Java/Python thermodynamics and process-simulation platform.

This campaign should close the largest refinery-model gaps relative to mature tools such as Aspen HYSYS, Petro-SIM and AVEVA PRO/II, but must not attempt to clone proprietary simulator behavior or datasets. The target is a transparent, testable and extensible refinery calculation framework built from public science, standards, open data and reproducible engineering correlations.

Target end-state

NeqSim should be able to take a crude/petroleum assay or characterized heavy hydrocarbon feed and support a reproducible workflow such as:

assay / TBP data → pseudo-components → thermodynamic characterization → preheat / flash → atmospheric fractionation → vacuum/further fractionation → product streams → blending / specifications → energy, emissions and economics

Selected simplified conversion-unit models may then be added where defensible public models and validation data exist.

Competitive benchmark

The campaign should periodically maintain a capability matrix against refinery functionality typically available in:

• Aspen HYSYS
• Petro-SIM
• AVEVA PRO/II / AVEVA Process Simulation
• DWSIM

The matrix is for gap identification only. Do not reproduce proprietary equations, parameter databases or implementation details.

---

Workstreams

A. Crude assay and petroleum characterization — highest priority

Establish one coherent representation for refinery feeds and petroleum fractions.

Required capabilities

• TBP curve ingestion.
• ASTM D86/D1160-style distillation representations where implementation is legally and technically appropriate.
• Conversion between supported distillation-curve representations using published correlations with explicit provenance and validity limits.
• Pseudo-component generation from boiling-range cuts.
• Characterization from combinations of boiling point/range, density or specific gravity, API gravity and molecular weight.
• Watson/UOP K factor and other useful characterization descriptors.
• Heavy-end / plus-fraction splitting and lumping.
• Preserve characterization metadata and provenance through calculations.
• Re-lumping/re-characterization APIs suitable for refinery flowsheets.

Acceptance criteria

• Public reference datasets with regression tests.
• Mass and composition conservation demonstrated for splitting/lumping workflows.
• Round-trip characterization behavior documented where mathematically possible.
• Java and Python APIs.
• Clear warnings for extrapolation outside correlation ranges.

B. Refinery stream properties and product specifications

Provide first-class refinery properties rather than requiring users to reconstruct them externally.

Candidate properties include:

• API gravity / specific gravity
• average molecular weight
• density and viscosity
• normal/mean boiling descriptors
• RVP/TVP and volatility indicators where technically well-defined
• distillation curves and boiling-range yields
• heating value / energy density
• sulfur or other assay-carried quality attributes when represented in the feed model
• flash point, pour/cloud point or other quality correlations only when sufficiently validated public correlations exist
• quality/property mixing rules with explicit linear/nonlinear assumptions

Each property must expose units, source/model provenance, applicability range and validation evidence where possible.

C. Thermodynamic robustness for refinery fluids

Refinery support depends on reliable thermodynamics for very broad boiling ranges and heavy pseudo-components.

Required work

• Validate SRK/PR/CPA and relevant mixing-rule behavior for heavy characterized fractions.
• Stable TP/PH/PS flash behavior over atmospheric and vacuum tower conditions.
• Reliable vapor/liquid root selection for wide-boiling mixtures.
• Bubble/dew/saturation calculations with pseudo-components.
• Numerical behavior for traces of water/light gases in heavy feeds.
• Energy/enthalpy consistency for heating, cooling and fractionation calculations.
• Detect and report unsupported extrapolation rather than silently returning questionable results.

Do not introduce refinery-specific hacks into generic flash algorithms. Generic thermodynamic fixes should be coordinated with the relevant flash/thermodynamic roadmaps.

D. Atmospheric and vacuum fractionation

Make rigorous fractionation the central refinery unit-operation milestone.

Scope

• Atmospheric crude column workflows using existing NeqSim column abstractions where possible.
• Vacuum fractionation and low-pressure robustness.
• Side draws.
• Pump-around loops.
• Side strippers where supported by the process architecture.
• Condenser/reboiler and heat-balance handling appropriate to refinery service.
• Cut-point targeting / product-yield calculations.
• Column initialization and convergence improvements for very broad boiling mixtures.

Acceptance benchmark

Create at least one open/reference refinery fractionation case with:

• crude/pseudo-component feed characterization;
• atmospheric tower;
• multiple products/cuts;
• mass and energy balance closure;
• documented product boiling ranges/yields;
• repeatable Java/Python calculation.

E. Refinery front-end equipment

Prioritize models that compose naturally with ProcessSystem:

• crude preheat train workflows
• fired heater/furnace duty, fuel demand and emissions
• stabilizers/splitters
• flash drums
• desalting as an engineering/conceptual model where defensible
• heat-exchanger and utility integration
• compressor/pump energy

Prefer reusable equipment APIs over refinery-only monolithic classes.

F. Blending and optimization

Add refinery/product blending as a first-class optimization problem.

Scope

• crude blending
• intermediate/product blending
• linear property blending where valid
• nonlinear blending correlations where published and validated
• product quality constraints
• economic/objective-function interfaces
• integration with NeqSim optimization facilities

Representative use case:
minimize blend cost or energy while satisfying density/API, volatility, boiling-range and other represented specifications.

G. Conversion-unit engineering models — later phase

Only implement models for which NeqSim can provide transparent assumptions and credible validation.

Potential sequence:

1. hydrotreating / HDS engineering model
2. catalytic reforming simplified yield/property model
3. hydrocracking simplified yield model
4. FCC yield/surrogate model
5. coking or other conversion models if justified

Initially favor:

• yield/reactor-surrogate models;
• hydrogen consumption;
• heat duty;
• gas/liquid/product distribution;
• sulfur/removal bookkeeping;
• process integration.

High-fidelity proprietary-style kinetic packages are not required for campaign success.

H. Energy, emissions and economics

Refinery workflows should naturally connect to NeqSim's broader process capabilities:

• fired-heater fuel consumption
• compressor/pump power
• steam/utility duties
• hydrogen demand
• CO2 emissions
• heat integration metrics
• simple operating-cost/economic metrics

I. Validation, provenance and uncertainty

This is a differentiator for NeqSim and is mandatory.

For each substantial model/correlation, record where practical:

• publication/DOI/stable public reference;
• equation/model name;
• implementation assumptions;
• parameter provenance/licensing;
• units and basis;
• stated validity range;
• validation dataset;
• error/uncertainty statistics;
• extrapolation behavior.

Prefer primary literature, NIST/API/public government datasets, openly licensed academic data and reproducible benchmark cases.

---

Reference implementation roadmap

Phase 0 — inventory and benchmark

• Inventory existing NeqSim petroleum fraction, characterization, distillation, column and refinery-adjacent code/tests/docs.
• Identify duplicated/dead/inconsistent APIs.
• Build and maintain a refinery capability/gap matrix.
• Select the highest-value reusable foundation instead of creating parallel APIs.

Phase 1 — characterization foundation

• Unified assay/petroleum fraction model.
• TBP/boiling curves.
• Pseudo-component generation/splitting/lumping.
• Characterization validation suite.

Phase 2 — property framework

• Refinery stream property API.
• Validation and provenance.
• Mixing/blending property framework.

Phase 3 — fractionation

• Broad-boiling-mixture column robustness.
• Atmospheric fractionation reference case.
• Vacuum fractionation reference case.
• Side draws/pump-around workflows as supported.

Phase 4 — refinery process workflow

Create an end-to-end example:
crude assay → characterization → preheat → furnace → atmospheric column → products → vacuum/feed preparation → utilities/emissions.

Phase 5 — blending/optimization

• Crude and product blending.
• Specification constraints.
• Optimization examples.

Phase 6 — selected conversion models

Add only validated engineering-level models justified by public data and demonstrated user value.

---

Engineering quality gates

A refinery increment is not complete merely because an API exists.

Every implementation PR should, where applicable, include:

• focused unit tests;
• regression tests;
• mass/element/energy balance checks;
• literature/public-data validation;
• numerical edge cases;
• Java API coverage;
• Python accessibility/example;
• documentation of assumptions/limits;
• no unexplained degradation of generic thermodynamic behavior.

For numerical changes, compare accuracy and runtime before/after and preserve representative benchmark results.

Definition of campaign success

The campaign can be considered mature when NeqSim can reproducibly simulate a representative refinery front-end from crude characterization through atmospheric/vacuum separation and product blending, with:

• robust heavy-fraction thermodynamics;
• realistic refinery stream properties;
• reusable ProcessSystem equipment;
• energy/emission accounting;
• Java/Python workflows;
• published validation evidence and limitations;
• regression-protected benchmark cases;
• an explicit documented gap list for functionality intentionally left to specialist refinery simulators.

Campaign governance

• Maintain at most one active implementation PR for this issue at any time.
• Respect the portfolio cap of no more than ten open autonomous NeqSim campaign implementation PRs overall.
• At the start of every run, read this issue and newest comments, current master, repository instructions, relevant source/tests/docs, active/recent related issues and PRs, reviews/checks, recent commits and the previous refinery campaign ledger/progress comment.
• If an active [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 implementation PR exists, work only on its exact current remote head and advance/repair/validate it before considering new work.
• Do not merge or rebase master into an active campaign PR merely to continue or repair it.
• If no active [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 PR exists, verify the previous increment is merged/closed and a campaign slot is available before creating one draft PR.
• Maximize useful work per PR: implement the largest coherent dependency-ready batch that can be responsibly reviewed and validated.
• Coordinate generic thermodynamics/TP-flash/performance/dynamics work with their owning NeqSim roadmaps instead of duplicating fixes here.
• Use the connected GitHub repository state as authoritative for campaign continuity.
• Local Maven/Java/Python validation is useful but not a prerequisite for advancing an existing PR. If unavailable, use GitHub CI and state VALIDATION PENDING CI or VALIDATION BLOCKED BY INFRASTRUCTURE; never claim an unrun check passed.
• Do not modify scientific code merely to silence transient runner/network/infrastructure failures.
• Keep a concise campaign ledger in [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 after meaningful increments: exact PR/head, validation status, capability gained, benchmark evidence, remaining highest-value gaps and recommended next dependency-ready increment.

[EvenSol]

Refinery campaign ledger — initial assay/TBP foundation

Active implementation PR: #3308 — [AI-Assisted] feat(refinery): harden assay and TBP cut foundation

• Base/master selected after campaign inventory: b358d3c6dfff2d25967c6be48d0feb4887d4b207
• Current PR head: 0625f20d6ad0ccbc92e06a0a738485561fd48361
• Branch relation at publication: 4 commits ahead / 0 behind the selected base
• Portfolio check before publication: no existing [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 PR; only two other open autonomous implementation PRs were found, so the campaign remained below the 10-PR cap.

Capability gained:

• one explicit mass or liquid-volume assay basis per case;
• density-based volume→mass conversion with reconstructed mass closure;
• explicit kg/mol and g/mol molar-mass inputs and explicit kg/m3 density input;
• dense/negative-API cut support;
• cumulative 0–100 vol% pre-binned TBP cut-boundary ingestion in °C/K;
• preserved lower/upper boiling ranges;
• guards against incomplete/mixed-basis assays, invalid/non-monotonic TBP curves, duplicate cut names, and repeated assay application;
• expanded focused characterization regressions;
• source-aligned characterization docs plus first refinery capability/gap matrix.

Scientific boundary: no TBP/critical-property/EOS correlation coefficients were added or retuned. The new TBP-boundary API is for already-TBP pre-binned data and does not claim ASTM D86/D1160 conversion. Existing petroleum-property correlations remain the scientific layer to qualify independently.

Validation: VALIDATION PENDING CI. Local clone/Maven/Spotless was attempted but blocked by DNS resolution of github.com; no local check is claimed as passed. GitHub Actions started six workflows on the exact head (build/test/javadoc, pre-commit, Spotless patch, docs search, CodeQL, PaperLab gate) and they are currently in progress.

Remaining highest-value gaps: independent public refinery-assay property validation; atmospheric broad-boiling fractionation benchmark; vacuum benchmark; unified refinery stream properties; front-end energy/emissions; blending/specification optimization; conversion-unit models later.

Recommended next dependency-ready increment after #3308 merges: select an openly reproducible crude/refinery assay case and qualify the generated pseudo-component slate plus atmospheric fractionation with mass/energy closure, product cut yields/boiling ranges, numerical robustness and runtime. Do not add ASTM conversion or conversion-reactor correlations before that benchmark foundation is in place.

[EvenSol]

Refinery campaign ledger — PR #3308 advanced

Active implementation PR: #3308 [AI-Assisted] feat(refinery): harden assay and TBP cut foundation

• Base/master: b358d3c6dfff2d25967c6be48d0feb4887d4b207
• Exact current head: 4dd92be67c30a76ef60ac4d46746c4d1a711eaeb
• Ahead/behind base: 10 / 0
• Changed files: 5
• State: open draft, mergeable
• Validation: VALIDATION PENDING CI

Capability gained / hardening in this run

The existing assay/TBP foundation was reviewed against the generic SystemThermo.addTBPfraction(...) naming semantics. A concrete alias/collision edge case was found: generic TBP insertion canonicalizes names at the _PC pseudo-component marker, while the refinery preflight originally checked cutName + "_PC" literally. A cut name containing _PC could therefore pass the refinery preflight but be canonicalized to a different component identity downstream.

PR #3308 now rejects _PC in refinery assay cut names before any thermodynamic-system mutation. Focused tests cover both direct AssayCut names and TBP-boundary prefixes, including the no-partial-mutation condition.

Commits added on the existing exact PR head:

• 476b15301c3c965e67cfcbfb82a6b10c15052316 — reject reserved pseudo-component marker in assay names
• 35bb85ae1e927efad3a36410f559a7504f232c2e — regression tests for name aliases
• 4dd92be67c30a76ef60ac4d46746c4d1a711eaeb — Spotless-aligned test formatting

Validation state

Final-head CI restarted after the guard/test follow-up. At this ledger update:

• PaperLab Replication Gate: success
• Spotless format patch: success
• CodeQL: in progress
• Build/test/Javadocs: in progress
• Documentation search coverage: in progress
• Pre-commit checks: in progress

No full-CI success is claimed yet. Local Maven/Spotless validation remains unavailable in this runtime because github.com DNS resolution is blocked; GitHub CI remains authoritative.

Public benchmark evidence selected for the next increment

A strong public validation source has been identified: the U.S. Department of Energy Strategic Petroleum Reserve crude-oil assay collection:

• https://www.spr.doe.gov/reports/Crude_Oil_Assays.html
• Crude Oil Assay Manual, 5th ed., 1 Aug 2024: https://www.spr.doe.gov/reports/docs/CrudeOilAssayManual.pdf

The DOE page publishes assay workbooks for Bayou Choctaw, West Hackberry, Big Hill and Bryan Mound sweet/sour streams. The 2024 manual documents atmospheric/light-vacuum crude distillation by ASTM D2892 followed by D5236 for the residuum, and states that distillation fractions are measured on a mass-percent basis with volume-percent values calculated from each fraction's specific gravity. That measurement basis maps cleanly onto the new mass/volume-explicit assay bookkeeping and provides a credible independent refinery benchmark source.

The individual workbook has not yet been ingested or committed, so there is no numerical validation claim from DOE data in #3308.

Related issue boundaries

• Enhanced TBP fraction input: boiling point and (molar mass or desnity) #1393: generic addTBPfraction input from boiling point + one known property remains open; this refinery helper work does not close it.
• Make addTBPfraction2 boiling-point units explicit and unit-safe #3120: generic addTBPfraction2 boiling-point unit safety remains open; the refinery assay API's explicit units do not replace it.
• Generic TP-flash/root-selection changes remain owned by the flash roadmap and should not be duplicated here.

Remaining highest-value gaps / next dependency-ready increment

After #3308 is fully green, reviewed and merged, the next #3305 increment should freeze one DOE SPR assay workbook/reference stream and build a reproducible benchmark from assay → pseudo-component slate → atmospheric fractionation. Acceptance evidence should include source/access provenance, reconstructed assay mass, mass/energy balance closure, product yields and boiling ranges, numerical convergence/repeatability, and runtime before adding further refinery correlations or conversion-unit models.

[EvenSol]

Refinery campaign ledger — exact-head review of PR #3308

Sole active implementation PR: #3308 — [AI-Assisted] feat(refinery): harden assay and TBP cut foundation

• Base/master: b358d3c6dfff2d25967c6be48d0feb4887d4b207
• Exact current head: 51dacb1acf2e066a742a0ddf6a2fc53a0b0a1cad
• Ahead/behind selected base: 12 / 0
• Changed files: 5
• State: open draft, mergeable
• Portfolio remains below the 10 autonomous-implementation-PR cap; no competing [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 PR was created.
• Validation: VALIDATION PENDING CI

Validation evidence

Exact-head Spotless, PaperLab, pre-commit, CodeQL and documentation-search workflows are green. Java 21 Javadocs and agent-skill reference checks are also green within the build workflow. The full Java fast/slow test matrix is still running; no full-green result is claimed.

No submitted reviews, PR comments or unresolved review threads were present at review time.

Hardening finding on the active head

A source audit found an internal trace-cut consistency edge case: apply() skips each resolved cut at or below FRACTION_TOLERANCE = 1e-10, but then requires reconstructed relative mass error <= 1e-10. Multiple individually valid trace cuts can therefore be omitted and collectively violate the closure gate. This should be repaired and regression-tested on this same active PR before the assay foundation is declared complete. The mass-conservation gate itself should remain strict; trace-cut handling should be made consistent with it.

Public benchmark evidence / next dependency

The next benchmark is now narrowed to the DOE Strategic Petroleum Reserve Big Hill Sweet 2024 assay workbook (https://www.spr.doe.gov/reports/Assays/2024/BigHillSwAssay.xlsx) together with the DOE Crude Oil Assay Manual, 5th ed. (1 Aug 2024). The manual documents D2892 atmospheric/light-vacuum fractionation followed by D5236 for residuum, with fractions measured on a mass-percent basis and volume-percent calculated from fraction specific gravity. That measurement basis directly exercises the new explicit mass/volume bookkeeping.

The workbook is not yet ingested/frozen and no numerical DOE agreement is claimed. After #3308 is fully green and the trace-cut consistency issue is repaired, the next dependency-ready campaign increment remains assay → pseudo-component slate → atmospheric fractionation with mass/energy closure, product yields/boiling ranges, convergence/repeatability and runtime.

[EvenSol]

Refinery campaign ledger — DOE Big Hill assay qualification increment

Continuity / portfolio

• Previous refinery implementation PR [AI-Assisted] feat(refinery): harden assay and TBP cut foundation #3308 is merged (8aee98488a468f823815483c9c492a639a544f5a) and is now foundation work.
• Sole active [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 implementation PR: [AI-Assisted] test(refinery): qualify DOE Big Hill assay bookkeeping #3316, draft and mergeable.
• Exact base/master selected for this increment: 9e4e36d4b6a59404ac9aa629740fbc312610d3c8.
• Exact active PR head: 576d78c87be3ac0f0923d2c93b59f52c9e3398eb.
• Open [AI-Assisted] NeqSim PR portfolio remains below the campaign cap of ten.

Capability gained

PR #3316 adds the first independent public refinery-assay qualification for OilAssayCharacterisation rather than relying only on synthetic bookkeeping tests. It freezes a bounded 175–1050 degF distillate slice from the U.S. DOE Strategic Petroleum Reserve Big Hill Sweet assay, sample MLI 009 (1998-05-04), with published volume yields, weight yields, specific gravities, API gravities, and finite cut boundaries.

The regression:

• checks the published SG/API pairs against the conventional API relation;
• converts normalized DOE volume yields through the real OilAssayCharacterisation volume-to-mass path using published cut SG values;
• compares the result with independently published DOE weight yields;
• accepts maximum absolute normalized mass-fraction deviation < 0.007 (0.7 percentage points); frozen-source arithmetic is approximately 0.00667;
• creates five bounded pseudo-components and requires finite positive component amounts/properties plus reconstructed assay mass closure at 1e-10;
• adds durable public source/provenance, acceptance, and limitations documentation.

Public benchmark evidence / provenance

• U.S. GovInfo, SPR Crude Oil Comprehensive Analysis / Big Hill Sweet MLI 009: https://www.govinfo.gov/content/pkg/CFR-2004-title10-vol4/pdf/CFR-2004-title10-vol4-chapII-subchapI.pdf
• DOE SPR Crude Oil Assay Manual, 5th ed., 1 Aug 2024: https://www.spr.doe.gov/reports/docs/CrudeOilAssayManual.pdf
• DOE assay index: https://www.spr.doe.gov/reports/Crude_Oil_Assays.html

The DOE manual documents D2892 atmospheric/light-vacuum fractionation followed by D5236 for residuum and states that fractions are measured on a mass-percent basis while volume percentages are calculated using fraction specific gravity. No ASTM equations or proprietary simulator implementation/data are copied into NeqSim.

Validation state

VALIDATION PENDING CI on exact head 576d78c87be3ac0f0923d2c93b59f52c9e3398eb.

Exact-head evidence already green:

• pre-commit checks;
• hosted Spotless run, with an empty second exact-head formatting artifact after applying the initial formatting-only patch;
• Java 21 Javadocs;
• agent/skill cross-reference checks.

Full Java fast/slow matrix, CodeQL, and documentation search are still running at this ledger update. No running/unrun check is claimed as passed. There are no submitted reviews or unresolved review threads at this head.

Remaining highest-value gaps

• Complete crude representation including the unbounded light end and 1050 degF+ residue without inventing missing boiling bounds.
• Independent validation of generated pseudo-component MW/critical properties/acentric factor across refinery ranges.
• A reproducible atmospheric crude-fractionation benchmark using the qualified assay basis, then vacuum fractionation.
• Mass + energy closure, product boiling ranges/yields, convergence/repeatability, and runtime evidence for the column workflow.
• Generic TBP API work remains coordinated with Enhanced TBP fraction input: boiling point and (molar mass or desnity) #1393 and Make addTBPfraction2 boiling-point units explicit and unit-safe #3120; generic flash/root work remains outside [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305.

Next dependency-ready increment

After #3316 is green/reviewed/merged, extend this public DOE basis into a complete reproducible crude/pseudo-component slate and atmospheric fractionation case. Do not start vacuum/fractionation conversion-unit models until the atmospheric benchmark has independent yield/property evidence and robust mass/energy closure.

[EvenSol]

Refinery campaign ledger — DOE assay density-path hardening

Continuity / portfolio

• Sole active [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 implementation PR remains [AI-Assisted] test(refinery): qualify DOE Big Hill assay bookkeeping #3316: [AI-Assisted] test(refinery): qualify DOE Big Hill assay bookkeeping.
• Exact base/master remains 9e4e36d4b6a59404ac9aa629740fbc312610d3c8; current master is still at that SHA, so the PR is not behind master.
• Exact current PR head: 7e7ad317d2d4aa3342b58592fbcaad8a399f4312.
• Seven open [AI-Assisted] NeqSim PRs were found in this run, below the campaign cap of ten.
• No reviews or unresolved review threads are present on [AI-Assisted] test(refinery): qualify DOE Big Hill assay bookkeeping #3316.

Capability gained in this run

The existing DOE Big Hill bookkeeping qualification was extended on the same PR to cover the second refinery density descriptor exposed by the public assay API:

• published four-decimal SG values remain the primary volume-to-mass path;
• published one-decimal API gravities are now supplied through AssayCut.withApiGravity(...) on an independent thermodynamic system;
• the resulting normalized mass-fraction shape must agree with the SG path within 5e-5 mass fraction;
• direct arithmetic from the frozen DOE values gives a maximum expected SG-vs-rounded-API difference of approximately 4.27e-5 mass fraction.

This closes a practical user-path gap without adding or retuning any petroleum correlation.

Scientific/provenance correction

The DOE 2024 assay manual states that fraction mass percentages are measured while volume percentages are calculated from specific gravity. The #3316 documentation and PR description now make this dependence explicit: the paired DOE volume/weight yields are a public-source bookkeeping/provenance qualification, not statistically independent experimental validation of a petroleum-property model. No ASTM equation or proprietary simulator data/behavior is copied.

Validation

VALIDATION PENDING CI on exact head 7e7ad317d2d4aa3342b58592fbcaad8a399f4312.

• Previous head 576d78c87be3ac0f0923d2c93b59f52c9e3398eb: complete hosted PR workflow set passed.
• First extended head exposed only a branch-attributable Spotless formatting delta in the new Java test.
• The exact hosted formatter patch was applied as the current head.
• Current-head Spotless: pass, with an empty formatter artifact.
• Current-head pre-commit: pass.
• Current-head documentation search: pass.
• Current-head CodeQL: pass.
• Current-head Java 21 Javadocs and agent/skill cross-reference checks: pass.
• Current-head Java fast/slow matrix is still running; no running check is claimed as passed.

Remaining highest-value gaps

• complete DOE crude/pseudo-component slate rather than the bounded 175–1050 degF slice;
• atmospheric broad-boiling fractionation benchmark with mass/energy closure;
• independent product-yield/boiling-range evidence, convergence/repeatability and runtime;
• vacuum fractionation after atmospheric qualification;
• refinery stream property framework, front-end energy/emissions, blending/specification optimization; conversion units remain later.

Next dependency-ready increment

After #3316 is green/reviewed/merged, extend the qualified DOE basis into a reproducible atmospheric crude-fractionation benchmark. Keep generic TP-flash/root changes outside #3305 and coordinate generic TBP API work with #1393/#3120.

[EvenSol]

Refinery campaign ledger — DOE atmospheric integration benchmark

Active implementation PR: #3329 [AI-Assisted] test(refinery): qualify DOE atmospheric fractionation integration

Exact current head: 54f93603ec5725b21d052b8f57add8380cc04f80

Base selected when opened: master 83432c868043ae0adfb45bc630f3b22183fe85bd (no master-to-PR sync/rebase performed).

Capability gained

• Extends the merged DOE Big Hill bookkeeping foundation from [AI-Assisted] test(refinery): qualify DOE Big Hill assay bookkeeping #3316 into the first rigorous-column refinery integration regression.
• Uses the bounded 175–1050 °F Big Hill Sweet MLI 009 slice on DOE's published mass-yield basis, with published cut SG and finite boiling boundaries.
• Generates five real TBP pseudo-components through OilAssayCharacterisation and feeds them to an 8-tray near-atmospheric DistillationColumn with reboiler, partial condenser and a liquid side draw.
• The acceptance contract requires positive three-product flow, external/process mass closure, energy-balance closure, per-pseudo-component molar conservation, light/heavy enrichment, overhead < side draw < bottoms representative-boiling ordering, and repeated-solve stability.
• Added dedicated provenance/limitations documentation and indexed it from the characterization docs.

Scientific benchmark evidence

Public sources are DOE/US Government only:

• Big Hill Sweet MLI 009 comprehensive assay: https://www.govinfo.gov/content/pkg/CFR-2000-title10-vol4/pdf/CFR-2000-title10-vol4-part625-appA.pdf
• DOE SPR Crude Oil Assay Manual, 5th ed. (2024-08-01): https://www.spr.doe.gov/reports/docs/CrudeOilAssayManual.pdf

The DOE manual states D2892/D5236 fractions are measured on a mass-percent basis and volume percentages are calculated from cut specific gravity. The benchmark therefore uses the published weight yields for the process feed. Open-ended light and 1050 °F+ tails remain excluded rather than assigning invented boiling limits.

This is explicitly an integration/numerical-robustness qualification, not an independent validation of full-crude atmospheric product yields or pseudo-component property correlations.

Validation state

VALIDATION PENDING CI

On exact head 54f93603...:

• hosted Spotless workflow: passed, with an empty generated Spotless patch after applying the hosted formatting delta;
• pre-commit checks: passed;
• documentation search coverage: passed;
• CodeQL: passed;
• Java 21 Javadocs: passed;
• agent/skill cross-reference check: passed;
• full Ubuntu/Windows fast tests and four Ubuntu slow-test shards: running at the latest check.

No unrun check is claimed as passed.

Remaining highest-value gaps

1. Full openly reproducible crude representation including defensible light-end and 1050 °F+ residue treatment.
2. Independent public validation of generated refinery pseudo-component properties.
3. Atmospheric product-yield / boiling-range comparison against public reference evidence with tighter balance gates and recorded runtime.
4. Only after that: vacuum fractionation, front-end heater/energy/emissions integration, blending/optimization, then conversion-unit models.

Next dependency-ready increment

After #3329 is green and merged, extend the public DOE/open assay basis to a complete crude slate and require atmospheric cut yields/boiling ranges, mass and energy closure, convergence/repeatability and runtime evidence. Generic TP-flash/root-selection changes remain outside #3305, and generic TBP-input API work remains coordinated with #1393/#3120.

[EvenSol]

PR #3329 repair published at c17f3ba030d6705d12cee066e23f55ce9b49010f.

Root causes and repair:

• corrected OilAssayCharacterisation inferred molar mass from g/mol-sized correlation output to the API's kg/mol contract;
• added DOE cut molar-mass and boiling-interval regression gates;
• qualified the rigorous column with a partial condenser, solver-determined top temperature, 600 K reboiler, and tray-4 liquid side draw;
• added the dedicated per-tray material-balance acceptance gate and updated both refinery documents.

Local focused/adjacent tests, Spotless, documentation search, and diff checks pass. Full hosted CI is pending and remains authoritative. The PR stays draft.

[EvenSol]

Capability contract — refinery assay bulk density/API closure

1. Capability and engineering question
   Name: Refinery assay bulk density/API closure.
   Question: Can NeqSim reconstruct a whole-assay specific gravity and API gravity from user-supplied mass- or liquid-volume-basis cut yields and cut densities, without mutating the thermodynamic system, and reproduce an independent public crude-assay value within the source method's practical resolution?

2. Maturity
   Current: proposed. Target for the next bounded increment: experimental. Promotion to qualified requires more than one independent assay family and an explicit volume-contraction/temperature treatment.

3. Authoritative Java calculation/model
   Extend OilAssayCharacterisation with read-only bulk-property calculations. Inputs are the existing AssayCut fractions (dimensionless 0–1, one common mass or liquid-volume basis) and density descriptors (specific gravity at 60 °F, API gravity at 60 °F, or kg/m³ converted through the existing contract). Outputs are dimensionless bulk specific gravity and degrees API. Volume basis uses additive liquid volumes; mass basis uses the reciprocal-density mixture relation. Assumptions: positive finite densities, one complete common fraction basis summing to unity, ideal/additive liquid volume, no temperature correction and no excess-volume/contraction model. Intended for petroleum-assay screening around the source's 60 °F reference, not custody transfer or certified blend design.

4. Capability views

   • Java: applicable; authoritative public methods plus focused regression tests.
   • Python: applicable through NeqSim's JPype exposure of the same public Java object/methods; no duplicate Python formula.
   • JSON: not applicable in this increment because OilAssayCharacterisation has no owned stable JSON assay schema; schema design remains a follow-on gap.
   • MCP: not applicable until the assay/stream-property schema is owned by the MCP campaign; no parallel low-level tool will be introduced here.
   • Notebook: not applicable for this bounded API/validation increment; a complete crude-to-column notebook belongs after the complete-slate and product-yield gates.
   • Engineering validation: applicable; public DOE/OEDI Bureau of Mines crude-analysis data plus analytical synthetic checks.

5. Benchmark and acceptance criteria
   Use the CC BY 4.0 U.S. DOE/NREL OEDI Crude Oil Analysis (COA) Database, Bureau of Mines sample 920 (Turner Valley, Alberta). Its complete reported category yields are 70.5 vol% gasoline+naphtha at SG 0.754, 13.2 vol% kerosene at SG 0.813, 3.7 vol% gas oil at SG 0.831 and 12.6 vol% residuum at SG 0.889; published whole-crude SG is 0.779 and API is 50.1. The additive-volume reconstruction is SG 0.781647 and API about 49.528. Accept: fraction closure at source precision; reconstructed SG within 0.004 absolute and API within 0.7° of the public whole-crude values; analytical equality for synthetic mass/volume cases; finite positive outputs; input-order independence; no thermodynamic-system mutation. This increment adds O(assay cuts) work and no process-solver runtime path.

6. Dependencies, risk, documentation, stop boundary
   Depends on merged refinery assay foundation [AI-Assisted] feat(refinery): harden assay and TBP cut foundation #3308, DOE bookkeeping [AI-Assisted] test(refinery): qualify DOE Big Hill assay bookkeeping #3316 and atmospheric integration [AI-Assisted] test(refinery): qualify DOE atmospheric fractionation integration #3329. Compatibility risk is additive public API only; generic TBP/flash algorithms remain untouched and coordinated with Enhanced TBP fraction input: boiling point and (molar mass or desnity) #1393/Make addTBPfraction2 boiling-point units explicit and unit-safe #3120 and their owning roadmaps. Documentation must state units, additive-volume assumption, source/license/provenance, accuracy, validity boundary and Python accessibility. Stop boundary: no complete crude pseudo-component slate, no terminal-cut boiling extrapolation, no column retuning, no JSON/MCP schema, no vacuum fractionation, no blending optimization and no conversion-unit model in this PR.

[EvenSol]

Refinery campaign ledger — DOE/OEDI bulk density and API increment

Continuity / portfolio

• Previous refinery atmospheric integration PR [AI-Assisted] test(refinery): qualify DOE atmospheric fractionation integration #3329 is merged as a1aad0b258182a0ca63476092f9a2e86e018111f.
• Sole active [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 implementation PR: [AI-Assisted] feat(refinery): reconstruct assay bulk density and API #3341, open, mergeable draft.
• Capability contract was recorded before branch/PR creation in comment [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 (comment).
• Exact selected base: 7a7c5a4990b57597355d1182784e12d547b9fb3b.
• Exact current head: 2c4e130ccaf74d4ce6fdd44cbbb6557861de169b (6 commits ahead / 0 behind that base).
• Two other open AI-assisted campaign PRs were found before publication; [AI-Assisted] feat(refinery): reconstruct assay bulk density and API #3341 therefore becomes the third active capability and remains below both the transition target and absolute cap.

Capability gained

PR #3341 adds a first read-only refinery stream property to OilAssayCharacterisation:

• getBulkSpecificGravity() reconstructs ideal additive-volume whole-assay SG from either mass- or liquid-volume-basis cuts after the existing basis/closure validation;
• getBulkApiGravity() derives API from the same Java authority;
• analytical tests cover mass and volume bases, invalid/empty/mixed inputs, input-order independence and no thermodynamic-system mutation;
• public methods are automatically available through the Python/JVM gateway, without duplicating the equation;
• JSON/MCP and notebook views remain explicitly not applicable at this bounded schema-free API stage.

Target maturity is experimental. This is not promoted to qualified because only one independent assay family is included and there is no temperature/contraction treatment.

Public benchmark and quantitative evidence

Source: U.S. DOE/NREL OEDI Crude Oil Analysis (COA) Database, CC BY 4.0, Bureau of Mines sample 920 (Turner Valley, Alberta):

• https://catalog.data.gov/dataset/crude-oil-analysis-coa-database
• https://data.openei.org/submissions/178

The frozen complete public cut table is 70.5 vol% gasoline+naphtha at SG 0.754, 13.2% kerosene at 0.813, 3.7% gas oil at 0.831 and 12.6% residuum at 0.889. Ideal additive-volume reconstruction is SG 0.781647 and API about 49.528° versus the public whole-crude SG 0.779 and API 50.1°. Observed differences are 0.002647 SG and 0.572° API, within declared gates of 0.004 SG and 0.7° API; no coefficient is tuned.

Validation

VALIDATION BLOCKED BY BASE DEFECT on exact head 2c4e130ccaf74d4ce6fdd44cbbb6557861de169b.

Passed locally on the published source:

• direct Spotless apply/check;
• documentation search audit (674 Markdown pages + 1 standalone HTML page);
• pre-commit and pre-push stages;
• focused/adjacent Java tests for the generic assay, OEDI qualification and DOE Big Hill qualification;
• git diff --check.

Local Javadocs were attempted but cannot run because the environment has a Java 17 JRE without javac/javadoc; this is not claimed as passed.

Reused hosted exact-head evidence:

• Spotless: success
• pre-commit: success
• PaperLab: success
• documentation search: success
• CodeQL: success
• full build/test/Javadocs: failure, attributable only to the shared DEXPI regression DexpiInstrumentTest.testWriterProducesActuatingFunctions on Windows Java 21 after more than 12,462 tests had run.

The same DEXPI assertion fails on master: it expects legacy SignalConveyingFunction, while merged #3338 emits InformationFlow classified as SignalLineFunction. The bounded shared repair is PR #3342 at exact head 67a1c6102d8e85ff18df756ae02a67df4a939466; its Spotless, pre-commit, PaperLab, documentation-search, CodeQL, engineering-diagram performance, and process-to-engineering notebook workflows pass, while its authoritative full build/test/Javadocs matrix remains in progress. Per the fast-validation policy, this state was inspected once and not polled. No refinery code was changed, no local suite was redundantly rerun, and #3341 was not synchronized with master. There are no submitted reviews or unresolved review threads on #3341.

Scientific and compatibility boundary

The method assumes ideal additive liquid volumes at the density reference condition represented by the inputs. It is not temperature corrected and has no excess-volume/blend-contraction model; it is not a custody-transfer or certified blend-design calculation. The PR changes no TBP correlation, pseudo-component property coefficient, flash, column, process solver or runtime hot path. Generic TBP API work remains coordinated with #1393/#3120.

Remaining highest-value gaps

1. Extend whole-assay density/property validation beyond one COA assay family and define reference-condition/contraction handling.
2. Qualify generated pseudo-component molecular weight, critical properties and acentric factor against independent public data.
3. Build a complete public crude slate with defensible terminal light-end/residue representation and independent atmospheric product yield/boiling-range evidence.
4. Only after those gates: vacuum fractionation, refinery front-end energy/emissions, blending/specification optimization and later conversion-unit models.

Next dependency-ready increment

Preserve #3341 on exact head 2c4e130ccaf74d4ce6fdd44cbbb6557861de169b. After #3342 repairs the shared DEXPI base defect, requalify #3341 in a corrected merge context without inflating its frozen scope. Once #3341 is green and merged, select the next characterization/property increment from the public COA matrix or another open assay source, preserving the complete-crude atmospheric benchmark as the next process-level target. Do not add a competing #3305 PR while #3341 is open.

[EvenSol]

Merged-state handoff — assay bulk density/API increment

PR #3341 merged on 2026-08-30 from exact head 2c4e130ccaf74d4ce6fdd44cbbb6557861de169b as merge commit 6be71bcc52e054129589fd4d3cff9e4049e5b277.

• Capability delivered (experimental): read-only OilAssayCharacterisation.getBulkSpecificGravity() and getBulkApiGravity(), with mass- and liquid-volume-basis handling through the authoritative Java behavior; Python receives the same methods through JPype. JSON, MCP and notebook views remain outside this bounded increment.
• Public benchmark: DOE/NREL OEDI COA sample 920 reconstructs SG 0.781647 and API 49.528° versus published 0.779 and 50.1°; differences 0.002647 SG and 0.572° API meet the declared 0.004 and 0.7° gates without fitted coefficients.
• Exact-head evidence: focused/adjacent assay tests, Spotless, documentation search, pre-commit/pre-push, CodeQL and other static gates passed. The hosted Java 21 Windows build failed only the unchanged shared DexpiInstrumentTest; Ubuntu fast was cancelled by fail-fast and Java 8 was skipped. The failure was outside [AI-Assisted] feat(refinery): reconstruct assay bulk density and API #3341's six-file diff, so this ledger does not retroactively classify that exact head READY TO MERGE.
• Shared baseline resolution: the bounded DEXPI correction subsequently merged in #3342 at 67a1c6102d8e85ff18df756ae02a67df4a939466, with the complete Java 8/21 matrix passing.
• Stop boundary: ideal additive liquid volumes at the input reference condition; no temperature correction, excess-volume/blend contraction, custody-transfer authority, TBP coefficient change, flash, column or process-solver change.
• Remaining gaps: multiple assay families, explicit reference-condition/contraction treatment, independent pseudo-component property validation, and a complete public crude slate with atmospheric product-yield evidence.

Issue #3305 remains open because the broader refinery roadmap is not complete.

[EvenSol]

Capability contract — multi-assay COA bulk density qualification

1. Capability and engineering question
   COA multi-assay bulk density/API qualification. Can the merged Java OilAssayCharacterisation.getBulkSpecificGravity() / getBulkApiGravity() behavior reproduce every complete four-category assay found in the public DOE/OEDI Summary of Analyses.xls matrix within an explicit screening error envelope, rather than relying on one selected crude?

2. Maturity
   Current: experimental from single-sample [AI-Assisted] feat(refinery): reconstruct assay bulk density and API #3341 evidence. Target: qualified for standardized COA complete-category screening over the frozen public matrix; it remains experimental outside that validity domain and is not custody-transfer/design certification.

3. Authoritative calculation and contract
   Java remains authoritative. Inputs are one complete mass- or liquid-volume-basis assay with cut yields (fraction or percent) and cut specific gravity/density at the source reference condition. Output is dimensionless bulk SG from ideal additive liquid volumes and API in degrees API. The qualification domain is the five DOE/Bureau of Mines rows whose gasoline+naphtha, kerosene, gas-oil and residuum categories close to 100.0 vol%, have density for every positive category, and have no lubricating-distillate category: samples 920, 50146, 56337, 60205 and 68120; published crude SG spans 0.765–0.847. Assumptions: additive volumes, source precision, no temperature correction, pressure correction, excess volume or contraction model.

4. Capability views

   • Java: applicable; existing public methods plus matrix regression.
   • Python: applicable through JPype exposure of the same Java methods; no duplicate formula.
   • JSON: not applicable because this increment does not own a stable assay schema.
   • MCP: not applicable until the assay schema is owned by the MCP roadmap.
   • Notebook: not applicable for a bounded non-visual qualification matrix; the complete crude-to-column workflow remains the notebook boundary.
   • Engineering validation: applicable; CC BY 4.0 DOE/NREL OEDI COA archive, its method description and all five qualifying rows.

5. Benchmark and acceptance
   Freeze the archive URL/license, row identifiers, locations, category yields/densities and published whole-crude SG/API. Require 100.0 vol% closure, exact reconstruction of the additive-volume arithmetic, finite positive outputs, input-order independence, no thermodynamic-system mutation, per-row absolute error ≤0.006 SG and ≤1.5° API, and aggregate maximum/mean/RMSE evidence. The calculation is O(cuts), uses at most four positive cuts per case and adds no process-solver performance path. No conservation claim beyond source-yield closure and unchanged system state.

6. Dependencies, risk, documentation and stop boundary
   Depends on merged [AI-Assisted] feat(refinery): harden assay and TBP cut foundation #3308/[AI-Assisted] test(refinery): qualify DOE Big Hill assay bookkeeping #3316/[AI-Assisted] test(refinery): qualify DOE atmospheric fractionation integration #3329/[AI-Assisted] feat(refinery): reconstruct assay bulk density and API #3341 and current master 2b330659716d157727fd88ebc5d7c8019d88aa86. Compatibility risk is test/documentation-only: no production equation, TBP correlation, flash, column or ProcessSystem change. Update the OEDI evidence page, refinery assay guide/index as needed, and record the exact observed error matrix. Stop boundary: no coefficient tuning, formula change, new stream property, reference-condition/contraction model, terminal-cut boiling extrapolation, JSON/MCP schema, notebook, column change, vacuum model, blending optimization or conversion-unit model.

[EvenSol]

Refinery campaign ledger — COA density matrix staged at portfolio boundary

Continuity and exact state

• Merged refinery increment: [AI-Assisted] feat(refinery): reconstruct assay bulk density and API #3341, merge commit 6be71bcc52e054129589fd4d3cff9e4049e5b277.
• Shared DEXPI base repair: [AI-Assisted] feat(dexpi): model vessel taps and piping transitions #3342, merge commit/current selected master 2b330659716d157727fd88ebc5d7c8019d88aa86; its exact-head build/test/Javadocs workflow passed.
• No open [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 implementation PR exists.
• The next capability contract was recorded before branch creation in comment [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 (comment).
• Prepared branch: ai/refinery-coa-density-matrix-3305.
• Exact staged head: a7e243b6c730bc581b611dc74d4e8ec83a1c0f5c, one commit ahead / zero behind selected master.
• Changed files: 4 (one focused Java qualification class and three characterization documents); production Java is unchanged.

Capability and benchmark evidence

The staged batch expands the merged bulk SG/API evidence from one selected crude to all five complete four-category rows in the CC BY 4.0 DOE/NREL OEDI Summary of Analyses.xls matrix. The selection is fail-closed: gasoline+naphtha, kerosene, gas-oil and residuum yields must close to 100.0 vol%, every positive category must have density, lubricating-distillate buckets must be zero, and whole-crude SG/API must be published.

Samples 920, 50146, 56337, 60205 and 68120 span published crude SG 0.765–0.847. Frozen aggregate absolute-error evidence:

• SG maximum / mean / RMSE: 0.005964 / 0.002182 / 0.003017
• API maximum / mean / RMSE: 1.420670 / 0.510845 / 0.713312 degrees API

The regression requires source-yield closure, exact additive-volume arithmetic, finite outputs, reversed-order equality, unchanged thermodynamic system, and per-row limits of 0.006 SG / 1.5 degrees API. No coefficient is tuned and the largest error is retained.

Validation and publication state

VALIDATION PENDING CI. No local checkout/toolchain gate was run in this connector-first batch, so Maven, Spotless, documentation search, pre-commit and pre-push are not claimed. The exact remote diff was inspected and preserved.

A draft PR was not opened because concurrent campaign work now occupies the three-capability transition target: #3343, #3344 and #3345 are open. This is a portfolio-capacity boundary, not an infrastructure failure. The absolute ten-PR safety ceiling remains untested because the stricter three-capability target applies. No existing PR was closed, replaced or rebased.

Documentation and stop boundary

Documentation now records the archive URL/license, exhaustive row-selection rule, full matrix, equations, observed errors, validity range and limitations. The batch adds no production formula, temperature/contraction treatment, TBP/flash/column change, JSON/MCP schema, notebook, vacuum model, blending optimizer or conversion model.

Next dependency

When one of #3343/#3344/#3345 merges or closes and the portfolio target has a slot, re-read master and the staged branch head, then publish this exact coherent batch as the sole draft #3305 PR without inflating its scope. After that qualification merges, proceed to pseudo-component property evidence and the complete-crude atmospheric product-yield/boiling-range gate.

[EvenSol]

Refinery campaign ledger — 2026-08-30

• Sole active [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 implementation PR: [AI-Assisted] fix(refinery): format COA density qualification #3351, draft.
• Exact base/head: d65dceb54535a9af811c755fb43447ae5675a246 → 2bdd79d8438394a774ac149ecfd3f8254aa24113.
• Capacity: four positively identified open autonomous implementation capabilities including [AI-Assisted] fix(refinery): format COA density qualification #3351, below the target and absolute ceiling of ten.
• Capability continuity: formatter-only repair of merged test(refinery): qualify COA density matrix #3346's contracted multi-assay DOE/OEDI COA bulk-density qualification. The hosted spotless-format-patch target blob 5a998bce6483b3f29472e75b47543c63f5d5c3c5 is now applied exactly. No calculation, datum, tolerance, API, model, maturity, provenance, validity range, or documentation changed.
• Benchmark evidence retained: five qualifying complete public assay rows; SG max/mean/RMSE error 0.005964 / 0.002182 / 0.003017; API max/mean/RMSE error 1.420670 / 0.510845 / 0.713312°.
• Validation: reused test(refinery): qualify COA density matrix #3346 exact-head complete build/test/Javadocs, CodeQL, documentation-search, and formatter-artifact evidence. On the repair state, whitespace-stripped pre/post Java is identical, git diff --check passed, and the documentation-search audit passed (674 Markdown pages, one standalone HTML page). No Maven regression was rerun because the change is formatter-only. The local full-tree Spotless check remains blocked by three unrelated current-master files already owned by [AI-Assisted] fix(mcp): format electrolyte scale view #3349; no overlap was introduced.
• Hosted state: Pre-commit, Spotless patch, CodeQL, and full build/test/Javadocs workflows started on exact head 2bdd79d8438394a774ac149ecfd3f8254aa24113. VALIDATION PENDING CI.
• Stop boundary: PR [AI-Assisted] fix(refinery): format COA density qualification #3351 ends after exact-head formatting qualification. After it merges, the next dependency-ready refinery increment remains broader public-assay property qualification, followed by a complete reproducible crude slate and independent atmospheric product-yield/boiling-range validation before vacuum or conversion models.

[EvenSol]

Capability contract — API-gravity reference consistency

1. Capability / engineering question. Make refinery-assay API-gravity input and bulk density outputs reference-condition explicit: does an API value round-trip exactly through the conventional SG60/60 = 141.5 / (API + 131.5) relation, while still providing physical density at 60 °F without conflating density and dimensionless specific gravity?
2. Maturity. Current: experimental, because AssayCut.withApiGravity(...).resolveDensity() multiplies the conventional SG60/60 result by water density while withSpecificGravity(...) does not, so API- and SG-origin cuts have different semantics. Target: qualified for assay screening over the public DOE ranges below; negative API remains software-supported but outside public qualification.
3. Authoritative Java model. OilAssayCharacterisation.AssayCut and the existing bulk-property methods remain authoritative. Inputs are cut yields plus API gravity [°API] or SG60/60 [-]. Outputs are bulk SG60/60 [-], bulk API [°API], and a new explicitly named bulk density at 60 °F [kg/m³] using water density 999.016 kg/m³. Assumptions: conventional 60/60 °F API basis and ideal additive liquid volumes; no temperature/pressure correction, excess volume, or blend contraction. Public qualification range: DOE Big Hill bounded cuts API 17.8–49.6 and DOE/OEDI whole crudes API 35.6–53.5.
4. Views. Java: applicable and authoritative. Python/JPype: applicable through the same public Java methods. JSON and MCP: not applicable because no refinery-assay schema currently owns this object. Notebook: not applicable to this bounded reference-semantics correction. Engineering validation: applicable through public DOE SPR Big Hill and CC BY 4.0 DOE/OEDI COA SG/API pairs. No separate Python equation will be introduced.
5. Acceptance. API→SG→API round-trip to 1e-12; API- and exact-equivalent-SG assay paths produce identical mass fractions and bulk properties to 1e-12; physical density is exactly SG × 999.016 kg/m³; existing mass closure remains 1e-10; no system mutation; invalid/singular API fails closed; DOE reported pairs remain within source rounding; deterministic repeat and bounded constant-time property evaluation; no regression to the five-row SG/API error matrix. The public pairs are source-consistency evidence, not statistically independent property measurements.
6. Dependencies / compatibility / documentation / stop. Depends on merged [AI-Assisted] feat(refinery): reconstruct assay bulk density and API #3341/test(refinery): qualify COA density matrix #3346/[AI-Assisted] fix(refinery): format COA density qualification #3351 and does not touch TP flash, EOS, pseudo-component correlations, columns, ProcessSystem, optimization, or other roadmap ownership. Compatibility risk is a roughly 0.0985% correction for API-derived cut density values previously scaled by the 60 °F water density; record this explicitly. Update refinery-assay and DOE validation documentation. Stop before temperature-density correction, contraction, viscosity/volatility, pseudo-component coefficient qualification, complete-crude terminal treatment, atmospheric/vacuum yield validation, blending, or conversion models.

Selected base for implementation preparation: current master 1dec02d734eb5daef4df0ca567724635721e93f1.