⚠️ ARCHIVED - Development Moved to morphogen

project

type

status

beth_topics

⚠️ ARCHIVED - Development Moved to morphogen

This repository is archived. All active development has moved to https://github.com/scottsen/morphogen

See ARCHIVE_NOTICE.md for details.

Morphogen

Where computation becomes composition

Morphogen is a universal, deterministic computation platform that unifies domains that have never talked to each other before: audio synthesis meets physics simulation meets circuit design meets geometry meets optimization — all in one type system, one scheduler, one language.

Why Morphogen Exists

Current tools force you to:

Export CAD → import to FEA → export mesh → import to CFD → manually couple results
Write audio DSP in C++ → physics in Python → visualization in JavaScript
Bridge domains with brittle scripts and incompatible data formats

Morphogen eliminates this fragmentation. Model a guitar string's physics, synthesize its sound, optimize its geometry, and visualize the result — all in the same deterministic execution environment.

Two Surfaces, One Kernel

Morphogen presents two human-friendly faces powered by a single semantic kernel:

Morphogen.Audio — Declarative language for compositional audio, physics, and multi-domain scenes
RiffStack — Live performance environment for real-time interaction and improvisation

Both compile to the same Graph IR, share the same operator registry, and guarantee deterministic, reproducible results.

📐 Deep Dive: See docs/architecture/ for the complete stack design (kernel, frontends, Graph IR, MLIR compilation)

What Makes Morphogen Different

Cross-Domain Composition

Audio synthesis + fluid dynamics + circuit simulation in the same program
Type-safe connections between domains (e.g., field → agent force, geometry → audio impulse response)
Single execution model handles multiple rates (audio @ 48kHz, control @ 60Hz, physics @ 240Hz)

Deterministic by Design

Bitwise-identical results across runs, platforms, and GPU vendors
Explicit RNG seeding, sample-accurate event scheduling
Three profiles: strict (bit-exact), repro (deterministic FP), live (low-latency)

Transform-First Thinking

FFT, STFT, wavelets, DCT as first-class operations
Domain changes (time ↔ frequency, space ↔ k-space) are core primitives
Uniform transform API across all domains

Production-Grade Compilation

MLIR-based compiler with 6 custom dialects
Lowers to optimized CPU/GPU code via LLVM
Field operations, agents, audio DSP, temporal execution all compile to native code

Sister Project: Philbrick

Morphogen (software) and Philbrick (hardware) are two halves of one vision — modular computation in different substrates.

Aspect	Morphogen (Digital)	Philbrick (Analog/Hybrid)
Purpose	Digital simulation of continuous phenomena	Physical embodiment of continuous dynamics
Primitives	Streams, fields, transforms	Sum, integrate, nonlinearity, events
Safety	Type system (domain/rate/units)	Pin contracts (voltage/impedance/latency)
Execution	Multirate deterministic scheduler	Latency-aware routing fabric
Philosophy	Computation = composition	Computation = composition

The Bridge

Design in Morphogen → Simulate and optimize continuous-time systems
Build in Philbrick → Physical modules implementing the same primitives
Validate Together → Software and hardware mirror each other

Both platforms share the same four core operations (sum, integrate, nonlinearity, events) and the same compositional philosophy. They will eventually compile to each other.

🔧 Learn More: Philbrick - Modular analog/digital hybrid computing platform

Cross-Domain in Action

Here's what sets Morphogen apart — domains working together seamlessly:

# Couple fluid dynamics → acoustics → audio synthesis
use fluid, acoustics, audio

# Simulate airflow in a 2-stroke engine exhaust
@state flow : FluidNetwork1D = engine_exhaust(length=2.5m, diameter=50mm)
@state acoustic : AcousticField1D = waveguide_from_flow(flow)

flow(dt=0.1ms) {
    # Fluid dynamics: pressure pulses from engine
    flow = flow.advance(engine_pulse(t), method="lax_wendroff")

    # Couple to acoustics: flow → sound propagation
    acoustic = acoustic.couple_from_fluid(flow, impedance_match=true)

    # Synthesize audio from acoustic field
    let exhaust_sound = acoustic.to_audio(mic_position=1.5m)

    # Real-time output
    audio.play(exhaust_sound)
}

One program. Three domains. Zero glue code.

See docs/use-cases/2-stroke-muffler-modeling.md for the complete example.

Quick Start

Installation

git clone https://github.com/scottsen/morphogen.git
cd morphogen
pip install -e .

Your First Program

