Capacity and Utilization Analysis

Use this skill for capacity observations and safe input/data reconciliation. It complements neqsim-agentic-process-optimization (decision-space discovery and closed-loop objectives), neqsim-optimization-and-doe (optimizer algorithms), and neqsim-controllability-operability (operating envelopes and control performance). It does not replace equipment-specific engineering validation.

When to use this

• Find the enabled capacity constraint with highest utilization in a ProcessSystem or ProcessModel, and track its identity over a sweep or field-life timeline.
• Inspect the per-unit, per-constraint JSON snapshot including source and data-source metadata.
• Add or calibrate a hard, soft, design or empirical capacity constraint, or decide whether a fallback design value is credible enough for a decision.
• Compare process scenarios with KPIDashboard/ScenarioKPI and serialize equipment response DTOs for a reporting boundary.
• Apply validated single writes or transactional batches through ProcessAutomation.
• Fit a stream's produced gas rate, water rate, GOR or GVF to field/MPFM measurements; use Broyden only as an acceleration method inside a solver loop.

Use the existing optimizer skills for variable bounds, objective construction and optimizer selection. A high utilization number is a model observation, not by itself an approved operating limit.

Class map

Build pattern

This example builds one compressor flow path, establishes an explicit rated-power basis, runs it, reads the bottleneck snapshot, and changes outlet pressure through a validated write. A design value supplied in code is illustrative; replace it with installed/vendor evidence before using the resulting utilization as an engineering limit.

import neqsim.process.automation.ProcessAutomation;
import neqsim.process.automation.WriteValidationResult;
import neqsim.process.equipment.compressor.Compressor;
import neqsim.process.equipment.stream.Stream;
import neqsim.process.processmodel.ProcessSystem;
import neqsim.thermo.system.SystemInterface;
import neqsim.thermo.system.SystemSrkEos;

public class CapacitySnapshotExample {
  public static void main(String[] args) {
    SystemInterface fluid = new SystemSrkEos(298.15, 30.0);
    fluid.addComponent("methane", 0.85);
    fluid.addComponent("ethane", 0.10);
    fluid.addComponent("propane", 0.05);
    fluid.setMixingRule("classic");

    Stream feed = new Stream("feed", fluid);
    feed.setFlowRate(100000.0, "kg/hr");
    feed.setTemperature(25.0, "C");
    feed.setPressure(30.0, "bara");
    Compressor compressor = new Compressor("K-101", feed);
    compressor.setOutletPressure(60.0, "bara");
    compressor.getMechanicalDesign().setMaxDesignPower(500.0);

    ProcessSystem process = new ProcessSystem("compression");
    process.add(feed);
    process.add(compressor);
    process.run();
    System.out.println(process.getUtilizationSnapshotJson());
    System.out.println(process.findBottleneck().getConstraintName());

    ProcessAutomation automation = process.getAutomation();
    WriteValidationResult validation = automation.setVariableValueValidated(
        "K-101.outletPressure", 80.0, "bara");
    if (!validation.isAllowed()) {
      throw new IllegalArgumentException(validation.getMessage());
    }
    process.run();
  }
}

Equivalent Python class lookup:

from neqsim import jneqsim
import json

SystemSrkEos = jneqsim.thermo.system.SystemSrkEos
Stream = jneqsim.process.equipment.stream.Stream
Compressor = jneqsim.process.equipment.compressor.Compressor
ProcessSystem = jneqsim.process.processmodel.ProcessSystem

fluid = SystemSrkEos(298.15, 30.0)
fluid.addComponent("methane", 0.85)
fluid.addComponent("ethane", 0.10)
fluid.addComponent("propane", 0.05)
fluid.setMixingRule("classic")
feed = Stream("feed", fluid)
feed.setFlowRate(100000.0, "kg/hr")
feed.setTemperature(25.0, "C")
feed.setPressure(30.0, "bara")
compressor = Compressor("K-101", feed)
compressor.setOutletPressure(60.0, "bara")
compressor.getMechanicalDesign().setMaxDesignPower(500.0)
process = ProcessSystem("compression")
process.add(feed)
process.add(compressor)
process.run()
snapshot = json.loads(str(process.getUtilizationSnapshotJson()))
print(snapshot["bottleneck"], snapshot["anyHardLimitExceeded"])

