Circuit Lab

Development biography · earlier archive

Development profile compiled from project source and retained records in October 2026. Dates and test results describe those records; they do not imply a new build, live acceptance test or public release.

Circuit Lab (engine package families)

Origin and purpose: Built from an expanded brief and a 37-chapter scientific manuscript covering vintage components, dielectric and semiconductor physics, electromechanics, fitting and circuit discovery. The long-term aim is a circuit editor and discovery game above the engines (Chapter 37); the implementation map says plainly that the manuscript is complete and the software is not .

Audience: Engineers and researchers who want inspectable, test-backed reference models with stated limits, and the author's own downstream apps (Workbench, Bend Explorer, Stellar).

Features: Highlights: loaded voltage divider, Newton diode solve, RC with coherent sine, 12-bit ADC with Hamming SECDED damage and correction, DSP filter with THD+N ; practical transformer with magnetising, leakage, core loss and interwinding capacitance; magnetic core with cubic saturation and stop hysteresis; BJT and MOSFET charge storage; parasitic networks and subcircuits . Milestone 0.36 adds general charge-coordinate reduction preserving energy across nonlinear capacitor meshes .

User workflow: swift test at the root, then swift run circuit-lab plus flag variants that write JSON/CSV/WAV evidence to DemoOutput/ . Examples/PackageClient shows consuming the packages from another app.

Architecture and packages: CircuitLabCore, Components, Circuits, Audio, Logic, Converters, DSP, Physical, Measurements, Engineering, each with its own manifest under Packages/ and local sibling dependencies; not published or versioned releases . Solver: checked Double arithmetic, dense row-equilibrated pivoted solve capped at 512 unknowns, rejects floating or singular systems, no hidden conductance .

Maturity and evidence: Milestones 0.2 through 0.36 each documented in Documentation/Roadmap.md and per-milestone folders . Live ngspice comparisons cover restricted RC, transistor, charge-storage, transformer and oversampled diode fixtures . Coverage map updated from the main estate review on 18 October: 403 catalogue entries, 70 standalone capabilities, 40 circuit-integrated and 293 planned. The Workbench review above describes its separate inspected copy.

Roadmap: Chapter 37 tracks: calibrated device laws, general DAE index reduction and impacts, Bayesian identification, sensitivities and adjoints, reduced real-time processors, Accelerate/Metal backends, the discovery game UI .

Limits: No measured-device calibration, no general SPICE interchange, no GPU backend, no plug-in export, no game UI . Tape relaxation is lag, not hysteresis.

FAQ: Is it real-time? No; offline rendering with explicit delay. Is it SPICE? No, but selected fixtures are compared against a pinned ngspice. Can I use one package alone? Yes, via local path dependency; nothing is published.

Circuit Lab Workbench

Origin and purpose: The first UI above the engines; it exists to make the solver's behaviour visible and audible with every caveat on screen. Three sessions (main, fuzz, MXR) plus bending and engine sessions have added surfaces independently; a normalisation plan dated 2026-10-17 now proposes one window, one Study document, one control catalogue .

Audience: The author as researcher-musician; demonstrators who need an honest "this is a reconstruction" surface.

Features and workflow : Gear locker on launch; create a Fuzz Factory reconstruction study or the RC "Paper & current" example. Add parts from the library, wire terminals, orbit the specimen, apply Moisture/Heat/Cool/Corrosion/Mechanical stress recipes; leakage becomes a parallel resistor. Timeline with 100 snapshots, ⌘Z branching undo, versioned JSON studies (schema 5–6). Run circuit (⌘R) with sine/DC/step stimulus, settling and oversampling; scope, spectrum and measurements share one capture; JSON export with provenance. Fuzz Factory: drag the five photographic knobs (Shift fine, double-click reset, one undo checkpoint per drag); Use Doug's guitar or Load audio for offline audition; Circuit & components editor exposes the solver's real netlist; Audio I/O preferences and Live input stream an interface through the circuit with 23.2 ms lookahead .

