# Theoretical Framework: ODE-Programming & Rheo
## 1. Core Metaphysics & Paradigm Inversion
Traditional programming relies on a **discrete approximation of reality**, slicing time into arbitrary finite steps ($\Delta t$) and accumulating numerical drift and phase errors. **ODE-Programming** fundamentally flips this paradigm by elevating continuous differential equations directly into first-class source code.
| Traditional Imperative Programming | Declarative ODE-Programming (Rheo) |
| --- | --- |
|
**Assignment is the Primitive:** `x = x + dt * f(x)`
|
**Derivative is the Primitive:** $\frac{dx}{dt} = f(x, t)$
|
|
**State as Value:** Stored as static memory register values.
|
**State as Trajectory:** Treated as a continuous-time function $x(t)$.
|
|
**Discrete Time:** Governed by explicit `for`/`while` loops.
|
**Continuous Time:** Time $t \in \mathbb{R}$ is a smooth parameter.
|
|
**Accumulated Drift:** Unbounded truncation errors over time.
|
**Bounded Error:** Strictly guaranteed to user-defined tolerances.
|
Under this paradigm, **control flow is abolished**. Iteration and branching emerge organically from vector fields and root-finding events rather than explicit conditionals.
---
## 2. Mathematical Foundation
Rheo compiles declarative equations into rigorous mathematical systems solved by specialized adaptive algorithms:
*
**Initial Value Problems (IVPs):** Modeled as $\frac{d\mathbf{x}}{dt} = \mathbf{f}(\mathbf{x}, t), \mathbf{x}(0) = \mathbf{x}_0$. Well-posedness is governed by the **Picard-Lindelöf theorem**, which guarantees a unique solution given Lipschitz continuity in $\mathbf{x}$.
*
**Stiffness Control:** Systems exhibiting widely separated timescales (e.g., rapid chemical transitions alongside slow equilibria) are evaluated dynamically. Rheo computes the local Jacobian Matrix ($J = \frac{\partial f}{\partial x}$) to analyze its eigenvalues. If the local stiffness ratio passes a threshold, it transitions from explicit methods to highly stable implicit solvers.
*
**Differential-Algebraic Equations (DAEs):** Modeled as $\mathbf{F}(\mathbf{x}, \dot{\mathbf{x}}, t) = 0$ to enforce exact invariants (such as physical constraints in mechanics or circuits) without drifting away from the constraint manifold.
*
**Delay (DDE) & Stochastic (SDE) Systems:** Supports delayed recursion through continuous history buffers evaluated via dense interpolation. Stochastic behaviors are modeled using Brownian Wiener processes ($dW$), defaulting to Itô calculus integration rules.
---
## 3. Compiler & Execution Architecture
Rather than interpreting code sequentially, the Rheo compiler builds a mathematical model optimized for underlying computational graphs:
```
[Source Code Equations] ──> [Variable Dependency DAG] ──> [Automatic Differentiation (AD)] ──> [Stiffness Profiling] ──> [Target Code Generation (LLVM/CUDA)]
```
1.
**Variable DAG Optimization:** Constructs a Directed Acyclic Graph tracking equation dependencies to perform symbolic simplifications, isolate sparsity structures, and map execution paths.
2.
**Exact Automatic Differentiation (AD):** Computes machine-precision Jacobians and Hessians exactly via Forward-mode or Reverse-mode AD. This completely eliminates the numerical error associated with traditional finite-difference approximations.
3.
**Dynamic Method Selection Hierarchy:** Integrations are handled by selecting algorithms specialized to the topological traits of the vector field:
*
*Dormand-Prince 5(4) / 8(7):* Default explicit Runge-Kutta embedded pairs designed for high-accuracy, non-stiff regimes.
*
*Backward Differentiation Formulas (BDF / Gear Methods):* Variable-order implicit multi-step methods reserved for standard stiff profiles.
*
*Radau IIA & Symplectic Gauss Integrators:* Implicit Runge-Kutta frameworks specialized for DAE index reductions and long-term energy conservation in Hamiltonian mechanics.
---
## 4. Error Constraints & The Accuracy Invariant
Accuracy behaves as a strict language invariant rather than a post-processing metric. The compiler guarantees that the numerical trajectory $\tilde{x}(t)$ conforms to user-specified absolute (`atol`) and relative (`rtol`) tolerances across the entire domain:
$$|\text{LTE}| \leq \max(\text{atol}, \text{rtol} \cdot |x|)$$
To ensure this constraint holds without killing performance, the solver implements **Adaptive Step Size Control** steered by a PID loop. Embedded pairs calculate local truncation error (LTE) tracking vectors for free at each step. If the error violates bounds, the step is discarded, the step size $h$ is throttled down dynamically, and the integration step is automatically retried.
Output is returned as **Dense Output**—a continuous Hermite polynomial interpolant spanned across execution steps—enabling users to evaluate state variables with high precision at any arbitrary slice of continuous time.
---
## 5. Syntax & Programming Reference Guide
### Variable Declarations
```rheo
// Continuous-time states initialized at t = 0
state x = 1.0 // Scalar state
state positions[3] = [0.0, 1.0, 2.0] // Vector state
// Static parameters and compile-time constants
param g = 9.81 // Sweppable simulation parameters
const pi = 3.141592653589793 // Immutable constant values
```
### High-Order Derivatives
Higher-order derivatives are treated natively. The compiler automatically decomposes them down into canonical first-order systems via internal auxiliary variables:
```rheo
// Declaring a classic Second-Order Harmonic Oscillator
d2x/dt2 = -omega² * x
```
### Execution Blocks & Boundary Rules
The `evolve` block establishes the definitive temporal domain, accuracy bounds, and tracking diagnostics for computation:
```rheo
evolve 0..10 with
abs_tol = 1e-12,
rel_tol = 1e-9,
stiffness_monitor = true
```
### Precise Discontinuous Events
Transitions and collisions use precise root-finding algorithms (e.g., Brent's Method) to track boundaries down to machine precision ($\approx 10^{-15}$ s), eliminating missing interactions caused by discrete polling steps:
```rheo
// Modeling a precise instantaneous collision bounce event
when y crosses 0 from above:
vy <- -e * vy
```