Metadata-Version: 2.4
Name: napix-stability
Version: 1.1.1
Summary: Community Edition: SDK for structural collapse detection in DAE systems (limited to 5 variables, rate-limited)
Project-URL: Homepage, https://napix.ai
Project-URL: Documentation, https://napix.ai/docs
Project-URL: Repository, https://github.com/napix/napix-stability
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: full
Requires-Dist: jax>=0.4.0; extra == 'full'
Requires-Dist: jaxlib>=0.4.0; extra == 'full'
Provides-Extra: gpu
Requires-Dist: cupy>=12.0; extra == 'gpu'
Description-Content-Type: text/markdown

[![PyPI](https://img.shields.io/pypi/v/napix-stability)](https://pypi.org/project/napix-stability/)
[![Python](https://img.shields.io/pypi/pyversions/napix-stability)](https://pypi.org/project/napix-stability/)
[![License](https://img.shields.io/pypi/l/napix-stability)](https://github.com/napix/napix-stability/blob/main/LICENSE)

# NAPIX Stability Engine

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

## Quick Start

```python
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

```bash
pip install napix-stability
```

Optional GPU acceleration:

```bash
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
