Modal2D · Guide

01 Recipes

Concrete walkthroughs. Each one assumes you've started the viewer and are in Play mode. Step counts in the headers are rough — your hands move faster than reading does.

02 Keyboard shortcuts

Global

Play-mode preset hotkeys

Spectrum interactions

03 Fine-tune state machine

Every fine-tune mode (1, 2, 3, 4, 5, 6, 7, 8, 9) shares the same fine_phase_ state machine. The pick-next logic varies per mode; the phase transitions are universal.

The pickers vary by mode:

• Mode 1, 6, 9: bisection mid-point, or HF Newton step when available.
• Mode 2: bisection on a uniform scale factor.
• Mode 3: alternating W/H bisections per round.
• Mode 4: adaptive sampler scores bracket / near-best / gap regions, picks highest.
• Mode 5: sweep then per-bracket bisection.
• Mode 7, 8: GP fit + Expected-Improvement argmax on a fine grid.

04 Threading & data flow

Three threads operate concurrently. Mutexes guard the small set of shared state; the rest is single-owner.

Render thread (60 Hz)

1. Process input (keyboard, mouse).
2. Drain solve worker result if ready: modal_res_ = solve_worker_.take_result().
3. Apply per-frame state pushes (drift, damping, sympathetic config, gravity).
4. Read displacements via modal_get_displacements.
5. Write displacement VBO → draw mesh (OpenGL).
6. ImGui begin → draw_layout (tabs, panels, viewport) → end.
7. Swap buffers.

Solve worker (background thread)

1. Started by solve_worker_.start(modal_obj_, num_modes) from the render thread.
2. Runs modal_solve: assemble K / M → eigensolve → build ModalResult.
3. Result picked up by the next render frame via is_done().
4. Joined before any destroy of modal_obj_ / modal_res_ to avoid use-after-free.

Audio callback (PortAudio, ~5 ms blocks)

1. Drain strike events from libmodal's strike_buf, project onto modes via compute_strike_impulse.
2. Run GPU synthesis (CUDA kernel) → PCM samples per mode → sum.
3. Apply air-cavity bandpass (if enabled).
4. Run noise gate (HP-filter envelope, smoothstep).
5. Post-process: gain → low-pass → soft-clip → auto-normalize.
6. Write to PortAudio output buffer.

Strike flow: a click in the viewport calls modal_strike(res, x, y, mag). That pushes to the audio strike_buf (drained by the audio callback) AND immediately injects into vis_impulses for visualisation (no audio latency).

05 File layout

Top-level split: libmodal/ (pure physics + audio synthesis, no UI) and modal_viewer/ (App, OpenGL renderer, ImGui UI).

06 Glossary

07 Troubleshooting

08 Basics: modal analysis from first principles

This section builds up from the simplest example (a plucked guitar string) to the framework the rest of the viewer uses. No prior knowledge of FEM or eigenvalues assumed — equations introduced as they become necessary, never before.

8.1 · What is modal analysis?

Pluck a guitar string. You hear a pitch (the fundamental), plus quieter higher pitches (overtones). The string isn't vibrating in just one shape — it's vibrating in many shapes at once, each with its own frequency. Each of those independent vibration patterns is a mode, and the observation that any motion of the string can be written as a sum of them is the heart of modal analysis.

Why is this useful? Because each mode evolves independently. The fundamental does its thing, the second overtone does its thing, and they don't interfere. So if we can find the modes once and know how hard each one was struck, we can compute the entire future of the vibrating object by summing analytical sine waves — no iterative physics simulation needed.

8.2 · Eigenmodes of a 1D string

The simplest case. A string of length L, tension T, and mass per length μ, pinned at both ends, has displacement v(x, t) obeying the wave equation:

Try a separated-variables solution v(x, t) = φ(x) · sin(ωt). Substituting gives

plus the boundary conditions φ(0) = φ(L) = 0. The only solutions are

Each φ_n is a mode shape; each ω_n is its natural angular frequency. The pair (φ_n, ω_n) is called an eigenmode because the equation above is an eigenvalue problem in disguise: φ_n is an eigenvector of the operator −(T/μ) ∂²/∂x² with eigenvalue ω_n².

The first three modes look like:

Three things to notice that generalise to all modes, in any geometry:

• Each mode has its own frequency. Higher modes oscillate faster.
• Each mode has a fixed shape. Mode 3 always vibrates with two interior zeros (nodes); it doesn't morph into mode 2.
• Different modes don't interfere. A plucked string's motion is exactly the sum of every mode's contribution, each evolving independently in time.

8.3 · Striking, sound, and decay

A real strike is a transient: a brief force impulse at one position on the string. The string's response is the sum of mode contributions, each scaled by how much the strike "looked like" that mode:

Where A_n is the projection of the strike onto mode n — essentially, "how much does mode n's shape match where I struck?". Strike at the middle of the string (x = L/2): odd modes (1, 3, 5, …) have a peak there, so they ring loud; even modes (2, 4, …) have a zero there, so they ring not at all. This is why striking different parts of an instrument changes its timbre.

Real materials dissipate energy. We model that with a damping ratio ζ_n per mode, giving an exponential envelope:

Two consequences worth absorbing:

• Higher modes decay faster at the same ζ, because the exponent ζ ω t grows quicker with ω. That's why a struck bell's bright initial timbre mellows out over time — the overtones die first.
• Decay time is 1 / (ζ ω). For ζ = 0.01 and an audible 440 Hz mode (ω ≈ 2765 rad/s), that's ~36 ms — a percussive sound. For ζ = 0.0001 it's 3.6 seconds — a bell.

To turn vibration into sound, every mode shape radiates into the surrounding air with an efficiency α_n that depends on its shape and the medium. The final audio signal is the radiated pressure at the listener position; in the viewer we approximate this as a weighted sum where each mode's contribution scales by α_n:

α_n is computed from the modal velocity normal to the boundary and the medium's impedance. This is why setting the Acoustic Medium to vacuum-like properties silences the output — the structure still vibrates, it just doesn't radiate.

8.4 · Going from 1D to 2D shapes

A 1D string has modes with a single index n: shape number 1, 2, 3, …, ordered by frequency. A 2D shape has modes indexed by two numbers in the simplest case (number of bulges along x, number along y), and ordered modes start to mix the two indices. For a rectangular plate fixed at the edges:

The patterns of zero displacement are nodal lines; for higher modes they form intricate curves. In Chladni's classical experiment (the demo this viewer's Chladni-mode C toggle is named for), sand sprinkled on a plate gathers along these nodal lines because they're the only places that don't shake the sand off.

For arbitrary shapes (not just rectangles), the modes can't be written as products of 1D sines — they're whatever shape comes out of solving the 2D wave equation with the actual boundary. Closed-form solutions rarely exist. We need a numerical method: FEM.

8.5 · FEM: from continuous PDE to a matrix problem

The 2D wave equation we want to solve is

in some 2D region, with material parameters E (stiffness), ρ (density), and boundary conditions on the region's edge. Three steps turn this into something a computer can chew on:

Step 1: mesh the shape

Cut the 2D region into a triangulation. Each triangle has three nodes at its corners. The displacement field u(x, t) is approximated as linear interpolation between the displacement values at those nodes. So instead of a continuous unknown function we have a finite list of unknowns: u_i(t), one per node DOF.

Triangulation in this viewer is done with shewchuk's Triangle library, invoked via mesh::triangulate in libmodal/src/mesh/triangulator.cpp.

Step 2: assemble K and M

For each triangle, you can derive (from the wave equation + linear interpolation) a small element stiffness matrix K_e (6×6 for the 2D CST element — 3 nodes × 2 DOFs) and an element mass matrix M_e. The full system is built by summing contributions from every element into global sparse matrices:

K encodes how much force each unit displacement produces; M encodes inertia. Both are sparse because each node only couples to its triangle neighbours.

Assembly happens in libmodal/src/fem/assembler.cpp (pure 2D CST) and assembler_mixed.cpp (CST + beam elements for strings). The element matrices themselves come from element_cst.cpp and element_beam.cpp.

Step 3: eigensolve

For free vibration (no external force, f = 0) we look for solutions of the form u(t) = φ · sin(ωt). Substituting into M ü + K u = 0 gives

Dropping the time factor leaves the generalised eigenvalue problem:

Solve this and you get a discrete set of eigenpairs (ω_k, φ_k) — exactly the modes from §8.2, but for an arbitrary 2D geometry instead of a 1D string. We solve typically 24 – 120 of the lowest modes using sparse Lanczos iteration in libmodal/src/solver/eigensolve_sparse.cpp.

8.6 · How a click becomes a sound

End-to-end trace of what happens when you click the viewport. This is the complete pipeline; every step touches a specific file in the codebase.

Three details that surprise newcomers:

• Visual and audio are decoupled. They share strike events but run on different threads with different time bases. Visual uses scaled time (S key cycles slow-motion), audio always runs at real time. Each path stores its own copy of recent impulses.
• Audio synthesis is analytical, not simulated. The CUDA kernel computes the exact sum Σ α_k A_k exp(−ζω t) sin(ω_d t) at every PCM sample, with no time-stepping. No accumulated error, no stability concerns, and trivially parallel across samples.
• The strike acts on one node. We snap the world click to the nearest mesh node, then project that node's eigenvector entry onto the strike direction (outward boundary normal for boundary nodes, +Y for interior). The whole strike-to-modes projection lives in compute_strike_impulse.

