Metadata-Version: 2.4
Name: metastablex
Version: 0.1.1
Summary: Metastable dynamics detection for complex systems
Author: Lucas Amaral Dourado
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: torch

<h1 align="center">🧠 MetastableX</h1>
<h3 align="center">A Unified Computational Framework for Metastability and Critical Transitions in Complex Systems</h3>

<p align="center">
Bridging statistical physics, machine learning and epidemiology to detect systemic instability in real-world dynamics.
</p>

<p align="center">
⚙️ PyTorch • 📊 Time-Series • 🧠 Complex Systems • 🏥 Public Health • 🌍 Open Science
</p>

---

# 📌 Abstract

Complex systems—from biological organisms to healthcare infrastructures—operate near the **edge of stability**, where small perturbations can trigger large-scale transitions.

We introduce **MetastableX**, a computational framework for detecting:

- metastable regimes  
- early warning signals  
- critical transitions  

using **time-series analysis, statistical physics, and machine learning**.

The framework combines:

- stochastic dynamical systems modeling  
- information-theoretic metrics  
- learned representations via neural networks  

and is validated on **real-world epidemiological data from SIH/SUS (Brazil)**.

We show that healthcare systems exhibit signatures consistent with **marginal criticality**, enabling early detection of systemic stress and potential collapse.

---

# 🧠 1. Introduction

Many natural and social systems exhibit **nonlinear dynamics** characterized by abrupt transitions.

Examples include:

- cardiac arrhythmias  
- ecosystem collapse  
- financial crises  
- hospital overload  

Traditional statistical approaches fail to capture these transitions because they rely on:

- averages  
- linear correlations  

Instead, such systems require a **structural and dynamical analysis framework**.

---

# ⚙️ 2. Theoretical Framework

## 2.1 Stochastic Dynamics

We model the system as:

$$
\frac{dx}{dt} = f(x) + \sigma \eta(t)
$$

where:

- $x(t)$ is the system state  
- $f(x)$ encodes deterministic dynamics  
- $\eta(t)$ is stochastic noise  

---

## 2.2 Potential Landscape

The system can be represented through an effective potential:

$$
U(x) = -\frac{\sigma^2}{2}\log P(x)
$$

Interpretation:

| Regime | Landscape |
|------|-----------|
Stable | deep wells |
Metastable | shallow wells |
Critical | flattened |

---

## 2.3 Criticality Condition

We hypothesize that complex systems operate near:

$$
\lambda \approx 0
$$

where $\lambda$ is the **Lyapunov exponent**, defining the boundary between:

- order ($\lambda < 0$)  
- chaos ($\lambda > 0$)  

---

## 2.4 Information-Theoretic Principle

We define an informational optimality condition:

$$
\max (H + F)
$$

where:

- $H$ = Shannon entropy  
- $F$ = Fisher information  

This condition corresponds to **maximum structural adaptability**.

---

# ⚠️ 3. Early Warning Signals

## Variance

$$
\sigma^2 = \frac{1}{N}\sum (x_i - \mu)^2
$$

## Autocorrelation

$$
AC_1 =
\frac{
\sum (x_t-\mu)(x_{t-1}-mu)
}{
\sum (x_t-\mu)^2
}
$$

### Interpretation

| Signal | Meaning |
|------|--------|
↑ Variance | instability |
↑ Autocorrelation | critical slowing down |

---

# 🧬 4. Information Geometry

## Entropy

$$
H = -\sum p_i \log p_i
$$

## Fisher Information

$$
F = \int \frac{(\nabla p)^2}{p} dx
$$

Together, they define a **statistical manifold** where:

- entropy → exploration  
- Fisher → curvature  

---

# 🤖 5. Machine Learning Formulation

MetastableX extends classical physics with a learned representation:

```python
features = metastable_features(x)
y_pred = model(features)
```

The model learns:

- latent regime transitions  
- nonlinear instability patterns  
- hidden structural signals  

---

# 🏥 6. Application to Health Systems

Healthcare systems behave as **complex adaptive systems**.

We model hospitalization dynamics using:

- SIH/SUS data  
- municipal time series  
- population-normalized rates  

---

## 6.1 Data Source

**SIH/SUS — Brazilian Hospital Information System**

Each record corresponds to a hospitalization (AIH).

---

## 6.2 Rate Definition

$$
Rate =
\frac{\text{Hospitalizations}}{\text{Population}} \times 10^4
$$

---

## 6.3 Structural Monitoring

For each municipality we compute:

- variance  
- autocorrelation  
- entropy  
- metastable score  

---

# 📊 7. Results

Empirical analysis shows that:

- hospital systems exhibit **metastable regimes**  
- transitions are preceded by **early warning signals**  
- critical phases correspond to **system overload risk**  

---

# 🧠 8. Interpretation

We interpret healthcare systems as operating near:

> **marginal criticality**

This enables:

- adaptability  
- responsiveness  
- but also vulnerability to collapse  

---

# 🌍 9. Implications

MetastableX enables:

- early detection of hospital stress  
- structural monitoring of public health systems  
- real-time systemic risk assessment  

---

# ⚙️ 10. Implementation

## Installation

```bash
pip install metastablex
```

## Usage

```python
from metastablex import MetastableModel

model = MetastableModel()
model.fit(series)

score = model.predict(series)
```

---

# 📊 11. Dashboard

The framework includes an interactive dashboard for:

- time-series visualization  
- regime classification  
- risk ranking  

---

# 🧱 12. Architecture

```text
metastablex/
├── ml/
├── physics/
├── regimes/
├── model.py
```

---

# 🔬 13. Scientific Contributions

This work contributes:

- a unified framework for metastability detection  
- integration of physics + ML + epidemiology  
- empirical validation on large-scale health data  

---

# 🚀 14. Future Work

- multiscale modeling  
- spatial epidemiology  
- digital twin of health systems  
- real-time surveillance  

---

# 👨‍🔬 Author

**Lucas Amaral Dourado**

- Medical Student — Federal University of Tocantins  
- Biomedical Engineering Student — UNINTER  

---

# 📜 License

MIT License

---

<p align="center">
MetastableX — Toward a physics of complex adaptive systems
</p>
