🧱 Oakfield Architecture Overview
1. Introduction
The Oakfield runtime architecture implements the Oakfield Operator Calculus (OOC) in C++. It provides the computational substrate — the memory layout, scheduling, and numerical kernels — that bring the abstract operator algebra to life.
The runtime is modular and extensible. Every operator, field, and integrator is defined through a common interface, allowing them to be composed dynamically at runtime or patched interactively in the UI.
2. High-Level Structure
At the highest level, Oakfield consists of five tightly integrated subsystems:
| Layer | Responsibility |
|---|---|
| Field Layer | Memory and data layout for scalar/vector/tensor fields. |
| Operator Layer | Defines analytic, stochastic, and differential transformations. |
| Integration Layer | Time evolution and step control (RKF45, EM, etc.). |
| Scheduling Layer | Multi-threaded task orchestration and execution graph. |
| Instrumentation Layer | Profiling, logging, configuration, and runtime introspection. |
3. Field Layer — The State Manifold
Role: Defines the field space ℱ, the domain on which all operators act.
Key Features
- N-dimensional, strongly typed data containers (
float,double,complex, etc.) - Contiguous or strided layouts suitable for CPU and GPU backends
- Pluggable allocators for pinned or device-aware buffers
- Explicit ownership semantics (create/destroy) rather than shared/RC handles
Analogy: In OOC terms, SimField is the object of the category — the carrier manifold for dynamics.4. Operator Layer — The Algebra Engine
Purpose
Implements the operator algebra 𝒪: the set of morphisms acting on fields.
Operators are registered at runtime via descriptors that bind user state, field ports, and evaluation callbacks. The system builds a dependency graph from those descriptors and schedules evaluations on demand.
Relation to OOC
Operators here correspond to morphisms in the category 𝒪 : ℱ → ℱ. Composition and commutation are implemented as graph operations in the IR.
5. Integration Layer — Time Functors
Purpose
Provides functors ℐ that map static operators into time-evolving flows.
Core Integrators (Current runtime)
| Name/ID | Method | Description |
|---|---|---|
"rkf45" | Runge–Kutta–Fehlberg | Adaptive-step deterministic solver. |
"rk4" | Runge–Kutta | Fixed-step fourth-order solver. |
"heun" | Heun / RK2 | Two-stage predictor–corrector with better stability than Euler. |
"euler" | Forward Euler | Simple explicit, fixed-step integrator. |
"backward_euler" | Backward Euler | Implicit first-order integrator for stiff drifts. |
"crank_nicolson" | Crank-Nicolson | Semi-implicit second-order scheme. |
"subordination" | Convolution kernel | Implements fractional-time subordination. |
Integrators are registered dynamically and operate over the scheduled operator graph, evaluating sub-steps as needed. They are functors in the OOC sense: they act on morphisms to produce time-evolved flows.
6. Scheduler Layer — Runtime Orchestration
Purpose
The simulation scheduler manages the execution of all registered operators and integrators over time.
Responsibilities
- Builds execution DAGs (directed acyclic graphs) from operator dependencies.
- Dispatches computation across CPU cores or GPU streams.
- Synchronizes I/O and logging.
- Supports asynchronous, event-driven simulation (restarts, checkpoints, dynamic operator injection).
Analogy: The scheduler is the ensemble functor — it coordinates multiple operator evaluations into a consistent temporal evolution.
7. Instrumentation Layer — Observation and Feedback
| Component | Role |
|---|---|
| Profiler | Records execution time, kernel latency, and memory bandwidth per operator. |
| Logger | Asynchronous, lock-free message system for diagnostics and analytics. |
| Config Hooks | Integration points for embedding in UIs or scripting layers (Lua, etc.). |
This layer provides the feedback that turns Oakfield from a black box into a playable instrument. Profiling and logging correspond to observation operators in the calculus — real-world sieves on performance and behavior.
8. Operator Families (Current Modules)
| Operator Family | Description |
|---|---|
| Stimulus | Base waveform and field generators. |
| Phase Feature | Extracts phase or coordinate features. |
| Analytic Warp | Core analytic transformations (digamma, Bessel, Gaussian). |
| Measurement | Remainder–sieve–mixer loop with symbolic descriptors. |
| Linear Dissipative | Implements linear decay or damping operators. |
| Fractional Memory | Fractional differential and hereditary kernels. |
| Stochastic Noise | White and colored noise injectors. |
| Coupling/Mixer | Field combination, bias, and mixing operators. |
| Spatial Derivative | Finite-difference gradient/Laplacian families. |
| Thermostat | Energy-regulating feedback operators. |
| Remainder (Complex) | Complex/polar residue measurement for analytic comparisons. |
Upcoming:
- Measurement metrics helpers (complexity summaries, curvature spectra)
- Visualization bridge for live measurement inspection
9. Execution Flow
Each step corresponds directly to one morphism in the operator calculus.
10. Future Architecture Expansions
| Module | Goal | Description |
|---|---|---|
| Measurement Metrics | Complexity feedback loop | Higher-order analytics built on remainder/sieve outputs |
| Neural Operator Layer | Learning integration | Runtime-trainable analytic operators |
| Quantum Operator Layer | Operator lifting | Mode-based Fock-space evolution |
| Visualization Engine | Real-time "oscilloscope" | GPU-based analytic waveform renderer |
| Patch Interface | Modular operator graph UI | Drag-and-drop composition of operators |
11. Summary
Oakfield's architecture is the embodied calculus. Where OOC provides the theoretical rules of composition, the architecture executes them — faithfully, efficiently, and interactively.
It's built to grow by composition, not replacement: every new operator or integrator extends the language of the system without breaking it.
In short: the architecture is to Oakfield what circuitry is to a modular synthesizer — it carries the current that makes the math audible.
Ready to explore the implementation?