8.7 · Why the same machinery handles strings, plates, and bells

Everything in §8.5 and §8.6 was general. The viewer has different elements (CST triangle, Bernoulli beam, DKT plate) but each one just contributes its own little K_e and M_e block during assembly. After assembly the eigenvalue problem looks identical regardless of which elements were used. Same Lanczos solve, same modal sum for synthesis.

That's why adding tension to strings (§7) was a small change: tension contributes an extra term K_geom to the beam element's K_e. Everything downstream — eigensolve, MAC, HF derivatives, audio synthesis — is unchanged. The element layer is where the physics lives; everything above it operates on abstract sparse matrices.

Multi-material support (§5) works the same way: each triangle's element matrix is computed with its own material, then the assembler sums all elements into a single global K and M. The eigensolver doesn't know or care that the material varies — it just sees a different sparse pattern of stiffness values.

8.8 · Deeper: Hellmann-Feynman, MAC, geometric stiffness

With the basics in place, the three "advanced" results in the rest of the viewer become short corollaries.

Why Hellmann-Feynman is cheap

Conventional derivative df/dW: change W, redo the entire eigensolve, finite-difference. Cost: one extra eigensolve per derivative.

Hellmann-Feynman insight: for an eigenpair (λ, φ) of K φ = λ M φ with M-normalisation φᵀ M φ = 1,

No new eigensolve. Cost: one matrix re-assembly at perturbed W (much cheaper than eigendecomposition) plus a quadratic-form evaluation. Total ~5% of an eigensolve. We use this for Newton-step Fine-W / Manual-W via the Rayleigh-quotient formulation, which handles M-normalisation automatically (see features §3).

MAC mode tracking

Two eigenvectors φ_a and φ_b from different solves are "the same mode" if their shapes correlate strongly. The Modal Assurance Criterion measures this with a single scalar in [0, 1]:

The square handles sign flips (eigenvectors are only defined up to sign). Above 0.6 means "clearly the same mode topology"; below 0.3 means the modes diverged — the geometry change crossed a mode-identity boundary and the tracker needs a fresh reference. Used by Manual-W to auto-retrack the pinned mode across W changes.

Geometric stiffness from tension

A taut string's pitch comes from tension, not bending. Why? The transverse equation for a beam under axial tension T is

When T · L² ≫ EI the bending term EI ∂⁴v/∂x⁴ is negligible and the equation collapses to the pure-string wave equation from §8.2. Frequencies follow f_n = (n/2L) · √(T/μ).

In FEM terms, the tension contributes a geometric stiffness matrix K_geom = T/L · [transverse-block] that adds to the usual bending stiffness:

High tension → geometric term dominates → string-like behaviour. Zero tension → pure bending beam. Same eigensolve handles both regimes because the only thing that changed is the values in K.

09 Further reading

Modal synthesis

• Adrien, J.-M. "The Missing Link: Modal Synthesis" — the foundational paper on the analytical sum-of-modes approach to audio.
• van den Doel, K. & Pai, D. "The Sounds of Physical Shapes" — modal sound generation for shape-aware audio in graphics.
• O'Brien, J., Cook, P., Essl, G. "Synthesizing Sounds from Physically Based Motion" — coupling FEM to audio in real time.

Finite element method

• Cook, R. Concepts and Applications of Finite Element Analysis. Canonical reference; CST, beam, plate elements all derive here.
• Bathe, K.-J. Finite Element Procedures. The standard graduate text. Sparse eigensolve methods covered in depth.

Mode tracking and sensitivity

• Allemang, R. "The Modal Assurance Criterion — Twenty Years of Use and Abuse" (Sound and Vibration, 2003). Practical guide to MAC.
• Fox, R., Kapoor, M. "Rates of Change of Eigenvalues and Eigenvectors". Original Hellmann-Feynman application to FEM eigenproblems.

Bayesian optimisation

• Rasmussen, C., Williams, C. Gaussian Processes for Machine Learning. Free online; chapters 2–5 cover what we use.
• Frazier, P. "A Tutorial on Bayesian Optimization" (arXiv 1807.02811). EI, acquisition strategies, when BO works.

Acoustic radiation

• Fahy, F. Sound and Structural Vibration. Structure → air coupling, radiation efficiency, near vs far field.
• Rossing, T. Science of Sound. Approachable, covers Helmholtz, instrument-cavity physics, anisotropic materials.

This codebase

• features.html — what's here, command-reference style.
• roadmap.html — upcoming work, longer-term trajectory.
• project-structure.html — full code tree with descriptions.