pydae.core.diagnostics.dae_check

Numerical diagnostic tool for DAE solver failures.

Works with both dense and sparse Jacobians. When the solver is compiled with a sparse backend (KLU, PARDISO, Accelerate), the Jacobian flat array contains only the NNZ packed values — this module reconstructs the full dense matrix from the sparsity pattern before running the analysis.

Improvements over the original version

  • Sparse support via (Ap, Ai) reconstruction.

  • Zero-row / zero-column detection (equations or variables disconnected).

  • Diagonal dominance check (useful for implicit integrators).

  • Near-zero pivot detection along the diagonal.

  • Newton convergence estimate from residual + condition number.

  • Colour-coded terminal output (OK / WARNING / CRITICAL).

  • Heatmap saved to file instead of blocking on plt.show().

  • Summary verdict at the end with actionable next steps.

Functions

diagnose_dae_model(jac_flat, fg, Nx, Ny[, ...])

Perform a numerical health check on the DAE Jacobian and residuals.
pydae.core.diagnostics.dae_check.diagnose_dae_model(jac_flat, fg, Nx, Ny, x_names=None, y_names=None, sparse_backend=None, Ap=None, Ai=None, save_figure='jacobian_diagnostic.png')[source]

Perform a numerical health check on the DAE Jacobian and residuals.

Parameters:

  • jac_flat (ndarray) – Flat Jacobian array from the C solver. Dense: length N², Sparse: length NNZ.

  • fg (ndarray) – Residual vector [f; g], length N.

  • Nx (int) – Number of differential / algebraic variables.

  • Ny (int) – Number of differential / algebraic variables.

  • x_names (list of str, optional) – Human-readable variable names.

  • y_names (list of str, optional) – Human-readable variable names.

  • sparse_backend (str or None) – None for dense, or 'klu' / 'pardiso' / 'accelerate'.

  • Ap (array-like or None) – Sparsity structure arrays (required when sparse_backend is set).

  • Ai (array-like or None) – Sparsity structure arrays (required when sparse_backend is set).

  • save_figure (str or None) – Path to save the heatmap image. None to skip.