Metadata-Version: 2.4
Name: rlds-mat
Version: 1.1.0
Summary: Mathematical core SDK for Regime-Limited Dynamical Systems (RLDS): analysis of one-dimensional autonomous ODEs with singular restoring force.
Author-email: Aleksander Kubanski <aleksander@kubanski.pro>
Maintainer-email: Aleksander Kubanski <aleksander@kubanski.pro>
License-Expression: MIT
Project-URL: Homepage, https://research.kubanski.pro
Project-URL: Repository, https://github.com/AKubanski/rlds-mat
Project-URL: Issue Tracker, https://github.com/AKubanski/rlds-mat/issues
Project-URL: Changelog, https://github.com/AKubanski/rlds-mat/blob/main/CHANGELOG.md
Project-URL: Paper I (RLDS I), https://doi.org/10.5281/zenodo.19627496
Project-URL: Paper II (RLDS II), https://doi.org/10.5281/zenodo.19628881
Keywords: dynamical systems,differential equations,stability analysis,equilibrium,attractor,RLDS,regime-limited,singular ODE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.6
Requires-Dist: reportlab>=3.6
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: full
Requires-Dist: pyyaml>=6.0; extra == "full"
Requires-Dist: toml>=0.10; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# rlds-mat

**Regime-Limited Dynamical Systems — Mathematical Core**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
[![CI](https://github.com/AKubanski/rlds-mat/actions/workflows/ci.yml/badge.svg)](https://github.com/AKubanski/rlds-mat/actions/workflows/ci.yml)

A Python library for analyzing one-dimensional autonomous ordinary differential
equations within the **Regime-Limited Dynamical Systems (RLDS)** framework.

`rlds-mat` is the mathematical core of a broader research SDK family. It
implements the existence, uniqueness, global stability, and reduction-criteria
machinery developed in the RLDS theory papers.

## Theory references

This library implements the methods from:

1. Kubanski, A. (2026). *RLDS I: On a Global Attractor for a Class of
   One-Dimensional Autonomous Systems with Singular Restoring Force.*
   Zenodo. [doi:10.5281/zenodo.19627496](https://doi.org/10.5281/zenodo.19627496)
2. Kubanski, A. (2026). *RLDS II: Regime-Limited Dynamical Systems — Theory and
   Reduction Criteria for Singular ODEs.* Zenodo.
   [doi:10.5281/zenodo.19628881](https://doi.org/10.5281/zenodo.19628881)

The canonical mathematical-methodological reference is **Paper II**.

## Features

- **Classification**: Verify whether a one-dimensional autonomous ODE belongs
  to the RLDS class (reduction criteria C1–C4).
- **Threshold analysis**: Compute the critical, boundary, and admissible
  thresholds (κc, κ_bdy, κ_adm).
- **Equilibrium analysis**: Locate equilibria and classify their stability.
- **Visualization**: H(x) curves, phase portraits, trajectory simulations.
- **Reports**: Generate publication-style PDF analysis reports.
- **Multiple formats**: Load system definitions from JSON, YAML, or Python.

## Installation

```bash
pip install rlds-mat

# With YAML support
pip install rlds-mat[yaml]

# Full optional dependencies
pip install rlds-mat[full]

# Development install
pip install -e .[dev]
```

## Quick start

### From Python

```python
import rlds_mat

# Define a system
params = rlds_mat.RLDSParameters(
    alpha=3.0,
    beta=0.16,
    xc=0.52,
    phi=rlds_mat.phi.regularized(),
    w=rlds_mat.w.sigmoid(delta=0.08),
)

# Analyze
report = rlds_mat.analyze(params)
print(report.summary())

# Generate a PDF report
rlds_mat.generate_report(params, "my_report.pdf")

# Plot
rlds_mat.plot(params)
```

### From file

```python
import rlds_mat

# Load from JSON, YAML, or Python
params = rlds_mat.load("my_system.json")

# Analyze
report = rlds_mat.analyze(params)
```

### JSON format

```json
{
    "name": "My System",
    "alpha": 3.0,
    "beta": 0.16,
    "xc": 0.52,
    "phi": {"type": "regularized", "eps": 1e-6},
    "w":   {"type": "sigmoid",     "delta": 0.08}
}
```

### YAML format

```yaml
name: "My System"
alpha: 3.0
beta:  0.16
xc:    0.52
phi:
  type: regularized
  eps:  1.0e-6
w:
  type:  sigmoid
  delta: 0.08
```

## Command-line interface

`rlds-mat` exposes a CLI that mirrors the Python API. Available subcommands:

```bash
rlds-mat info                                # show version and references
rlds-mat analyze examples/my_system.json     # full analysis report
rlds-mat analyze --json my_system.json       # machine-readable output
rlds-mat verify my_system.json               # verify reduction criteria (C1–C4)
rlds-mat verify --structural my_system.json  # κ-independent check (C1, C3, A3, A4)
rlds-mat report my_system.json -o out.pdf    # generate PDF report
rlds-mat plot my_system.json -o plot.png     # save H(x) and phase-portrait plots
```

Exit codes follow Unix conventions: `0` success, `1` I/O or parser errors
(messages on stderr), `2` for `verify` when a system fails the relevant
criteria.

## Predefined systems

```python
import rlds_mat

# System A from RLDS II  (x* ≈ 0.2308)
params = rlds_mat.systems.system_a()

# Numerical example from RLDS I, Section 7  (x* ≈ 0.385)
params = rlds_mat.systems.zenodo_example()
```

## Built-in profiles

### Restoring profiles φ(x)

| Function     | Constructor                         | Formula     |
|--------------|-------------------------------------|-------------|
| Power-law    | `rlds_mat.phi.power_law(gamma=1)`   | x^(−γ)      |
| Regularized  | `rlds_mat.phi.regularized(eps=1e-6)`| (1−x)/(x+ε) |
| Logarithmic  | `rlds_mat.phi.logarithmic()`        | −ln(x)      |
| Custom       | `rlds_mat.phi.custom(func, name)`   | User-defined|

A note on regularization: with `eps = 0` the Power-law and Logarithmic
profiles are *exact* singular profiles and the RLDS theorems apply directly.
With `eps > 0` (the default for `regularized`, and optional for the others)
the profile is a smooth numerical surrogate — `lim_{x→0⁺} φ = 1/ε < ∞`, not
`+∞`. The SDK reports this honestly: `verify_A3` sets
`details["singularity_mode"]` to `"exact"` or `"regularized"`, and the
analysis guarantees note when results apply to the idealized `ε → 0` model
rather than to the regularized function literally (see RLDS II, Remark 2.3).

### Gating profiles w(y)

| Function   | Constructor                       | Formula           |
|------------|-----------------------------------|-------------------|
| Sigmoid    | `rlds_mat.w.sigmoid(delta=0.1)`   | ½(1 + tanh(y/Δ))  |
| Constant   | `rlds_mat.w.constant()`           | 1                 |
| Custom     | `rlds_mat.w.custom(func, name)`   | User-defined      |

### Educational / non-strict profiles

The following profile is provided for teaching and comparison, but does
**not** satisfy the strict RLDS assumptions and should not be used when
certified RLDS membership is required:

| Function   | Constructor                       | Formula           | Caveat                                  |
|------------|-----------------------------------|-------------------|-----------------------------------------|
| Linear     | `rlds_mat.w.linear(delta=0.1)`    | min(y/Δ, 1)       | Only C⁰ (kinked); violates Assumption 3(W1) of RLDS II, which requires w ∈ C¹ |

## Loading systems from files

`rlds-mat` can load system definitions from JSON, YAML, and Python files.

> **Security note.** Loading a `.py` system file *executes arbitrary Python
> code* (the file is imported via `importlib`). Only load `.py` files you
> trust. For untrusted or third-party input, use the JSON, YAML, or TOML
> formats, which are parsed as data and do not execute code. Custom
> mathematical expressions are evaluated with a restricted `eval` namespace,
> which reduces but does not eliminate risk — it is **not** a security
> sandbox.

## Analysis output

A complete `AnalysisReport` includes:

- **Verification**: Pass/fail status of conditions C1–C4.
- **Classification**: RLDS membership.
- **Thresholds**: κc, κ_bdy, κ_adm and the current regime.
- **Equilibrium**: x*, stability type, and uniqueness diagnostics.
- **Guarantees**: Which theorems of the RLDS framework apply.

## Mathematical scope

RLDS systems have the form:

```
dx/dt = -α · x(1 - x) + β · φ(x) · w(xc - x)
```

with parameters `α, β > 0`, boundary `xc ∈ (0, 1]`, singular restoring profile
`φ` and gating profile `w`. The dimensionless regime parameter is `κ = β/α`.

Key results (see RLDS II for full statements):

| Regime              | Result                                                |
|---------------------|-------------------------------------------------------|
| `κ < κ_adm`         | Unique, globally asymptotically stable equilibrium.   |
| `κ_adm ≤ κ < κc`    | Unique stable equilibrium on the increasing branch.   |
| `κ = κc`            | Marginal (degenerate) equilibrium.                    |
| `κ > κc`            | No equilibrium in (0, xc).                            |

## Development

```bash
git clone https://github.com/AKubanski/rlds-mat.git
cd rlds-mat
pip install -e ".[dev,yaml]"
pytest tests/                                # 154 tests, ~10 seconds
pytest tests/ --cov=rlds_mat                 # with coverage report
python -m build                              # build sdist + wheel
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for development conventions.

## Author

Aleksander Kubanski — Independent Researcher, Poland.

- Email: `aleksander@kubanski.pro`
- Homepage: [research.kubanski.pro](https://research.kubanski.pro)
- ORCID: [0009-0006-7239-5074](https://orcid.org/0009-0006-7239-5074)

## License

MIT. See [LICENSE](LICENSE).
