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

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:

hydrotreating / HDS engineering model
catalytic reforming simplified yield/property model
hydrocracking simplified yield model
FCC yield/surrogate model
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.

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.

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.

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.

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.

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.

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

Full openly reproducible crude representation including defensible light-end and 1050 °F+ residue treatment.
Independent public validation of generated refinery pseudo-component properties.
Atmospheric product-yield / boiling-range comparison against public reference evidence with tighter balance gates and recorded runtime.
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.

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.

Capability contract — refinery assay bulk density/API closure

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?
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.
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.
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.
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.
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.

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):

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

Extend whole-assay density/property validation beyond one COA assay family and define reference-condition/contraction handling.
Qualify generated pseudo-component molecular weight, critical properties and acentric factor against independent public data.
Build a complete public crude slate with defensible terminal light-end/residue representation and independent atmospheric product yield/boiling-range evidence.
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.

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.

Capability contract — multi-assay COA bulk density qualification

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?
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.
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.
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.
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.
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.

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.

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.

Capability contract — API-gravity reference consistency

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?
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.
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.
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.
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.
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.

feat(refinery): add hydrocracking yield and hydrogen supply balance

[AI-Assisted] feat(refinery): add hydrocracking yield and hydrogen su…

feat(refinery): add FCC yield and coke regenerator balance

