Allomorph

Allomorph is an analog modeling and digital twin pipeline that transforms bass pickup and transducer signals—across active, passive, and acoustic piezo topologies—into authentic digital twin voices of iconic high-impedance passive pickup circuits, active preamps, and acoustic instruments.

Designed specifically for neural-capable pedalboards like the Darkglass Anagram, Tone3000 web training, and DAW plugin hosts, Allomorph produces:

1. Direct Digital Twin Wet Audio Stems: High-precision 48 kHz / 24-bit PCM wet stems synthesized via native WAV SPICE circuit simulation and non-linear magnetic dynamics with ITU-R BS.1770-4 gated loudness calibration ($-20.50\text{ LUFS}$) and true-peak safety.
2. Tone3000 Upload Bundles: Turnkey training packs partitioned by pickup affinity (neck, bridge, parallel, direct) conforming to Tone3000 Studio Trainer specifications with zero-scroll display naming ($\le 34$ chars) and cryptographic SHA256 manifest provenance.
3. Neural Amp Modeler (NAM) Profiles: High-efficiency Architecture 2 (A2) slimmable neural models (channels_3 + channels_8) trained wet-to-wet ($X_{\text{src}} \to Y_{\text{tgt}}$) under the A2 Studio Reference standard ($\text{ESR} \le 0.0080$) for single-block front-end deployment in Block 1 of the Darkglass Anagram.
4. Interactive Frequency Response Visualizations: High-performance Polars + Altair Vega-Lite interactive documentation portal (docs/frequency_responses.html) modeling analytical transfer functions and differential curves.

---

The Philosophy: Universal Transducer Transformation

In modern bass signal chains, trying to convert a passive bass to sound active with digital EQ/IRs runs into fundamental mathematical limits: high-frequency content has already been attenuated by the passive coil's 12 dB/octave low-pass filter. Boosting those missing frequencies elevates noise and introduces comb-filtering artifacts.

Allomorph provides bidirectional, universal transformation:

• Active Sources (e.g. EMG X-Series @ 18V): Deliver a flat, wideband (20 Hz – 20+ kHz), high-headroom, low-noise signal with near-zero inductive peaking, allowing Allomorph to forward-simulate the exact physical and electrical transfer function of any vintage passive or active target voicing without boosting background hiss.
• Passive Sources (e.g. Precision, Jazz, Mustang): Modeled via direct forward digital twin simulation rather than fragile linear deconvolution. Both the source passive pickup (with authentic RLC loading, pot damping, and magnetic core saturation) and the target voice are simulated forward from master unvoiced string excitation, enabling an Architecture 2 neural model to learn the direct wet-to-wet mapping ($X_{\text{src}} \to Y_{\text{tgt}}$). This eliminates the noise elevation and Gibbs truncation ringing inherent in attempting to invert a passive coil's steep 12 dB/octave low-pass filter, allowing vintage passive coils to morph seamlessly into modern active buffers, hot overwound humbuckers, or alternative scale lengths. (Analytical differential curves $H_{\text{diff}} = H_{\text{tgt}} / H_{\text{src}}$ remain available in the visualizer for frequency analysis).
• Acoustic & Piezo Transducers: Bridge force transducers and body cavity resonances faithfully emulated without artificial magnetic assumptions.

---

Why Not Just an Impulse Response (IR)?

While an Impulse Response (IR) or FIR filter can reproduce a static frequency curve, physical guitar and bass pickups and transducers are fundamentally non-linear, dynamic, reactive electro-mechanical systems. Relying solely on a linear IR misses the core physical behavior and tactile response of a real instrument:

1. Linear Time-Invariance (LTI) vs. Analog Dynamic "Give":

   • An IR is strictly linear and time-invariant: plucking pianissimo ($pp$) or digging in with aggressive slap or heavy pick strokes ($ff$) produces the identical transfer function.
   • Real passive magnetic pickups exhibit dynamic core excursion non-linearities and flux compression when strings swing close to the pole pieces. Allomorph models this dynamic non-linearity via vector soft-knee saturation ($V_{\text{sat}} \cdot \tanh(v / V_{\text{sat}})$), reproducing the $1.5\text{--}2.5\text{ dB}$ of tactile compression, bloom, and dynamic "give" experienced when digging into real copper coils.

2. Pre-Conditioning Downstream Distortion Stages:

   • In a digital modeler like the Darkglass Anagram, Allomorph sits in Block 1, directly feeding high-gain preamps and overdrives (Microtubes B7K, Vintage Ultra, Alpha·Omega).
   • A linear IR passes high-headroom active transients through uncompressed, causing subsequent overdrive stages to clip on artificial, brittle spikes. An Allomorph neural model pre-conditions the signal with true passive saturation and impedance damping, ensuring downstream distortion blocks saturate smoothly and musically.

3. Eddy Currents & Time-Domain Energy Storage:

   • Metal components (pole pieces, baseplates, covers) generate circulating eddy currents that produce frequency-dependent damping ($R_{\text{eddy}}$) and subtle phase lag during rapid string transients.
   • An IR treats this as a stationary frequency cut. A Neural Amp Modeler (NAM) neural network captures the dynamic time-domain energy storage and release of the complete reactive RLC network.

