NPSS Component Zooming: Managing Trust Boundaries in Propulsion System Models

The Problem: When System-Level Models Need Component Fidelity

NPSS (Numerical Propulsion System Simulation) users face a recurring architectural decision: how to introduce detailed component physics into a system-level deck without breaking solver convergence or introducing silent data errors at model boundaries. The tool's zooming feature replaces a system-level component with a detailed sub-model while preserving the component's external connections. Used well, it lets teams defer detail until a requirement demands it. Used poorly, it produces plausible but physically wrong results because variable names, units, or boundary conditions drift between the system deck and the zoomed component.

Requirements That Drive Zooming

Start by identifying the specific system-level requirement that cannot be satisfied with a map-based or lumped-parameter component. Common triggers:

• Compressor or turbine off-design performance maps no longer cover the operating envelope (e.g., new flight condition, degraded hardware).
• Turbine cooling flows must be balanced against cycle performance, requiring internal flow-path resolution.
• Transient response requirements demand component inertia and thermal mass that lumped models omit.
• Hardware-in-the-loop (HIL) integration requires a component interface that matches a real controller's I/O.

If the requirement can be met by adjusting map tables or adding a correction factor, do not zoom. Each zoom boundary adds a trust boundary that must be audited.

Smallest Suitable Design: System Deck First, Zoom on Demand

Build the system deck with placeholder components that expose only the variables the system solver needs: mass flow, total pressure ratio, total temperature ratio, efficiency, and shaft speed. Use NPSS Element base classes (e.g., Compressor, Turbine) with map-based performance. Keep the deck monolithic until a requirement forces a zoom.

When zooming, replace the placeholder with a sub-model that implements the same external interface. The sub-model lives in a separate NPSS file (often called a neutral file) and is instantiated via the zoom command or by setting the component's modelFile attribute. The sub-model may contain multiple elements (stator, rotor, clearance, cooling circuit) but must expose exactly the same named input and output variables.

Trust and Data Boundaries: The Neutral File Contract

The neutral file is the contract between system and component. It defines:

• Variable names: Case-sensitive identifiers (e.g., W for mass flow, PRtot for total pressure ratio).
• Units: NPSS uses SI internally; the neutral file must declare units for each variable (kg/s, K, Pa, dimensionless).
• Direction: input (system → component) or output (component → system).

A minimal neutral file header for a zoomed compressor might declare:

// CompressorZoom.neutral
// Variables exchanged with system solver
input  double Nmech     "rpm"      // shaft speed
input  double W_in      "kg/s"     // inlet mass flow
input  double Pt_in     "Pa"       // inlet total pressure
input  double Tt_in     "K"        // inlet total temperature
output double PRtot     "-"        // total pressure ratio
output double TRtot     "-"        // total temperature ratio
output double eff       "-"        // isentropic efficiency
output double W_out     "kg/s"     // exit mass flow (may include bleed)

The system deck references this file. Any mismatch—missing variable, unit typo, direction flip—causes either a solver error or, worse, silent substitution of default values.

Operational Checks: Verifying the Boundary

After each zoom, run these checks before trusting system-level results:

1. Mass and energy balance across the zoom boundary. In the system deck, add a post-solve audit that sums W_in and W_out for each zoomed component and verifies abs(W_in - W_out - W_bleed) < 1e-6. For energy, verify W_in * Cp * Tt_in ≈ W_out * Cp * Tt_out + Q_cool within tolerance.
2. Neutral-file variable name and unit match. Write a small script (Python, MATLAB, or NPSS exec block) that parses the neutral file and the system deck's component instantiation, then compares variable lists. Flag any name not present in both, or any unit string that differs.
3. Monolithic equivalence test. Create a second deck where the zoomed component is inlined (all sub-elements placed directly in the system deck). Run the same design point and compare system-level outputs: net thrust, SFC, spool speeds, turbine inlet temperature. Differences > 0.1% indicate a boundary mismatch.

Failure Modes and How to Detect Them

Failure Mode	Symptom	Detection
Variable-name mismatch at interface	Solver converges but component receives default (often zero) for missing input	Neutral-file audit script; monolithic equivalence test
Unit inconsistency (e.g., rpm vs rad/s, Pa vs kPa)	Physically implausible pressure ratios or temperatures; solver may still converge	Unit audit; energy-balance check across boundary
Under-specified boundary conditions	Component converges to off-design point that satisfies local equations but violates system constraints	Off-design sweep: vary system inputs and verify component outputs move monotonically and physically
Convergence to non-physical root	Multiple mathematical solutions; solver picks one that violates second law or map limits	Add inequality constraints in sub-model (e.g., PRtot > 1.0, eff < 1.0); log iteration history

Conditions That Change the Design

Re-evaluate the zoom architecture when:

• Preliminary sizing → detailed component analysis: The number of zoomed components grows. Consider a component library with versioned neutral files and a CI check that runs the monolithic equivalence test on every commit.
• HIL or real-time constraints added: The zoomed component must execute within a fixed time step. This may require replacing iterative solvers with explicit approximations or pre-computed response surfaces, changing the neutral file contract (new outputs: computation time, convergence flag).
• Distributed execution: System and component run on separate processes or machines. The neutral file becomes a network interface (e.g., MPI, gRPC, FMI). Variable names and units must be frozen; add schema versioning.
• NPSS release upgrade: Syntax for neutral files, solver options, or element base classes may change. Run the full verification suite (monolithic equivalence, energy audit, unit check) after any upgrade before using results for decisions.

Practical Verification Workflow

For each zoomed component, maintain a verification directory with:

verification/
  monolithic_deck.npss      # inlined version
  zoomed_deck.npss          # system + neutral file
  neutral_file.neutral      # current contract
  audit.py                  # runs checks, exits non-zero on failure
  reference_outputs.csv     # baseline from last approved run

Run python audit.py as part of the model review gate. The script should:

1. Execute both decks at the design point.
2. Parse output files for key system variables.
3. Compare against reference_outputs.csv with relative tolerance 1e-3.
4. Run energy-balance audit across each zoom boundary.
5. Validate neutral file variable list against both decks.

If any check fails, the zoom is not release-quality.

Limitations and Scope

NPSS zooming manages thermodynamic and performance boundaries. It does not handle:

• CAD geometry exchange (use separate geometry kernel).
• CFD-level flow resolution (couple via boundary conditions, not zoom).
• Electronic control logic (model controllers as separate elements with discrete-time solvers).

Treat the neutral file as a versioned API. Document every variable, its unit, and its physical meaning. When in doubt, keep the component at system level and refine maps instead of zooming.