feat(refinery): add FCC yield and coke regenerator balance (#4488)

fix(refinery): close FCC dry-gas molar balance

fix(refinery): close FCC dry-gas molar balance (#4492)

feat(refinery): add delayed-coking screening balances

feat(refinery): add delayed-coking screening balances (#4493)

Campaign ledger — connected workflow merged; next API prerequisite frozen

PR feat(refinery): connect Big Hill atmospheric and vacuum fractionation #4498 merged from its preserved exact head b672beaa54a6b4cbef5226dc13ebe91669ab47cd as d4435f07850faf147522ccf12054d3623f22709f on 2026-10-21.
Hosted acceptance was complete before merge: 8/8 workflow groups and 19/19 Core jobs passed, including both Java 8 lanes, Java 21 fast lanes, all eight slow-test shards, Javadocs, model specifications, benchmark accuracy, documentation search, engineering coverage, PaperLab, Spotless, and pre-commit.
Protected master subsequently advanced to 48b40e3efa76869f8bc702869f63b942c74a4c88 through documentation repair docs: repair labyrinth guide rendering contract (D206) #4500; no refinery head was rebased, restarted, replaced, or abandoned.
feat(optimization): report refined boundary headroom #4489 and [AI-Assisted] feat(well): add explicit liquid mass injectivity #4490 have also merged. Current positively identified autonomous implementation occupancy is 0/10. The separate open fix: validate interfacial tension models and reject incomplete profiles #4499 interfacial-tension fix is user-directed and is not counted as an autonomous campaign capability.
The one-active-PR-for-[Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 gate is clear. No open PR, issue, or default-branch code search overlaps the Big Hill connected atmospheric/vacuum sensitivity scope.

Frozen next increment

Add a public overload of the existing Big Hill vacuum reboiler-temperature sensitivity that consumes a solved atmospheric-bottoms StreamInterface and delegates each independently cloned point through createFromAtmosphericBottoms(...). Acceptance requires:

one DOE assay identity preserved across the handoff at every point;
finite, positive, strictly increasing caller-owned temperatures;
independent point construction and qualified MESH-result evaluation;
mass, component, energy, residual, product-ordering, immutability, and fail-closed input checks;
explicit non-claims: numerical screening only; no plant operating envelope, yield calibration, or ASTM qualification.

This is a real dependency split. The executed Python/JPype notebook cannot precede the public Java overload it must call, and the current runner has neither NeqSim nor JPype available. The next cross-repository increment after this API merges remains an executed/rendered NeqSim-Colab connected workflow with a bounded atmospheric/vacuum sensitivity receipt. No unexecuted notebook will be published.

Campaign checkpoint — draft #4501 published

Draft PR: feat(refinery): screen connected Big Hill vacuum operation #4501 — feat(refinery): screen connected Big Hill vacuum operation #4501
Preserved branch: automation/3305-connected-vacuum-sensitivity
Exact base: 48b40e3efa76869f8bc702869f63b942c74a4c88
Exact branch head: 2e1ae89d7fe6aa9978a346c3ba0f6b3b84a5d603
Active [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 implementation PRs: 1/1
Positively identified autonomous implementation occupancy: 1/10

The increment adds the composition-preserving atmospheric-bottoms overload to the existing vacuum reboiler-temperature sensitivity, plus fail-closed and connected engineering regression evidence. It introduces no new public dataset or correlation and retains the DOE/Sarir evidence boundary.

Fast hosted follow-up found and repaired two deterministic repository-contract issues on the same preserved branch:

restored the exact DOE/Sarir identity-guard phrase required by the documentation regression;
applied the hosted Spotless rewrites to the overload and null-source test.

The engineering-coverage bot then regenerated the source digest as commit f2cb76ec9a2f64c3ad85f2263a722cf8ce975e4c; the final human-authored documentation commit 2e1ae89d7fe6aa9978a346c3ba0f6b3b84a5d603 is one fast-forward commit above it and leaves the generated digest unchanged. GitHub PR metadata/workflow indexing is currently lagging that branch ref, so full exact-head hosted validation remains PENDING CI. No rebase, force update, replacement PR, readiness transition, merge, or issue closure was performed.

Next gate: wait for the exact 2e1ae89d... workflow set, repair only deterministic failures on this branch, and retain draft status pending accountable refinery/domain review. The executed/rendered Python/JPype notebook remains the next cross-repository increment after this Java API prerequisite merges.

Campaign checkpoint — #4501 merged; draft Colab #194 published

NeqSim prerequisite #4501 merged from preserved exact head 2e1ae89d7fe6aa9978a346c3ba0f6b3b84a5d603 as merge commit 404891092424a20ae0091d88254ba5c495ef546b; all eight exact-head workflow groups passed.
New sole active [Campaign] Refinery simulation: crude assays, petroleum fractions, fractionation, blending and conversion models #3305 increment: EvenSol/NeqSim-Colab#194, draft-only.
Preserved branch: automation/3305-big-hill-vacuum-colab.
Exact Colab base: c4332e2023f594e83fabe93212602a7e996d0a71.
Exact draft head: 4364a2b970235d8b554569995fec89cbd1929587.
Current-source NeqSim commit: 74a0529d19db577cb41034685905067a8ac9d0c6.
Source-built JAR SHA-256: da6d66a14de7410b596308358664df4b50f20091799e4d48aad0686561f44270.

Delivered capability

One executed, versioned notebook carries the public DOE SPR Big Hill Sweet assay through the source-pinned fired heater and rigorous atmospheric column, then evaluates a connected 698/700/702 K vacuum reboiler-temperature sensitivity. It retains conservation, MESH residual, product ordering, source-stream immutability, public provenance, rendered evidence, catalog entries, and a dedicated maintenance-ledger record. No Java API or numerical model is changed.

Engineering and validation receipt

7/7 code cells executed sequentially with stored outputs; 8 markdown cells.
5000.0 kg/h feed; 2034.516494 kg/h atmospheric bottoms.
Vacuum overhead mass fraction: 71.953165%, 72.234274%, 72.496050%.
Max relative mass closure: 2.728e-13; component closure: 9.329e-13.
Max column energy-balance error: 0.02480694; max MESH residual: 0.01225151.
Caller-owned source mass and composition deltas: exactly zero.
Strict notebook check: 0 errors, 0 warnings; checker tests: 6 passed.
Full repository integrity: 368 notebooks, 0 errors, 47 pre-existing warnings.
HTML/MathJax render, three tables, one two-panel figure, and both compact conservation equations visually verified.
All five remote files match the validated local artifacts exactly.

Scientific boundary and campaign gate

Numerical screening only: the DOE data identify the assay, not the modeled operating conditions. No plant-yield benchmark, ASTM qualification, hydraulics, coking, corrosion, controls, safe-operability, or design-approval claim is made.

Autonomous capability occupancy is now 4/10. The one-active-PR rule blocks another #3305 increment while draft #194 remains open. Hosted notebook CI is running on the exact head above; next action is exact-head review/CI follow-up without rebase, replacement, restart, closure, or abandonment.

Exact-head CI completion — Colab #194

All five hosted workflow groups passed on preserved draft head 4364a2b970235d8b554569995fec89cbd1929587:

Notebook integrity
Validate seismic to RMS notebook
CO2 low-temperature notebook validation
Northern Lights open-data notebook validation
Data reconciliation and Bayesian twin validation

EvenSol/NeqSim-Colab#194 remains open, mergeable, and draft-only with no head movement. Status is now exact-head CI passed; draft review pending. The one-active-PR gate remains engaged and autonomous occupancy remains 4/10.

READY TO MERGE classification — Colab #194

EvenSol/NeqSim-Colab#194 is READY TO MERGE on preserved exact head 4364a2b970235d8b554569995fec89cbd1929587.

Final gate evidence:

unchanged exact base c4332e2023f594e83fabe93212602a7e996d0a71; current Colab master is still that commit,
five intended changed files only,
all five hosted workflows completed successfully on the exact head,
clean notebook execution, strict repository validation, complete stored outputs, compatible HTML/MathJax rendering, and visual inspection passed,
public DOE assay provenance, source-built NeqSim commit/JAR identity, engineering validation, limitations, documentation impact, and maintenance-ledger evidence are complete,
PR is mergeable with no reviews, requested changes, comments, or unresolved threads.

This is a readiness classification only. The PR remains open and draft; no merge, readiness-state change, rebase, or head mutation was performed. The one-active-PR-for-#3305 gate remains binding. Autonomous implementation occupancy remains 4/10.

#3305 exact-head continuity checkpoint — Colab #194

EvenSol/NeqSim-Colab#194 became conflicted after master advanced to 387193477b4a15788bf003b5a60ba1fd327df961 with the merged #4509/#4528 notebook and catalog updates. The existing branch was repaired with two-parent merge commit 5ee224ddaf62b45b9312ce594ab3696a4c24f3a8 (parents: previously validated head 4364a2b970235d8b554569995fec89cbd1929587 and current master 387193477b4a15788bf003b5a60ba1fd327df961), with no rebase, force-push, replacement, or scope expansion.

Conflict scope was limited to README/catalog/root-ledger integration. Both the new upstream additions and the Big Hill entries were retained; the root notebook count is now 325. The executed Big Hill notebook and provenance-shard blobs are byte-identical to validated head 4364a2b970235d8b554569995fec89cbd1929587, so no scientific model, result, or provenance content changed.

Hosted validation on exact head 5ee224ddaf62b45b9312ce594ab3696a4c24f3a8 completed 4/5 workflows successfully: Notebook integrity, CO2 low-temperature, Northern Lights open-data, and data-reconciliation/Bayesian-twin passed. The unrelated seismic-to-RMS workflow failed because XTGeo emitted a pandas deprecation warning to stderr in notebooks/reservoir/seismic_to_rms_input_workflow.ipynb; this PR does not touch that notebook, its generator, or the workflow. The shared current-base failure is tracked in NeqSim-Colab #198, now with a second exact-head reproduction from PR #194.

PR #194 remains open, draft, and mergeable on the preserved exact head. It is validation-blocked and not READY TO MERGE pending resolution of the unrelated base workflow failure. The one-active-PR gate for #3305 remains binding.

#3305 exact-head continuity checkpoint — Colab #194

EvenSol/NeqSim-Colab#194 has been repaired after master advanced to 303da564dfca02a1feefcc0cd4da07ea6939f0dd.

New exact head: 14cd1cd211d8823729706249b8c60d519abc68a4.
Two-parent merge: first parent 5ee224ddaf62b45b9312ce594ab3696a4c24f3a8; second parent current master 303da564dfca02a1feefcc0cd4da07ea6939f0dd.
No rebase, force-push, replacement branch, or scope expansion.
Final PR scope remains five files.
Validated Big Hill notebook blob preserved: bb516fa245633cb7a60c154555343686865021ad.
Provenance shard blob preserved: bd195ee1e0e3f4c8a66e5be411e91894365339f6.
Notebook SHA-256 remains 483d39d54751630d9e35253f1a26f38be770f188f97d36e981e739ac4926be3e.
Latest HISEP and offshore-report README/catalog/ledger changes are retained; aggregate active-notebook count reconciled to 327.
All five exact-head hosted workflows are queued.
Shared unrelated base blocker remains NeqSim-Colab#198.

Status: VALIDATION PENDING EXACT-HEAD CI. Draft state is preserved; the one-active-PR-for-#3305 gate remains binding. The autonomous implementation ceiling remains 10.

Exact-head CI completion

All hosted workflows completed on preserved head 14cd1cd211d8823729706249b8c60d519abc68a4:

Notebook integrity: passed.
CO2 low-temperature notebook validation: passed.
Northern Lights open-data notebook validation: passed.
Data reconciliation and Bayesian twin validation: passed.
Seismic-to-RMS validation: failed on the existing unrelated base defect.

The failed job again stopped at notebook cell 12 because XTGeo emitted pandas 3.1 Pandas4Warning messages from xtgeo/xyz/polygons.py to stderr. The refinery PR does not touch that notebook, XTGeo, pandas, its generator, or the strict runner. The deterministic shared blocker remains NeqSim-Colab#198; no speculative rerun was made.

Final status on this head: VALIDATION BLOCKED BY UNRELATED BASE WORKFLOW. PR #194 remains open, draft, mergeable, and the sole active #3305 increment. The one-active-PR gate remains binding under the global ceiling of 10.

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

Description

Goal

Target end-state

Competitive benchmark

Workstreams

A. Crude assay and petroleum characterization — highest priority

Required capabilities

Acceptance criteria

B. Refinery stream properties and product specifications

C. Thermodynamic robustness for refinery fluids

Required work

D. Atmospheric and vacuum fractionation

Scope

Acceptance benchmark

E. Refinery front-end equipment

F. Blending and optimization

Scope

G. Conversion-unit engineering models — later phase

H. Energy, emissions and economics

I. Validation, provenance and uncertainty

Reference implementation roadmap

Phase 0 — inventory and benchmark

Phase 1 — characterization foundation

Phase 2 — property framework

Phase 3 — fractionation

Phase 4 — refinery process workflow

Phase 5 — blending/optimization

Phase 6 — selected conversion models

Engineering quality gates

Definition of campaign success

Campaign governance

Activity

EvenSol commented on Aug 28, 2026

Refinery campaign ledger — initial assay/TBP foundation

EvenSol commented on Aug 28, 2026

Refinery campaign ledger — PR #3308 advanced

Capability gained / hardening in this run

Validation state

Public benchmark evidence selected for the next increment

Related issue boundaries

Remaining highest-value gaps / next dependency-ready increment

EvenSol commented on Aug 28, 2026

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

Validation evidence

Hardening finding on the active head

Public benchmark evidence / next dependency

EvenSol commented on Aug 28, 2026

Refinery campaign ledger — DOE Big Hill assay qualification increment

Continuity / portfolio

Capability gained

Public benchmark evidence / provenance

Validation state

Remaining highest-value gaps

Next dependency-ready increment

EvenSol commented on Aug 29, 2026

Refinery campaign ledger — DOE assay density-path hardening

Continuity / portfolio

Capability gained in this run

Scientific/provenance correction

Validation

Remaining highest-value gaps

Next dependency-ready increment

EvenSol commented on Aug 29, 2026

Refinery campaign ledger — DOE atmospheric integration benchmark

Capability gained

Scientific benchmark evidence

Validation state

Remaining highest-value gaps

Next dependency-ready increment

EvenSol commented on Aug 30, 2026

EvenSol commented on Aug 30, 2026

Capability contract — refinery assay bulk density/API closure

EvenSol commented on Aug 30, 2026

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

Continuity / portfolio

Capability gained

Public benchmark and quantitative evidence

Validation

Scientific and compatibility boundary