4. Multi-Coil Spatial Phase Summing:

   • Instruments with multiple coils or pickups (Jazz Bass pairs, P/J, StingRay dual coils) feature complex spatial cancellation patterns that vary with string amplitude and string displacement. NAM neural models capture compound phase interactions and harmonic cancellation across the full frequency spectrum without comb-filtering artifacts or phase smearing.

5. Non-Linear Harmonic Generation vs. Noise Floor Explosion (Restoring Missing High End):

   • An Impulse Response (IR) or linear FIR filter is strictly linear time-invariant ($Y(f) = X(f) \cdot H(f)$). If the source pickup has missing or heavily attenuated high frequencies—such as wide neck coil aperture low-pass sinc filtering, warm active preamp roll-offs, or physical comb-filter notches down by $-20\text{ to }-40\text{ dB}$ at $8\text{--}12\text{ kHz}$—a linear IR can only attempt to restore high end by applying an extreme linear boost ($+20\text{ to }+40\text{ dB}$).
   • Linearly boosting an attenuated band amplifies everything in that frequency range—including input thermal Johnson noise, pickup hiss, and electromagnetic interference (EMI)—creating an unlistenable wall of high-frequency noise. Furthermore, if a physical harmonic was extinguished in a comb null ($H_{\text{src}}(f) \approx 0$), linear multiplication by zero remains zero.
   • In sharp contrast, a direct stem $\to$ stem Neural Amp Modeler (NAM) neural network is a deep non-linear convolutional system. Rather than blindly multiplying low-amplitude bins, the network generates appropriate, phase-coherent upper harmonics directly from the strong fundamental and lower-order string overtones present in the source signal. This dynamically synthesizes authentic high-end sparkle, metallic attack clank, and top-end air, restoring the missing high end without boosting the underlying noise floor or amplifying pickup hiss.

Note

Allomorph synthesizes zero-latency minimum-phase FIR filters internally (via its homomorphic real-cepstrum Hilbert transform engine) to model physical aperture sinc responses, saddle boundary stiffness, and linear circuit stages starting strictly at sample 0. However, Allomorph does not output static linear IRs for hardware IR loaders—because real pickups are dynamic, non-linear systems. Its flagship pipeline trains lightweight NAM Architecture 2 (A2) neural models and Tone3000 upload packs to preserve the full dynamic touch sensitivity, magnetic flux sag, core hysteresis, and analog bloom of physical passive circuits.

---

