math-sonify

math-sonify is a real-time generative audio engine that runs mathematical dynamical systems (differential equations, maps, and coupled oscillators) and routes every variable of their evolving state directly into audio synthesis parameters. The Lorenz attractor is actually integrating at 120 Hz; the Kuramoto coupling constant is live; the Three-Body gravitational problem advances at each control frame. The result is not a preset synthesiser with math-themed names: the mathematics is the music, and every parameter change propagates to sound within 8 ms.

It is a desktop app (egui GUI, cpal audio), a VST3/CLAP plugin built from the same code, and a headless WAV renderer. Useful if you make ambient or generative music, teach dynamical systems and want students to hear chaos onset, or just want a synth whose knobs are the parameters of the Lorenz equations.

Lorenz phase portrait	Kuramoto math view	Waveform and spectrum

Feature highlights

1. 53 dynamical systems: Lorenz, Rossler, Double Pendulum, Kuramoto, Three-Body, Hyperchaos (Chen-Li), WINDMI, Finance, all Sprott cases, Tinkerbell map, and more (full list below).
2. 9 sonification modes: Direct, Orbital, Granular, Spectral, FM, AM, Vocal, Waveguide, Resonator.
3. 20 musical scales: Pentatonic through Microtonal, EDO-19/24/31, Harmonic Series, Just Intonation.
4. MIDI export: trajectory-to-MIDI conversion; outputs Standard MIDI Files (SMF) importable into any DAW.
5. Presets: 43 built-in presets in six categories, with search and favorites (see Presets).
6. Play together: --collab 127.0.0.1:9001 lets other people move the parameters live over WebSocket, from the bundled collab.html page or any WebSocket client. A player can lock a parameter so nobody else changes it.
7. Microphone steering: --mic turns the room's sound into the Lorenz parameters while the synth keeps playing: louder means more chaos (sigma), brighter means higher rho, mid-band energy moves beta.
8. Lyapunov exponent tracker: real-time estimation of the maximal Lyapunov exponent; displayed in the MATH VIEW tab.
9. FFT spectral overlay: live FFT spectrum superimposed on the phase portrait and the WAVEFORM tab.
10. Scene arranger: 8-scene timeline with smooth parameter morphs; AUTO generator builds full arrangements from a mood pool.
11. VST3 / CLAP plugin: load inside Ableton, FL Studio, Logic Pro, Reaper, and any other NIH-plug-compatible DAW.
12. Headless render: --headless --duration 60 --output clip.wav with no display required.
13. Live config reload: edit config.toml while the engine runs; changes take effect without restart.

5-minute quickstart

Pre-built binary

Download the file for your system from the latest release, unzip it and run math-sonify. Audio starts immediately on the system default output device. See Installation for which file to pick.

Build from source

Requires Rust 1.85+ and a working audio output device.

git clone https://gitlab.com/mattbusel/math-sonify
cd math-sonify
cargo run --release

Headless export (no GUI)

cargo run --release -- --headless --duration 60 --output clip.wav

Architecture

ODE Solver (120 Hz, sim thread)
    |
    |  53 dynamical systems -- Lorenz, Rossler, Duffing, Kuramoto, Three-Body,
    |  Hyperchaos (4D), Finance, WINDMI, Liu, Genesio-Tesi, Shimizu-Morioka, ...
    |  RK4 integration per configured dt
    |
    v
Parameter Morphing (arrangement layer)
    |
    |  Scene arranger linearly interpolates all numeric config fields
    |  between named snapshots; string fields switch at midpoint
    |
    v
Sonification Mapper (sim thread, 120 Hz)
    |
    |  DirectMapping    -- state quantized to musical scale -> oscillator freqs
    |  OrbitalResonance -- angular velocity + Lyapunov exponent drive pitch
    |  GranularMapping  -- trajectory speed -> grain density and pitch
    |  SpectralMapping  -- state -> 32-partial additive envelope
    |  FmMapping        -- attractor drives carrier/modulator ratio and index
    |  AmMapping        -- amplitude modulation driven by state variables
    |  VocalMapping     -- state interpolates between vowel formant positions
    |  Waveguide        -- Karplus-Strong string with chaotic modulation
    |  Resonator        -- modal resonator bank driven by attractor
    |
    v  [crossbeam bounded channel, try_recv in audio callback]
    v
Audio Synthesis (audio thread, 44100 / 48000 Hz)
    |
    |  Per-layer DSP:
    |    Oscillator(s) [PolyBLEP anti-aliased] --> ADSR --> Waveshaper --> Bitcrusher
    |
    |  Master bus (shared across up to 4 layers):
    |    3-Band EQ --> LP BiquadFilter --> Stereo DelayLine --> Chorus
    |    --> FDN Reverb (8-channel, modulated) --> Lookahead Limiter
    |
    v
DAW (VST3 / CLAP plugin) or Desktop (standalone cpal output)

Thread safety: the sim thread and audio thread communicate through a bounded crossbeam-channel of capacity 16. The audio callback calls try_recv and renders silence on a miss, so it is never blocked. The UI thread reads shared state through parking_lot::Mutex on the control rate.

