EPSILON-PHASE

EPSILON-PHASE is an interactive wind-simulation physics engine with a built-in frontend, powered by a numeric robustness layer for quantization and noise handling.

What It Does (Plain English)

You can open a local wind tunnel UI, choose a shape (circle, square, triangle, or airfoil), set wind conditions, and immediately see the simulated flow field.

Under the hood, EPSILON-PHASE runs a 2D fluid-style simulation and stabilizes its numeric updates with stochastic resonance + subtractive dithering.

In practical terms, it can:

• run wind simulation on multiple shapes,
• visualize speed fields and flow vectors in a frontend canvas,
• estimate drag/lift proxies and wake deficit,
• reduce quantization artifacts that create "steppy" numeric behavior,
• inject controlled noise when progress is flat,
• keep error less correlated with the original signal,
• report clear metrics (SNR change, MSE, stability norms),
• plug into real-time or offline systems through a stable pull_chunk() noise-input contract.

Core Capabilities

• Primary API: epsilon_phase.architecture.NumericRobustnessLayer
• Physics API: epsilon_phase.physics.simulate_wind_field
• Local wind-lab frontend: epsilon-phase-windlab
• Adaptive stochastic resonance gain control
• Subtractive dithering for quantization decorrelation
• Optional GPUDirect-compatible ring ingestion
• Reproducible robustness and flow benchmarks

Important Math

This section captures the key equations implemented by the code.

1) Noise normalization

Environmental noise is centered and scaled before mixing:

$$ z_t = \frac{n_t - \mu(n_t)}{\sigma(n_t) + \varepsilon} $$

where $n_t$ is raw noise, and $\varepsilon$ prevents divide-by-zero.

2) Stochastic resonance injection

The deterministic signal $x_t$ is mixed with normalized noise using adaptive gain $g_t$:

$$ x_t^{(sr)} = x_t + g_t z_t $$

3) Adaptive gain update

Let $m_t$ be a progress metric (or loss proxy). Gain increases when progress is flat, and decays when progress changes strongly:

$$ g_{t+1}= \begin{cases} \min(g_{\max}, g_t \alpha_{\uparrow}) & \text{if } |m_t - m_{t-1}| < \tau \\ \max(g_{\min}, g_t \alpha_{\downarrow}) & \text{otherwise} \end{cases} $$

4) Subtractive dithering and quantization

Draw dither from a uniform distribution:

$$ d_t \sim \mathcal{U}\left(-\frac{\Delta}{2}, \frac{\Delta}{2}\right) $$

Quantize with step size $\Delta$:

$$ Q(u) = \Delta \cdot \mathrm{round}\left(\frac{u}{\Delta}\right) $$

Apply subtractive dither:

$$ y_t = Q\left(x_t^{(sr)} + d_t\right) - d_t $$

This reduces signal-correlated quantization error.

5) Quality metrics

Output error:

$$ e_t = x_t - y_t $$

Mean squared error:

$$ \mathrm{MSE} = \mathbb{E}[e_t^2] $$

Signal-to-noise ratio form used by the layer:

$$ \mathrm{SNR}(r,e) = 10\log_{10}\left(\frac{\mathbb{E}[r^2]}{\mathbb{E}[e^2] + 10^{-12}}\right) $$

with benchmark delta:

$$ \Delta \mathrm{SNR} = \mathrm{SNR}_{out} - \mathrm{SNR}_{in} $$

6) Stability benchmark recurrence

The stability benchmark tracks iterative boundedness with:

$$ s_{t+1} = 0.92, s_t + 0.08, y_t $$

and reports $|s_t|_2$ statistics.

7) Optional stochastic dynamics (SDE module)

For users who need stochastic state updates, EPSILON-PHASE also provides:

$$ s_{t+\Delta t} = s_t + f_t\Delta t + \sigma_t J_t \sqrt{\Delta t}, z_t $$

with optional post-step subtractive dithering and norm clamping.

8) Wind simulation update model

The wind engine uses a fluid-style velocity update with diffusion, advection, and pressure projection:

$$ u^* = u_t + \Delta t\left(- (u_t \cdot \nabla)u_t + \nu\nabla^2u_t + f_{wind} + f_{turb}\right) $$

$$ \nabla^2 p = \frac{1}{\Delta t}\nabla \cdot u^* $$

$$ u_{t+1} = u^* - \Delta t\nabla p $$

Obstacle boundary condition (no-slip approximation inside obstacle mask):

$$ u_{t+1}(x) = 0, \quad x \in \Omega_{obstacle} $$

Tracer transport used for wake visualization:

$$ \rho_{t+1} = \mathrm{Advect}(\rho_t, u_{t+1}) + \kappa\nabla^2\rho_t $$

Numeric robustness can be applied to velocity channels each step:

$$ u_{t+1}^{(robust)} = \mathcal{R}(u_{t+1}, z_t), \quad v_{t+1}^{(robust)} = \mathcal{R}(v_{t+1}, z_t) $$

where $\mathcal{R}$ is the resonance+dither layer defined in sections 2-4.

Default Parameter Intuition

• Base resonance gain is small (0.02) to avoid overwhelming the signal.
• Gain is bounded (0.005 to 0.30) for numerical safety.
• Quantization step defaults to 1/4096 as a practical fine-grain baseline.

Repository Layout

• src/epsilon_phase/: Python package (numeric layer, runtime hooks, benchmarks)
• src/epsilon_phase/physics/: wind simulation engine
• src/epsilon_phase/windlab/: local frontend server and web UI assets
• tests/: Python tests for robustness behavior and benchmark execution
• docs/: architecture and roadmap for numeric robustness
• rust/epsilon_prefetch/: optional experimental prototype track

Quickstart

1. Create a Python environment

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install -e .[dev]

2. Run Python tests

pytest -q

3. Run local robustness benchmarks

epsilon-phase --benchmark quantization --steps 8 --dim 128
epsilon-phase --benchmark stability --steps 8 --dim 128

4. Launch the interactive wind lab frontend

epsilon-phase-windlab

Open your browser at http://127.0.0.1:8787 if it does not auto-open.

5. Minimal Python usage

import numpy as np

from epsilon_phase.architecture import NumericRobustnessLayer
from epsilon_phase.runtime import GPUDirectRDMARing

layer = NumericRobustnessLayer(vector_dim=128)
ring = GPUDirectRDMARing(seed=42)
noise = ring.pull_chunk(128)

signal = np.linspace(-1.0, 1.0, 128)
result = layer.process(signal, noise, progress_metric=1.0)

print(result.snr_delta_db, result.mse)

Scope

EPSILON-PHASE now targets a concrete end-to-end goal: an interactive wind physics engine for trying multiple shapes in a frontend, with numeric robustness built directly into the simulation pipeline.

Status

This repository is software-first and integration-ready. The current ring layer is a compatibility hook with simulation fallback. Replace the producer side with your transport while preserving the pull_chunk() API.

License

MIT