Source Instrument Hardware Architectures (34" Standard Scale)

While Allomorph supports any active, passive, or acoustic source bass, physical transducer hardware fundamentally determines the raw harmonic information and dynamic boundary conditions delivered to the digital twin modeling pipeline. On a standard 34.0" scale ($863.6\text{ mm}$), Allomorph establishes two reference hardware architectures depending on the engineering priority:

1. The Actual Ideal Bass: Real Harmonic Dual-Transducer Architecture (Reverse PX + MMTWX) — Built for maximum acoustic realism, tactile dynamic feedback, reverse-split string balancing, and standalone analog versatility by sampling string standing-wave modes at their physical harmonic antinodes.
2. The Ideal Single-Pickup Bass: The Zero-Decoupling Reference Transducer — Built for zero cognitive overhead, foolproof patch switching on stage, zero inter-pickup phase comb notches, and zero secondary magnetic string drag.

---

Architecture 1: The Actual Ideal Bass — Real Harmonic Dual-Transducer (34" Scale)

In physical string mechanics, transverse wave reflections off the rigid bridge saddle impose an absolute, fret-invariant spatial comb filter envelope on string displacement: $$H_{\text{pos}}(f) = \left| \sin\left(\frac{2\pi f x}{v}\right) \right|$$ where $x$ is the physical distance from the bridge saddle and $v = \sqrt{T/\mu}$ is the string's intrinsic transverse wave speed.

Because wave speed $v$ is constant for each tuned string, the cancellation nulls occur at fixed frequencies in Hertz across all frets: $$f_{\text{null}, k} = k \cdot \frac{v}{2x}, \quad k \in {1, 2, 3, \dots}$$

A single pickup at any fixed location $x$ enforces a single set of comb nulls. By deploying a Reverse EMG PX Split-Coil + EMG MMTWX Dual-Mode with active parallel blending (EMG ABCX) on a 34" scale, the instrument physically captures real spatial wave mechanics at their authentic source locations:

[Nut] ════════════════════════════════════════════════════════════════════════════════ [Bridge]
                                  ◄─── Reverse PX ───►      ◄─── MMTWX ───►
                                   D/G: 145.4 mm            Neck: 77.4 mm
                                   E/A: 115.6 mm            Bridge: 54.6 mm

1. Real Spatial Comb Filtering Across the Frequency Spectrum

• Neck Transducer (Reverse EMG PX Split @ $130.5\text{ mm}$ Centerline):
  • Low-Frequency Output ($\propto f \cdot x$): Large distance from the bridge saddle yields $+7.5\text{ dB}$ higher raw fundamental output ($20\log_{10}(130/55)$) than the bridge position, providing deep, authoritative fundamental body physically at the transducer.
  • Forward D/G Half ($x = 145.4\text{ mm}$): Senses high strings where physical excursion is naturally small, adding warm low-mids, singing body, and long sustain without thinness.
  • Rearward E/A Half ($x = 115.6\text{ mm}$): First comb null sits at $307\text{ Hz}$ on low E. Senses heavy low strings closer to the bridge where mechanical excursion is controlled, tightening low-end fundamental transient attack and eliminating flub.
• Bridge Transducer (EMG MMTWX Dual-Mode @ $66.0\text{ mm}$ Centerline):
  • Dual-Coil Centerline ($x = 66.0\text{ mm}$): Pushes the first spatial comb null up to $538\text{ Hz}$ on low E (leaving the entire low-mid growl passband completely un-notched). Its physical $0.90''$ coil spacing generates the authentic $2.5\text{ kHz}$ acoustic humbucker notch directly on the string.
  • Single-Coil Mode ($x = 54.6\text{ mm}$): Pushes the first comb null to $651\text{ Hz}$. Senses high transverse velocity and saddle witness-point boundary stiffness ($H_{\text{saddle}}$), delivering biting 60s/70s Jazz bridge growl and percussive attack.

2. Physical & Dynamic Advantages Over a Single Point

• Optimal Neural Convergence & Rapid Training ($\text{ESR} \le 0.0080$): When targeting a Vintage P-Bass (precision_vintage) or a StingRay (stingray_parallel), the pickup is already in the physically authentic harmonic position. Because the source wet stem ($X_{\text{src}}$) already contains real standing-wave antinodes and genuine physical displacement, the NAM Architecture 2 neural network only needs to learn the passive RLC circuit impedance and magnetic core saturation dynamics—never having to synthesize missing harmonic content or un-notch spatial comb cancellations from an arbitrary pickup position.
• Tone3000 Affinity Bundling (bundles/<pickup>/): Aligns seamlessly with Tone3000's strict 1 Dry + Multiple Wet Stems constraint. Target voicings partition naturally by physical position affinity:
  • bundles/px/ for Neck voicings (precision_*, jazz_neck_*, mudbucker_deep, upright_acoustic)
  • bundles/mmtwx_dual/ and mmtwx_single/ for Bridge voicings (stingray_*, jazz_bridge_*, rickenbacker_*, dingwall_bridge)
  • bundles/blend_parallel/ for Parallel blends (jazz_pair_*, pj_*, p_mm_*, dingwall_parallel) Each bundle maps a dedicated, physically authentic dry excitation stem to its affine target stems, maximizing training accuracy and preserving acoustic realism.
• Physical Dynamic Excursion & Soft-Knee Compression: Large string displacement over the neck pickup drives the magnetic core into natural soft-knee flux compression ($V_{\text{sat}} \cdot \tanh(v/V_{\text{sat}})$) and dynamic inductance modulation ($\lambda_L$ "quack"), responding with tactile give when digging in hard.
• Broad Production Bass Support: While the dual-transducer Reverse PX + MMTWX configuration provides dedicated multi-position harmonic capture, Allomorph natively supports standard single-pickup and multi-pickup production instruments (e.g. 34" Precision Bass, 34" Jazz Bass, 34" StingRay, 30" Mustang P/J, Dingwall NG/Combustion) through their own physical configuration models and dedicated dry excitation bundles.

---

Modeling Architecture

Allomorph models the complete electro-acoustic path in four distinct layers:

[String Vibration]
        │
        ▼
1. Magnetic Aperture & Spatial Comb Filtering
   ├── Coil Sensing Width (w): High-frequency sinc filtering across multi-string wave speeds
   └── Dual-Coil Spacing (d): Humbucker spatial phase cancellation
        │
        ▼
2. Coil RLC Network (Passive Digital Twin)
   ├── Coil Inductance (L) & DC Resistance (R_dc)
   ├── Inter-Winding Self-Capacitance (C_coil)
   └── Eddy-Current Core Damping (R_eddy) in pole pieces & blades
        │
        ▼
3. On-Instrument Control Circuit
   ├── Master Volume Potentiometer (500k audio taper)
   ├── Hybrid Treble-Bleed Network (1.0 nF || 150 kΩ + 20 kΩ)
   └── Optional Capacitive C-Switch Bank
        │
        ▼
4. Output Environment
   ├── Instrument Cable Capacitance (~750 pF for standard 15-ft cable)
   └── Receiver Input Impedance (1 MΩ || 30 pF Darkglass Anagram input stage)

Scale-Length & Multi-Scale Transformation

Allomorph converts the lower tension and warm low-mid "bloom" of 30" short-scale and 32" medium-scale instruments into the focused, piano-like authority of full-scale and fanned-fret instruments:

• Wave-Speed Scaling ($\kappa_v$): Up-shifts aperture and comb-filter null frequencies by $+13.3%$ (for 34") and $+23.3%$ (for 37" multi-scale).
• String Tension Filtering: Tightens tubby $180\text{--}250\text{ Hz}$ boom while adding laser-tight sub-bass ($40\text{--}80\text{ Hz}$) and metallic Dingwall-style clank ($2.5\text{--}3.8\text{ kHz}$).
• Spatial Placement Tracking: Relocates pickups from short-scale bridge positions to standard 34" and 37" sweet spots.

---

Target Voice Catalog (24 Master Voicings & Transducers)

Allomorph includes pre-configured physical and electrical parameters for 24 distinct pickup topologies, active buffers, and transducers including active 2-band preamps, Stellartone ToneStyler discrete capacitive switching, fanned-fret multi-scale, and upright double bass (see docs/voice_catalog.md for full engineering specifications):

Profile ID	Tone Name	Pickup Type	Topology	Harness / Controls	$L_{\text{eq}}$	$f_r$ (Peak)	Circuit & Acoustic Character
precision_vintage	Precision Vintage	Vintage '62 P	Single Split	Vintage CTS $250\text{k}\Omega$ Vol/Tone Open, $47\text{nF}$ PIO Cap	$3.80\text{ H}$	$2.1\text{ kHz}$	Classic Alnico V split-coil wide open; touch-sensitive dynamic response, woody organic bloom.
precision_mids	Precision Mids	Vintage '62 P (22nF)	Single Split	22nF ToneStyler Pure Shunt ($R_{\text{tone}}=3.3,\Omega$)	$3.80\text{ H}$	$440\text{ Hz}$	Modern Fender spec; punchy $440\text{ Hz}$ low-mid resonant focus (+1.5 dB), $-3\text{ dB}$ cutoff at $750\text{ Hz}$.
precision_warm	Precision Warm	Vintage '62 P (47nF)	Single Split	47nF ToneStyler Pure Shunt ($R_{\text{tone}}=3.3,\Omega$), Flatwound Heavy	$3.80\text{ H}$	$450\text{ Hz}$	Authentic Jamerson Motown flatwound thump; 47nF pure capacitive shunt with pillowy low-end warmth.
precision_active	Precision Active	Modern Active Split P	Single Split	Sadowsky 2-Band Active Preamp ($R_{\text{in}}=1\text{M}\Omega, R_{\text{out}}=100,\Omega$), $500\text{k}\Omega$ Vol	$4.80\text{ H}$ (isolated)	$4.8\text{ kHz}$	Ceramic split-coil with active 2-band buffer; transparent punch, pick attack clarity, and wide headroom.
precision_dub	Precision Dub	Vintage '50s P (100nF)	Single Split	100nF ToneStyler Pure Shunt ($R_{\text{tone}}=3.3,\Omega$)	$3.80\text{ H}$	Sub-bass	Original 1951–1959 Fullerton factory paper-in-oil spec; massive sub-bass shelf rolloff ($-3\text{ dB}$ at $240\text{ Hz}$).
jazz_pair_open	Jazz Pair Open	Vintage 60s J-Bass Pair	Dual Parallel	Vintage $2\times 250\text{k}\Omega$ Vol ($125\text{k}\Omega$ net), $250\text{k}\Omega$ Tone, $47\text{nF}$	$1.69\text{ H}$	$2.7\text{ kHz}$	Dual narrow single-coils in parallel; 60s $92.1\text{ mm}$ aperture scoop with woody resonance.
jazz_pair_mids	Jazz Pair Mids	60s J-Bass Pair (22nF)	Dual Parallel	Vintage $2\times 250\text{k}\Omega$ Vol, 22nF ToneStyler Pure Shunt ($R_{\text{tone}}=3.3,\Omega$)	$1.69\text{ H}$	$762\text{ Hz}$	Vocal midrange honk ($762\text{ Hz}$ peak, $-3\text{ dB}$ at $1225\text{ Hz}$); pure capacitive shunt preserves Jaco bridge growl.
jazz_pair_active	Jazz Pair Active	Modern Active Jazz	Active 2-Band	Sadowsky 2-Band ($R_{\text{in}}=1\text{M}\Omega, R_{\text{out}}=100,\Omega$)	$1.69\text{ H}$	$7.8\text{ kHz}$	Isolated 60s J-pair with Sadowsky active 2-band boost; wideband sparkle with $+4\text{ dB}$ bass/treble.
jazz_bridge_growl	Jazz Bridge Growl	Jaco Biased J-Pair (100%/75%)	Dual Parallel Decoupled	Bridge 100% ($0,\Omega$), Neck 75% ($55\text{k}\Omega$ wiper decoupling), $250\text{k}\Omega$ Tone	$1.69\text{ H}$	$3.4\text{ kHz}$	Signature Jaco Pastorius vocal bridge growl; $55\text{k}\Omega$ neck decoupling shifts notch to $550\text{--}800\text{ Hz}$.
jazz_bridge_open	Jazz Bridge Open	60s J-Bass Bridge	Single Coil	Vintage $250\text{k}\Omega$ Vol, $250\text{k}\Omega$ Tone, $47\text{nF}$	$3.60\text{ H}$	$2.8\text{ kHz}$	60s bridge single-coil ($63.5\text{ mm}$ datum); focused midrange bite, authentic Jaco growl.
jazz_neck_warm	Jazz Neck Warm	60s J-Bass Neck	Single Coil	Vintage $250\text{k}\Omega$ Vol, $250\text{k}\Omega$ Tone, $47\text{nF}$	$3.40\text{ H}$	$2.9\text{ kHz}$	60s neck single-coil ($155.6\text{ mm}$ datum); warm, woody round fundamental with vintage clarity.
stingray_parallel	StingRay Parallel	Music Man StingRay	Active MM Buffer	Music Man 2-Band ($R_{\text{in}}=1\text{M}\Omega, R_{\text{out}}=100,\Omega$)	$1.20\text{ H}$	$8.5\text{ kHz}$	Authentic active 2-band MM humbucker; cable isolation, comb notch at $2.5\text{ kHz}$, metallic clank.
stingray_series	StingRay Series	Music Man MM (Series)	Active Series Buffer	Music Man 2-Band Preamp Buffer	$4.80\text{ H}$	$4.1\text{ kHz}$	Dual-coil humbucker in series with active buffer; $+5.6\text{ dB}$ series EMF surge and focused active resonance.
dingwall_bridge	Dingwall Bridge	Multi-Scale MM Bridge	Angled Parallel	Dingwall Active Onboard Buffer ($R_{\text{in}}=1\text{M}\Omega, R_{\text{out}}=100,\Omega$)	$2.30\text{ H}$	$7.3\text{ kHz}$	34"-37" fanned-fret angled bridge sweet spot ($48.0\text{ mm}$) with active buffer and stainless clank.
dingwall_middle	Dingwall Middle	Multi-Scale MM Middle	Angled Parallel	Dingwall Active Onboard Buffer ($R_{\text{in}}=1\text{M}\Omega, R_{\text{out}}=100,\Omega$)	$2.30\text{ H}$	$6.8\text{ kHz}$	34"-37" fanned-fret angled middle sweet spot ($87.8\text{ mm}$); punchy low-mid bloom with high tension.
dingwall_parallel	Dingwall Parallel	Multi-Scale Bridge/Middle	Dual Parallel	Dingwall Active Onboard Buffer ($R_{\text{in}}=1\text{M}\Omega, R_{\text{out}}=100,\Omega$)	$1.15\text{ H}$	$8.2\text{ kHz}$	Dual angled FD3n coils in parallel; modern scooped slap tone with extended harmonic overtone series.
rickenbacker_clank	Rickenbacker Clank	High-Pass Bridge	Series HPF	Factory Rickenbacker $330\text{k}\Omega$ Vol/Tone, $4.7\text{nF}$ Series Cap	$3.80\text{ H}$	$2.2\text{ kHz}$	High-output bridge coil with vintage $4.7\text{ nF}$ series capacitor; tight high-pass cut below $150\text{ Hz}$.
rickenbacker_open	Rickenbacker Open	Rickenbacker Toaster Neck	Single Coil	Factory Rickenbacker $330\text{k}\Omega$ Vol/Tone, $47\text{nF}$	$3.80\text{ H}$	$2.6\text{ kHz}$	Warm, open vintage toaster neck pickup voicing; organic low end with glassy high-mid articulation.
pj_passive	PJ Passive	Vintage '80s Passive P/J	Parallel Sum	Dual $250\text{k}\Omega$ Vol ($125\text{k}\Omega$ net), $250\text{k}\Omega$ Tone, $47\text{nF}$	$1.85\text{ H}$	$2.8\text{ kHz}$	Vintage Alnico V split-P and 60s J-bridge in parallel; authentic '80s Fender Special / Yamaha BB thump.
pj_active	PJ Active	Modern Active P/J	Active 2-Band	Sadowsky/Spector 2-Band ($R_{\text{in}}=1\text{M}\Omega, R_{\text{out}}=100,\Omega$)	$2.06\text{ H}$	$7.6\text{ kHz}$	Active 2-band boost with isolated ceramic P/J coils; punchy sub-bass fundamental and aggressive clank.
p_mm_parallel	P/MM Parallel	Modern Active P/MM	Active Buffer	Studio Active Buffer ($R_{\text{in}}=1\text{M}\Omega, R_{\text{out}}=100,\Omega$)	$0.96\text{ H}$	$3.4\text{ kHz}$	Authentic active parallel P/MM (Sandberg VM / Lakland 44-02); Split-P neck + MM parallel bridge into buffer.
p_mm_series	P/MM Series	Modern Active P/MM (Series)	Active Series Buffer	Studio Active Buffer ($R_{\text{in}}=1\text{M}\Omega, R_{\text{out}}=100,\Omega$)	$8.40\text{ H}$	$3.2\text{ kHz}$	Split P and MM parallel humbucker wired in series before active buffer; $+5.8\text{ dB}$ inductive boost.
mudbucker_deep	Mudbucker Deep	Heavy Series MM	Ultra Series	Gibson $500\text{k}\Omega$ Vol/Tone, $22\text{nF}$ Cap	$14.40\text{ H}$	$1.2\text{ kHz}$	Overwound dual-coil series humbucker; subterranean low end with natural high-frequency rolloff.
upright_piezo	Upright Piezo	Double Bass Transducer	Bridge Force	High-Impedance PZT Piezo Buffer, $8\text{ Hz}$ DC Block	—	$800\text{ Hz}$ / $3.8\text{ kHz}$	Bridge saddle force transducer; maple rocking resonance, wood mass rolloff, Spirocore compliance (pair with 3 Sigma AST IRs).

---

SPICE $\to$ NAM Pipeline & CLI Usage

Allomorph models acoustic aperture and scale tension in Python, executes the passive circuit digital twin directly using its native WAV SPICE simulator, and trains lightweight NAM (.nam) neural captures for Block 1 of the Darkglass Anagram:

1. Interactive Acoustic & Electrical Visualizer (scripts/analyze_voices.py)

Renders interactive frequency response curves in Altair (Vega-Lite), comparing all 24 target configurations against any source instrument. Outputs are organized into per-instrument standalone charts and a unified interactive portal:

# Generate interactive charts for all configured source instruments and refresh master portal:
uv run python scripts/analyze_voices.py

# Generate or refresh for a specific instrument (preserves all other instrument charts):
uv run python scripts/analyze_voices.py --instrument 32in_fretless
uv run python scripts/analyze_voices.py --instrument 30in

Outputs: Master interactive portal at docs/frequency_responses.html (and docs/frequency_responses/index.html) with embedded tabbed navigation and spec breakdown, and per-instrument standalone visualizations in docs/frequency_responses/<instrument_id>.html.

2. Native WAV SPICE Circuit Simulation (allomorph-sim)

Directly streams raw bass string excitation audio (audio/input.wav) through the entire physical digital twin in a single in-memory forward pass:

1. Acoustic Aperture & Placement: De-humbucking sinc aperture filtering, spatial standing-wave comb filtering, displacement tilt ($\Delta x$), scale tension filtering, saddle boundary layer stiffness ($H_{\text{saddle}}$), and multi-pickup causal arrival delay ($\tau_i$).
2. Branch-Wise Dynamic Non-Linear Compliance: Pre-summing magnetic saturation for composite pickups with soft-knee saturation ($V_{\text{sat}} \cdot \tanh(v / V_{\text{sat}})$), Lenz flux sag, Dahl hysteresis, back-EMF braking, dynamic reluctance quack, velocity-modulated aperture bloom ($\kappa_{\text{ap}}$), and GIL-free (nogil=True) state-space ODE kernels for full multi-core scalability.
3. Passive Pickup Circuit Twin: Exact closed-form nodal AC transfer functions, Foster 2-stage eddy-current damping, solid Alnico pole skin dispersion, authentic volume/tone pot dividers, active preamp buffers (flat DC transmission, zero Gibbs ripples), hybrid treble bleed, cable capacitance ($750\text{ pF}$), and pedalboard load ($1\text{ M}\Omega \parallel 30\text{ pF}$).
4. Calibrated Loudness & True-Peak Safety: ITU-R BS.1770-4 gated loudness normalization ($-20.50\text{ LUFS}$ / $-20.50\text{ dBFS}$ RMS) strictly bounded by a 4x oversampled true-peak safety ceiling ($\le 0.9900$ / $-0.09\text{ dBFS}$) via transparent linear peak scaling to avoid double compression.

Allomorph features a built-in WAV SPICE simulator running natively on Apple Silicon (arm64). Accelerated by a master 21-point Lossless $C^\infty$ SIMD, Tensor & Real-FFT Optimization Suite (pure real-FFT homomorphic cepstrum synthesis, 2D continuum tensor broadcasting, branchless 3-stage fsqrt rail limiters, Horner dipole polynomials, and passband-constrained oversampling), the engine evaluates exact analytical nodal equations and vector non-linearities directly in memory on the audio waveform, eliminating external SPICE dependencies (such as LTspice or ngspice) and intermediate disk writes while executing in ~0.8s per voice (>1500x faster than traditional transient SPICE engines):

# Run unified WAV SPICE simulation from raw audio for a specific voice (~0.8s):
uv run allomorph-sim --voice precision_active --instrument 30in

# Simulate all voices in parallel across multi-core CPU (-j / --jobs):
uv run allomorph-sim --voice all --instrument 30in -j 8

# Rapid prototyping run on first 2 seconds (96,000 samples):
uv run allomorph-sim --voice stingray_parallel --max-samples 96000

# Run via master pipeline (direct forward simulation stage):
uv run allomorph --stage sim --voice precision_active

3. NAM Neural Model Training (Architecture 2 / A2)

Trains a high-efficiency NAM Architecture 2 (A2) neural model directly pairing the source instrument wet stem ($X_{\text{src}}$) to the target voice wet stem ($Y_{\text{tgt}}$). A2 replaces legacy A1 models (nano/feather/standard) with a "slimmable (full/lite)" neural architecture designed specifically for low-power hardware like the Darkglass Anagram:

# Train NAM Architecture 2 (A2) model for Darkglass Anagram Block 1:
# Both input (X_src) and target (Y_tgt) are synthesized wet audio files:
nam train audio/wet/30in_emg_mmtw/mmtw_dual.wav audio/wet/34in_standard_p/precision_vintage.wav ./models/30in_emg_mmtw/precision_vintage.nam --architecture "A2"

# Run via the automated Allomorph trainer (defaults to Architecture 2 slimmable container with goal ESR <= 0.0080):
uv run allomorph --stage train --instrument 30in --voice precision_active

# Customize goal ESR or disable early stopping:
uv run allomorph --stage train --instrument 30in --voice precision_active --goal-esr 0.0050
uv run allomorph --stage train --instrument 30in --voice precision_active --no-goal-esr --epochs 400

# Train A2-Lite channels_8 only (instead of the default slimmable container):
uv run allomorph --stage train --instrument 30in --voice precision_active --a2-lite-only

(In modern versions of neural-amp-modeler and the official Google Colab trainer, --architecture A2 is the default. With the optimal bass dry excitation file featuring the Section 9E Dedicated Representative Bass Performance Suite, Allomorph trains the full slimmable Architecture 2 container (both channels_3 and channels_8) by default under the A2 Studio Reference standard (--goal-esr 0.0080, 400 max epoch safety ceiling, --batch-size 32, monitoring channels_8). To isolate the 8-channel submodel only, supply --a2-lite-only).

Note

Complete Training Guide & Audio Pairings: For the complete reference table of input/target audio pairings for direct single-block and Tone3000 models, see docs/training.md.

4. Master Automation Runner (allomorph)

Execute the entire pipeline or specific stages with a single command:

# Run complete pipeline for 30" source instrument (sim -> pack -> train -> viz):
uv run allomorph --instrument 30in

# Direct forward simulation of wet audio stems (with multi-core parallel jobs):
uv run allomorph --stage sim --instrument 30in --jobs 4

# Clear audio/ directory and regenerate wet stems across all instruments:
uv run allomorph --clean-audio --stage sim --jobs 4

# Export Tone3000 upload bundles:
uv run allomorph --stage pack --instrument 30in

# Train local NAM models:
uv run allomorph --stage train --instrument 30in --voice precision_active

# Audit catalog audio telemetry (loudness, true-peak, crest factor, DC offset):
uv run allomorph --stage audit
uv run allomorph --stage audit --verbose

# Generate interactive Altair frequency visualizations:
uv run allomorph --stage viz

---

Signal Flow on the Darkglass Anagram

[Bass: Active / Passive / Piezo]
             │
             ▼
[Block 1: Allomorph NAM Preamp]
     └── Model: "stingray_parallel.nam" (Architecture 2 neural capture)
             │
             ▼
[Block 2: Darkglass Preamp / Drive]
     └── Microtubes B7K, Vintage Ultra, or Alpha·Omega
             │
             ▼
[Block 3: Speaker Cabinet IR Loader]
     └── Ampeg 8x10, Darkglass 4x10, or custom speaker cab impulse
             │
             ▼
[Output to FOH / Audio Interface]

---

Project Structure

allomorph/
├── README.md                              # Project vision, theory, architecture, and CLI guide
├── docs/                                  # In-depth technical guides
│   ├── architectural_guardrails.md        # Master mathematical reference handbook & derivations
│   ├── dsp_simulation_engine.md           # Virtual Analog SIMD simulation engine & Numba JIT
│   ├── configuration_reference.md         # Complete schema & field reference for TOML configurations
│   ├── voice_catalog.md                   # Complete passive pickup technical catalog & parameters
│   ├── circuit_theory.md                  # RLC, eddy current, and cable impedance math
│   ├── aperture_math.md                   # Magnetic aperture sinc, multi-string & scale physics
│   └── anagram_workflow.md                # Darkglass Anagram Block 1 routing & gain staging
├── config/                                # Modular TOML configuration files
│   ├── instruments/                       # Source bass geometries, pickups & embedded circuits
│   │   ├── 30in_emg_mmtw.toml             # 30" active EMG MMTWX dual-mode bass
│   │   ├── 34in_active_stingray.toml      # 34" active Music Man StingRay bass
│   │   ├── 34in_standard_p.toml           # 34" standard P-bass template
│   │   └── 34in_standard_jazz.toml        # 34" standard Jazz bass template
│   ├── preamps.toml                       # Reusable active preamp catalog (Sadowsky, StingRay, Aguilar, Dingwall)
│   ├── scales.toml                        # Scale lengths & baseline string wave speeds
│   └── strings.toml                       # Physical string core/wrap mechanical presets
├── src/                                   # Core reusable library package
│   └── allomorph/
│       ├── config/                        # Modular TOML configurations & geometry
│       │   ├── scales.py                  # Scale length & wave-speed loader
│       │   ├── strings.py                 # String mechanics presets loader
│       │   ├── voices.py                  # Voice registry & 24 declarative target models
│       │   ├── instruments.py             # Source instrument loader & cache
│       │   └── geometry.py                # Pickup coils & aperture geometry resolution
│       ├── naming.py                      # UI slugs, Tone3000 filenames, and CLI resolution
│       ├── dsp.py                         # Minimum-phase FIR synthesis and 24-bit WAV I/O
│       ├── physics/                       # Physical acoustic & spatial modeling subpackage
│       │   ├── strings.py                 # String mechanics, dispersion, wave continuum
│       │   ├── aperture.py                # Sinc & Bessel aperture integrals, saddle stiffness
│       │   └── prefilter.py               # Minimum-phase FIR prefilter synthesis
│       ├── circuit/                       # Native WAV SPICE circuit simulation subpackage
│       │   ├── parser.py                  # SPICE value parsing & magnet metallurgy properties
│       │   ├── solver.py                  # Modified Nodal Analysis (MNA) solver & AC curves
│       │   ├── saturation.py              # State-space non-linear saturation & Numba kernels
│       │   ├── audio.py                   # Vectorized FFT convolution & 24-bit audio buffers
│       │   ├── simulation.py              # Audio simulation orchestration & batch workers
│       │   └── staging.py                 # Virtual analog circuit simulator & allomorph-sim CLI
│       ├── visualizer/                    # Polars + Altair frequency visualization library
│       │   ├── dataframe.py               # Polars data modeling & continuum transfer curves
│       │   ├── charts.py                  # Interactive Altair visualization builders
│       │   └── portal.py                  # Responsive dark-mode HTML portal generator
│       ├── pipeline/                      # Multi-stage automation & batch orchestration
│       │   ├── stages.py                  # Visualization, prefilter, simulation, training stages
│       │   ├── batch.py                   # Concurrency pool & ProcessPoolExecutor runner
│       │   └── cli.py                     # Allomorph CLI argument parsing & workflow dispatcher
│       └── cli.py                         # Master CLI entrypoint delegation for `allomorph`
├── scripts/                               # Workflow utilities & CLI entrypoints
│   ├── analyze_voices.py                  # Thin delegating CLI wrapper for allomorph.visualizer
│   ├── train_nam.py                       # Local NAM A2 PyTorch/MPS GPU trainer
│   └── generate_tone3000_artwork.py       # Tone3000 storefront artwork generator
├── tests/                                 # Hierarchical pytest test suite (365 tests)
│   ├── circuit/                           # SPICE netlists, nodal RLC solving, ODE saturation, simulation
│   └── physics/                           # Aperture sinc filters, string mechanics, dispersion, FIR synthesis
└── models/                                # Exported .nam neural models

---

Roadmap

Completed Milestones

• Electro-Acoustic Physical Modeling: Magnetic aperture sinc filtering, spatial comb nulls, scale-length wave-speed scaling ($30''/32'' \to 34''/37''$), 2D rod apertures, saddle boundary layer stiffness, longitudinal clank, and differential string tension modeling.
• Native WAV SPICE Simulator: High-performance Apple Silicon engine (allomorph-sim) solving analytical nodal RLC equations, Foster 2-stage core eddy diffusion, Dahl magnetic domain-wall pinning hysteresis, asymmetric magnet saturation compliance, sub-audible 8 Hz DC blocking, passive RLC Johnson noise dither, and automatic output level normalization based on input sweep dBFS at >1500x speed.
• Lossless $C^\infty$ SIMD, Tensor & Real-FFT Optimization Suite: Master 21-point mathematical vectorization accelerating FIR synthesis via pure real-FFT homomorphic cepstrum, 2D continuum tensor broadcasting, branchless 3-stage fsqrt rail limiting, passband-constrained oversampling, and analytical impedance Jacobians.
• 24 Master Voice Profiles & Transducers: Modern active 2-band Jazz, vintage single-coil, split-coil, series/parallel dual-coils, active Music Man, fanned multi-scale, upright double-bass bridge piezo force transducers, and flat dynamic twins.
• DSP Generation 5 Architecture & Audio QA Telemetry: Direct unified forward digital twin simulation, Multi-Technique Bass Performance Suite excitation (audio/input.wav) with dedicated representative validation window, branch-wise pre-summing magnetic saturation with causal delay $\tau_i$, dynamic ITU-R BS.1770-4 gated loudness normalization (-20.50 LUFS), 4x oversampled true-peak safety ceiling ($\le 0.9900$), GIL-free ODE kernels, Tone3000 upload pack bundles (bundles/<pickup>/), and automated catalog audit (allomorph --stage audit).
• Interactive Visualization Portal: Polars + Altair frequency response portal with spec sheets and per-instrument interactive charts (docs/frequency_responses.html).
• Automated NAM Training Pipeline: End-to-end Architecture 2 (A2) neural model training targeting Darkglass Anagram Block 1.
• Automated Test Suite: Comprehensive 304-test pytest verification covering physical filters, nodal transfer functions, real-FFT homomorphic cepstrum DSP, 2D tensor continuum, ODE saturation, audio simulation, and architectural guardrails.

Upcoming Objectives

• Interactive A/B Audio Auditioning CLI: Terminal and real-time audio auditioning tool (scripts/preview_voices.py) with seamless dry-to-wet switching, looping bass riffs, and instantaneous A/B comparison across pickup voices before neural training or pedalboard export.
• Hardware Reference Calibration: Dry-DI spectral matching and A/B verification against physical vintage instruments (1962 P-Bass, 1975 Jazz Bass, 1979 StingRay).
• In-Browser Audio Player: Interactive audio preview player embedded directly into the Altair documentation portal.
• Anagram Marketplace Native Block: Develop a dedicated, all-in-one "Allomorph" custom block for the Darkglass Anagram Marketplace (marketplace.anagram.shop), featuring rotary voice switching across all 24 pickup configurations, automatic gain normalization, and interactive volume/cable load controls in a single native Block 1 module.

---

Contributing

We welcome community contributions, netlists, and optimizations! Because Allomorph uses a dual-licensing model, all contributors must agree to the Contributor License Agreement via standard commit sign-off (git commit -s).

Please see CONTRIBUTING.md for full development setup, coding guidelines, and pull request instructions.

---

License

This project and its distributed assets are licensed under the PolyForm Noncommercial License 1.0.0.

Scope & Permissions

• Permitted Uses: Free to use, study, modify, and distribute for personal study, experimentation, sound design, and noncommercial music production.
• Coverage: This license applies to all source code, SPICE netlists, configuration schemas, compiled/trained neural models (.nam), and synthesized audio stems (.wav) generated by or distributed with Allomorph.
• Commercial Restrictions: Commercial use, sale, bundling into commercial plugins/pedalboards, or monetization of the software, neural profiles, or audio stems is strictly prohibited without prior written permission and a commercial license from the author.
• Commercial Licensing Inquiries: Contact Peter Nguyen (peter@phn.dev).