Supported mathematical systems (53)

Sonification modes (9)

Generative Composition Engine (src/composer.rs)

The composition engine (ComposerEngine) turns the running attractor into a structured musical piece in real time, without any pre-written score.

Musical forms

Components

MIDI export example

use math_sonify::composer::{ComposerEngine, MusicalForm, ProgressionStyle, TimeSig};

use math_sonify::systems::{DynamicalSystem, Lorenz};

let mut engine = ComposerEngine::new(
    MusicalForm::Aba,
    ProgressionStyle::JazzTurnaround,
    TimeSig::FOUR_FOUR,
    120.0,   // BPM
    120.0,   // control rate Hz
    8,       // section length in bars
);

// Tick the engine once per control step with the attractor's state:
let mut lorenz = Lorenz::new(10.0, 28.0, 8.0 / 3.0);
for _ in 0..120 * 30 {
    lorenz.step(1.0 / 120.0 / 10.0);
    let state = lorenz.state();
    let pitch = (60.0 + state[0].clamp(-20.0, 20.0)) as u8; // x picks the note
    let frame = engine.tick(state, pitch, 90, 0.5, 0.9);
    // frame.chord, frame.motif, frame.section_idx, frame.bar_position, ...
    let _ = frame;
}

// Export when done:
engine.export_midi("composition.mid", 120.0).ok();

Fractal Dimension Analyzer (src/fractal.rs)

The fractal analyzer characterises the geometric and dynamical structure of the attractor in real time. All metrics are displayed in the Math View tab.

Algorithms

AttractorCharacterization struct

pub struct AttractorCharacterization {
    pub fractal_dim: f64,                    // Box-counting D₀
    pub correlation_dim: f64,                // Grassberger-Procaccia D₂
    pub lyapunov_spectrum: Vec<f64>,         // Full spectrum λ₁ ≥ λ₂ ≥ ... ≥ λₙ
    pub kaplan_yorke_dim: f64,               // D_KY from the spectrum
    pub kolmogorov_entropy: f64,             // hKS = Σ positive λᵢ
    pub phase_space_volume_contraction: f64, // Σ all λᵢ (< 0 for dissipative)
    pub attractor_type: AttractorType,       // FixedPoint / LimitCycle / StrangeAttractor / Hyperchaos
    pub sample_size: usize,
    pub last_updated_ticks: u64,
}

AttractorType is derived automatically from the spectrum sign pattern:

Usage

use math_sonify::fractal::FractalAnalyzer;

use math_sonify::systems::{DynamicalSystem, Lorenz};

let mut analyzer = FractalAnalyzer::new(3); // 3-D system

// Collect a stretch of trajectory, then analyse it:
let dt = 0.005;
let mut lorenz = Lorenz::new(10.0, 28.0, 8.0 / 3.0);
let trajectory: Vec<Vec<f64>> = (0..4000)
    .map(|_| {
        lorenz.step(dt);
        lorenz.state().to_vec()
    })
    .collect();
let deriv = |s: &[f64]| lorenz.deriv_at(s);
let ch = analyzer.analyze(&trajectory, &deriv, dt, 0);
println!("{}", analyzer.lyapunov_spectrum().summary());
// λ = [+0.9053, -0.0001, -14.572]  D_KY=2.062  hKS=0.9053  div=-13.667

Network of Coupled Oscillators (src/network.rs)

OscillatorNetwork places up to 16 coupled oscillators on an arbitrary graph topology, with each oscillator mapped to a separate audio voice.

Network topologies

Oscillator models

Kuramoto network: phase oscillators on an arbitrary graph:

dθᵢ/dt = ωᵢ + Σⱼ Kᵢⱼ sin(θⱼ − θᵢ)

Each oscillator's phase maps directly to an audio frequency. The order parameter r ∈ [0, 1] measures synchronisation.

Stuart–Landau network: complex-amplitude oscillators (normal form of the Hopf bifurcation):

dAᵢ/dt = (μᵢ + iωᵢ − |Aᵢ|²)·Aᵢ + Σⱼ Kᵢⱼ·Aⱼ

With diffusive coupling and heterogeneous μ, the network exhibits:

• Amplitude death (μ < 0 and coupling pushes all voices to zero).
• Oscillation revival (coupling restores oscillations suppressed by individual μ < 0).

Audio voice mapping

Each tick, OscillatorNetwork::state() returns a NetworkState:

pub struct NetworkState {
    pub n: usize,
    pub frequencies: Vec<f64>,   // per-voice audio frequency (Hz)
    pub amplitudes: Vec<f64>,    // per-voice amplitude [0, 1]
    pub phases: Vec<f64>,        // oscillator phase (radians)
    pub order_parameter: f64,    // Kuramoto r or mean amplitude
    pub amplitude_death: bool,   // true if network collapsed to zero
    pub active_voices: usize,    // number of non-silent voices
}

NetworkState::sorted_voices() returns (frequency, amplitude) pairs sorted by amplitude, ready for polyphonic voice assignment.

Example

use math_sonify::network::{OscillatorNetwork, NetworkTopology};

