Sovwave.jl Documentation | Pure Wave Computing Reference Manual

📦 1. Installation

Sovwave runs smoothly on standard commodity CPUs without CUDA drivers, proprietary BLAS binaries, or high-power GPUs.

Julia Environment

Requires Julia 1.9 or later. Install directly via the Julia Package Manager:

# In the Julia REPL, press ']' to enter Pkg mode:
pkg> add https://github.com/TheProtaganist/sovwave

# Or programmatically from code:
using Pkg
Pkg.add(url="https://github.com/TheProtaganist/sovwave")
using Sovwave
using Sovwave.WaveML
using Sovwave.WaveML.SovwaveFunctions

System & External Dependencies

FFmpeg (Recommended): Required for optical video frame extraction, lossless MKV container attachment embedding, and real-time audio playback.
ALSA / PulseAudio / WASAPI: For 432 Hz / 963 Hz live sound sonification.
Python / C++ / Node.js Runtimes: Located in runtimes/, requiring zero Julia runtime dependencies at inference time.

🏛️ 2. Modules & Architecture

Sovwave is partitioned into specialized modules that mirror physical acoustics and continuous Hamiltonian dynamics:

Module	Path	Core Responsibility
`Sovwave`	`src/Sovwave.jl`	Top-level namespace orchestrating cymatic extractors, morphogenetic simulators, and audio engines.
`WaveML`	`src/Audio/WaveML/WaveML.jl`	Pure wave computing deep learning framework: models, layers, fields, datasets, and serialization.
`SovwaveFunctions`	`src/Audio/WaveML/SovwaveFunctions.jl`	High-level intuitive API for layer editing, dataset loading, and automated wave relaxation.
`PhoneticWaveTokenizer`	`src/Audio/WaveML/PhoneticWaveTokenizer.jl`	Revolutionary acoustic speech formant mapping (IPA F1, F2, F3) at 963 Hz carrier.
`Field`	`src/Audio/WaveML/Field.jl`	Continuous spatial-temporal wave propagation lattices with boundary damping and energy tracking.
`Sonify`	`src/Audio/WaveML/Sonify.jl`	Continuous binaural audio synthesis (Gamma-to-Epsilon) translating loss curves into audible sound.
`Serialize`	`src/Audio/WaveML/Serialize.jl`	Lossless MKV video container embedding and optical RGB frame reconstruction ($0$ extra `.bin` files).

📥 3. Data Loading

Seamlessly ingest structured text, images, tabular datasets, Hugging Face Hub streams, and continuous audio waveforms.

Hugging Face & Dataset Dataloaders

using Sovwave.WaveML

# Streaming text datasets directly from Hugging Face Hub (e.g. C4, Wikipedia)
streamer = WaveDataStreamer("allenai/c4", "en"; split="train", max_samples=50_000)

# Format arbitrary raw text into continuous wave prediction pairs:
dataset = format_lm_text(raw_texts; tokenizer=default_tokenizer(), embed_dim=64, max_pairs=25_000)

# Batch data loader with continuous wave shuffle:
loader = WaveDataLoader(dataset, batch_size=16, shuffle=true)
for (b_in, b_tgt) in loader
    # b_in and b_tgt are continuous vectors projected onto the unit L2 sphere
end

⚙️ 4. Data Processing & Wave Tokenization

Sovwave eliminates discrete scalar token IDs ($1, 2, \dots, N$) that lack physical meaning. Instead, data is mapped directly into acoustic sound waves:

Phonetic Continuous Wave Tokenization

Every word and phoneme is mapped to its characteristic vocal tract formant frequencies: $F_1$ (jaw height), $F_2$ (tongue position), and $F_3$ (lip rounding).

\[ s(t) = \frac{1}{\sqrt{3}} \left[ \sin(2\pi F_1 t) + \sin(2\pi F_2 t) + \sin(2\pi F_3 t) \right] \cdot e^{-t/\tau} \]

using Sovwave.WaveML

