Architecting Custom Components in NPSS: Requirements, Design, and Verification

Requirements for a NPSS Custom Component

Before writing a new component, list the physical quantities the solver must exchange and the conditions under which the component operates.

Functional Requirements

• Define inlet total pressure, temperature, mass flow, and enthalpy.
• Compute outlet total pressure, temperature, mass flow, and enthalpy based on the chosen physics.
• Return a residual vector that the Newton‑Raphson solver can drive to zero.

Data‑Boundary Contract

NPSS expects each component to expose exactly the same set of flow variables at its inlet and outlet ports. The variable names must match those declared in the component’s interface file (.cpt) and the solver’s global variable map.

Smallest Suitable Design

Start with a component that only modifies a single thermodynamic property; this limits the chance of introducing coupling errors.

Subroutine Signature

SUBROUTINE MYBURNER(INLET, OUTLET, IERR)
  TYPE(NPSS_FLOW) :: INLET, OUTLET
  INTEGER :: IERR
END SUBROUTINE MYBURNER

The NPSS_FLOW derived type contains the standard fields: PT (total pressure), TT (total temperature), WF (mass flow), HT (specific enthalpy), plus any user‑added scalars.

Minimal Variable Set

1. Copy inlet values to outlet as a baseline.
2. Apply a simple pressure‑loss factor DP and a temperature rise DT:

OUTLET%PT = INLET%PT * (1.0 - DP)
OUTLET%TT = INLET%TT + DT
OUTLET%WF = INLET%WF   ! mass‑conserving
OUTLET%HT = HTFROMPTTT(OUTLET%PT, OUTLET%TT)  ! ideal‑gas enthalpy

Trust and Data Boundaries

The component is trusted only to respect the variable contract; any deviation (e.g., returning a different set of fields) will cause the solver to mis‑align residuals and typically abort with a “variable mismatch” error.

Operational Checks

Convergence Monitoring

Run NPSS with the iteration log enabled (-log iter.log). A healthy run shows the residual norm decreasing monotonically and falling below the solver tolerance (default 1e‑5).

Mass/Energy Balance Verification

After completion, inspect the summary block in iter.log or the restart file for reports of Mass imbalance and Energy imbalance. Acceptable limits are usually set by the user; a common threshold is <0.1 % of the inlet flow.

Failure Modes and Design Triggers

• If the pressure‑loss factor DP exceeds 1.0, the outlet pressure becomes non‑physical and the Newton‑Raphson step may diverge.
• Changing the solver tolerance (e.g., to 1e‑4) can mask convergence problems; always re‑run the verification suite after a tolerance change.
• Upgrading NPSS to a new major version may alter the default tolerance or the layout of NPSS_FLOW. Re‑compile the custom component against the new headers and repeat the convergence check.

Example: Adding a Simple Constant‑Pressure Burner

Assume a burner that raises temperature by 500 K while keeping pressure constant (DP = 0.0). The Fortran source (burner.f90) would contain:

SUBROUTINE BURNER(INLET, OUTLET, IERR)
  USE NPSS_TYPES
  TYPE(NPSS_FLOW) :: INLET, OUTLET
  INTEGER :: IERR
  REAL(KIND=8) :: DT
  DT = 500.0D0
  OUTLET%PT = INLET%PT
  OUTLET%TT = INLET%TT + DT
  OUTLET%WF = INLET%WF
  OUTLET%HT = HTFROMPTTT(OUTLET%PT, OUTLET%TT)
  IERR = 0
END SUBROUTINE BURNER

To make NPSS aware of the component:

1. Create an interface file burner.cpt that lists the same inlet/outlet variables.
2. Compile the subroutine: gfortran -c burner.f90 -o burner.o (requires read access to NPSS include directories).
3. Link it into the user library: npss_link burner.o -libuser (needs write permission in the NPSS library directory).
4. Reference the component in the deck file, e.g., BURNER: burner.

Run the simulation:

npss -i turbojet.dat -log iter.log

Check the log:

• Look for a line like Final residual norm = 3.2e-06 (below 1e‑5).
• Verify that the summary reports Mass imbalance = 0.0004 % and Energy imbalance = 0.0007 %, both under the 0.1 % limit.

If either check fails, examine the component for variable name typos or an excessive DT that drives the outlet temperature outside the ideal‑gas table range.

Limitations

The approach assumes quasi‑one‑dimensional flow and ideal‑gas thermodynamics. For high‑pressure‑ratio turbines or real‑gas effects, couple NPSS to a 3‑D CFD or chemistry solver via external interface, treating the NPSS component as a boundary condition provider.

Practical Verification

Run the NPSS verification suite (e.g., npss -v) before and after adding the custom component. Successful completion indicates that the global solver, data boundaries, and operational checks remain intact.