linoss-dynamics 0.1.0__tar.gz

linoss_dynamics-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 linoss-dynamics contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

linoss_dynamics-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: linoss-dynamics
+Version: 0.1.0
+Summary: Small NumPy runtime helpers for LinOSS-style oscillator dynamics with explicit damping.
+Author-email: Mani Saint-Victor <drmani215@gmail.com>
+Maintainer-email: Mani Saint-Victor <drmani215@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bionicbutterfly13/linoss-dynamics
+Project-URL: Source, https://github.com/bionicbutterfly13/linoss-dynamics
+Project-URL: Issues, https://github.com/bionicbutterfly13/linoss-dynamics/issues
+Project-URL: Changelog, https://github.com/bionicbutterfly13/linoss-dynamics/blob/main/CHANGELOG.md
+Project-URL: Provenance, https://github.com/bionicbutterfly13/linoss-dynamics/blob/main/PROVENANCE.md
+Keywords: linoss,state-space-models,oscillator,dynamics,numpy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: ruff>=0.4; extra == "test"
+Dynamic: license-file
+
+# linoss-dynamics
+
+[![CI](https://github.com/bionicbutterfly13/linoss-dynamics/actions/workflows/ci.yml/badge.svg)](https://github.com/bionicbutterfly13/linoss-dynamics/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Status](https://img.shields.io/badge/status-public%20alpha-orange)
+
+`linoss-dynamics` is a small NumPy runtime package for LinOSS-style oscillator
+dynamics with explicit non-negative damping support.
+
+Status: **public alpha**.
+
+## How this differs from the upstream LinOSS reference
+
+The original [tk-rusch/linoss](https://github.com/tk-rusch/linoss) is a
+**training-time JAX/Equinox neural-network library** that exposes LinOSS as
+trainable layers (`LinOSSLayer`, `LinOSSBlock`, `LinOSS`) inside a deep-learning
+model. It is the right choice when you are building or training a sequence model
+that uses LinOSS as a learnable encoder.
+
+`linoss-dynamics` is a **runtime physics package**. Same mathematics, different
+audience and abstraction:
+
+| Dimension | Upstream `tk-rusch/linoss` | `linoss-dynamics` |
+|---|---|---|
+| Use case | Training neural networks with LinOSS layers | Runtime simulation, control, replay-safe systems |
+| Stack | JAX + Equinox | NumPy only — zero deep-learning dependencies |
+| Granularity | Sequence-level via JAX `scan` (`apply_linoss_im`, `apply_linoss_imex`) | Single-step (`linoss_step`, `damped_linoss_step`) |
+| Damping | Implicit (rolled into `A`) | **Explicit, non-negativity validated** (`G` parameter) |
+| Energy diagnostics | Not exposed | `energy`, `delta_energy`, `convergence_window` |
+| Errors | Generic shape errors | Typed hierarchy (`LinOSSError`, `InvalidShapeError`, `InvalidDampingError`, `UnsupportedModeError`) |
+| Determinism contract | Best-effort (training-oriented) | Replay-safe — pure NumPy, deterministic, no hidden state |
+| Install footprint | Heavy (JAX, Equinox, dataset deps) | Tiny (NumPy 1.24+) |
+
+### Who needs `linoss-dynamics` specifically
+
+- **Replay-safe agentic systems** — needed inside deterministic kernels where
+  every step must be byte-reproducible (e.g. consumed by
+  [`elume`](https://github.com/bionicbutterfly13/elume) at runtime).
+- **Simulation and control** — robotics, signal processing, vibration analysis,
+  and any context that uses oscillatory dynamics as a runtime model rather than
+  a learnable layer.
+- **Reference implementation for porting** — a clean NumPy baseline to validate
+  custom JAX/PyTorch ports of LinOSS against.
+- **Embedded or minimal-dependency contexts** — anywhere a JAX install is too
+  heavy or unavailable.
+- **Teaching and pedagogy** — a self-contained, well-tested, single-file solver
+  that students can read end-to-end in an afternoon.
+- **Energy-based analysis** — applications that need to monitor energy drift
+  and detect convergence; these diagnostics are not exposed by the upstream
+  reference.
+
+If you are training a neural network, use the upstream package. If you are
+running a system that needs LinOSS as a deterministic physics step, use this one.
+
+## What It Provides
+
+- Classic implicit and implicit-explicit LinOSS step helpers.
+- Explicit non-negative damping `G` for D-LinOSS-style runtime damping.
+- Energy, energy-delta, and convergence-window helpers.
+- A dependency-light package core with NumPy as the only runtime dependency.
+
+## Install
+
+From PyPI (recommended):
+
+```bash
+pip install linoss-dynamics
+```
+
+From GitHub (latest main):
+
+```bash
+python -m pip install "linoss-dynamics @ git+https://github.com/bionicbutterfly13/linoss-dynamics.git@main"
+```
+
+For local development:
+
+```bash
+git clone https://github.com/bionicbutterfly13/linoss-dynamics.git
+cd linoss-dynamics
+python -m pip install -e ".[test]"
+```
+
+## Quickstart
+
+Classic LinOSS-style step:
+
+```python
+import numpy as np
+from linoss_dynamics import linoss_step
+
+y = np.array([0.2])
+z = np.array([1.0])
+A = np.array([1.0])
+
+y_next, z_next, metrics = linoss_step(y, z, A, dt=0.1, mode="implicit")
+
+print(y_next, z_next, metrics["energy_after"])
+```
+
+Damped step with explicit `G`:
+
+```python
+import numpy as np
+from linoss_dynamics import damped_linoss_step
+
+y = np.array([0.2])
+z = np.array([1.0])
+A = np.array([1.0])
+G = np.array([0.5])
+
+y_next, z_next, metrics = damped_linoss_step(y, z, A, G, dt=0.1)
+
+assert metrics["damping_mode"] == "explicit_g"
+```
+
+## Numerical Contract
+
+`A` controls oscillator stiffness/frequency.
+
+`G` controls damping/forgetting.
+
+The package deliberately keeps those controls separate. Damping is not modeled
+as hidden `A` scaling, and negative `G` values are rejected.
+
+Supported damping shapes:
+
+- scalar `G`
+- vector `G` with the same length as `y` and `z`
+- diagonal matrix `G`
+
+Supported step modes:
+
+- `implicit` / `IM`
+- `implicit_explicit` / `IMEX`
+
+## Public API
+
+| Name | Role |
+| --- | --- |
+| `linoss_step(y, z, A, dt, mode="implicit", B=None, u=None, damping=None, G=None)` | Advance one step, optionally dispatching to explicit damping when `damping` or `G` is supplied. |
+| `damped_linoss_step(y, z, A, G, dt, mode="implicit", B=None, u=None)` | Advance one step with explicit non-negative damping. |
+| `energy(y, z, A)` | Return diagonal oscillator energy. |
+| `delta_energy(previous_energy, next_energy)` | Return signed energy delta. |
+| `convergence_window(deltas, threshold, window)` | Return true when recent absolute deltas are below a threshold. |
+| `linoss_step_impl(...)` | Backward-compatible alias for callers using the implementation name. |
+
+Public errors:
+
+| Error | Raised when |
+| --- | --- |
+| `InvalidShapeError` | Inputs cannot be broadcast to the oscillator state. |
+| `InvalidDampingError` | Damping is outside the supported stable path, including negative `G`. |
+| `UnsupportedModeError` | The discretization mode is unsupported. |
+
+## Scope
+
+The package does not implement JAX training loops, Discretax integrations,
+active-inference runtimes, metacognitive policy, event buses, graph databases,
+or web APIs.
+
+Host applications should keep adapters outside this package and depend on
+`linoss-dynamics` through the public API above.
+
+## Development
+
+Run the full local check set:
+
+```bash
+python -m ruff check src tests
+python -m pytest tests -v --tb=short
+python -m compileall -q src tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [PROVENANCE.md](PROVENANCE.md), and
+[CLAIMS.md](CLAIMS.md) before changing package behavior or public wording.
+
+## Citation
+
+If this package is useful in research or technical writing, cite the package
+metadata in [CITATION.cff](CITATION.cff) and cite the upstream LinOSS and
+D-LinOSS papers listed below.
+
+Release and publishing steps are tracked in
+[docs/release-checklist.md](docs/release-checklist.md).
+
+## Attribution
+
+This package is not the original LinOSS or D-LinOSS research implementation.
+
+- LinOSS / Oscillatory State-Space Models: T. Konstantin Rusch and Daniela Rus,
+  `Oscillatory State-Space Models`, arXiv:2410.03943.
+- D-LinOSS / learned damping: Jared Boyer, T. Konstantin Rusch, and Daniela Rus,
+  `Learning to Dissipate Energy in Oscillatory State-Space Models`,
+  arXiv:2505.12171.
+- Official LinOSS ecosystem: <https://github.com/tk-rusch/linoss>.
+- Discretax / former Linax ecosystem: <https://github.com/camail-official/discretax>.
+
+See [PROVENANCE.md](PROVENANCE.md) and [CLAIMS.md](CLAIMS.md) before making
+public claims.

linoss_dynamics-0.1.0/README.md

@@ -0,0 +1,201 @@
+# linoss-dynamics
+
+[![CI](https://github.com/bionicbutterfly13/linoss-dynamics/actions/workflows/ci.yml/badge.svg)](https://github.com/bionicbutterfly13/linoss-dynamics/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Status](https://img.shields.io/badge/status-public%20alpha-orange)
+
+`linoss-dynamics` is a small NumPy runtime package for LinOSS-style oscillator
+dynamics with explicit non-negative damping support.
+
+Status: **public alpha**.
+
+## How this differs from the upstream LinOSS reference
+
+The original [tk-rusch/linoss](https://github.com/tk-rusch/linoss) is a
+**training-time JAX/Equinox neural-network library** that exposes LinOSS as
+trainable layers (`LinOSSLayer`, `LinOSSBlock`, `LinOSS`) inside a deep-learning
+model. It is the right choice when you are building or training a sequence model
+that uses LinOSS as a learnable encoder.
+
+`linoss-dynamics` is a **runtime physics package**. Same mathematics, different
+audience and abstraction:
+
+| Dimension | Upstream `tk-rusch/linoss` | `linoss-dynamics` |
+|---|---|---|
+| Use case | Training neural networks with LinOSS layers | Runtime simulation, control, replay-safe systems |
+| Stack | JAX + Equinox | NumPy only — zero deep-learning dependencies |
+| Granularity | Sequence-level via JAX `scan` (`apply_linoss_im`, `apply_linoss_imex`) | Single-step (`linoss_step`, `damped_linoss_step`) |
+| Damping | Implicit (rolled into `A`) | **Explicit, non-negativity validated** (`G` parameter) |
+| Energy diagnostics | Not exposed | `energy`, `delta_energy`, `convergence_window` |
+| Errors | Generic shape errors | Typed hierarchy (`LinOSSError`, `InvalidShapeError`, `InvalidDampingError`, `UnsupportedModeError`) |
+| Determinism contract | Best-effort (training-oriented) | Replay-safe — pure NumPy, deterministic, no hidden state |
+| Install footprint | Heavy (JAX, Equinox, dataset deps) | Tiny (NumPy 1.24+) |
+
+### Who needs `linoss-dynamics` specifically
+
+- **Replay-safe agentic systems** — needed inside deterministic kernels where
+  every step must be byte-reproducible (e.g. consumed by
+  [`elume`](https://github.com/bionicbutterfly13/elume) at runtime).
+- **Simulation and control** — robotics, signal processing, vibration analysis,
+  and any context that uses oscillatory dynamics as a runtime model rather than
+  a learnable layer.
+- **Reference implementation for porting** — a clean NumPy baseline to validate
+  custom JAX/PyTorch ports of LinOSS against.
+- **Embedded or minimal-dependency contexts** — anywhere a JAX install is too
+  heavy or unavailable.
+- **Teaching and pedagogy** — a self-contained, well-tested, single-file solver
+  that students can read end-to-end in an afternoon.
+- **Energy-based analysis** — applications that need to monitor energy drift
+  and detect convergence; these diagnostics are not exposed by the upstream
+  reference.
+
+If you are training a neural network, use the upstream package. If you are
+running a system that needs LinOSS as a deterministic physics step, use this one.
+
+## What It Provides
+
+- Classic implicit and implicit-explicit LinOSS step helpers.
+- Explicit non-negative damping `G` for D-LinOSS-style runtime damping.
+- Energy, energy-delta, and convergence-window helpers.
+- A dependency-light package core with NumPy as the only runtime dependency.
+
+## Install
+
+From PyPI (recommended):
+
+```bash
+pip install linoss-dynamics
+```
+
+From GitHub (latest main):
+
+```bash
+python -m pip install "linoss-dynamics @ git+https://github.com/bionicbutterfly13/linoss-dynamics.git@main"
+```
+
+For local development:
+
+```bash
+git clone https://github.com/bionicbutterfly13/linoss-dynamics.git
+cd linoss-dynamics
+python -m pip install -e ".[test]"
+```
+
+## Quickstart
+
+Classic LinOSS-style step:
+
+```python
+import numpy as np
+from linoss_dynamics import linoss_step
+
+y = np.array([0.2])
+z = np.array([1.0])
+A = np.array([1.0])
+
+y_next, z_next, metrics = linoss_step(y, z, A, dt=0.1, mode="implicit")
+
+print(y_next, z_next, metrics["energy_after"])
+```
+
+Damped step with explicit `G`:
+
+```python
+import numpy as np
+from linoss_dynamics import damped_linoss_step
+
+y = np.array([0.2])
+z = np.array([1.0])
+A = np.array([1.0])
+G = np.array([0.5])
+
+y_next, z_next, metrics = damped_linoss_step(y, z, A, G, dt=0.1)
+
+assert metrics["damping_mode"] == "explicit_g"
+```
+
+## Numerical Contract
+
+`A` controls oscillator stiffness/frequency.
+
+`G` controls damping/forgetting.
+
+The package deliberately keeps those controls separate. Damping is not modeled
+as hidden `A` scaling, and negative `G` values are rejected.
+
+Supported damping shapes:
+
+- scalar `G`
+- vector `G` with the same length as `y` and `z`
+- diagonal matrix `G`
+
+Supported step modes:
+
+- `implicit` / `IM`
+- `implicit_explicit` / `IMEX`
+
+## Public API
+
+| Name | Role |
+| --- | --- |
+| `linoss_step(y, z, A, dt, mode="implicit", B=None, u=None, damping=None, G=None)` | Advance one step, optionally dispatching to explicit damping when `damping` or `G` is supplied. |
+| `damped_linoss_step(y, z, A, G, dt, mode="implicit", B=None, u=None)` | Advance one step with explicit non-negative damping. |
+| `energy(y, z, A)` | Return diagonal oscillator energy. |
+| `delta_energy(previous_energy, next_energy)` | Return signed energy delta. |
+| `convergence_window(deltas, threshold, window)` | Return true when recent absolute deltas are below a threshold. |
+| `linoss_step_impl(...)` | Backward-compatible alias for callers using the implementation name. |
+
+Public errors:
+
+| Error | Raised when |
+| --- | --- |
+| `InvalidShapeError` | Inputs cannot be broadcast to the oscillator state. |
+| `InvalidDampingError` | Damping is outside the supported stable path, including negative `G`. |
+| `UnsupportedModeError` | The discretization mode is unsupported. |
+
+## Scope
+
+The package does not implement JAX training loops, Discretax integrations,
+active-inference runtimes, metacognitive policy, event buses, graph databases,
+or web APIs.
+
+Host applications should keep adapters outside this package and depend on
+`linoss-dynamics` through the public API above.
+
+## Development
+
+Run the full local check set:
+
+```bash
+python -m ruff check src tests
+python -m pytest tests -v --tb=short
+python -m compileall -q src tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [PROVENANCE.md](PROVENANCE.md), and
+[CLAIMS.md](CLAIMS.md) before changing package behavior or public wording.
+
+## Citation
+
+If this package is useful in research or technical writing, cite the package
+metadata in [CITATION.cff](CITATION.cff) and cite the upstream LinOSS and
+D-LinOSS papers listed below.
+
+Release and publishing steps are tracked in
+[docs/release-checklist.md](docs/release-checklist.md).
+
+## Attribution
+
+This package is not the original LinOSS or D-LinOSS research implementation.
+
+- LinOSS / Oscillatory State-Space Models: T. Konstantin Rusch and Daniela Rus,
+  `Oscillatory State-Space Models`, arXiv:2410.03943.
+- D-LinOSS / learned damping: Jared Boyer, T. Konstantin Rusch, and Daniela Rus,
+  `Learning to Dissipate Energy in Oscillatory State-Space Models`,
+  arXiv:2505.12171.
+- Official LinOSS ecosystem: <https://github.com/tk-rusch/linoss>.
+- Discretax / former Linax ecosystem: <https://github.com/camail-official/discretax>.
+
+See [PROVENANCE.md](PROVENANCE.md) and [CLAIMS.md](CLAIMS.md) before making
+public claims.

linoss_dynamics-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "linoss-dynamics"
+version = "0.1.0"
+description = "Small NumPy runtime helpers for LinOSS-style oscillator dynamics with explicit damping."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mani Saint-Victor", email = "drmani215@gmail.com" }]
+maintainers = [{ name = "Mani Saint-Victor", email = "drmani215@gmail.com" }]
+keywords = ["linoss", "state-space-models", "oscillator", "dynamics", "numpy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.4",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/bionicbutterfly13/linoss-dynamics"
+Source = "https://github.com/bionicbutterfly13/linoss-dynamics"
+Issues = "https://github.com/bionicbutterfly13/linoss-dynamics/issues"
+Changelog = "https://github.com/bionicbutterfly13/linoss-dynamics/blob/main/CHANGELOG.md"
+Provenance = "https://github.com/bionicbutterfly13/linoss-dynamics/blob/main/PROVENANCE.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+pythonpath = ["src"]

linoss_dynamics-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

linoss_dynamics-0.1.0/src/linoss_dynamics/__init__.py

@@ -0,0 +1,31 @@
+"""NumPy runtime helpers for LinOSS-style oscillator dynamics.
+
+The package keeps the core dependency-light and separates stiffness/frequency
+(`A`) from explicit damping/forgetting (`G`).
+"""
+
+from .solver import (
+    InvalidDampingError,
+    InvalidShapeError,
+    LinOSSError,
+    UnsupportedModeError,
+    convergence_window,
+    damped_linoss_step,
+    delta_energy,
+    energy,
+    linoss_step,
+    linoss_step_impl,
+)
+
+__all__ = [
+    "InvalidDampingError",
+    "InvalidShapeError",
+    "LinOSSError",
+    "UnsupportedModeError",
+    "convergence_window",
+    "damped_linoss_step",
+    "delta_energy",
+    "energy",
+    "linoss_step",
+    "linoss_step_impl",
+]

linoss_dynamics-0.1.0/src/linoss_dynamics/solver.py

@@ -0,0 +1,227 @@
+"""NumPy LinOSS stepping helpers with explicit damping support."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+
+class LinOSSError(ValueError):
+    """Base error for LinOSS dynamics failures."""
+
+
+class InvalidShapeError(LinOSSError):
+    """Raised when LinOSS inputs cannot be broadcast to the oscillator state."""
+
+
+class InvalidDampingError(LinOSSError):
+    """Raised when damping `G` is outside the supported stable path."""
+
+
+class UnsupportedModeError(LinOSSError):
+    """Raised when a discretization mode is not supported."""
+
+
+def _normalize_mode(mode: str) -> str:
+    normalized = str(mode or "implicit").lower().replace("-", "_")
+    if normalized in {"im", "implicit"}:
+        return "implicit"
+    if normalized in {"imex", "implicit_explicit"}:
+        return "implicit_explicit"
+    raise UnsupportedModeError(f"Unsupported LinOSS mode: {mode!r}")
+
+
+def _state_vectors(y: Any, z: Any) -> tuple[np.ndarray, np.ndarray]:
+    y_arr = np.asarray(y, dtype=float).reshape(-1)
+    z_arr = np.asarray(z, dtype=float).reshape(-1)
+    if y_arr.shape != z_arr.shape:
+        raise InvalidShapeError(
+            f"y and z must have the same shape, got {y_arr.shape} and {z_arr.shape}"
+        )
+    return y_arr, z_arr
+
+
+def _diagonal_vector(name: str, value: Any, size: int) -> np.ndarray:
+    arr = np.asarray(value, dtype=float)
+    if arr.ndim == 0:
+        return np.full(size, float(arr))
+    if arr.ndim == 1:
+        if arr.size == 1:
+            return np.full(size, float(arr[0]))
+        if arr.size == size:
+            return arr.astype(float, copy=True)
+    if arr.ndim == 2 and arr.shape == (size, size):
+        off_diag = arr - np.diag(np.diag(arr))
+        if np.allclose(off_diag, 0.0):
+            return np.diag(arr).astype(float, copy=True)
+    raise InvalidShapeError(
+        f"{name} must be scalar, length-{size} vector, or {size}x{size} diagonal matrix"
+    )
+
+
+def _forcing_vector(B: Any, u: Any, size: int) -> np.ndarray:
+    if B is None and u is None:
+        return np.zeros(size)
+
+    if B is None:
+        u_arr = np.asarray(u, dtype=float)
+        if u_arr.ndim == 0:
+            return np.full(size, float(u_arr))
+        u_flat = u_arr.reshape(-1)
+        if u_flat.size == size:
+            return u_flat
+        raise InvalidShapeError(f"u must be scalar or length-{size} when B is omitted")
+
+    if u is None:
+        return np.zeros(size)
+
+    B_arr = np.asarray(B, dtype=float)
+    u_arr = np.asarray(u, dtype=float)
+
+    if B_arr.ndim == 1:
+        if B_arr.size != size:
+            raise InvalidShapeError(f"B vector must have length {size}")
+        if u_arr.ndim == 0:
+            return B_arr * float(u_arr)
+        u_flat = u_arr.reshape(-1)
+        if u_flat.size == size:
+            return B_arr * u_flat
+        raise InvalidShapeError(f"u must be scalar or length-{size} for vector B")
+
+    if B_arr.ndim == 2 and B_arr.shape[0] == size:
+        try:
+            forcing = B_arr @ u_arr.reshape(-1)
+        except ValueError as exc:
+            raise InvalidShapeError(f"B and u shapes are incompatible: {exc}") from exc
+        return np.asarray(forcing, dtype=float).reshape(-1)
+
+    raise InvalidShapeError(f"B must be length-{size} vector or matrix with {size} rows")
+
+
+def energy(y: Any, z: Any, A: Any, G: Any | None = None) -> float:
+    """Return oscillator energy for diagonal LinOSS state parameters."""
+
+    del G
+    y_arr, z_arr = _state_vectors(y, z)
+    A_vec = _diagonal_vector("A", A, y_arr.size)
+    return float(0.5 * np.sum(A_vec * y_arr**2 + z_arr**2))
+
+
+def delta_energy(previous_energy: float, next_energy: float) -> float:
+    """Return signed energy delta."""
+
+    return float(next_energy) - float(previous_energy)
+
+
+def convergence_window(deltas: list[float] | tuple[float, ...], threshold: float, window: int) -> bool:
+    """Return true when the most recent absolute deltas are all below threshold."""
+
+    if window <= 0:
+        raise ValueError("window must be positive")
+    if len(deltas) < window:
+        return False
+    return all(abs(float(delta)) < float(threshold) for delta in deltas[-window:])
+
+
+def linoss_step(
+    y: Any,
+    z: Any,
+    A: Any,
+    dt: float,
+    mode: str = "implicit",
+    B: Any | None = None,
+    u: Any | None = None,
+    damping: Any | None = None,
+    G: Any | None = None,
+) -> tuple[np.ndarray, np.ndarray, dict[str, Any]]:
+    """Advance one LinOSS step with optional explicit damping."""
+
+    if damping is not None or G is not None:
+        return damped_linoss_step(
+            y=y,
+            z=z,
+            A=A,
+            G=damping if damping is not None else G,
+            dt=dt,
+            mode=mode,
+            B=B,
+            u=u,
+        )
+
+    y_arr, z_arr = _state_vectors(y, z)
+    A_vec = _diagonal_vector("A", A, y_arr.size)
+    forcing = _forcing_vector(B, u, y_arr.size)
+    dt_f = float(dt)
+    mode_name = _normalize_mode(mode)
+    before = energy(y_arr, z_arr, A_vec)
+
+    if mode_name == "implicit":
+        schur = 1.0 / (1.0 + (dt_f**2) * A_vec)
+        z_next = schur * z_arr - dt_f * A_vec * schur * y_arr + dt_f * schur * forcing
+        y_next = schur * y_arr + dt_f * schur * z_arr + (dt_f**2) * schur * forcing
+    elif mode_name == "implicit_explicit":
+        z_next = z_arr - dt_f * A_vec * y_arr + dt_f * forcing
+        y_next = y_arr + dt_f * z_next
+    else:  # pragma: no cover - _normalize_mode guards this
+        raise UnsupportedModeError(f"Unsupported LinOSS mode: {mode!r}")
+
+    after = energy(y_next, z_next, A_vec)
+    return y_next, z_next, {
+        "mode": mode_name,
+        "energy_before": before,
+        "energy_after": after,
+        "delta_energy": delta_energy(before, after),
+        "damping_mode": "none",
+    }
+
+
+def damped_linoss_step(
+    y: Any,
+    z: Any,
+    A: Any,
+    G: Any,
+    dt: float,
+    mode: str = "implicit",
+    B: Any | None = None,
+    u: Any | None = None,
+) -> tuple[np.ndarray, np.ndarray, dict[str, Any]]:
+    """Advance one LinOSS step with explicit non-negative damping `G`."""
+
+    y_arr, z_arr = _state_vectors(y, z)
+    A_vec = _diagonal_vector("A", A, y_arr.size)
+    G_vec = _diagonal_vector("G", G, y_arr.size)
+    if np.any(G_vec < 0.0):
+        raise InvalidDampingError("G damping must be non-negative")
+
+    forcing = _forcing_vector(B, u, y_arr.size)
+    dt_f = float(dt)
+    mode_name = _normalize_mode(mode)
+    before = energy(y_arr, z_arr, A_vec)
+
+    if mode_name == "implicit":
+        denom = 1.0 + dt_f * G_vec + (dt_f**2) * A_vec
+        z_next = (z_arr - dt_f * A_vec * y_arr + dt_f * forcing) / denom
+        y_next = y_arr + dt_f * z_next
+    elif mode_name == "implicit_explicit":
+        denom = 1.0 + dt_f * G_vec
+        z_next = (z_arr - dt_f * A_vec * y_arr + dt_f * forcing) / denom
+        y_next = y_arr + dt_f * z_next
+    else:  # pragma: no cover - _normalize_mode guards this
+        raise UnsupportedModeError(f"Unsupported LinOSS mode: {mode!r}")
+
+    after = energy(y_next, z_next, A_vec)
+    return y_next, z_next, {
+        "mode": mode_name,
+        "energy_before": before,
+        "energy_after": after,
+        "delta_energy": delta_energy(before, after),
+        "damping_mode": "explicit_g",
+        "damping": G_vec,
+    }
+
+
+def linoss_step_impl(*args: Any, **kwargs: Any) -> tuple[np.ndarray, np.ndarray, dict[str, Any]]:
+    """Backward-compatible implementation alias for callers using this name."""
+
+    return linoss_step(*args, **kwargs)

linoss_dynamics-0.1.0/src/linoss_dynamics.egg-info/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: linoss-dynamics
+Version: 0.1.0
+Summary: Small NumPy runtime helpers for LinOSS-style oscillator dynamics with explicit damping.
+Author-email: Mani Saint-Victor <drmani215@gmail.com>
+Maintainer-email: Mani Saint-Victor <drmani215@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bionicbutterfly13/linoss-dynamics
+Project-URL: Source, https://github.com/bionicbutterfly13/linoss-dynamics
+Project-URL: Issues, https://github.com/bionicbutterfly13/linoss-dynamics/issues
+Project-URL: Changelog, https://github.com/bionicbutterfly13/linoss-dynamics/blob/main/CHANGELOG.md
+Project-URL: Provenance, https://github.com/bionicbutterfly13/linoss-dynamics/blob/main/PROVENANCE.md
+Keywords: linoss,state-space-models,oscillator,dynamics,numpy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: ruff>=0.4; extra == "test"
+Dynamic: license-file
+
+# linoss-dynamics
+
+[![CI](https://github.com/bionicbutterfly13/linoss-dynamics/actions/workflows/ci.yml/badge.svg)](https://github.com/bionicbutterfly13/linoss-dynamics/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Status](https://img.shields.io/badge/status-public%20alpha-orange)
+
+`linoss-dynamics` is a small NumPy runtime package for LinOSS-style oscillator
+dynamics with explicit non-negative damping support.
+
+Status: **public alpha**.
+
+## How this differs from the upstream LinOSS reference
+
+The original [tk-rusch/linoss](https://github.com/tk-rusch/linoss) is a
+**training-time JAX/Equinox neural-network library** that exposes LinOSS as
+trainable layers (`LinOSSLayer`, `LinOSSBlock`, `LinOSS`) inside a deep-learning
+model. It is the right choice when you are building or training a sequence model
+that uses LinOSS as a learnable encoder.
+
+`linoss-dynamics` is a **runtime physics package**. Same mathematics, different
+audience and abstraction:
+
+| Dimension | Upstream `tk-rusch/linoss` | `linoss-dynamics` |
+|---|---|---|
+| Use case | Training neural networks with LinOSS layers | Runtime simulation, control, replay-safe systems |
+| Stack | JAX + Equinox | NumPy only — zero deep-learning dependencies |
+| Granularity | Sequence-level via JAX `scan` (`apply_linoss_im`, `apply_linoss_imex`) | Single-step (`linoss_step`, `damped_linoss_step`) |
+| Damping | Implicit (rolled into `A`) | **Explicit, non-negativity validated** (`G` parameter) |
+| Energy diagnostics | Not exposed | `energy`, `delta_energy`, `convergence_window` |
+| Errors | Generic shape errors | Typed hierarchy (`LinOSSError`, `InvalidShapeError`, `InvalidDampingError`, `UnsupportedModeError`) |
+| Determinism contract | Best-effort (training-oriented) | Replay-safe — pure NumPy, deterministic, no hidden state |
+| Install footprint | Heavy (JAX, Equinox, dataset deps) | Tiny (NumPy 1.24+) |
+
+### Who needs `linoss-dynamics` specifically
+
+- **Replay-safe agentic systems** — needed inside deterministic kernels where
+  every step must be byte-reproducible (e.g. consumed by
+  [`elume`](https://github.com/bionicbutterfly13/elume) at runtime).
+- **Simulation and control** — robotics, signal processing, vibration analysis,
+  and any context that uses oscillatory dynamics as a runtime model rather than
+  a learnable layer.
+- **Reference implementation for porting** — a clean NumPy baseline to validate
+  custom JAX/PyTorch ports of LinOSS against.
+- **Embedded or minimal-dependency contexts** — anywhere a JAX install is too
+  heavy or unavailable.
+- **Teaching and pedagogy** — a self-contained, well-tested, single-file solver
+  that students can read end-to-end in an afternoon.
+- **Energy-based analysis** — applications that need to monitor energy drift
+  and detect convergence; these diagnostics are not exposed by the upstream
+  reference.
+
+If you are training a neural network, use the upstream package. If you are
+running a system that needs LinOSS as a deterministic physics step, use this one.
+
+## What It Provides
+
+- Classic implicit and implicit-explicit LinOSS step helpers.
+- Explicit non-negative damping `G` for D-LinOSS-style runtime damping.
+- Energy, energy-delta, and convergence-window helpers.
+- A dependency-light package core with NumPy as the only runtime dependency.
+
+## Install
+
+From PyPI (recommended):
+
+```bash
+pip install linoss-dynamics
+```
+
+From GitHub (latest main):
+
+```bash
+python -m pip install "linoss-dynamics @ git+https://github.com/bionicbutterfly13/linoss-dynamics.git@main"
+```
+
+For local development:
+
+```bash
+git clone https://github.com/bionicbutterfly13/linoss-dynamics.git
+cd linoss-dynamics
+python -m pip install -e ".[test]"
+```
+
+## Quickstart
+
+Classic LinOSS-style step:
+
+```python
+import numpy as np
+from linoss_dynamics import linoss_step
+
+y = np.array([0.2])
+z = np.array([1.0])
+A = np.array([1.0])
+
+y_next, z_next, metrics = linoss_step(y, z, A, dt=0.1, mode="implicit")
+
+print(y_next, z_next, metrics["energy_after"])
+```
+
+Damped step with explicit `G`:
+
+```python
+import numpy as np
+from linoss_dynamics import damped_linoss_step
+
+y = np.array([0.2])
+z = np.array([1.0])
+A = np.array([1.0])
+G = np.array([0.5])
+
+y_next, z_next, metrics = damped_linoss_step(y, z, A, G, dt=0.1)
+
+assert metrics["damping_mode"] == "explicit_g"
+```
+
+## Numerical Contract
+
+`A` controls oscillator stiffness/frequency.
+
+`G` controls damping/forgetting.
+
+The package deliberately keeps those controls separate. Damping is not modeled
+as hidden `A` scaling, and negative `G` values are rejected.
+
+Supported damping shapes:
+
+- scalar `G`
+- vector `G` with the same length as `y` and `z`
+- diagonal matrix `G`
+
+Supported step modes:
+
+- `implicit` / `IM`
+- `implicit_explicit` / `IMEX`
+
+## Public API
+
+| Name | Role |
+| --- | --- |
+| `linoss_step(y, z, A, dt, mode="implicit", B=None, u=None, damping=None, G=None)` | Advance one step, optionally dispatching to explicit damping when `damping` or `G` is supplied. |
+| `damped_linoss_step(y, z, A, G, dt, mode="implicit", B=None, u=None)` | Advance one step with explicit non-negative damping. |
+| `energy(y, z, A)` | Return diagonal oscillator energy. |
+| `delta_energy(previous_energy, next_energy)` | Return signed energy delta. |
+| `convergence_window(deltas, threshold, window)` | Return true when recent absolute deltas are below a threshold. |
+| `linoss_step_impl(...)` | Backward-compatible alias for callers using the implementation name. |
+
+Public errors:
+
+| Error | Raised when |
+| --- | --- |
+| `InvalidShapeError` | Inputs cannot be broadcast to the oscillator state. |
+| `InvalidDampingError` | Damping is outside the supported stable path, including negative `G`. |
+| `UnsupportedModeError` | The discretization mode is unsupported. |
+
+## Scope
+
+The package does not implement JAX training loops, Discretax integrations,
+active-inference runtimes, metacognitive policy, event buses, graph databases,
+or web APIs.
+
+Host applications should keep adapters outside this package and depend on
+`linoss-dynamics` through the public API above.
+
+## Development
+
+Run the full local check set:
+
+```bash
+python -m ruff check src tests
+python -m pytest tests -v --tb=short
+python -m compileall -q src tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [PROVENANCE.md](PROVENANCE.md), and
+[CLAIMS.md](CLAIMS.md) before changing package behavior or public wording.
+
+## Citation
+
+If this package is useful in research or technical writing, cite the package
+metadata in [CITATION.cff](CITATION.cff) and cite the upstream LinOSS and
+D-LinOSS papers listed below.
+
+Release and publishing steps are tracked in
+[docs/release-checklist.md](docs/release-checklist.md).
+
+## Attribution
+
+This package is not the original LinOSS or D-LinOSS research implementation.
+
+- LinOSS / Oscillatory State-Space Models: T. Konstantin Rusch and Daniela Rus,
+  `Oscillatory State-Space Models`, arXiv:2410.03943.
+- D-LinOSS / learned damping: Jared Boyer, T. Konstantin Rusch, and Daniela Rus,
+  `Learning to Dissipate Energy in Oscillatory State-Space Models`,
+  arXiv:2505.12171.
+- Official LinOSS ecosystem: <https://github.com/tk-rusch/linoss>.
+- Discretax / former Linax ecosystem: <https://github.com/camail-official/discretax>.
+
+See [PROVENANCE.md](PROVENANCE.md) and [CLAIMS.md](CLAIMS.md) before making
+public claims.

linoss_dynamics-0.1.0/src/linoss_dynamics.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/linoss_dynamics/__init__.py
+src/linoss_dynamics/py.typed
+src/linoss_dynamics/solver.py
+src/linoss_dynamics.egg-info/PKG-INFO
+src/linoss_dynamics.egg-info/SOURCES.txt
+src/linoss_dynamics.egg-info/dependency_links.txt
+src/linoss_dynamics.egg-info/requires.txt
+src/linoss_dynamics.egg-info/top_level.txt
+tests/test_solver.py

linoss_dynamics-0.1.0/src/linoss_dynamics.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

linoss_dynamics-0.1.0/src/linoss_dynamics.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy>=1.24
+
+[test]
+pytest>=7.4
+ruff>=0.4

linoss_dynamics-0.1.0/src/linoss_dynamics.egg-info/top_level.txt

@@ -0,0 +1 @@
+linoss_dynamics

linoss_dynamics-0.1.0/tests/test_solver.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from linoss_dynamics import (
+    InvalidDampingError,
+    convergence_window,
+    damped_linoss_step,
+    linoss_step,
+)
+
+
+def test_linoss_im_forced_closed_form_step():
+    y = np.array([0.2, -0.1])
+    z = np.array([0.3, 0.05])
+    A = np.array([2.0, 0.5])
+    dt = 0.1
+    B = np.array([[1.2, 0.4], [0.1, 0.9]])
+    u = np.array([0.5, -0.2])
+
+    y_next, z_next, metrics = linoss_step(y, z, A, dt, mode="IM", B=B, u=u)
+
+    forcing = B @ u
+    schur = 1.0 / (1.0 + (dt**2) * A)
+    z_expected = schur * z - dt * A * schur * y + dt * schur * forcing
+    y_expected = schur * y + dt * schur * z + (dt**2) * schur * forcing
+
+    np.testing.assert_allclose(y_next, y_expected)
+    np.testing.assert_allclose(z_next, z_expected)
+    assert metrics["mode"] == "implicit"
+
+
+def test_linoss_imex_alias_and_forcing():
+    y = np.array([1.0])
+    z = np.array([0.0])
+    A = np.array([1.0])
+    dt = 0.05
+    B = np.array([[1.0]])
+    u = np.array([0.2])
+
+    y_next, z_next, metrics = linoss_step(y, z, A, dt, mode="IMEX", B=B, u=u)
+
+    forcing = (B @ u)[0]
+    z_expected = z[0] - dt * A[0] * y[0] + dt * forcing
+    y_expected = y[0] + dt * z_expected
+
+    assert z_next[0] == pytest.approx(z_expected)
+    assert y_next[0] == pytest.approx(y_expected)
+    assert metrics["mode"] == "implicit_explicit"
+
+
+def test_damped_step_uses_g_without_mutating_a():
+    y = np.array([0.2])
+    z = np.array([1.0])
+    A = np.array([1.0])
+    A_before = A.copy()
+    dt = 0.1
+
+    _, _, low_metrics = damped_linoss_step(y, z, A, np.array([0.0]), dt)
+    _, _, high_metrics = damped_linoss_step(y, z, A, np.array([1.0]), dt)
+
+    np.testing.assert_array_equal(A, A_before)
+    assert high_metrics["energy_after"] < low_metrics["energy_after"]
+    assert high_metrics["damping_mode"] == "explicit_g"
+
+
+@pytest.mark.parametrize("mode", ["implicit", "implicit_explicit"])
+def test_zero_g_matches_classic_step_for_selected_mode(mode):
+    y = np.array([0.2, -0.1])
+    z = np.array([0.3, 0.05])
+    A = np.array([2.0, 0.5])
+    dt = 0.1
+
+    y_classic, z_classic, _ = linoss_step(y, z, A, dt, mode=mode)
+    y_damped, z_damped, metrics = damped_linoss_step(y, z, A, 0.0, dt, mode=mode)
+
+    np.testing.assert_allclose(y_damped, y_classic)
+    np.testing.assert_allclose(z_damped, z_classic)
+    assert metrics["damping_mode"] == "explicit_g"
+
+
+def test_scalar_vector_and_diagonal_damping_are_equivalent():
+    y = np.array([0.1, -0.2])
+    z = np.array([0.4, 0.3])
+    A = np.array([1.0, 2.0])
+    dt = 0.05
+
+    y_scalar, z_scalar, _ = damped_linoss_step(y, z, A, 0.5, dt)
+    y_vector, z_vector, _ = damped_linoss_step(y, z, A, np.array([0.5, 0.5]), dt)
+    y_diag, z_diag, _ = damped_linoss_step(y, z, A, np.diag([0.5, 0.5]), dt)
+
+    np.testing.assert_allclose(y_scalar, y_vector)
+    np.testing.assert_allclose(z_scalar, z_vector)
+    np.testing.assert_allclose(y_scalar, y_diag)
+    np.testing.assert_allclose(z_scalar, z_diag)
+
+
+def test_negative_damping_rejected():
+    with pytest.raises(InvalidDampingError):
+        damped_linoss_step(
+            y=np.array([1.0]),
+            z=np.array([0.0]),
+            A=np.array([1.0]),
+            G=np.array([-0.1]),
+            dt=0.1,
+        )
+
+
+def test_convergence_window_uses_recent_absolute_deltas():
+    assert convergence_window([0.10, 0.01, 0.02, 0.03], threshold=0.05, window=3)
+    assert not convergence_window([0.01, 0.20, 0.02], threshold=0.05, window=3)