Create hello.kairo (Morphogen source files use .kairo extension):

# hello.kairo - Heat diffusion

use field, visual

@state temp : Field2D<f32 [K]> = random_normal(
    seed=42,
    shape=(128, 128),
    mean=300.0,
    std=50.0
)

const KAPPA : f32 [m²/s] = 0.1

flow(dt=0.01, steps=500) {
    temp = diffuse(temp, rate=KAPPA, dt, iterations=20)
    output colorize(temp, palette="fire", min=250.0, max=350.0)
}

Run it:

morphogen run hello.kairo

🚀 Project Status & v1.0 Roadmap

Current Status (v0.11.0):

✅ 40 production-ready computational domains
✅ 900+ comprehensive tests (all passing)
✅ MLIR compilation pipeline complete (6 phases)
✅ Python runtime with NumPy backend
✅ Zero technical debt

v1.0 Release Plan (24 weeks):

Morphogen is on an aggressive path to v1.0 with a three-track strategy:

Track 1 - Language Evolution (13 weeks)
- Symbolic + numeric execution (SymPy integration)
- Transform space tracking with functorial translations
- Algebraic composition (∘ operator) + category theory optimization
- Domain plugin system for user extensibility
Track 2 - Critical Domains (12 weeks)
- Circuit domain with audio coupling ⭐ Unique differentiator
- Fluid dynamics (Navier-Stokes)
- Chemistry Phase 2 expansion
- Target: 50+ domains
Track 3 - Adoption & Polish (ongoing)
- PyPI release (alpha in week 4)
- 5 showcase examples with videos
- 7 progressive tutorials
- Complete API documentation
- Active community infrastructure

Read the full plan: Morphogen v1.0 Release Plan

What makes v1.0 special:

🔬 Symbolic + numeric execution (first platform to combine both)
🎵 Circuit → Audio coupling (design pedal circuits, hear sound instantly)
📐 Category theory optimization (verified composition, automatic fusion)
🔌 User extensibility (plugin system for custom domains)
🎯 50+ integrated domains (audio, physics, chemistry, graphics, AI)

Timeline: Current v0.11.0 → v1.0 release in 2026-Q2

Language Overview

Temporal Model

Morphogen programs describe time-evolving systems through flow blocks:

flow(dt=0.01, steps=1000) {
    # Execute this block 1000 times with timestep 0.01
    temp = diffuse(temp, rate=0.1, dt)
    output colorize(temp, palette="fire")
}

State Management

Persistent variables are declared with @state:

@state vel : Field2D<Vec2<f32>> = zeros((256, 256))
@state agents : Agents<Particle> = alloc(count=1000)

flow(dt=0.01) {
    vel = advect(vel, vel, dt)      # Updates vel for next step
    agents = integrate(agents, dt)   # Updates agents for next step
}

Deterministic Randomness

All randomness is explicit via RNG objects:

@state agents : Agents<Particle> = alloc(count=100, init=spawn_random)

fn spawn_random(id: u32, rng: RNG) -> Particle {
    return Particle {
        pos: rng.uniform_vec2(min=(0, 0), max=(100, 100)),
        vel: rng.normal_vec2(mean=(0, 0), std=(1, 1))
    }
}

Physical Units

Types can carry dimensional information:

temp : Field2D<f32 [K]>           # Temperature in Kelvin
pos : Vec2<f32 [m]>               # Position in meters
vel : Vec2<f32 [m/s]>             # Velocity in m/s
force : Vec2<f32 [N]>             # Force in Newtons

# Unit checking at compile time
dist : f32 [m] = 10.0
time : f32 [s] = 2.0
speed = dist / time               # OK: f32 [m/s]

# ERROR: cannot mix incompatible units
x = dist + time                   # ERROR: m + s is invalid

Domain Imports (USE Statement)

✅ NEW in v0.10.0 - Import domain-specific operators into your program:

use field, audio, rigidbody

@state temp : Field2D<f32> = zeros((256, 256))
@state sound : AudioBuffer = silence(duration=1.0)

flow(dt=0.01) {
    # Field operations
    temp = diffuse(temp, rate=0.1, dt)

    # Audio operations
    sound = sine_wave(freq=440.0, duration=dt)
}

Features:

Import operators from 23 available domains (field, audio, agents, graph, signal, etc.)
Comma-separated syntax: use domain1, domain2, domain3
Makes 374+ operators available to your program
Type checking and unit validation across domains
See Level 3 Type System for cross-domain type safety

