Architecture Overview | Oakfield Operator Calculus, Co.

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

Field ↔ Operator ↔ Integrator ↔ Scheduler ↔ Profiler/Logger
        ↑                ↓
     Registry          Ensemble

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 through eight registered integrators.
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

Multidimensional field buffers; the Lua API exposes double and complex_double storage.
Physical or spectral representation metadata, with real or complex value interpretation.
Field allocation and initialization through the field API.
Explicit runtime ownership; Lua Field handles are pinned to their context’s lifetime.

Analogy: In OOC terms, the field 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 𝒪 : ℱ → ℱ. The runtime composes executable operators through their field dependencies. The schema provides mathematical views and parameter symbols; it does not perform symbolic simplification or algebra-aware graph computation.

5. Integration Layer — Time Functors

Purpose

Provides functors ℐ that map static operators into time-evolving flows.

Core Integrators (Current runtime)

The runtime registry and Integrator Catalog contain eight methods:

Name/ID	Method	Description
`“rkf45”`	Runge–Kutta–Fehlberg	Adaptive-step deterministic solver.
`“rk4”`	Runge–Kutta	Fixed-step fourth-order solver.
`“etdrk4”`	Exponential time differencing RK4	Fixed-step solver for supported semilinear, single-field complex plans with exact linear flow.
`“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.

Stochastic forcing is available through noise operators and the subordination integrator’s stochastic options.

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 worker threads and supported execution backends.
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	Analytic profiles including digamma, trigamma, and hyperexponential warps.
Measurement	Phase features, convolution, sieves, and sound observation.
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.
Neural Inference / Hybrid	Experimental inference and analytic-plus-residual operators; training and autograd are outside the current runtime’s capabilities.
Thermostat	Energy-regulating feedback operators.
Remainder (Complex)	Complex/polar residue measurement for analytic comparisons.

9. Execution Flow

[ Field Initialization ]
↓
[ Operator Graph Build ]
↓
[ Integrator Selection ]
↓
[ Scheduler Dispatch ]
↓
[ Profiling / Logging / Visualization ]

Each step corresponds directly to one morphism in the operator calculus.

10. Runtime Scope

The runtime executes numerical field operations. General symbolic computation, automatic differentiation, training workflows, and quantum operator lifts are outside its documented capabilities. The Lua API reference describes the available interfaces.

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.