A monorepo of Wolfram Language physics simulations, data projects, and signal processing demonstrations — each runnable from the terminal via wolframscript and producing CSV data, an animated GIF, and audio output.

stem/
  stem-core/        Shared library: config, sonification pipeline, PCM synthesis, file export
  pendulum/         Simple and double pendulum ODE simulation
  lorenz/           Lorenz and Rössler strange attractor simulation
  asteroids/        NASA near-Earth asteroid tracker (live API data)
  cellular/         Conway's Game of Life and Wolfram Rule 110
  signal/           Fourier analysis demonstration (chord, sweep, AM)
  quantum/          Quantum mechanics (coherent state QHO, particle-in-a-box)
  primes/           Prime number patterns (Ulam spiral, prime gap rhythm)
  images/           2D image sonification via Hilbert curve traversal (brightness, colour, HSB modes)
  relativity/       General relativity (chirp: PN binary inspiral; geodesic: Schwarzschild orbits)
  cosmology/        CMB angular power spectrum and sky map sonification
  waves/            2D wave propagation and interference (FEM simulation)
  lagrange/         Circular restricted three-body problem, Lagrange point orbits
  config/           Global config defaults (config.json)
  docs/             Workflow guides

Download the free Wolfram Engine from https://www.wolfram.com/engine/ and follow the installer for your platform. wolframscript is included in the installer on all three platforms — no separate download needed.

Activate the free licence when prompted (requires a Wolfram account).

Verify your installation:

# macOS / Linux
wolframscript -version

# Windows (Command Prompt or PowerShell)
wolframscript -version

TTS is disabled by default. If the tool is missing the app prints a warning and continues.

Register for a free key at https://api.nasa.gov/. The built-in DEMO_KEY works at 30 requests/hour; a personal key removes that limit.

Set the key as an environment variable before running:

# macOS / Linux — add to ~/.zshrc or ~/.bashrc to persist
export NASA_API_KEY=your_key_here

# Windows PowerShell — set for the current session
$env:NASA_API_KEY = "your_key_here"

# Windows — set permanently via System Properties → Environment Variables
# Variable name: NASA_API_KEY   Value: your_key_here

Run any project from the stem/ root:

# Physics simulations
wolframscript -file pendulum/main.wl
wolframscript -file lorenz/main.wl

# Live NASA asteroid data
wolframscript -file asteroids/main.wl                                    # last 7 days
wolframscript -file asteroids/main.wl -- 2026-01-01 2026-12-31           # full year
wolframscript -file asteroids/main.wl -- 2026-01-01 2026-06-25 Phrygian  # date range + scale
wolframscript -file asteroids/main.wl -- 2026-06-20 2026-06-26 --no-orbital-elements

# Cellular automata
wolframscript -file cellular/main.wl                                     # Game of Life, R-pentomino
wolframscript -file cellular/main.wl -- --simulation.mode=rule110

# Signal processing
wolframscript -file signal/main.wl                                       # chord (default)
wolframscript -file signal/main.wl -- --simulation.mode=sweep
wolframscript -file signal/main.wl -- --simulation.mode=am

# Quantum mechanics
wolframscript -file quantum/main.wl                                      # QHO coherent state
wolframscript -file quantum/main.wl -- --simulation.mode=box             # particle-in-a-box
wolframscript -file quantum/main.wl -- --simulation.qho.alpha=3.0        # larger coherent amplitude

# Prime number patterns
wolframscript -file primes/main.wl                                       # Ulam spiral (default)
wolframscript -file primes/main.wl -- --simulation.mode=gaps             # prime gap rhythm
wolframscript -file primes/main.wl -- --simulation.ulam.size=201         # larger spiral
wolframscript -file primes/main.wl -- --simulation.gaps.count=10000      # more primes

# Gravitational waves — chirp mode
wolframscript -file relativity/main.wl                                   # GW150914 (36+29 M☉)
wolframscript -file relativity/main.wl -- --simulation.chirp.preset gw170817
wolframscript -file relativity/main.wl -- --simulation.chirp.mass1_solar 50 --simulation.chirp.mass2_solar 50
wolframscript -file relativity/main.wl -- --sonification.chirp.time_stretch 8

# Gravitational waves — geodesic mode (Schwarzschild black hole)
wolframscript -file relativity/main.wl -- --simulation.mode geodesic    # bound orbit (default)
wolframscript -file relativity/main.wl -- --simulation.mode geodesic --simulation.geodesic.orbit_type plunging
wolframscript -file relativity/main.wl -- --simulation.mode geodesic --simulation.geodesic.orbit_type photon

