NPSS Solver Convergence Diagnostics Guide

A diagnostic guide for NPSS Newton-Raphson solver failures in thermodynamic cycle models, with a cause table, ordered checks, fixes tied to findings, and escalation criteria for steady-state and transient simulations.

The recognizable failure

In NPSS steady-state runs the most common failure is "Solver failed to converge" with residual norm stagnating above 1e-3 after 50+ iterations. The Newton-Raphson solver with line search is used for steady-state convergence. When it stalls, the model is usually solvable but the initial guess, connections, or gas properties are outside the solver's basin of attraction.

A practical engineering decision that prevents most of these failures is to run a cold start convergence test at 10% power before any envelope sweep. This catches guess-related failures early and allows guess propagation via saveCase()/loadCase() or the parametric study feature.

Failure modes and diagnostic table

Observed symptom	Likely cause	Typical signature
Residual norm > 1e-2 after 10 iterations	Initial guess far from solution	Spool RPM or T4 far from design
Residual oscillates up and down	Line search damping too aggressive or element Jacobian singular	No monotonic decrease
Residual drops then rises	Thermodynamic property table extrapolation	Gas properties outside valid T/P range
"Pivot element zero" error	Disconnected shaft or missing flow path	Singular Jacobian

NPSS diagnostics are terse. "Pivot element zero" often masks a missing connection, and gas table extrapolation can fail silently with rising residuals and no explicit error.

Ordered checks

Verify physically plausible initial guesses. Run in NPSS Script Editor or via Java API with model read access. Check spool RPM within ±20% of design and burner exit temperature T4 within ±50 K of expected. Risk: unrealistic guesses cause immediate divergence.
Enable solver trace. setSolverTraceLevel(2) writes per-variable residuals. Inspect residual history for the variable that stalls. This is diagnostic only, no model change.
Check model integrity. Run checkModel() on the open model. It reports unconnected ports and singular Jacobian risks. Required permission: model read. A clean checkModel() is a prerequisite before escalation.
Validate gas property tables. Compare getGasTableMinMax() bounds against expected operating envelope from cycle analysis. Validate tables cover at least 1.5x expected T/P range. Extrapolation causes non-smooth derivatives.
Assess line search behavior. If oscillations persist, reduce line search damping factor with setLineSearchDamping(0.5). In NPSS 2.4+ the line search changed from cubic to quadratic interpolation, affecting damping behavior.

Fixes tied to findings

Initial guess far from solution

Use design-point results as initial guess via saveCase() and loadCase(). For NPSS 2.4+ use estimateInitialGuess() on standard elements compressor, turbine, burner to automate generation. In 2.3 and earlier this must be scripted manually. For envelope sweeps, propagate guesses with the parametric study feature.

Oscillating residual

Increase maxIterations to 100 and relax damping. Test custom elements in isolation first, as user-defined Jacobians can introduce non-smooth derivatives.

Residual rise after initial drop

Extend gas tables or switch to NASA Glenn coefficient polynomials. Ensure Tmin/Tmax and Pmin/Pmax cover the operating point.

Pivot element zero

Add missing shaft elements or connect bleed ports. Re-run checkModel() until no unconnected ports remain.

Transient runs

Transient convergence criteria differ from steady-state. Use setTransientTolerance(1e-4) not setSteadyTolerance(). Reduce time step dt < 0.01 s and enable adaptive stepping.

Version-sensitive behavior

NPSS 2.4+ introduced automatic initial guess generation for standard elements via estimateInitialGuess(). The line search algorithm changed in 2.4 from cubic to quadratic interpolation. Known solver bugs exist in NPSS 2.3.0–2.3.2 for models with >500 elements. Parallel solver MPI introduced in NPSS 2.5 changes convergence characteristics; single-threaded diagnostics may not apply.

Escalation criteria

If convergence fails after the checks above with a clean model where checkModel() passes, escalate to NPSS support with:

solver trace log from setSolverTraceLevel(2)
.npss model file
gas table files
exact NPSS version from Help → About

Upgrade to 2.4+ before escalation if on 2.3.0–2.3.2.

How to verify the fix

Practical verification steps:

Run the built-in tutorial turbofan.npss and intentionally corrupt initial guesses to reproduce each failure mode.
After changes, confirm checkModel() reports no unconnected ports.
Confirm residual norm falls below steady-state tolerance, typically 1e-6, and iteration count is stable across nearby operating points.
Compare gas table bounds via getGasTableMinMax() against expected envelope.

Limitations: custom elements with user-defined Jacobians may still diverge despite clean diagnostics. Always test elements in isolation first.

NPSS Newton-Raphson Solver Convergence Diagnostics for Thermodynamic Cycle Models