Runtime NPZ Output Contract¶
The shared driver writes one compressed .npz file per run through
linstabpy.driver.io.save_results. The archive is the handoff between long
computations, parity checks, plotting scripts, and campaign summaries, so key
names should be treated as a compatibility surface.
The checked contract lives in
linstabpy.driver.payload.RUNTIME_NPZ_CONTRACT_KEYS.
build_runtime_payload groups the keys before io.py writes them. Runtime
outputs may include extra arrays, but the checked keys should not be renamed
or removed without a migration note and an update to downstream readers.
Groups¶
Core spectra and resolvent:
omega,direct_modesgains,responses,forcingsresolvent_rho_fwd,resolvent_rho_adjomega_target,St,beta
Mesh, state, and weights:
X,Y,U,spongeW_diag,invW_diagfd_order,alpha_filter
Boundary-condition provenance:
bc_indices,bc_total_indicesbc_effective_dirichlet_indicesbc_column_zeroed_dirichlet_indicesbc_effective_neumann_indices,bc_overlap_indices
Stability solver metadata:
stability_eps_nev,stability_eps_ncv,stability_eps_nconvstability_eps_iterations,stability_eps_reason,stability_ksp_reasonstability_eps_conv_test,stability_eps_tol,stability_eps_max_itstability_true_residual,stability_reduce_dirichletstability_residual_estimates,stability_residual_absolutestability_residual_relative,stability_residual_backward
Stability postcheck and acceptance:
stability_postcheck_residual_absstability_postcheck_residual_relstability_postcheck_target_distancestability_all_omegastability_all_postcheck_relstability_all_target_distancestability_all_reject_reason_codestability_acceptance_postcheck_rel_maxstability_acceptance_target_distance_maxstability_acceptance_omega_real_abs_maxstability_acceptance_omega_imag_abs_maxstability_acceptance_conjugate_awarestability_accepted_countstability_accepted_indicesstability_rejected_indicesstability_missing_conjugate_partner_indicesstability_partner_rejected_indices
Numerical policy and provenance:
numerics_operator_dissipation_enablednumerics_operator_dissipation_epsilonnumerics_operator_dissipation_order_dissnumerics_operator_dissipation_apply_to_stabilitynumerics_operator_dissipation_apply_to_resolventsolver_eigen_st_solver_usedsolver_apply_to_resolvent_effectiveprovenance_config_hashprovenance_linstabpy_git_sharesolvent_sign_convention(physicalormatlab_parity; see resolvent sign convention; a file without this key was written with the old LinStab2D sign, that ismatlab_parity)
Cost keys are merged by save_results from collect_cost_metrics. They are
part of the contract even though the payload builder does not set them.
Rules For Changes¶
Additive keys are fine when a new diagnostic or provenance field is useful.
Renames and removals are not silent cleanup: update this document, update
RUNTIME_NPZ_CONTRACT_KEYS, update tests, and adjust every reader that consumes
the old name.