PITS-MRAS: Physics-Informed Time-Series Model-Reference Adaptive Systems

A unified framework merging Physics-Informed Neural Networks (PINNs), Time-Series Deep Learning, and Model-Reference Adaptive Systems (MRAS) for robust adaptive control of complex dynamical systems.

⚠️ Project Status

This is a research and engineering exploration combining control theory with modern AI/ML (see CHANGELOG.md for release history):

✅ Complete mathematical framework - formal specification with algorithms
✅ Full Python implementation - config/math → NN models → losses → controllers → training → inference → examples → tests → CI, plus the PCML physics-constraint layer
✅ Verified core identities - Lyapunov value function, costate = critic gradient, CLF-CBF forward invariance, and IRL → CARE convergence are numerically checked in the test suite
✅ Quality gates - full pytest suite CI-green, ruff check + ruff format + mypy clean, dependency graph 0 circular / 0 unused (regenerated by tools/create-dependency-graph/)
🔄 Experimental validation - the bundled examples run on nonlinear plants (examples/plants.py: sin-gravity pendulum, tanh tyre-saturation lateral model, 2-node RC thermal network), but these are illustrative — not validated against real hardware

Honest scope note: the rigorously-verified part is the mathematical core (the identities above). The example demos are illustrative and use synthetic/linear dynamics — they are not validated against real hardware. Contributions to extend the plants and add experimental validation are welcome.

🎯 Overview

PITS-MRAS represents a novel integration of three powerful paradigms:

Physics-Informed Neural Networks - Encode domain knowledge through conservation laws and PDEs
Time-Series Learning - Leverage LSTM and Transformer architectures for temporal reasoning
Model-Reference Adaptive Control - Provide stability guarantees via Lyapunov theory

This framework enables:

✅ Guaranteed stability through rigorous control theory
✅ Sample-efficient learning via physics constraints
✅ Long-horizon temporal reasoning with attention mechanisms
✅ Real-time deployment with parallel thread architecture
✅ Robustness to model uncertainty and disturbances

📚 Documentation

Comprehensive technical documentation is available in the docs/ directory.

Living project docs (track the implementation):

ROADMAP.md - the 9 build phases / milestones and their status
CHANGELOG.md - released versions and what landed in each

Design document + its validation (historical, describe the mathematical framework spec, not the code):

Main Technical Document - complete mathematical framework, algorithms, and architecture (the design spec)
Validation Report and Final Summary - the Oct-2025 A+/publication-readiness review of the design document above (not of the code implementation)

Architecture docs (graph-backed)

docs/architecture/ holds the trace/map/visualize documentation, generated and informed by the dependency-graph tool (tools/create-dependency-graph/create_dependency_graph.py):

OVERVIEW.md — orientation: the three-paradigm merger, module map, entry points, stats
ARCHITECTURE.md — full design blueprint + a §0 graph-backed as-built summary
COMPONENTS.md — per-module component breakdown
API.md — public API reference (signatures, config, usage)
DATAFLOW.md — runtime data flow (pre-train → co-train → inference)
DEPENDENCY_GRAPH.md + dependency-graph.{json,yaml} — the import graph
TEST_COVERAGE.md and unused-analysis.md

Regenerate with: python tools/create-dependency-graph/create_dependency_graph.py --include-tests

Key Sections

Philosophical Foundation - Three-paradigm integration rationale
Mathematical Framework - Complete formulation with 5 loss components
Architectural Design - Network structure and port-Hamiltonian physics decoder
Algorithms - Three formal algorithms (Forward Pass, Pre-Training, Co-Training)
Implementation - Python pseudocode and parallel thread architecture
Case Studies - Robotics, autonomous vehicles, building HVAC
Theoretical Contributions - Approximation theory and sample complexity
Practical Recommendations - When to use PITS-MRAS vs alternatives

🏗️ Architecture

High-Level System Architecture

Input Sequence → [PITNN Encoder] → [Physics Decoder] → Control Output
       ↓              ↓                    ↓
   Embedding      LSTM + Attn      Port-Hamiltonian
                                    Energy Enforcer
       ↓              ↓                    ↓
    [MRAS Adaptive Controller] ← [Reference Model]
                  ↓
           [Physical Plant]

