NPSS Cycle Deck Element Configuration for Missing Analytic Jacobian Boundary Conditions

Solver Substitution and Boundary Conditions

In NPSS, the solver defaults to numerical differentiation (finite-difference approximation) whenever an analytic partial derivative is omitted or returns a null/undefined entry in the element's derivative matrix. This substitution is triggered automatically at the point of Jacobian assembly during the Newton-Raphson iteration process.

Likely Implementation Behavior

While the exact perturbation logic is implementation-defined, the following behaviors are typical for NPSS custom elements:

• Trigger: The solver identifies a missing entry in the analytic Jacobian for a specific variable pair and initiates a perturbation of the independent variable to estimate the slope.
• Convergence Risk: Because numerical differentiation is sensitive to the step size, implicit constraints lacking analytic derivatives may cause solver oscillation or divergence if the function is non-smooth or if the variable scales differ by several orders of magnitude.
• Performance Impact: Relying on numerical fallbacks significantly increases the number of function evaluations per iteration, which can be observed as a slowdown in convergence speed compared to fully analytic elements.

Variable Scoping in Multi-Instance Elements

NPSS manages variable scoping through a hierarchical encapsulation model. When a custom element is instantiated multiple times within a single cycle deck, locally declared solver variables are mapped to unique internal identifiers.

Interaction Rules:

• Local Isolation: Variables declared within the element's local scope are isolated to that specific instance. This prevents "cross-talk" where the state of one instance inadvertently modifies another.
• Outer-Scope Interaction: Local variables only interact with outer-scope names if they are explicitly mapped to cycle-level variables or passed as arguments. If a local variable shares a name with an outer-scope variable, the local definition typically takes precedence within the element's execution context.

Discovering Perturbation Defaults

Internal perturbation step sizes and policies are generally not exposed as configurable parameters in the standard cycle-deck interface. However, you can infer their impact through the following verification steps:

1. Verbose Solver Logs: Enable verbose convergence reporting. While the step size itself may not be printed, a spike in the number of function evaluations per iteration indicates the solver is relying on numerical differentiation.
2. Convergence Comparison: Compare the iteration count of a simplified version of your element (with analytic derivatives) against the version using numerical fallbacks.
3. Isolation Test: Instantiate the same custom element twice with divergent input values. If the output variables of Instance A change based on the inputs of Instance B, there is a scoping leak.

Missing Diagnostic Detail: To provide a more specific recommendation on convergence stability, please specify if the implicit constraints are linear or highly non-linear (e.g., involving transcendental functions).