rlds-mat 1.1.0

Mathematical core SDK for Regime-Limited Dynamical Systems (RLDS): analysis of one-dimensional autonomous ODEs with singular restoring force.

rlds-mat

Regime-Limited Dynamical Systems — Mathematical Core

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
2. Kubanski, A. (2026). RLDS II: Regime-Limited Dynamical Systems — Theory and Reduction Criteria for Singular ODEs. Zenodo. doi: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

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

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

import rlds_mat

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

# Analyze
report = rlds_mat.analyze(params)

JSON format

{
    "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

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:

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

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

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 for development conventions.

Author

Aleksander Kubanski — Independent Researcher, Poland.

• Email: [e-mail]
• Homepage: research.kubanski.pro
• ORCID: 0009-0006-7239-5074

License

MIT. See LICENSE.