# CMB power spectrum sonification
wolframscript -file cosmology/main.wl                                    # spectrum mode, simulated ΛCDM
wolframscript -file cosmology/main.wl -- --simulation.mode=sky           # sky map via Hilbert traversal
wolframscript -file cosmology/main.wl -- --simulation.cosmology.source=planck  # real Planck 2018 data

# 2D wave propagation (FEM)
wolframscript -file waves/main.wl                                        # ripple mode (circular membrane)
wolframscript -file waves/main.wl -- --simulation.mode=interference      # two-source interference pattern
wolframscript -file waves/main.wl -- --simulation.waves.wave_speed=1.5   # faster propagation
wolframscript -file waves/main.wl -- --simulation.waves.source_frequency=3.0

# Lagrange point orbits (CR3BP)
wolframscript -file lagrange/main.wl                                     # L4 libration, Sun-Jupiter
wolframscript -file lagrange/main.wl -- --simulation.mode=l5             # L5 libration
wolframscript -file lagrange/main.wl -- --simulation.mode=l1             # L1 saddle-point escape
wolframscript -file lagrange/main.wl -- --simulation.lagrange.preset=earth_moon

# 2D image sonification
wolframscript -file images/main.wl                                       # brightness mode, Gaussian test image
wolframscript -file images/main.wl -- --simulation.mode=colour           # colour mode
wolframscript -file images/main.wl -- --simulation.mode=hsb              # full HSB stereo mode
wolframscript -file images/main.wl -- --simulation.images.test_image=temperature

Each project writes outputs into its own directory:

Play audio:

# macOS
afplay signal/output/chord_narrative_full.wav
afplay pendulum/output/double_audio.wav
afplay lorenz/output/lorenz_audio.wav
afplay asteroids/output/asteroids_*.wav
afplay cellular/output/life_rpentomino_audio.wav
afplay quantum/output/qho_audio.wav
afplay primes/output/ulam_audio.wav
afplay primes/output/gaps_audio.wav
afplay relativity/output/chirp.wav
afplay relativity/output/gw170817.wav
afplay relativity/output/geodesic.wav
afplay cosmology/output/cmb_spectrum_audio.wav
afplay waves/output/ripple_audio.wav
afplay waves/output/interference_audio.wav
afplay lagrange/output/l4_audio.wav
afplay lagrange/output/l1_audio.wav
afplay images/output/images_brightness_audio.wav

# Linux — replace afplay with aplay
aplay signal/output/chord_narrative_full.wav
aplay pendulum/output/double_audio.wav

# Windows PowerShell — replace afplay with Start-Process wmplayer
Start-Process wmplayer signal\output\chord_narrative_full.wav
Start-Process wmplayer pendulum\output\double_audio.wav

See RELEASE_NOTES_v1.0.0.md for full app descriptions, physics notes, and listening guides.

Run all twelve apps with their most interesting presets and collect outputs into demo/:

wolframscript -file demo.wl

With spoken announcements:

# macOS / Linux
STEM_SPEAK=1 wolframscript -file demo.wl

# Windows PowerShell
$env:STEM_SPEAK = "1"; wolframscript -file demo.wl

With NASA asteroid data (requires API key):

# macOS / Linux
NASA_API_KEY=$NASA_API_KEY wolframscript -file demo.wl

# Windows PowerShell
$env:NASA_API_KEY = "your_key_here"; wolframscript -file demo.wl

Check whether a previous demo run completed successfully:

wolframscript -file demo.wl -- --check-only

Outputs are collected in demo/ with a written report at demo/demo-report.md. A full run takes approximately 3–4 minutes.

Solves the nonlinear pendulum ODE with NDSolve. Two modes: simple (one rod) and double (two rods, chaotic). The simple pendulum maps swing angle to an A minor pentatonic scale — each half-swing becomes one note, volume set by angular velocity. The double pendulum sonifies both rods independently in binaural stereo. See pendulum/README.md.

Simulates the Lorenz and Rössler strange attractors. Apex events on the trajectory trigger pitched notes; spatial position controls the stereo pan. The GIF renders the growing trajectory in x-z projection with a blue→cyan→orange→red colour gradient. See lorenz/README.md.