Core Components

PITNN (Physics-Informed Temporal Neural Network)
- Embedding layer: Maps raw inputs to latent space
- LSTM encoder: Captures temporal dependencies
- Multi-head attention: Enables long-range reasoning
- Physics decoder: Enforces conservation laws
Port-Hamiltonian Structure
- Energy conservation: $\frac{dE}{dt} = P_{\text{control}} - P_{\text{dissipation}}$
- Positive-definite dissipation: $R = L^T L \succeq 0$
- Structured dynamics: Conservative + dissipative components
MRAS Controller
- Hybrid learning: Gradient descent + adaptive control laws
- Stability guarantee: Lyapunov function $V(e,\theta)$ with $\dot{V} < -\mu V$
- Parameter adaptation: Dual adaptation for plant and controller

🚀 Getting Started

Prerequisites

Python 3.10+
PyTorch 2.0+
NumPy
SciPy
PyYAML
Matplotlib (for the examples' figures)

Installation

# Clone the repository
git clone https://github.com/danielsimonjr/PITS-MRAS.git
cd PITS-MRAS

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Quick Start

import numpy as np
import torch

from pits_mras import (
    PITNN, MRASController, LinearReferenceModel,
    RealtimeInferenceEngine, pretrain_pitnn, cotraining_loop,
)
from pits_mras.config import PITSMRASConfig, NetworkConfig, PhysicsConfig

# 1) Configure the physics-informed temporal network.
cfg = PITSMRASConfig()
cfg.network = NetworkConfig(
    input_dim=2, hidden_dim=64, output_dim=2,
    lstm_layers=1, attention_heads=2, embedding_dim=16,
)
cfg.physics = PhysicsConfig(n_generalized_coords=1)
pitnn = PITNN(cfg.network, cfg.physics)

# 2) A Hurwitz linear reference model + MRAS controller (with CLF-CBF filter).
A_m = np.array([[0.0, 1.0], [-4.0, -4.0]])
B_m = np.array([[0.0], [1.0]])
ref = LinearReferenceModel(A_m, B_m, np.eye(2), np.eye(2), np.eye(1))
controller = MRASController(
    reference_model=ref, state_dim=2, control_dim=1,
    ref_dim=1, plant_dim=2, use_safety_filter=True,
)

# 3) Phase 1 — physics-informed pre-training (3-stage curriculum).
pretrain_pitnn(pitnn, cfg, epochs=50)

# 4) Phase 2 — closed-loop actor-critic co-training.
cotraining_loop(pitnn, controller, ref, cfg, n_episodes=5, n_steps=50)

# 5) Phase 3 — real-time inference (one control cycle).
#    The engine takes un-batched tensors: x_p shape [n_state], r shape [n_ctrl].
engine = RealtimeInferenceEngine(pitnn, controller, ref, horizon=50, device="cpu")
x_plant = torch.zeros(2)       # current plant state  [n_state]
r = torch.zeros(1)            # reference input      [n_ctrl]
out = engine.step(x_plant, r)  # -> dict: u_safe, e, v_hat, h_cbf, cbf_active, f_hat, ...

See examples/ — robotic_manipulator.py, autonomous_vehicle.py, building_hvac.py, and pcml_heat_diffusion.py — for full runnable closed-loop demos. Each exposes run(steps=..., show=False) -> dict and a main() entry point.

🔬 Key Features

1. Physics-Informed Learning

Energy conservation constraints enforced during training
PDE residuals minimize violations of governing equations
Symmetry preservation (e.g., translation/rotation invariance)
Curriculum learning balances physics vs data-driven objectives
Physics-Constrained ML (PCML, v0.3.0) upgrades soft physics penalties to hard constraint satisfaction: a soft mode augments the loss with DAE residuals (Patel et al. 2022), and a hard mode projects predictions onto the differential-algebraic constraint manifold via a differentiable KKT-Newton layer (DAE-HardNet, arXiv:2512.05881), activated dynamically once the data loss is small. See pits_mras.constraints and pits_mras.models.pcml.

2. Temporal Reasoning

Multi-step prediction loss ensures accurate future forecasting
Attention regularization prevents overfitting to spurious correlations
Temporal smoothness encourages stable long-term behavior
Causal LSTM prevents information leakage from future

3. Adaptive Control

Lyapunov-based stability guarantees boundedness of tracking error
Dual parameter adaptation for plant model and controller
Hybrid gradient + MRAS updates combine learning with control theory
Persistency of excitation conditions for parameter convergence

4. Real-Time Implementation

Thread-safe single-loop engine (RealtimeInferenceEngine) — implemented: lock-guarded @torch.no_grad closed-loop step() with bounded history, optional PCML projection bypass
Multi-rate parallel deployment (1 kHz control / 100 Hz adaptation / 10 Hz monitor) — ParallelInferenceEngine runs a real double-buffered IRL critic update and captures thread failures (fail-fast); still a scaffold (fixed inputs, cooperative scheduler — not hard-real-time)
Uncertainty quantification — deep-ensemble predictive variance plus split- and adaptive-conformal prediction intervals (pits_mras.utils.uq)
Rollout diagnostics — energy-drift, valid-prediction-time, and rollout-Jacobian spectral-radius monitors (pits_mras.utils.diagnostics)

5. Robust & Advanced Control

H∞ robust control — analytic GARE core (solve_gare + AdversaryHead) and a neural adversarial min-max training loop (NeuralAdversary + pits_mras.training.hinf_minmax)
Deep Koopman lifting — a Koopman lifting model with linear latent dynamics (pits_mras.models.koopman) plus a Koopman-LQR controller (pits_mras.controllers.koopman_control)
GENERIC / GFINN decoder — structure-preserving reversible-plus-irreversible dynamics (pits_mras.models.generic)
SAC and TD-MPC2 learners — soft actor-critic (pits_mras.training.sac) and a TD-MPC2-style world-model + MPPI planner (pits_mras.training.tdmpc)
Adaptive loss weighting — automatic balancing across the loss families (pits_mras.losses.adaptive_weighting)
Opt-in trajectory data — synthetic trajectory generation and a TrajectoryDataset / dataloader (pits_mras.data)

📊 Performance Targets

These are design targets from the framework specification — not yet experimentally validated. The example plants are now nonlinear (examples/plants.py) but still illustrative (not hardware-validated); the numbers below describe what the framework aims for, not measured results.

Robotic Manipulator Control

Tracking error: < 1 cm (vs 3 cm baseline)
Sample efficiency: 5x fewer demonstrations required
Adaptation time: < 500 ms to new payloads

Autonomous Vehicle Lateral Control

Lane keeping accuracy: ± 5 cm at 80 km/h
Disturbance rejection: 20% better than Model Predictive Control
Computational overhead: < 2 ms per control cycle

Building HVAC Optimization

Energy savings: 15-25% compared to conventional PID
Comfort maintenance: ± 0.5°C temperature regulation
Model adaptation: Handles seasonal variations automatically

Note: these are specification targets, not measured results. See the honest scope note under Project Status.

🛠️ Project Structure

PITS-MRAS/
├── docs/                          # Documentation
│   ├── architecture/              # Graph-backed OVERVIEW/ARCHITECTURE/COMPONENTS/API/DATAFLOW + dep-graph
│   ├── ROADMAP.md                 # 9 build phases + milestones
│   ├── PITS-MRAS — ...Adaptive Systems.md   # design spec (math framework)
│   ├── PITS-MRAS_VALIDATION_REPORT.md / _FINAL_SUMMARY.md   # validation of the design spec
│   └── superpowers/               # per-feature design specs + plans
├── src/pits_mras/                 # Implemented package (11 modules)
│   ├── config.py                  # PITSMRASConfig / NetworkConfig / PhysicsConfig / LossConfig / ...
│   ├── models/                    # PITNN, attention, port-Hamiltonian decoders, critic+costate+adversary, PCML, Lagrangian, Koopman, SAC, TD-MPC2, GENERIC/GFINN
│   ├── losses/                    # physics, temporal, stability, IRL, HJB, adaptive weighting + TotalLoss
│   ├── controllers/               # MRASController, LinearReferenceModel, CLF-CBF safety filter, Koopman-LQR
│   ├── constraints/               # PhysicsConstraints ABC, MechanicalDAE, HeatConductionDAE (PCML)
│   ├── training/                  # pretrain_pitnn, cotraining_loop, IRL trainer, H∞ min-max, SAC, TD-MPC2
│   ├── inference/                 # RealtimeInferenceEngine, ParallelInferenceEngine
│   ├── data/                      # synthetic trajectory generation + TrajectoryDataset (opt-in)
│   └── utils/                     # Lyapunov/Riccati engine (incl. GARE), Hamiltonian helpers, PE monitor, UQ, diagnostics, linearization
├── examples/                      # robotic_manipulator, autonomous_vehicle, building_hvac, pcml_heat_diffusion
├── tests/                         # pytest suite (test_models/losses/controllers/training/inference/pcml_*/identity_* ...)
├── tools/create-dependency-graph/ # standalone Python dependency-graph generator
├── CHANGELOG.md  README.md  requirements.txt  setup.py  LICENSE  .gitattributes
└── .github/workflows/ci.yml       # ruff (check + format) + mypy + pytest (Python 3.10–3.12)

📖 Citation

If you use PITS-MRAS in your research, please cite:

@article{pits-mras2025,
  title={PITS-MRAS: Physics-Informed Time-Series Neural Networks Enable Model-Reference Adaptive Systems},
  author={Simon Jr., Daniel},
  journal={GitHub Repository},
  year={2025},
  url={https://github.com/danielsimonjr/PITS-MRAS}
}

🤝 Contributing

Contributions are welcome! Please see our contributing guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow PEP 8 style guidelines for Python code
Add unit tests for new features
Update documentation for API changes
Ensure all tests pass before submitting PR

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Acknowledgments

This work builds upon foundational research in:

Physics-Informed Neural Networks (Raissi et al., 2019)
Model-Reference Adaptive Control (Narendra & Annaswamy, 1989)
Transformer Architectures (Vaswani et al., 2017)
Port-Hamiltonian Systems (Van der Schaft & Jeltsema, 2014)

📧 Contact

For questions, suggestions, or collaboration opportunities:

GitHub: @danielsimonjr
LinkedIn: danielsimonjr
Website: danielsimonjr.github.io/resume
Issues: GitHub Issues
Discussions: GitHub Discussions

🗺️ Roadmap

See docs/ROADMAP.md for the phase-by-phase build plan and CHANGELOG.md for the full per-release history.

Implemented

The package ships the full build (config/math → models → losses → controllers → training → inference → examples → tests → CI) plus:

✅ PCML — soft (augmented-loss) and hard (DAE-HardNet KKT-projection, with line-search-robust Newton solve) physics-constraint enforcement
✅ H∞ robust control — analytic GARE core (solve_gare + AdversaryHead) and the neural adversarial min-max training loop
✅ Deep Koopman lifting + Koopman-LQR control, GENERIC/GFINN structure-preserving decoder, SAC and TD-MPC2 learners
✅ Uncertainty quantification (deep ensembles + conformal intervals) and rollout diagnostics
✅ Nonlinear example plants (pendulum, tyre-saturation lateral, RC thermal) and opt-in trajectory data/

Future

🔮 Multi-agent coordination · hierarchical PITS-MRAS · GPU/TPU acceleration · real-time monitoring dashboard · experimental hardware validation

👤 Author

Daniel Simon Jr.

Systems Engineer specializing in Test Program Set Development and Avionics Testing
B.S. Electrical Engineering, University of Texas at Dallas
Currently: Senior Test Engineer, Lockheed Martin
Background: Control Systems, Automated Test Equipment, Physics-Informed AI

Research Interests:

Physics-informed machine learning for control systems
Model-reference adaptive control with stability guarantees
Integration of domain knowledge in neural network architectures
Real-time adaptive systems for aerospace and robotics

Connect:

Built with ❤️ for robust, physics-aware adaptive control

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
examples		examples
src		src
tests		tests
tools		tools
.dropboxignore		.dropboxignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
GITHUB_SETUP.md		GITHUB_SETUP.md
LICENSE		LICENSE
PROJECT_SETUP_SUMMARY.md		PROJECT_SETUP_SUMMARY.md
README.md		README.md
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup.py		setup.py
todo.md		todo.md

Latest commit

History

Folders and files

Repository files navigation