// 8 Kuramoto oscillators in a small-world graph.
let mut net = OscillatorNetwork::kuramoto(
    8,
    &NetworkTopology::SmallWorld { rewire_prob: 0.15 },
    2.0,   // coupling K
    0.4,   // natural frequency spread
    220.0, // base audio frequency (Hz)
    440.0, // frequency range (Hz)
    42,    // seed
);

// Sim loop (120 Hz):
net.step(1.0 / 120.0);
let st = net.state();
// Route st.frequencies[i] and st.amplitudes[i] to audio voice i.
println!("r = {:.3}  voices = {}", st.order_parameter, st.active_voices);

Musical scales (20)

MIDI export guide

math-sonify can export attractor trajectories to Standard MIDI Files (SMF format 0) that import cleanly into Ableton Live, FL Studio, Logic Pro, Reaper, and any other DAW.

Mapping

From the GUI

1. Open the MIXER tab.
2. Click Record MIDI to start capturing. The status bar shows the frame count.
3. Click Stop + Export to choose a filename and write the .mid file.

From Rust code

use math_sonify::midi_export::{MidiExporter, SCALE_PENTATONIC_C4};
use math_sonify::systems::{DynamicalSystem, Lorenz};

// Collect (x, y, z) points from the ODE solver
let mut lorenz = Lorenz::new(10.0, 28.0, 8.0 / 3.0);
let trajectory: Vec<(f64, f64, f64)> = (0..2000)
    .map(|_| {
        lorenz.step(0.005);
        let s = lorenz.state();
        (s[0], s[1], s[2])
    })
    .collect();
let exporter = MidiExporter::new();   // 480 ticks per quarter note
let track = exporter.trajectory_to_track(
    "Lorenz Take 1",
    &trajectory,
    SCALE_PENTATONIC_C4,
    120.0,   // BPM
);
exporter.export_to_file(&[track], "lorenz_take1.mid").unwrap();

Multiple tracks can be passed to export_smf / export_to_file; they are merged into the single track required by SMF format 0, with each track's notes placed on a different MIDI channel (0-15) for DAW separation.

Headless export

cargo run --release -- --headless --duration 30 --output take.wav --export-midi take.mid

Collaborative session guide

Run the app with a collaboration address and other people can play it with you:

math-sonify --collab 127.0.0.1:9001     # this machine only
math-sonify --collab 0.0.0.0:9001       # anyone on your network

Then open collab.html (included in the repository and the release downloads) in a browser, enter ws://<your-ip>:9001, and press Connect. Every connected player gets sliders for the main parameters, buttons to switch systems, and a box to set any config.toml value by its dotted path. Changes are heard within one control tick and every player sees them. The status bar shows who joined and what they changed.

Any WebSocket client works too, for example websocat ws://127.0.0.1:9001, one JSON object per message:

// Client -> server
{ "set":     { "lorenz.rho": 28.5, "system.name": "rossler" } }
{ "claim":   ["lorenz.rho"] }
{ "release": ["lorenz.rho"] }
{ "get":     ["lorenz.rho", "system.speed"] }

// Server -> client
{ "welcome":     { "client_id": 3, "peers": 2 } }
{ "update":      { "param": "lorenz.rho", "value": 28.5, "owner": 3 } }
{ "values":      { "lorenz.rho": 28.5, "system.speed": 1.0 } }
{ "claimed":     ["lorenz.rho"] }
{ "error":       "parameter 'lorenz.rho' is owned by client 1" }
{ "peer_joined": { "client_id": 4, "total": 2 } }
{ "peer_left":   { "client_id": 4, "total": 1 } }

Parameters are the dotted paths of config.toml (lorenz.sigma, system.speed, audio.reverb_wet, sonification.mode, ...). Values get the same clamping as config.toml, and a value of the wrong type is refused with an error. A claimed parameter can only be changed by its owner until they release it or disconnect.

The server is also a library type, if you want the same thing in your own program:

use math_sonify::collab::{ApplyFn, CollabServer, GetFn};
use math_sonify::config::Config;
use parking_lot::Mutex;
use std::sync::Arc;

let config = Arc::new(Mutex::new(Config::default()));
let (c1, c2) = (config.clone(), config.clone());
let apply: Box<ApplyFn> = Box::new(move |path, value| c1.lock().set_path(path, value));
let get: Box<GetFn> = Box::new(move |path| c2.lock().get_path(path));
let (events, _rx) = crossbeam_channel::unbounded();

let server = CollabServer::new("127.0.0.1:9001", apply, get, events).unwrap();
server.run_background().unwrap();

Legacy performance protocol (collaboration.rs)

math_sonify::collaboration is a separate building block: a JSON message format for performers who each run their own instance and share attractor state. The app does not use it (use --collab above); it lets multiple performers share attractor state in real time. Any transport layer (WebSocket, UDP, OSC) can carry the messages; the module itself only handles serialisation and session logic.

Concepts