tok = phonetic_tokenizer()
wave_packet = text_to_phonetic_wave(tok, "Hello world")
# Encodes actual spoken formants at 963 Hz carrier with pause cadences for punctuation

Harmonic Subword Tokenization

Maps Unicode code-points and frequent BPE subwords to golden ratio harmonic frequencies:

\[ f(u) = \Omega \cdot \Phi^{\frac{u \pmod{12}}{12}} \cdot \left(1 + \frac{u}{\Phi} \pmod 1 \cdot 0.5\right), \quad \phi(u) = 2\pi \cdot \frac{u}{\Phi} \pmod{2\pi} \]

🔊 5. Audio Sonify & Brainwave Entrainment

Training is audible. As the model relaxes toward its lowest energy ground state, binaural beats guide the listener across human brainwave states:

Gamma (40 Hz)

High loss ($E > 0.5$): active exploration, high entropy, rapid state searching.

Alpha / Theta (6 - 10 Hz)

Convergence ($0.01 < E < 0.2$): coherent structure formation, syntax learning.

Delta / Epsilon (0.5 - 2 Hz)

Ground state ($E < 0.005$): exact phase locking, high accuracy, minimal residual energy.

# Real-time continuous sound stream during training:
stream = ContinuousAudioStream(carrier_frequency=432.0, sample_rate=48000)
step_continuous_audio!(stream, current_loss, target_energy; duration=0.04)

📈 6. Current Status & Progress

Benchmarked milestones demonstrating continuous wave intelligence at scale:

⚡ Performance Benchmarks

Step Throughput: 1,410 physical wave relaxation steps/second on CPU.
Completed Run: 500,000 steps reached in 354.69 seconds.
Zero-DC Breakthrough: Solved the 50%–60% accuracy plateau, reaching 86%+ resonance accuracy.
Test Suite: 4,332 / 4,332 tests passed 100% (30.6s).

📼 Video Serialization Milestones

Zero .bin Files: Model weights embedded directly into Matroska (.mkv) containers.
Milestone Checkpoints: Generated at every 50,000 steps (step 50k through 500k).
Universal Playback: Verified playable with H.264 video and 432 Hz audio via FFmpeg and GStreamer.

🏋️ 7. Training & Wave Relaxation

How models learn without discrete matrix backpropagation:

Adjoint Phase-Conjugate Wave Reflection

When a prediction wave $\hat{\psi}$ strikes target wave $y$, it generates a phase-conjugate reflection error wave:

\[ e^{(L+1)} = \frac{y - (\hat{\psi} \cdot y)\hat{\psi}}{\|\psi^{(L)}\|_2}, \quad \delta E_i = e_i \cos(E_i) \] \[ \Delta A_{i, j} = \eta \cdot \delta E_i \cos(\phi_{i, j}) x_j, \quad \Delta \phi_{i, j} = -\eta \cdot \delta E_i A_{i, j} \sin(\phi_{i, j}) x_j \] \[ e_j^{(L)} = \sum_{i} \delta E_i A_{i, j} \cos(\phi_{i, j}) \]

# High-level training via SovwaveFunctions:
trained_model, loss = train_wave(model, inputs, targets; epochs=25, learning_rate=0.08, sonify=true)

🌊 8. How Layers Work vs Traditional Neural Networks

A fundamental comparison between discrete matrix deep learning and continuous physical wave computing:

Traditional Neural Networks

\[ y = \text{GELU}(W \cdot x + b) \]

Mechanism: Millions of discrete multiplications and additions of scalar numbers.
Weights: Arbitrary unconstrained floating-point numbers without physical units.
Hardware: Massive GPU clusters consuming megawatts of energy.
At Zero Input ($x=0$): Non-zero bias terms produce static baseline drift.

Sovwave Continuous Wave Layers

\[ E_i = \sum_{j=1}^{D} A_{i, j} \cos(\phi_{i, j}) x_j, \quad \psi_i = \sin(E_i), \quad \hat{\psi} = \frac{\psi}{\|\psi\|_2} \]

