StressPy

Core numerical routines for the Geometric Stress Criterion (GSC).

stresspy decomposes a model--data discrepancy into a component aligned with the model's local parameter-accessible tangent space and a component normal to that space. It also reports numerical rank, singular values, the normal fraction, conditioning and a minimum-norm local repair vector.

StressPy is an early reference implementation. It performs the deterministic geometric calculation; it does not yet fit models, construct ODE Jacobians or perform bootstrap calibration.

Installation

pip install stresspy

Quick example

import numpy as np
from stresspy import decompose

observed = np.array([1.1, 1.9, 0.9])
predicted = np.array([1.0, 2.0, 1.0])
jacobian = np.array([
    [1.0, 0.0],
    [1.0, 1.0],
    [0.0, 1.0],
])
sigma = np.array([0.1, 0.1, 0.1])

result = decompose(
    observed=observed,
    predicted=predicted,
    jacobian=jacobian,
    sigma=sigma,
)

print("Tangent stress:", result.tangent_stress)
print("Normal stress:", result.normal_stress)
print("Normal fraction (%):", result.normal_fraction_pct)
print("Numerical rank:", result.rank)
print("Repair vector:", result.repair_vector)

The discrepancy convention is

[ r = y - f(\hat{\theta}). ]

With observation-space whitening matrix (L), StressPy forms (r_W=Lr) and (J_W=LJ). If (U_r) contains the retained left singular vectors of (J_W), then

[ r_{\parallel,W}=U_rU_r^\top r_W, \qquad r_{\perp,W}=r_W-r_{\parallel,W}. ]

The squared norms give total, tangent and normal stress. The minimum-norm local repair is calculated in the parameter coordinates represented by the supplied Jacobian. Consequently, repair magnitude is coordinate-dependent, and local tangent accessibility does not guarantee a practical finite nonlinear repair.

Principal functions

• decompose: single tangent--normal decomposition with optional uncertainty or covariance weighting.
• decompose_blocks: joint interrogation of multiple independent observation blocks sharing the same parameter coordinates.
• floor_sigma: explicit uncertainty-floor preprocessing.
• jacobian_to_log_coordinates: conversion of selected Jacobian columns to log-parameter coordinates.

decompose returns an immutable GSCResult containing the component vectors, stress measures, normal fraction, numerical-rank diagnostics and local repair.

Interpretation

Normal stress measures discrepancy outside the retained local Jacobian column space in the selected observation metric. It is a local geometric diagnostic, not by itself a calibrated hypothesis test. Conclusions can depend on the chosen weighting, parameter point and singular-value threshold.

Licence and commercial use

StressPy is available under the PolyForm Noncommercial License 1.0.0. It may be used, studied, modified and redistributed for permitted non-commercial purposes under those terms. Commercial use requires separate written permission from the copyright holder.

Citation

If StressPy contributes to academic work, please cite the software and the associated GSC publication when available. Citation metadata is provided in CITATION.cff.

Suggested software citation:

James, D. (2026). StressPy: Core numerical routines for the Geometric Stress Criterion (Version 0.0.3) [Computer software]. https://pypi.org/project/stresspy/