• Session -- a named room (e.g. "concert-2026-03-22") that holds up to 8 performers.
• Performer -- identified by a unique string ID, carries live (x, y, z) attractor coordinates, BPM, volume, and an RGB colour.
• Messages -- typed JSON objects: JoinSession, LeaveSession, StateUpdate, ParameterSync, ChatMessage, KickOff.

Example flow

use math_sonify::collaboration::{CollaborationClient, PerformerState};

// Create local performer
let performer = PerformerState::new("alice-01", "Alice");
let mut client = CollaborationClient::new(performer);

// Join
let join_msg = client.join_message("my-session");
let json = CollaborationClient::serialize_message(&join_msg);
// ... send json over your WebSocket / UDP socket ...

// Each sim tick: push current attractor state
let (x, y, z) = (1.2, -3.4, 20.5);
let update = client.push_xyz(x, y, z);
let json = CollaborationClient::serialize_message(&update);
// ... send json ...

// Receive a message
let incoming_json = r#"{"type":"KickOff","session_id":"my-session","bpm":128.0}"#;
let msg = CollaborationClient::deserialize_message(incoming_json).unwrap();

Server-side session tracking

use math_sonify::collaboration::{CollaborationSession, PerformerState};

let mut session = CollaborationSession::new("my-session");

// On receive JoinSession
let performer_state = PerformerState::new("alice-01", "Alice");
session.join(performer_state.clone()).expect("session has room");

// On receive StateUpdate
session.update_state(performer_state);

// Broadcast mean-attractor coordinates to new joiners
let sync_msg = session.broadcast_message();

Message reference

{ "type": "JoinSession",   "session_id": "room1", "performer": { ... } }
{ "type": "LeaveSession",  "performer_id": "alice-01" }
{ "type": "StateUpdate",   "performer": { "x": 1.2, "y": -3.4, "z": 0.8, ... } }
{ "type": "ParameterSync", "params": { "rho": 28.0, "sigma": 10.0 } }
{ "type": "ChatMessage",   "performer_id": "alice-01", "text": "raising sigma now" }
{ "type": "KickOff",       "session_id": "room1", "bpm": 128.0 }

Presets

math-sonify ships with 43 named presets in six categories. In the app, pick one from the preset list; type in the search box to filter by name, click the star to mark favorites, and tick Favorites only to see just those. From code, math_sonify::patches::load_preset(name) returns the preset's full Config.

The AUTO arrangement generator picks 6 presets from a mood pool, scatters system parameters into varied dynamical regimes, randomises synthesis settings, and builds an 8-scene timeline with morphs as the main musical event.

Audio output

math-sonify outputs 32-bit IEEE float stereo PCM at the system default sample rate (44100 or 48000 Hz).

Installation

Download

Grab a prebuilt app from the latest release. Pick the file that matches your computer:

Unpack it and run math-sonify (math-sonify.exe on Windows). Keep config.toml next to it if you want to change the defaults. math-sonify --help lists the headless WAV render options. SHA256SUMS.txt on the release page lets you check the download. collab.html is the page for playing together (see the collaborative session guide).

The binaries are not code-signed, so your system will be cautious the first time:

• Windows: SmartScreen may say "Windows protected your PC" or "unknown publisher". Click More info, then Run anyway.
• macOS: Gatekeeper may refuse to open it. Right-click (or Control-click) the file, choose Open, then Open again. From a terminal, xattr -d com.apple.quarantine ./math-sonify does the same.
• Linux: needs ALSA (libasound2), which almost every desktop already has.

With Cargo

If you have Rust installed:

cargo install math-sonify

On Linux, install the audio and windowing headers first, for example on Debian/Ubuntu: sudo apt install pkg-config libasound2-dev libx11-dev libxcursor-dev libxrandr-dev libxi-dev libxkbcommon-dev libgl1-mesa-dev libudev-dev.

From source

Requires Rust 1.85+ and a working audio output device.

git clone https://gitlab.com/mattbusel/math-sonify
cd math-sonify
cargo run --release

Build the VST3 / CLAP plugin

The plugin lives in the plugin/ workspace crate (it is not published to crates.io because nih-plug is only available from git):

cargo build --release -p math-sonify-plugin

Copy the output to your DAW plugin folder:

After copying, trigger a plugin rescan in your DAW (Options > Plug-in Manager in Ableton; Plug-in Database > Rescan in FL Studio).

VST/CLAP plugin setup

1. Run cargo build --release -p math-sonify-plugin.
2. Locate the output file in target/release/.
3. Copy to the system VST3 folder for your platform (table above).
4. Open your DAW and trigger a plugin rescan.
5. Search for "math-sonify" in the plugin browser.
6. The plugin exposes all system parameters as automatable VST3 parameters.
7. MIDI output from the plugin can be routed to any instrument track.

GUI

Five top-level tabs:

• SYNTH -- system selector, parameter sliders, sonification mode, scale, effects chain, randomize, preset browser.
• MIXER -- per-layer volume/pan/ADSR, master effects (EQ, delay, chorus, reverb), VU meters, WAV export, MIDI record/export.
• ARRANGE -- scene timeline, morph time controls, AUTO arrangement generator with mood selection.
• MATH VIEW -- live phase portrait (XY/XZ/YZ/3D), bifurcation diagram, custom ODE text input, state readout.
• WAVEFORM -- oscilloscope and spectrum analyzer.

