Neqsim Troubleshooting

NeqSim Troubleshooting Playbook

Ranked recovery strategies for common failure modes. Try steps in order — stop when the issue is resolved.

Flash Non-Convergence

Symptom: TPflash() or other flash throws exception or returns wrong phase count.

NaN / Zero Enthalpy After Clone + Re-Flash

Symptom: A reservoir/well stream flashes fine at source, but after passing through WellFlow, PipeBeggsAndBrills, or an isenthalpic choke (or after clone() + re-flash) it returns NaN enthalpy — often surfacing as NaN compressor power or a non-finite separator duty downstream.

Dynamic-depletion caveat: SimpleReservoir.runTransient() rewrites each producer stream's fluid in place (via setMolarComposition / setPressure) with the depleted, recombination-corrected reservoir fluid. If a downstream topside ProcessModel is re-run after a reservoir transient step, those overwritten producer fluids can reintroduce NaN enthalpy through the inlet choke. For lifetime studies, prefer holding a rigorous steady facility snapshot at plateau for equipment loading and using an analytical plateau+decline production profile for lifetime volumes/economics, rather than re-running the topside off each transient depletion step.

Recycle Non-Convergence

Symptom: process.run() completes but recycle did not converge, or throws after max iterations.

Adjuster Non-Convergence

Symptom: Adjuster fails to find the target value.

Zero or NaN Property Values

Symptom: getDensity(), getViscosity(), or getThermalConductivity() returns 0.0 or NaN.

Wrong JT / Isenthalpic Expansion Temperature

Symptom: Manual PHflash() on a cloned fluid gives wrong temperature after pressure reduction (Joule-Thomson expansion). Tested: 14.9°C error vs 1.7°C with correct method.

Correct pattern (Python):

proc = ProcessSystem()
feed = Stream('SG', fluid.clone())
feed.setFlowRate(flow, 'kg/hr')
feed.setTemperature(T, 'C')
feed.setPressure(P_in, 'bara')
proc.add(feed)
valve = ThrottlingValve('JT', feed)
valve.setOutletPressure(P_out)
proc.add(valve)
proc.run()
T_jt = float(valve.getOutletStream().getTemperature('C'))  # Correct JT temperature

Phase Identification Issues

Symptom: Phase labeled "gas" but behavior is liquid-like, or vice versa.

Silent g/mol TBP unit error

addTBPfraction(name, moles, molarMass, density) and addPlusFraction(...) expect molar mass in kg/mol. Passing g/mol throws no exception — the characterization silently produces nonsense pseudo-component properties and the flash collapses to one phase.

Diagnostic tell: TPflash() at standard conditions (15 °C, 1.01325 bara) returns getNumberOfPhases() == 1 with getType() == GAS but a density of 700–800 kg/m3. A gas at 1 atm cannot exceed a few kg/m3, so a "gas" phase with liquid density means the pseudo-components are broken, not that the fluid is single-phase.

Confirm by printing the pseudo-component properties — the broken case shows molarMass ~1000x too large, Tc in the thousands of K, and acentricFactor pinned at -0.99:

for (int i = 0; i < fluid.getNumberOfComponents(); i++) {
  ComponentInterface c = fluid.getComponent(i);
  logger.info("{} MW={} g/mol Tc={} K Pc={} bara omega={}", c.getName(),
      c.getMolarMass() * 1000.0, c.getTC(), c.getPC(), c.getAcentricFactor());
}

Fix: divide by 1000 at the call site — fluid.addTBPfraction("C10-C12", 0.054, 150.0 / 1000.0, 0.790);

Pipe Outlet Temperature Equals Ambient

Symptom: A PipeBeggsAndBrills tubing string or flowline always arrives at the ambient / formation temperature, no matter the length, rate or insulation. Hydrate margins, cooldown times and arrival temperatures all look pessimistic and insensitive.

CO2 Injection Well Issues

Symptom: CO2 wellbore model gives unexpected phase splits or impurity enrichment.

Distillation Column Non-Convergence

Symptom: Column solver fails after max iterations or produces unreasonable results.

Column runs hundreds of iterations / dominates ProcessModel runtime

Symptom: one column takes tens of seconds per solve and the outer ProcessModel loop never finishes, even though setMaxNumberOfIterations(10) was called.

Column reports solved() == true but the answer is wrong

Symptom: solved() is true, the residuals printed by getConvergenceDiagnostics() look clean, but the product split, reboiler duty or tray profile disagrees with every other solver (vapour traffic collapsing mid-column is a giveaway).

NAPHTALI_SANDHOLM reports Double.NaN as its temperature residual because it has no successive-substitution sweep. That is intentional: for that solver the MESH residual vector is the convergence measure, and solved() requires the MESH gate to be active instead.

ProcessModel Boundary Convergence

Symptom: getConvergenceSummary() reports a relative error but not where it comes from — most confusingly Flow rate: 1.00e+00.

Symptom: a stagnant dead leg dominates the convergence gate

getConvergenceSummary() reports e.g. Flow rate: 6.56e-02 (gas export ht) and the model never converges, while the real residual sits on a large stream. The gate is a max over relative errors, so 0.007 kg/hr of wobble on a 0.1 kg/hr branch beats a genuine 443 kg/hr residual on a 138 t/hr export stream (3.2e-03).

// 1. Do not solve the stagnant section at all (units auto-bypass).
//    Manifold, ThrottlingValve, PipeBeggsAndBrills and MultiStreamHeatExchanger
//    honour this too, and still publish their outlet pressure at zero flow.
plant.get("HT injection process A").setSectionLowFlowThreshold(50.0, "kg/hr");