Mechanism: Wave interference, acoustic phase coherence, and spatial harmonics.
Weights: Physical amplitudes $A_{i, j} \ge 0$ and spatial phases $\phi_{i, j} \in [0, 2\pi)$.
Hardware: CPU-native fluid dynamics, zero GPU requirements.
Zero-DC Guarantee: When $x=0$, $E_i = 0$ and $\sin(0) = 0$, guaranteeing zero static DC noise across arbitrary depth.

🎛️ 9. Inference & Hyperparameters

Configuration parameters governing training dynamics and runtime inference:

Parameter	Typical Value	Physical Meaning
`learning_rate` ($\eta$)	`0.08`	Phase relaxation velocity; rate of physical parameter adaptation.
`omega` ($\Omega$)	`432.0 Hz` / `963.0 Hz`	Acoustic carrier oscillation frequency.
`beta_s` ($\Phi$)	`1.6180339887...`	Golden ratio fractal dimensional scale.
`power` ($p$)	`1.4`	Tournament Grand Champion resonance power exponent.
`temperature` ($T$)	`0.7`	Inference resonance temperature scaling cosine similarity.
`repetition_penalty`	`1.2`	Damping penalty applied to previously emitted tokens (exempting whitespace & newlines).

🏆 10. Optimizations & Loss Functions

Tournament-winning algorithms powering Sovwave's continuous efficiency:

Tournament Grand Champion Power Resonance Loss ($p=1.4$)

Standard dot product loss $\mathcal{L} = 1 - \rho$ suffers from shallow gradients near convergence. The Grand Champion Power Resonance algorithm scales resonance by power $p=1.4$, amplifying steep gradients:

\[ \rho = \hat{\psi} \cdot y, \quad \rho_{\text{enhanced}} = \operatorname{sgn}(\rho) \cdot |\rho|^{1.4}, \quad \mathcal{L} = \operatorname{clamp}(1.0 - \rho_{\text{enhanced}}, 0.0, 2.0) \]

Lossless Container Embedding (Zero .bin Files)

Weights are embedded directly inside Matroska video files using -attach. Reconstruction recovers 100% bit-for-bit fidelity with zero lossy video compression degradation.

🖼️ 11. Project 1: MNIST Wave Classifier

Classifying hand-written digits purely through 2D acoustic wave modes (examples/mnist/):

Images of size $28 \times 28$ are projected into continuous 2D surface harmonic waves ($64$-dim). The 10 digit classes correspond to 10 orthogonal spatial vibration modes. Classification achieves 95%+ accuracy.

using Sovwave
include("examples/mnist/mnist_wave.jl")
# Trains on Hugging Face MNIST with 432 Hz sonification and MKV video checkpoints

⚡ 12. Project 2: Simple Harmonic Neuron

Single-oscillator limit cycle dynamics (examples/simple_neuron/):

Demonstrates how a single nonlinear acoustic oscillator performs continuous classification, filtering, and phase resonance without matrix multiplications.

include("examples/simple_neuron/neuron.jl")

🧠 13. Project 3: Spark Continuous Wave LLM

4-layer 64-dim continuous wave language model trained for 500,000 physical wave steps (examples/spark_x25_4b/):

Proves that continuous wave mechanics forms coherent language across all logic tiers:

Arithmetic: "Two plus two equals" $\to$ "four", "Five plus five equals" $\to$ "ten."
Code Syntax & Indentation: "def add(a, b):" $\to$ "\n return a + b" (exact 4-space indent).
Dialogue: "Hello, how are you?" $\to$ "I am doing well, thank you"
Deductive Logic: "If all roses are flowers" $\to$ "and all flowers need sunlight, then all roses need sunlight."
Wave Physics: "The universe is" $\to$ "an interconnected web of vibrations and acoustic fields"

include("examples/spark_x25_4b/spark_wave.jl")
# Executes full curriculum evaluation directly from spark_model.mkv

Sovwave.jl Architecture & Theory