Performance mode (F) switches to fullscreen phase portrait only.

Keyboard shortcut reference

Configuration

The application reads config.toml from the current working directory at startup. The file is watched with notify; edits take effect without restarting.

[system]
name  = "lorenz"   # see full system list above
dt    = 0.001      # ODE integration time step (clamped 0.0001..0.1)
speed = 1.0        # simulation speed multiplier (0..100)

[lorenz]
sigma = 10.0
rho   = 28.0
beta  = 2.6667

[rossler]
a = 0.2
b = 0.2
c = 5.7

[hyperchaos]
a = 35.0
b = 3.0
c = 28.0
d = -7.0     # must be negative

[windmi]
a = 0.9
b = 2.5

[finance]
a = 3.0
b = 0.1
c = 1.0

[kuramoto]
n_oscillators = 8
coupling      = 1.5

[duffing]
delta = 0.3
alpha = -1.0
beta  = 1.0
gamma = 0.5
omega = 1.2

[van_der_pol]
mu = 2.0

[audio]
sample_rate      = 44100
buffer_size      = 512
reverb_wet       = 0.4
delay_ms         = 300.0
delay_feedback   = 0.3
master_volume    = 0.7
bit_depth        = 16.0    # 1..32 (32 = bypass bitcrusher)
rate_crush       = 0.0     # 0..1 (0 = bypass)
chorus_mix       = 0.0
chorus_rate      = 0.5     # Hz
chorus_depth     = 3.0     # ms
waveshaper_drive = 1.0
waveshaper_mix   = 0.0

[sonification]
mode                = "direct"
# Modes: direct | orbital | granular | spectral | fm | am | vocal | waveguide | resonator
scale               = "pentatonic"
# Scales: pentatonic | natural_minor | harmonic_minor | dorian | phrygian | lydian
#         | mixolydian | locrian | whole_tone | blues | hirajoshi | hungarian_minor
#         | octatonic | chromatic | just_intonation | microtonal | edo19 | edo31 | edo24
#         | harmonic_series
base_frequency      = 220.0
octave_range        = 3.0
transpose_semitones = 0.0
chord_mode          = "none"
# Chord modes: none | major | minor | power | sus2 | octave | dom7 | open_fifth | cluster
portamento_ms       = 80.0
voice_levels        = [1.0, 0.8, 0.6, 0.4]
voice_shapes        = ["sine", "sine", "sine", "sine"]
# Shapes: sine | saw | square | triangle | noise

[viz]
trail_length = 800
projection   = "xy"   # xy | xz | yz | 3d
glow         = true
theme        = "neon" # neon | amber | ice | mono

Audio-driven ODE morphing guide

In addition to the classic forward pipeline (ODE state → audio), math-sonify can reverse the flow: use incoming microphone audio to continuously modify ODE parameters in real time.

In the app, start it with --mic:

math-sonify --mic

The default input device then steers the Lorenz attractor (sigma from loudness, rho from brightness, beta from mid-band energy) while the synth keeps playing, so pick the Lorenz system to hear it. Lock a slider in the app to keep the microphone off that parameter. Headphones keep the speakers from feeding back into the microphone.

How it works

Microphone / line-in (cpal default input)
    |
    v  per-frame (configurable hop size, default 512 samples)
AudioInputAnalyzer
    |  computes:
    |    RMS        → Lorenz σ  (louder = more chaos, σ ∈ [5, 30])
    |    Centroid   → Lorenz ρ  (brighter spectrum = higher ρ, ρ ∈ [15, 60])
    |    Flux       → system switch trigger (transients trigger attractor changes)
    |    8-band energy → Lorenz β (mid-band energy → β ∈ [1.5, 4.0])
    v
AudioFeatures { rms, centroid, flux, bands: [f32; 8] }
    |
    v
AudioOdeBridge  (delta suppression: only emits patch when change exceeds threshold)
    |
    v
OdePatch → simulation thread (applies sigma/rho/beta overrides)

Dual mode

DualMode lets both pipelines run simultaneously:

Usage

use math_sonify::audio_driven::{BridgeConfig, DualMode};

// Build the reverse pipeline
let dual = DualMode::new(BridgeConfig::default());
let (mut analyzer, patch_rx, _stop) = dual.build_reverse_pipeline();

// Feed audio samples from cpal input callback:
// analyzer.feed(sample);  // called per sample in the cpal callback

// In the simulation thread:
let mut lorenz = math_sonify::config::LorenzConfig::default();
for patch in patch_rx.try_iter() {
    if let Some(sigma) = patch.sigma { lorenz.sigma = sigma; }
    if let Some(rho)   = patch.rho   { lorenz.rho   = rho;   }
    if patch.trigger_system_switch   { /* switch to next attractor */ }
}

Configuration (BridgeConfig)

Mathematical background

Dynamical systems and attractors

A dynamical system is a set of differential equations dx/dt = f(x) or a map x_{n+1} = f(x_n). The long-term behaviour of trajectories in phase space determines the system's character:

• Fixed point: all trajectories converge to a single point (stable equilibrium).
• Limit cycle: trajectories converge to a closed loop (periodic oscillation).
• Quasi-periodic: trajectories wind around a torus; the ratio of frequencies is irrational.
• Chaotic attractor (strange attractor): trajectories are bounded but never repeat; nearby trajectories diverge exponentially (sensitive dependence on initial conditions).

Lyapunov exponents

The maximal Lyapunov exponent λ₁ quantifies the average rate of exponential divergence of nearby trajectories:

||δx(t)|| ≈ e^{λ₁ t} ||δx(0)||

• λ₁ < 0: stable fixed point or limit cycle.
• λ₁ = 0: quasi-periodic or at a bifurcation boundary.
• λ₁ > 0: chaotic. The Lorenz system at standard parameters has λ₁ ≈ 0.906.

math-sonify estimates λ₁ using a standard rescaling algorithm: a shadow trajectory is integrated alongside the main one, the separation is measured every N steps, its logarithm is accumulated, and the separation is rescaled. This runs at LYAP_INTERVAL_TICKS (every 2 seconds of sim time).

Hindmarsh-Rose Neuron

src/hindmarsh_rose.rs provides a clean typed API for the Hindmarsh-Rose bursting neuron model (HindmarshRoseConfig, HindmarshRoseState, HindmarshRoseNeuron). The neuron implements the classic three-variable system:

dx/dt = y - a·x³ + b·x² - z + I_ext
dy/dt = c - d·x² - y
dz/dt = r · (s·(x - x_rest) - z)

Classic chaotic-bursting parameters: a=1, b=3, c=1, d=5, r=0.001, s=4, x_rest=-1.6, i_ext=1.5.

Headless CLI

# Render hindmarsh-rose to WAV
math-sonify --headless --attractor hindmarsh-rose --duration 5 --output hr.wav

# Run spectral analysis on the trajectory
math-sonify --headless --attractor hindmarsh-rose --spectrum

Spectral Analysis

src/spectrum_analyzer.rs provides SpectralAnalyzer which computes the DFT of an arbitrary sample sequence and returns dominant frequencies.

• Cooley-Tukey radix-2 FFT for power-of-2 lengths; O(N²) DFT fallback.
• Hann windowing to reduce spectral leakage.
• DftResult { frequencies, magnitudes, dominant_freq, spectral_centroid }.
• SpectralAnalyzer::dominant_frequencies(result, top_k): sorted by magnitude.

FFT spectral analysis

The FFT module (spectrum.rs) computes a 1024-point Hann-windowed FFT of the synthesised audio output and displays:

• Magnitude spectrum (dB scale, linear frequency axis).
• Spectral centroid (brightness indicator).
• Fundamental frequency estimate via parabolic interpolation on the magnitude peak.

The audio-driven morphing module uses the same FFT on the input signal to extract audio features.

Chaos onset in the Lorenz system

The Lorenz system (σ=10, β=8/3, ρ) undergoes the following transitions as ρ increases:

Building and testing

# Run all unit and integration tests (1,800+ tests, no display required)
cargo test --lib --tests

# Release binary
cargo build --release --bin math-sonify

# Release plugin
cargo build --release -p math-sonify-plugin

# Documentation
cargo doc --no-deps --open

The test suite covers: ODE solver accuracy (attractor bounds, energy conservation, synchronization thresholds), scale quantization, polyphony, config parsing and clamping, scene arranger timeline consistency, oscillator amplitude bounds, ADSR envelope behavior, all-presets load/validate, lerp_config correctness for every system, bifurcation parameter sweeps, MIDI frame recording and SMF export, preset gallery filtering and discovery, and collaboration session/client message round-trips.

Troubleshooting

No audio / device not found

• math-sonify uses cpal::default_host().default_output_device(). Ensure a device is selected in OS audio settings.
• Windows exclusive mode: close any application holding the device exclusively.
• Linux ALSA: sudo apt install libasound2-dev, add user to audio group.
• Sample rate mismatch: set sample_rate = 48000 in config.toml.

High CPU usage

• Increase buffer_size to 1024 or 2048.
• Disable Evolve mode when not in use.
• For Three-Body and Lorenz-96, reduce system.speed.

Distorted audio

• Lower audio.master_volume.
• Set waveshaper_drive = 1.0 and waveshaper_mix = 0.0.

Phase portrait blank

• Wait 2-3 seconds for the trail to build after startup or after pressing R.

Config not loading

• math-sonify looks for config.toml in the current working directory.

VST3/CLAP not appearing

• Copy to the correct system folder and trigger a plugin rescan in your DAW.
• The plugin is built from the plugin/ crate with cargo build --release -p math-sonify-plugin.

MIDI export produces empty file

• Start recording before the session (click Record MIDI in the MIXER tab), then export.
• Headless: pass --export-midi output.mid on the command line.

Bifurcation Sweeper (src/bifurcation.rs)

The bifurcation sweeper runs a dynamical system across a continuous range of a single parameter, records the steady-state attractor at each step, and exports the results in two formats.