automation = process.getAutomation()
validation = automation.setVariableValueValidated("K-101.outletPressure", 80.0, "bara")
if not validation.isAllowed():
    raise ValueError(str(validation.getMessage()))
process.run()

For multiple coordinated writes, prefer setValuesTransactional(updates, unit) over repeated setters. Supply a LinkedHashMap<String, Double> in Java to preserve request order; use null unit when addresses use different default units. Inspect isCommitted(), getRollbackCategory(), and every WriteOutcome. In Python, use the Java LinkedHashMap exposed through the Java bridge if batching, or make separate setVariableValueValidated calls followed by one run; do not confuse setValues(...) with a transaction.

To record bottleneck migration, after each converged model state call tracker.record(time, label, process.findBottleneck()). The time coordinate is caller-defined; the tracker does not advance the process or establish chronological order for you.

Result extraction

• CapacityConstraint.getUtilization() is a fraction: 1.0 means 100% of its design value; values above 1.0 exceed that design reference. Constraints can use maximum or minimum limits, so read getUnit(), getCurrentValue(), getDesignValue(), getMinValue()/getMaxValue(), getType(), getSeverity(), getSource(), getSourceReference() and getDataSource() together.
• BottleneckResult.getUtilization() is a fraction; getUtilizationPercent() is percent. getMargin() is remaining fraction (positive means headroom), and isExceeded()/isNearLimit() give explicit flags.
• ProcessSystem.getCapacityUtilizationSummary() maps equipment name to utilization percent. The snapshot JSON uses fractions in maxUtilization/constraint utilization, and percentages in corresponding *Percent fields; the result includes schemaVersion, units, bottleneck, anyOverloaded and anyHardLimitExceeded.
• ProcessModel snapshots add an area and use qualified bottleneck names where necessary. Tests confirm deterministic insertion order and distinguish equipment with duplicate names in separate areas.
• BottleneckTracker.Snapshot.getUtilizationPercent() is percent. getMigrationEvents(), getMigrationCount(), getPeakSnapshot() and toJson() summarize identity changes and peak loading. Time units remain caller-defined.
• CompressorResponse fields include pressure bara, temperature °C, power kW, massflow kg/hr, standard flow Sm3/hr, volume flow m3/hr, polytropic head/efficiency and speed. These are public data fields; serialize with your chosen JSON library after constructing a response.
• ScenarioKPI stores caller-supplied values with documented units (pressure bara, temperature °C, rates kg/hr, production loss kg, flare Nm3, CO2 kg, energy kWh, currency USD and time seconds). KPIDashboard.addScenario stores records; printDashboard prints rather than returning JSON.
• ProductionRateFitter.setGasRate(rate, unit) accepts standard-volume examples such as MSm3/day, Sm3/day, Sm3/hr or Sm3/sec. setWaterRate(rate, unit) accepts Sm3/day, Sm3/hr or Sm3/sec. Its output is the unit's outlet stream; it does not return a separate fit-result object.
• GORfitter.getGOR() reports GOR; its historical getGFV() spelling returns GVF. MPFMfitter exposes the same outputs and supports setReferenceFluidPackage; prefer its non-deprecated (String, StreamInterface) constructor.

Gotchas

