napix-stability 1.0.0

Professional SDK for structural collapse detection in DAE systems

NAPIX Stability Engine

A professional SDK for detecting structural collapse in Differential-Algebraic Equation (DAE) systems before failure occurs.

Quick Start

from napix_stability import StabilityEngine, StabilityResult

engine = StabilityEngine(w1=0.4, w2=0.35, w3=0.25)

system = {
    "equations": ["x1 - x2 + sin(t)", "x1 + x2 - cos(t)"],
    "constraints": ["x1**2 + x2**2 - 1"],
    "variables": ["x1", "x2"]
}

data = {"x1": 0.8, "x2": 0.6}

result = engine.analyze(system, data)
print(f"Risk Score: {result.risk_score:.1f}")
print(f"State: {result.state}")
print(f"Time to Failure: {result.time_to_failure} min")

Features

• Constraint Sensitivity Analysis — Detect Implicit Function Theorem breakdown
• Reduced Jacobian Spectral Radius — Identify eigenvalue blow-up
• Pencil Condition Number — Quantify algebraic loop ill-conditioning
• Unified Risk Score (0–100) — Single actionable metric
• State Classification — STABLE / PRE-COLLAPSE / IMMINENT_SHOCK
• Time-to-Failure Estimation — Trend-based extrapolation

Installation

pip install napix-stability

Optional GPU acceleration:

pip install napix-stability[gpu]

API Reference

StabilityEngine(w1=0.4, w2=0.35, w3=0.25)

Parameter	Description
w1	Weight for constraint sensitivity (default 0.4)
w2	Weight for spectral radius (default 0.35)
w3	Weight for pencil condition (default 0.25)

engine.analyze(system_definition, live_data) → StabilityResult

StabilityResult fields:

Field	Type	Description
sigma_g	float	Constraint sensitivity
lambda_max	float	Spectral radius of reduced Jacobian
kappa_p	float	Pencil condition number
risk_score	float	Unified collapse score (0–100)
state	str	Classification
dominant_mode	str	Driving instability mode
time_to_failure	float or None	Estimated minutes until collapse

Use Cases

• Aviation — Detect flight control surface jamming via actuator DAE models
• Energy — Monitor power grid voltage collapse boundaries
• Finance — Identify systemic risk in coupled asset-liability models
• Healthcare — Predict hemodynamic decompensation in critical care

License

MIT