Usage

Trigger from the UI with the Bifurcation Sweep button in the Bifurc tab (tab 7), or call from Rust:

# fn main() -> anyhow::Result<()> {
use math_sonify::bifurcation::{BifurcationConfig, BifurcationSweeper};
use math_sonify::config::Config;
use std::path::Path;

let base_cfg = Config::default();

let config = BifurcationConfig {
    parameter_name: "rho".into(),
    range_start: 0.5,
    range_end: 30.0,
    steps: 200,
    duration_per_step_ms: 300,
};
let result = BifurcationSweeper::sweep(&config, &base_cfg, Path::new("recordings"))?;
println!("WAV written to: {}", result.audio_path.display());
# Ok(())
# }

Files are written to the recordings/ directory (created automatically).

Preset Interpolation and Morphing (src/preset_interpolation.rs)

Linear interpolation between any two named presets. All numeric fields are blended continuously; string fields (system name, mode, scale, chord mode) switch at t = 0.5.

Key types

Usage

use math_sonify::patches::load_preset;
use math_sonify::preset_interpolation::{interpolate, MorphTimeline, PresetMorphSchedule};

// Single interpolation at t = 0.5
let mid = interpolate(&load_preset("Midnight Approach"), &load_preset("Glass Harp"), 0.5);

// Full morph timeline (durations in milliseconds of wall time)
let sched = PresetMorphSchedule::from_pairs(&[
    ("Midnight Approach", 8_000),
    ("Glass Harp", 6_000),
    ("Clockwork Insect", 10_000),
]);
let mut timeline = MorphTimeline::new(sched);
while !timeline.is_finished() {
    let cfg = timeline.tick(); // call each frame; hand cfg to your engine
    # let _ = cfg;
}

The Morph control in the ARRANGE tab exposes source/target preset selectors and a duration slider.

Collaborative OSC Sync (src/osc_sync.rs, osc feature)

A library building block for syncing parameters between instances over UDP multicast. The app itself does not use it; to play together, use --collab (see the collaborative session guide).

Enable with --features osc (adds the rosc optional dependency).

Supported OSC paths

Components

# #[cfg(not(feature = "osc"))] fn main() {}
# #[cfg(feature = "osc")]
# fn main() -> anyhow::Result<()> {
use math_sonify::osc_sync::{OscSyncServer, OscSyncClient, CollaborativeSession};

let server  = OscSyncServer::new()?;
let client  = OscSyncClient::new()?;
let session = CollaborativeSession::new();

// Broadcast a parameter change:
client.send_param("reverb_wet", 0.6)?;

// Receive and apply incoming changes:
if let Some((addr, msg)) = server.try_recv() {
    session.apply(addr, msg);
}
println!("{} peer(s) connected", session.peer_count());
# Ok(())
# }

Audio Recording Mode (src/recorder.rs)

Press R to start/stop recording. Files are saved to recordings/YYYYMMDD_HHMMSS.wav (epoch timestamp). A pulsing red REC indicator appears in the status bar while active.

Configuration

Types

# fn main() -> anyhow::Result<()> {
use math_sonify::recorder::{AudioRecorder, RecordingDepth, RecordingSampleRate, SegmentRecorder};
use std::path::Path;

let stereo_f32_samples = vec![0.0f32; 2 * 44_100]; // one second of interleaved L/R

// Open a rolling recorder
let mut rec = AudioRecorder::start(
    Path::new("recordings"),
    RecordingDepth::Bits32,
    RecordingSampleRate::Hz44100,
)?;
rec.push_samples(&stereo_f32_samples)?;
let path = rec.stop()?;

// Auto-named segment (60 s clip)
let mut seg = SegmentRecorder::start(
    Path::new("recordings"),
    "lorenz",
    "Lorenz Ambience",
    60,
    RecordingDepth::Bits32,
    RecordingSampleRate::Hz44100,
)?;
let done = seg.push_samples(&stereo_f32_samples)?;  // returns true when clip is full
if done { seg.finish()?; }
# Ok(())
# }

Contributing

1. Fork and create a feature branch.
2. Run cargo fmt --all and cargo clippy --all-targets --all-features -- -D warnings.
3. Add tests for new public API (unit tests in the module, integration tests in tests/integration.rs).
4. Open a pull request. CI (fmt, clippy, test, doc, release build) must pass.

Code style: no unsafe without comment, no .unwrap() in src/ outside tests, audio thread must be real-time safe (no heap allocation, no blocking I/O).

Rössler Attractor (src/rossler.rs)

A standalone module providing idiomatic config/state types for the Rössler spiral strange attractor.

Types

Equations of motion

dx/dt = -y - z
dy/dt =  x + a·y
dz/dt =  b + z·(x - c)

With a=0.2, b=0.2, c=5.7 the attractor is bounded (|x|, |y| < 30) and exhibits near-periodic chaos.

Example

use math_sonify::rossler::{RosslerAttractor, RosslerConfig};