• getUtilizationSnapshotJson() is side-effect-free and does not run the model. Run/converge first; the API reports stored/current constraint data, not a fresh simulation.
• Default equipment strategies may use incomplete/default design inputs. Inspect each limit's unit, enabled state, source, sourceReference, dataSource, confidence and validity range. A default/fallback is not vendor or installed capacity evidence.
• Utilization and summary scales differ: CapacityConstraint.getUtilization() and snapshot utilization are fractions; ProcessSystem.getCapacityUtilizationSummary() and BottleneckResult.getUtilizationPercent() are percentages. Avoid comparing them without conversion.
• A no-chart compressor has chart-dependent surge/speed constraints disabled; tests verify that power utilization can still be reported and becomes more loaded as flow rises. Do not interpret absence of a chart constraint as proof of surge margin.
• setValues(...) continues after bad addresses and can partially apply; it returns a successful-write count. setValuesTransactional(...) validates the full batch, applies, runs and rolls back on failure. Previously unreadable input values have no snapshot and are skipped during rollback.
• setVariableValueSafe is for address/bounds diagnostics; setVariableValueValidated invokes typed equipment checks. Neither should be mistaken for an engineering feasibility check or automatic process convergence.
• EmpiricalCarryOverConstraint treats units as labels: caller must align the driver, calibration x-values, carry-over y-values and limit. Values above the last x-point extrapolate linearly using the final segment; evidence must support that extrapolation.
• ProductionRateFitter matches gas rate by scaling total hydrocarbon flow and then adjusts water. If the feed has no water component, water matching is skipped; if no gas phase exists at standard conditions, gas-rate fitting is skipped. GORfitter/MPFMfitter retain total mass flow for their GOR/GVF adjustment; these are not equivalent reconciliation objectives.
• BroydenAccelerator returns direct fixed-point output during its initial delay iterations and does not test convergence itself. Handle damping, bounds, residual criteria and failure recovery in the owning solver.

Validation / benchmarks

• UtilizationSnapshotTest verifies schema version, unit records, process-area labels, duplicate-name qualification, deterministic JSON and chartless-compressor constraint behavior.
• CapacityConstraintMetadataTest verifies unset confidence/validity metadata, inclusive validity boundaries and that metadata does not alter utilization math. CapacityConstraintCurrentValueTest and CapacityConstraintMinimumLimitTest cover sampled values and minimum-bound constraints.
• BottleneckTrackerTest verifies empty results, migration identity, peak percent and JSON keys. Record snapshots only after the corresponding process state is converged.
• ProcessAutomationTransactionalTest verifies successful commits, validation rollback and stable JSON fields. WriteValidatorRegistryTest covers registry dispatch; AutomationDiagnosticsTest covers address/value diagnostics.
• Fit production measurements against independently reconciled plant data. Check gas standard conditions, reference conditions, phase presence and water basis before comparing rates; internal regression tests are not a field-data benchmark.
• When a capacity result drives an operating/design decision, supply a documented basis and compare the limiting condition with vendor, installed, empirical or otherwise approved data. A utilization snapshot is not a safety assessment.

Tie-in bottleneck study on an existing process model

When a satellite field is tied to a host that has a Python-driven process model and a datasheet utilization register:

• Feed the model plan rates by year, not the calibration day: split every manifold stream into oil, gas and water at standard conditions with the model EOS and scale the three parts to the plan rate of the field. Include every manifold of the field (a test-separator manifold carried 0.96 MSm3/d gas and was missed once). Check that the standard volumes of the feeds sum to the PDM facility rates before running years.
• Map the satellite fluid into the model pseudo-components (light ends by name, cuts by molar-mass interpolation, moles and mass conserved), check GOR and stock-tank density in the model EOS, and mix it into the intended header with an adiabatic mixer.
• Run annual-mean and p90-day rates (PDM p90 over mean is 1.17-1.21 for oil, gas and water on a North Sea host); annual means hide the exceedances.
• Keep surge and minimum-continuous-flow rows apart from capacity rows; they are turndown indicators.
• Fit linear responses per (unit, metric), never per unit: the binding metric of a vessel can switch (water to oil) when the feed changes. Verify with a run at twice the satellite rate. The multiplier at which a unit reaches 100 % gives the ullage.
• Units outside the model (produced water, water injection, flare) get a separate screen against demonstrated peaks and any STID design case, labelled as such.
• Budget the run time: low-flow years can take 15-60 minutes per case or not converge when swing compressors idle; run jobs as resumable parallel processes and write one result line per point.

Capacity-step value curve (what is a capacity step worth?)

Use when the question is "what is +x MSm3/d of handling capacity worth, and where do I stop?" (worked case: Grane LP gas 2.48 to 4.0 MSm3/d).

