Physics-First Instrument Architecture

Why this simulator is structured like a laboratory instrument (not a toy)

Most simulators start with UI and “make the math fit”. This project intentionally does the opposite: we treat the solver as the instrument, and the interface as a thin control surface.

Design Philosophy

Physics first. Rendering second. UI last.

Strict architectural direction:

state → core → physics → metrics → panels → rendering → ui → main

No circular imports.
No hidden coupling.
No solver logic inside UI.

Architecture Flow Diagram

Rule: Dependencies may only flow downward. Upstream layers must never import downstream layers.

What “Physics First” means (in practice)

• Determinism: identical inputs produce identical waveforms and metrics.
• Frame-rate independence: slower rendering must not change physics results.
• Auditability: equations and state variables are visible and testable.
• Instrument behavior: UI can be removed without changing solver correctness.

The One-Way Dependency Rule

Every layer is allowed to depend only on layers to its left. Nothing “downstream” may be imported “upstream”. This prevents circular imports and prevents accidental feedback loops.

Layer	Responsibility	May depend on
state	Mutable runtime parameters (inputs)	—
core	Pure helpers (τ, Rtotal, periods, duty)	state
physics	Closed-form kernels (RL/RLC waveforms)	state, core
metrics	Measurement math (P/Q/S, energy per period, validation)	state, core, physics
panels	Formatting + presentation synthesis (numbers → UI)	metrics
rendering	Canvas drawing (scope, field, helix)	physics (via wave builder), panels (readouts)
ui	Event binding (sliders, toggles, focus mode)	state (write), rendering hooks (callbacks only)
main	Orchestration + lifecycle (init + loop)	everything (as a coordinator)

Why “No Solver Logic in UI” is critical

If solver logic lives in UI code, then:

• results can change due to UI timing
• bugs hide inside event handlers
• testing becomes almost impossible
• later refactors break physics silently

Instead, UI is restricted to two safe actions:

• Write state: L, R, C, f, duty, timebase, topology…
• Change visibility: show/hide controls, switch view modes

Rendering is not allowed to influence results

Rendering is downstream. It consumes already-computed waves/metrics and draws them.

This is why the simulator stays defensible: even if you export a PNG, pause the view, or drop to 15 FPS, the computed values are unchanged — only the presentation changes.

“No Hidden Coupling” (what we actively avoid)

Hidden coupling is when two parts of the app affect each other without an explicit interface. Examples we avoid:

• physics reading canvas size
• metrics writing directly into DOM
• render loop modifying solver parameters
• UI calling private physics internals directly

Instead, data flows in one direction: inputs → state → physics/metrics → panels/render → pixels.

Why this matters for a reference-grade tool

• Reproducibility: the same settings produce the same output today and later.
• Defensibility: you can explain where every number comes from.
• Modularity: you can replace the renderer without touching physics.
• Validation: you can build test harnesses against physics + metrics only.

A short “instrument contract”

The math must remain correct if the UI is deleted.
The UI must remain functional if the renderer is replaced.
Rendering must never change physics.

Where to go next

• For formulas and derivations: Mathematics
• For verification methodology: Validation
• For how metrics are interpreted: Measurement