// 2. Keep the dead leg out of the plant convergence metric.
plant.setBoundaryFlowFloor(1.0);                      // drop sub-1 kg/hr streams

// 3. Converge on relative OR absolute flow change.
boolean ok = plant.runUntilConverged(15, 1e-3, 1.0);  // rel 1e-3 OR abs 1 kg/hr

Both filters also apply to getNonConvergedBoundaryStreamErrors(), so the offender list stops being dominated by noise. getConvergenceSummary() prints the absolute Δflow next to each relative error and a Flow filters: line when a filter is active.

Prefer the self-configuring form. plant.runUntilConverged(maxIterations) derives all three filters from the plant's own feed rate, so the hand-picked 1.0 / 1.0 / 50 kg/hr numbers above are only needed when you must override it. See "Model grinds toward the last decade of the residual" below.

Model grinds toward the last decade of the residual

Symptom: converged=False after the iteration cap, but the residual is small — e.g. Flow rate: 3.19e-03 against a 1e-3 gate, which is 434 kg/hr on a 136 t/hr stream. That is slow convergence, not a limit cycle, and it is usually the gate being tighter than the model is worth.

// Self-configuring: no tolerance, no noise filters, no per-plant numbers.
boolean ok = plant.runUntilConverged(60);
System.out.println(plant.getAutoTuningSummary());     // flow-noise filters chosen
System.out.println(plant.getAutoToleranceSummary());  // accuracy chosen/accepted

Gotcha: any explicit setTolerance() / setFlowTolerance() / runUntilConverged(n, tol) marks the tolerance as user-owned and disables both the engineering default and the stall acceptance. If you set 1e-3 "to be helpful" you also switch off the feature that would have accepted a stalled 1.4e-3.

Gotcha: setSectionLowFlowThreshold() deactivates units for the remainder of the solve pass. Do not set it on a section that is legitimately dry only on the first recycle iteration (e.g. a JT valve on a separator liquid outlet) — it will never recover within that pass.

"Converged: YES" but a unit is out of mass balance

The plant gate says every boundary stream is inside tolerance, yet checkMassBalance() flags a downstream unit by ~1 %. The two disagree because the link between the areas is invisible to boundary detection, not because the tolerance is too loose.

ProcessModel discovers boundary streams through getInletStreams() / getOutletStreams(). Equipment that stores its streams in its own private lists and does not override those two methods falls back to the inherited two-port inStream/outStream — often never assigned — and so reports no connections. Such a link is dropped from both the convergence gate and the incremental dirty-area propagation, so the consumer never gets re-run.

Diagnosis — do not start by loosening tolerances:

1. List the units that fail mass balance and trace what feeds them.
2. If only the units fed by one equipment type are unbalanced while every other unit is exactly 0.0000 %, suspect missing stream introspection on that type.
3. Confirm with unit.getInletStreams().size() / getOutletStreams().size() — a multi-port unit reporting 0 or 1 is the bug.

// Any multi-port equipment MUST expose all ports, or it is invisible to
// topology walks, DEXPI export, ProcessConnection and boundary detection.
List<StreamInterface> in = heatEx.getInletStreams();   // expect all feeds
List<StreamInterface> out = heatEx.getOutletStreams(); // expect all products

Fixed for MultiStreamHeatExchanger in PR #2712; the two-stream HeatExchanger always overrode both. Apply the same override when adding new multi-port equipment.

Process Equipment Errors

Compressor: Negative or Unreasonable Power

Separator: No Phase Split

Heat Exchanger: Zero Duty

Serialization / Copy Errors

Symptom: equipment.copy() or ProcessSystem.copy() throws NotSerializableException.

Performance Issues

Symptom: Simulation runs very slowly.

Common Exception Messages

Phase Envelope Branch Labels Swapped

Load neqsim-phase-envelope for the canonical structured segment API, physical dew/bubble classification, numerical-zero component behavior, and solver-change test protocol. Use this section for symptom-driven recovery after following that workflow.

Symptom: When plotting a phase envelope calculated with calcPTphaseEnvelope(true, 1.0), the bubble and dew curves appear swapped — the "bubble" array has higher temperatures (cricondentherm) which is physically the dew side, and vice versa.

Cause: The Michelsen continuation algorithm always starts with isDewPhase=true regardless of the bubblePointFirst flag. When tracing from the bubble side first, initial points go into the dew list. At the critical point the flag flips, so actual dew-side data ends up in the bubble list.

Fix: Classify branches by physical reasoning, NOT by method names:

# The DEW curve always contains the cricondentherm (maximum temperature)
if np.array(envelope.getBubblePointTemperatures()).max() > np.array(envelope.getDewPointTemperatures()).max():
    dew_T = np.array(envelope.getBubblePointTemperatures())  # swapped!
    bub_T = np.array(envelope.getDewPointTemperatures())     # swapped!
else:
    dew_T = np.array(envelope.getDewPointTemperatures())
    bub_T = np.array(envelope.getBubblePointTemperatures())

When All Else Fails

1. Simplify radically — reduce to 2-3 components, remove equipment, test one unit at a time
2. Check a known-good case — run an existing test (e.g., SeparatorTest) to verify NeqSim works
3. Compare with standalone flash — take the inlet fluid, run TPflash manually, check phases
4. Search existing tests — grep_search for similar equipment/components in src/test/java/neqsim/
5. Report the issue — if it's a genuine NeqSim bug, file a GitHub issue with minimal reproducer