let mut attractor = RosslerAttractor::new(RosslerConfig::default());
for _ in 0..1000 {
    attractor.step(0.01);
}
let s = attractor.state();
println!("x={:.3} y={:.3} z={:.3}", s.x, s.y, s.z);

Van der Pol Oscillator (src/vanderpol.rs)

A standalone module for the Van der Pol self-sustaining limit-cycle oscillator.

Types

Equations of motion

dx/dt = y
dy/dt = μ·(1 − x²)·y − x

For μ > 0 the system converges to a stable limit cycle. Larger μ gives increasingly relaxation-oscillator-like behaviour with sharp transitions.

Example

use math_sonify::vanderpol::{VanDerPolConfig, VanDerPolOscillator};

let mut osc = VanDerPolOscillator::new(VanDerPolConfig { mu: 2.0 });
for _ in 0..2000 {
    osc.step(0.01);
}
let s = osc.state();
println!("x={:.3} y={:.3}", s.x, s.y);

FM Synthesis (src/synthesis/physical.rs)

DX7-style frequency modulation synthesis is now available as a PhysicalSynth mode.

New types

State mapping

Usage

use math_sonify::synthesis::{build_physical_synth, FmConfig, FmSynth, PhysicalMode};

let mut synth = build_physical_synth(PhysicalMode::Fm, 80.0, 1200.0, 44100.0);
let state = [1.0f64, 0.5, 0.0];
let sample = synth.next_sample(&state, 44100.0);

Multi-Attractor Blend (src/blend.rs)

Smoothly interpolates between two attractor states and sequences multiple attractors with S-curve crossfades.

use math_sonify::blend::{AttractorBlend, AttractorState, BlendConfig, MultiAttractorSequencer, SequenceEntry};

// Linear blend at 50%
let a = AttractorState::new(1.0, 2.0, 3.0);
let b = AttractorState::new(10.0, 20.0, 30.0);
let cfg = BlendConfig::new(0.5);
let mid = AttractorBlend::interpolate(a, b, &cfg);

// S-curve crossfade between two trajectories
let a_traj: Vec<AttractorState> = vec![AttractorState::new(0.0, 0.0, 0.0); 100];
let b_traj: Vec<AttractorState> = vec![AttractorState::new(5.0, 5.0, 5.0); 100];
let blended = AttractorBlend::smooth_transition(&a_traj, &b_traj, 50);

// Alpha schedule (smoothstep 0→1)
let schedule = AttractorBlend::morph(64);

// Sequence two attractors with crossfade
let entries = vec![
    SequenceEntry { attractor_name: "lorenz".to_string(), duration_samples: 200, crossfade_samples: 40 },
    SequenceEntry { attractor_name: "rossler".to_string(), duration_samples: 200, crossfade_samples: 40 },
];
let trajectory = MultiAttractorSequencer::render(&entries, 0.01);

CLI: --blend lorenz:rossler: renders a blended trajectory and prints state count.

Key types:

• AttractorState { x, y, z }: phase-space point
• BlendConfig { alpha }: blend weight (0 = A, 1 = B)
• AttractorBlend::smooth_transition: smoothstep S-curve crossfade
• AttractorBlend::morph: alpha schedule from 0 to 1
• MultiAttractorSequencer::render: full multi-segment sequencer

Scale/Mode Mapper (src/scale_mapper.rs)

Maps attractor state values to musical pitches in a chosen scale/mode.

use math_sonify::scale_mapper::{MusicalScale, ScaleMapper, ScaleMode, midi_to_freq};
use math_sonify::blend::AttractorState;

// Create a D major scale
let scale = MusicalScale::new(62, ScaleMode::Major);
println!("{:?}", scale.pitch_class_set()); // [0, 2, 4, 5, 7, 9, 11]

// Quantize a value to the nearest note
let midi = scale.quantize(0.3, 2); // across 2 octaves

// Get a triad
let chord = scale.chord(-0.5); // [root, third, fifth]

// Full attractor → MIDI pipeline
let mapper = ScaleMapper::new(scale, 2);
let state = AttractorState::new(2.5, -0.8, 14.0);
let pitch = mapper.map_state(&state);
println!("MIDI {} ({:.1} Hz), degree {}, chord {:?}",
    pitch.midi_note, pitch.freq_hz, pitch.scale_degree, pitch.chord);

// Hz conversion
let freq = midi_to_freq(69); // 440.0

CLI: --scale major:60: maps a sample Lorenz trajectory to the C major scale and prints MIDI notes.

Supported modes: Major, Minor, Pentatonic, Dorian, Phrygian, Lydian, WholeTone, Chromatic.

Key types:

• MusicalScale { root_midi, mode }: scale definition
• MusicalScale::pitch_class_set(): semitone intervals above root
• MusicalScale::quantize(value, octaves): maps [-1,1] → nearest MIDI note
• MusicalScale::chord(value): returns triad [root, third, fifth]
• ScaleMapper::map_state(state) → MappedPitch { midi_note, freq_hz, scale_degree, chord }

License

MIT. See LICENSE.

Built with Rust, cpal, egui, nih-plug, crossbeam, parking_lot, hound, rayon, tracing, serde, serde_json, midly.