1. Unit ladder from the plant model. Add the new load in the shared currency (LP gas) at the capacity targets and record the utilisation of every unit; interpolate per unit and find the load where each reaches 100 %. Name the binding unit at each step.
2. Hard against soft units. Units already above 100 % at the demonstrated load (here a cooler at 120 %) have an unknown real rating: bind them at about 1.1 x today's utilisation, not at 100 %, and say so. Run the ladder with 100, 105 and 110 % allowed overload; the optimum capacity moves with this single number.
3. Cost ladder. Price each unit above its limit as a fixed part (ramped in over the first 5 % of overload, so a 1 % overload is a trim, not a new machine) plus a part per 20 % scale-up, capped at a replacement cost; add contingency and a lever-package route (lift-gas optimisation, suction pressure drop) and take the cheaper route per capacity.
4. Demand in the same currency. Express every user as oil times (GOR + lift GLR) so one capacity is shared; check intensities against the allocated measurements. A demand model that lets lift gas follow only water cut underestimates late-life load: test the alternative where lift gas per well stays at the planned rate (the company forecast) and put the choice in the Monte Carlo.
5. Sharing rule is a first-order lever. Hard allocation caps (BB 1.2, Svalin 0.7, rest to the host) throttle the user with the most oil per gas even with idle capacity; compare caps, revised caps and a pooled rule that fills by oil per unit of gas (order recomputed each year, never hard-coded). The pooled rule needs no CAPEX and was worth more than the first hardware steps; report equity effects separately.
6. Value = incremental after-tax oil of the capacity case against an explicit reference, with curtailed oil recovered later at a stated share, less CAPEX, fixed opex, extra shutdown days and the fuel/CO2 of the extra compression. Report the reference (demonstrated, design, target) and show the same step against each.
7. Report the value curve (mean, P10/P50/P90, P(NPV<0)), the marginal value per MSm3/d, the optimum, the value of flexibility (staging) and the extra enabled volume each step must win; a step whose break-even volume exceeds what the portfolio can supply is a no.

Traps seen: a TP/third-party owner reusing another owner's blown-up intensity; division of served gas by an intensity that is zero after the economic limit (guard with a floor); capacity labelled "after lever" while demand counts lift gas before the lever (add the lever credit explicitly and keep one convention); Centuries oil can be 14 % below allocated PDM rates and its RC1 tail 50 % above Sodir remaining reserves, so tie profiles to one stated source.

Equipment limit register (data-book limits per machine)

neqsim.process.equipment.capacity.EquipmentLimitRegister holds verified/assumed limits as entries {equipmentTag, quantity, value, unit, validFromYear/validToYear, source, status VERIFIED|ASSUMPTION, confidence}. load(path) / fromJson / save / toJson, lookup(tag, quantity, year), merge(other, overwrite), fromCompressorLimitsDatabase(json) (nested machines/facts layout), and applyTo(process, year) which writes the values into the matching CapacityConstraints (map quantity names with mapQuantityToConstraint) so they show up in the utilisation snapshot; the ApplyReport lists applied, unmatched and assumption-based limits. Keep ASSUMPTION entries visible in reports.

Shaft and platform-power variables are also addressable via ProcessAutomation (AutomationAddressable); see neqsim-rotating-equipment-design.

Related skills

• neqsim-capacity-increase-screening — turns the constraint map into ranked lever ideas (wells, subsea, topside), an idea register and a maturation pipeline.
• neqsim-agentic-process-optimization — adjustable process inputs, convergence gates, trial feasibility and objectives.
• neqsim-optimization-and-doe — optimizer families, DoE, sweeps, Pareto and uncertainty.
• neqsim-controllability-operability — operating envelopes, turndown and loop response.
• neqsim-process-modeling — process construction and converged process results.
• neqsim-model-calibration-and-data-reconciliation — measured data quality, calibration and residual analysis.
• neqsim-production-optimization — production surveillance, rate allocation and profile fitting.
• neqsim-operational-risk-and-safety-validation — safety-system scenario interpretation and review boundaries.
• neqsim-vfp-lift-curves — turns a binding capacity (compressor head limit, separator pressure) into a rate cap and full-system VFP curve.