Architecture and packages: Apps/CircuitLabWorkbench/Package.swift: WorkbenchCore (Study, SimulationContract), WorkbenchSimulation (CircuitLabAdapter, FuzzFactoryCircuit), FuzzLiveKernel (C++ with AudioToolbox), executable CircuitLabWorkbench; depends on ResearchControls and AuioIO (external Xcode/Utilities), CircuitLabCircuits/Components/Audio/DSP/MXR/Measurements and CircuitLabBendingUI. Source boundaries table at README lines 56–69.

Maturity and evidence: Version history v0.2 → v0.21 in Documentation/Workbench/ . v0.10: 88 tests; v0.21: 137 release tests, 45 guitar cases, 135 timestep runs, zero underruns in the recorded workloads, but the 3% cross-timestep accuracy target is unmet . Live timing is an observation, not a deadline certificate . Note: the app README's status line still says v0.16.0 while evidence runs to v0.21; treat the README header as stale.

Roadmap: UI normalisation steps B–G (one window, one Study kind per gear/RC/bend, one WorkbenchUI control catalogue, positional shortcuts, chip vocabulary, AX audit); pending ordered branches for fuzz v0.22 and AUv3, MXR rotary enclosures, component inventory placement, keyboard/MIDI performance surface .

Limits: E1 candidate is a Flare-derived reconstruction with synthetic transistors; interface voltage scaling assumed not calibrated; external interface not yet physically accepted ; adapter limited to 32 parts; THD unavailable until periodicity gate passes.

FAQ: Is the pedal sound accurate? No claim; it is an uncalibrated reconstruction and says so on screen. Does it run live? Yes with a buffered path and visible underrun counters; no real-time certification. Does it need special hardware? macOS 26, Swift 6.2, a Metal Mac.

Fuzz Factory research

Origin and purpose: A 56-section original specification, a Claude review, an independent mathematical audit (2026-10-13) and their reconciliation . Purpose: make "circuit reproduced", "hardware calibrated" and "real-time qualified" separate, testable claims .

Audience: Future implementers and reviewers; readers interested in how a modelling claim is bounded.

Features and workflow: Read documents 01–08 in order; run python3 Checks/check_pack.py for structure, links, template contracts and mathematical fixtures; verify payload hashes with Checks/verify_manifest.py . Templates: topology/evidence register, five-control worksheet, experiment and device records, acceptance matrix.

Architecture: Pack-v1.0/04-Architecture-Roadmap.md maps reuse of existing Circuit Lab packages. The running E1 candidate lives in Apps/CircuitLabWorkbench/Sources/WorkbenchSimulation/FuzzFactoryCircuit.swift and FuzzLiveKernel (C++), with the pot-travel convention (300 degrees, 21 optional clock positions, unverified mechanically) recorded in the plan .

Maturity and evidence: Pack: prepared and verified, delivery verification JSON . Candidate: v0.6 ngspice default-fixture oracle (Documentation/Workbench/Evidence-v0.6), all 32 knob endpoint combinations finite , v0.21 germanium accuracy evidence as above.

Roadmap: Calibrated implementation after the Circuitry roadmap; specimen measurements; AUv3 effect and photographic editor lab in the unmerged ordered/fuzz-v0.22 branch .

Limits: Exact hardware topology and specimen data open; the older reviews contain superseded wiring assumptions and must not be used as instructions .

FAQ: Is this the real Fuzz Factory circuit? No; a Flare-derived E1 reconstruction with declared substitutions. Why publish an uncalibrated model? Because the method, not the sound, is the deliverable.

Circuit Bending

Origin and purpose: A 25-part proposal consolidated in Documentation/CircuitBending/Roadmap.md: four operating modes (circuit, physical, computational, performance bend), bend graph, prepared variants, attribution, DSP export. Governing rule: a bend must enter the circuit equations; no DSP effect substitutes for a claimed modification . Implementation started 2026-10-16 in an isolated worktree on advice recorded in README lines 20–30.

Audience: Sound designers and experimental musicians who want causes, not just results; researchers in attribution.

Features and workflow : choose Diode clipper or Loaded RC, set input, frequency, samples per cycle and integrator; configure three resistive bridges; Preview connections runs 24 DC checks; Run experiment solves eight equilibrium/burst/silence subsets; Compare A with B; inspect burst RMS, peak or tail mean-square with Shapley allocation and signed pair/triple interactions; Export report (schema-2 JSON); Save study preserves net identities and layout. Listen, Test tone or note buttons, B1/B2/B3 live slot switches, MIDI notes 21–108 and CC20–22, Panic.