Fetches live close-approach data from NASA's NeoWs API. Each asteroid becomes one note — pitch reflects miss distance, timbre distinguishes hazardous from safe. The GIF shows a top-down solar system view with asteroids revealed farthest-to-closest, coloured cyan (safe) or red (hazardous). Asteroid directions are computed from Keplerian orbital elements fetched from the JPL Small Body Database. Accepts arbitrary date ranges and a musical scale argument. See asteroids/README.md.

Two cellular automata: Conway's Game of Life (2D, toroidal, B3/S23 rule) and Wolfram's Rule 110 (1D, Turing-complete). Population dynamics are mapped to pitch, pan, and volume; extinction and explosion events trigger short tone bursts. See cellular/README.md.

Demonstrates the discrete Fourier transform. Three modes — chord (sum of sinusoids), sweep (linear chirp), and am (amplitude modulation) — each generate a signal, corrupt it with Gaussian noise, recover it via frequency-domain filtering, and export the three stages as WAV files plus a spoken narrative. Unlike all other apps, the WAV output is the phenomenon rather than a sonification of something else. See signal/README.md.

Simulates quantum mechanical wave-packet evolution in two exactly-solvable systems. qho mode evolves a coherent state |α⟩ in the quantum harmonic oscillator using a truncated Hermite-Gauss basis (ħ=m=1). box mode evolves an equal superposition of the ground state and first excited state in a particle-in-a-box. Both modes export an animated probability-density GIF, a 3×3 snapshot PNG, and a time-series CSV of ⟨x⟩, Var(x), and speed. Stereo pan tracks mean position, pitch encodes position variance, and volume follows |d⟨x⟩/dt|. See quantum/README.md.

Visualises prime number structure in two modes. ulam mode generates a size×size grid winding the integers outward in a spiral — prime cells appear white, composites black — revealing the diagonal stripes that emerge from polynomial prime-rich progressions. The app also exports a 31×31 centre zoom with cell borders. gaps mode maps the sequence of gaps between consecutive primes to percussive audio: each prime triggers a short sine burst at a time proportional to its distance from p₁, so twin primes (gap=2) produce near-simultaneous attacks and large gaps leave audible rests. A second WAV at quarter tempo stretches the rhythm so individual gap lengths become easier to count by ear. See primes/README.md.

Two modes of general relativity simulation.

chirp — gravitational wave strain from a binary inspiral using the post-Newtonian (PN) approximation, the same analytic model behind LIGO's matched filters. The strain h(t) is literally an audio waveform: a chirp sweeping upward in frequency and amplitude, ending in an abrupt merger followed by an exponentially damped ringdown. Three preset comparison WAVs are produced automatically (gw150914, gw170817, stellar). Four physical correctness checks verify the PN formulas on each run and abort if they fail.

geodesic — test-particle and photon orbits around a Schwarzschild black hole, integrated numerically by NDSolve. Three orbit types: bound (elliptical orbit; GR periapsis precession traces a rosette), plunging (particle spirals past the event horizon in finite proper time), photon (light deflected by gravity — impact parameter controls deflection vs. capture). Each orbit is visualised as a polar plot showing the event horizon, photon sphere, and ISCO, and sonified with pitch mapped to the orbital angular frequency or gravitational blueshift depending on orbit type. See relativity/README.md.

Sonifies the Cosmic Microwave Background (CMB) angular power spectrum — the oldest light in the universe. Two modes: spectrum traverses the angular power spectrum from ℓ = 2 to ℓ = 2000, mapping each multipole to a note so the Sachs-Wolfe plateau, the first acoustic peak near ℓ ≈ 220, and the Silk damping tail are directly audible. sky generates a flat-sky Gaussian random field from the spectrum and traverses it pixel by pixel in Hilbert curve order, making the spatial temperature pattern of the CMB sound as a correlated noise texture. Both modes accept a --simulation.cosmology.source=planck flag to fetch the actual Planck 2018 best-fit spectrum from the Planck Legacy Archive (internet required). The PNG output shows the power spectrum with peak markers. See cosmology/README.md.

Solves the 2D wave equation using the finite element method (NDSolveValue on a spatial Region). Two modes: ripple places a Gaussian impulse at the centre of a circular membrane and records the wavefront as it reaches a set of listening points at increasing distances — the stereo sweep of arrivals from left to right makes the propagation speed directly audible. interference drives two coherent point sources in a rectangular tank and sweeps a listening point across the resulting fringe pattern — constructive and destructive fringes produce swells and silences in the audio. Four sanity checks (numerical stability, arrival time, causality, Dirichlet boundary) run on every execution. See waves/README.md.