Four Dialects

1. Field Dialect - Dense Grid Operations

use field

@state temp : Field2D<f32> = random_normal(seed=42, shape=(256, 256))

flow(dt=0.1) {
    # PDE operations
    temp = diffuse(temp, rate=0.2, dt)
    temp = advect(temp, velocity, dt)

    # Stencil operations
    let grad = gradient(temp)
    let lap = laplacian(temp)

    # Element-wise operations
    temp = temp.map(|x| clamp(x, 0.0, 1.0))
}

2. RigidBody Physics - 2D Rigid Body Simulation

✅ PRODUCTION-READY - implemented in v0.8.2!

use rigidbody  # ✅ WORKING - fully implemented!

// Create physics world
let world = physics.world(gravity=(0, -9.81))

// Create bodies
let ball = physics.circle(pos=(0, 5), radius=0.5, mass=1.0)
let ground = physics.circle(pos=(0, -10), radius=10.0, mass=0.0)  // Static

// Simulate
flow(dt=0.016) {  // 60 FPS
    world = physics.step(world)
}

Features:

Full rigid body dynamics (position, rotation, velocity, angular velocity)
Circle and box collision shapes
Impulse-based collision response with restitution and friction
Static and dynamic bodies
Deterministic physics simulation
Example simulations: bouncing balls, collisions, stacking

Status: Production-ready as of v0.8.2

3. Agent Dialect - Sparse Particle Systems

✅ PRODUCTION-READY - implemented in v0.4.0!

use agent  # ✅ WORKING - fully implemented!

struct Boid {
    pos: Vec2<f32>
    vel: Vec2<f32>
}

@state boids : Agents<Boid> = alloc(count=200, init=spawn_boid)

flow(dt=0.01) {
    # Per-agent transformations
    boids = boids.map(|b| {
        vel: b.vel + flocking_force(b) * dt,
        pos: b.pos + b.vel * dt
    })

    # Filter
    boids = boids.filter(|b| in_bounds(b.pos))
}

Features:

Complete agent operations (alloc, map, filter, reduce)
N-body force calculations with spatial hashing (O(n) performance)
Field-agent coupling (particles in flow fields)
85 comprehensive tests
Example simulations: boids, N-body, particle systems

Status: Production-ready as of v0.4.0 (2025-11-14)

4. Audio Dialect (Morphogen.Audio) - Sound Synthesis and Processing

✅ PRODUCTION-READY - implemented in v0.5.0 and v0.6.0!

Morphogen.Audio is a compositional, deterministic audio language with physical modeling, synthesis, and real-time I/O.

use audio  # ✅ WORKING - fully implemented!

# Synthesis example (v0.5.0)
let pluck_excitation = noise(seed=1) |> lowpass(6000)
let string_sound = string(pluck_excitation, freq=220, t60=1.5)
let final = string_sound |> reverb(mix=0.12)

# I/O example (v0.6.0)
audio.play(final)           # Real-time playback
audio.save(final, "out.wav") # Export to WAV/FLAC

Features (v0.5.0 - Synthesis):

Oscillators: sine, saw, square, triangle, noise
Filters: lowpass, highpass, bandpass, notch, EQ
Envelopes: ADSR, AR, exponential decay
Effects: delay, reverb, chorus, flanger, drive, limiter
Physical modeling: Karplus-Strong strings, modal synthesis
192 comprehensive tests (184 passing)

Features (v0.6.0 - I/O):

Real-time audio playback with audio.play()
WAV/FLAC export with audio.save()
Audio loading with audio.load()
Microphone recording with audio.record()
Complete demonstration scripts

Status: Production-ready as of v0.5.0 (2025-11-14), I/O added in v0.6.0

5. Graph/Network Domain - Network Analysis and Algorithms

✅ PRODUCTION-READY - implemented in v0.10.0!

use graph

// Create social network
let network = graph.create_empty(directed=false)
network = graph.add_edge(network, 0, 1, weight=1.0)
network = graph.add_edge(network, 1, 2, weight=1.0)

// Analyze network
let centrality = graph.degree_centrality(network)
let path = graph.shortest_path(network, source=0, target=2)
let components = graph.connected_components(network)

Features:

Graph creation and modification
Path algorithms: Dijkstra, BFS, DFS, shortest paths
Network analysis: degree/betweenness/pagerank centrality
Community detection: connected components, clustering coefficient
Advanced algorithms: MST, topological sort, max flow
Graph generators: random graphs, grid graphs