Architecture and packages: Packages/CircuitLabBending (pure attribution target with no solver import; CircuitLabBendingExperiments on CircuitLabCircuits; bend-experiment CLI), Packages/CircuitLabBendingUI (SwiftUI/Charts views shared by both hosts), Apps/BendExplorer, Workbench integration in Apps/CircuitLabWorkbench/Sources/CircuitLabWorkbench/BendExplorerIntegration.swift. Live path: fixed three-slot C kernel, serial producer rendering 128-frame chunks into a 16384-frame SPSC ring with 4096-frame reserve (92.9 ms at 44.1 kHz), AVAudioSourceNode consumer that allocates nothing, silence latched on underrun or three late callbacks .

Maturity and evidence: Phase 1 attribution and phase 2 RC/diode fixtures implemented with ngspice 8/8 comparisons; 24 DC preview checks; fixture documents with layout-invariance tests; prepared runtime candidate awaiting engine review; live audio exercised on an actual device and virtual MIDI with no quiet-machine admission . Evidence folders: Evidence-Phase1-RC, Evidence-Phase2-Diode, Evidence-App-0.1/0.2, Evidence-Preview-0.4, AudioKernel, PreparedRuntime, LiveAudio (JSON, CSV, manifests, logs). Known UI issue: system Open/Save panels could not be driven by native automation; path dialogs are the tested fallback .

Roadmap: general bend graph, dynamic C/L activation, phase 3 state-transfer contract, spectral and THD measurements, sample-accurate live control, discovery engine and DSP export; migration into a Workbench Study kind under normalisation step D.

Limits: Uncalibrated synthetic diode fixture; three resistive bridges only, 100 Ω–1 MΩ; recovery is a finite-window observation; MIDI not timestamp-scheduled; engine review of the state-transfer candidate pending.

FAQ: Is Shapley attribution causal? It allocates measured interaction among the three bends; no causal claim beyond the measurement . Can I bend any circuit? Not yet; two fixtures.

Stellar oscillators and networks

Origin and purpose: Implemented from three brainstorming documents as a dependable oscillator foundation with explicit unit conventions (phase in cycles, frequency in Hz) and no hidden state .

Audience: Instrument developers who want a source-level real-time-safe kernel with honest guarantees; researchers in coupled oscillators.

Features and workflow: Oscillator(waveform:sampleRate:quality:precision:) render into caller-owned buffers; through-zero FM via negative frequency; OscillatorGraph with modulation connections and per-sample controls, compile-time cycle checks, 256 nodes / 4096 routes maximum; KuramotoNetwork with sparse coupling and coherence; IntentCompiler producing archived experiment JSON . Consume via local path dependency on an individual package.

Architecture: each package under Packages/Stellar* with its own manifest and tests, also registered at the workspace root. Kernel: no allocation, no locks, bounded per-sample work as a source property . Prepared network rendering with immutable signal pointers and grouped routes for the device adapter .

Maturity and evidence: Physical-device validation 2026-10-13 on Apple M3 Pro, 44.1 kHz, 512-frame callbacks: an optimised 32-node / 64-route / 4x graph completed a 60-second speaker soak with no budget miss, discontinuity, HAL overload or DSP rejection; dense 256-node / 4096-route graphs still overloaded at 4x and 2x; headphones dropped from Core Audio during a stress run . Further evidence folders: Buffer64, Controlled64, Dense4x, HostTrace64, Oversampling, PairedGap64, PreparedRendering, Resident64, Scheduler64, SmallBuffers, Sustained64, each with README and JSON. No acoustic loopback or end-to-end latency measured.

Roadmap: GPU synthesis and FFT acceleration not implemented; seamless graph handover not implemented; hard-sync anti-alias not implemented .

Limits: Fixed64 phase does not imply 64-bit frequency precision; bit-identical libm output across architectures not promised; Kuramoto accuracy depends on chosen step; the Accelerate sine bank needs a benchmark before assuming speedup.

FAQ: Is it a synth? No, a library. Is it real-time safe? The kernel is by construction; the measured device evidence covers specific graphs on one Mac.