Integrates test-particle trajectories in the circular restricted three-body problem (CR3BP) in the co-rotating reference frame. Three modes: l4 and l5 place a particle near the stable triangular Lagrange points and let it librate in a tadpole pattern for six orbital periods — the bounded, quasi-periodic orbit of Jupiter's Trojan asteroids. l1 places a particle near the unstable L1 saddle point, where it escapes within one to three orbital periods along the unstable manifold. In all modes, pitch maps to instantaneous angular velocity around the barycentre, pan to x-position in the co-rotating frame, and volume to inverse distance to the nearest primary. Named presets cover Sun-Jupiter, Earth-Moon, and Sun-Earth systems. See lagrange/README.md.

Converts 2D images into audio via Hilbert curve traversal. The Hilbert curve visits every pixel in locality-preserving order — pixels adjacent in the audio timeline are also spatially nearby — so spatial gradients become smooth pitch sweeps and sharp edges become abrupt jumps. Three sonification modes: brightness maps grayscale intensity linearly to frequency (simplest, best for first-time listeners); colour maps each pixel to the nearest of ten named colours, each with a fixed musical pitch (good for categorical images); hsb encodes hue, saturation, and brightness simultaneously in left frequency, right frequency, and amplitude (most information-dense). Three built-in scientific test images are included: a 2D Gaussian, a false-colour temperature map, and a quantum probability density. See images/README.md.

Every project uses a four-layer configuration system:

$HardcodedDefaults  →  config/config.json  →  <app>/config.json  →  CLI --key=value

Inspect the fully merged config for any project:

wolframscript -file pendulum/main.wl -- --config-dump
wolframscript -file cellular/main.wl -- --config-dump | python3 -m json.tool

Override any parameter at runtime using dot-separated key paths:

wolframscript -file pendulum/main.wl -- --simulation.mode=double
wolframscript -file lorenz/main.wl -- --simulation.mode=rossler
wolframscript -file cellular/main.wl -- --simulation.life.starting_pattern=gliderlgun
wolframscript -file signal/main.wl -- --simulation.chord.noise_level=0.8
wolframscript -file asteroids/main.wl -- --simulation.days_ahead=14
wolframscript -file quantum/main.wl -- --simulation.qho.alpha=3.0
wolframscript -file relativity/main.wl -- --simulation.chirp.mass1_solar 50

See docs/APPS.md for a full listing of each app's config keys.

All twelve projects load stem-core as a shared library. It provides:

• Config — LoadConfig, GetCfg, DeepMerge — four-layer config merging and safe key lookup
• Sonification pipeline — SonifyTrajectory, SpatialLayer, MotionLayer, EventLayer, MixLayers, RenderAudio
• Scale and synth — ScaleLookup, StemSynthNote, NormalizeBuffer, ExportAudioBuffer
• Export — ExportCSV, ExportGIF
• Accessibility — STEMHeading, STEMSection, STEMPrintN, STEMDescribeCSV/WAV/GIF, STEMSay
• Utils — EnsureDir, FmtN, LogError

See stem-core/README.md for the full API and stem-core/AGENTS.md for parameter details.

All projects run fully headlessly and write plain WAV files. Every console output line is a self-contained announcement so screen readers (VoiceOver on macOS, Orca on Linux, Narrator on Windows) read each item cleanly without splitting numbers across lines.

To enable spoken announcements alongside normal printed output, set STEM_SPEAK=1 before running:

# macOS / Linux
STEM_SPEAK=1 wolframscript -file pendulum/main.wl
STEM_SPEAK=1 wolframscript -file signal/main.wl

# Windows PowerShell
$env:STEM_SPEAK = "1"; wolframscript -file pendulum/main.wl

Platform TTS: macOS uses say, Linux uses espeak-ng (install with sudo apt install espeak-ng), Windows uses the built-in System.Speech. If TTS is unavailable the app prints a warning and continues silently.

The signal app's {mode}_narrative_full.wav is the most accessible single output — it chains spoken text with the clean, noisy, and recovered signals so the entire Fourier demonstration can be followed by listening alone.

For the complete VoiceOver + wolframscript workflow see docs/voiceover-wolframscript-guide.md and stem-core/ACCESSIBILITY.md.

MINT Access is a Swiss organisation promoting accessible STEM education. Website: mintaccess.ch (German)