cymsim#

Explicit nonlinear finite-element simulation of struck cymbals. The cymbal is a Marguerre-von Karman shallow shell with a bell, a bow, a thickness taper and seeded imperfections, discretized on a triangulated disk with constant-strain membrane triangles and Discrete Kirchhoff bending triangles, integrated in time with an explicit leapfrog scheme, struck by one or more rigid exciters through power-law contact springs, and heard at a listener point through a Rayleigh-integral radiation model. The equations, the discretization and the time-stepping method are written out in docs/model.md.

Installation#

pip install -e ".[dev]"          # numpy, scipy, jax (CPU), pyyaml, h5py, pytest, matplotlib
pip install "jax[cuda12]"        # optional: run the time loop on a GPU

Runs at the default resolution (6 mm elements, about 4700 nodes and 38 sub-steps per audio sample) need a GPU to finish in minutes. On a CPU, use a coarser mesh and a shorter duration, as in examples/quick_cpu.yaml.

Usage#

cymsim example-config my_run.yaml --exciter mallet   # write a default config
cymsim check my_run.yaml                             # mesh, time step, element self-tests, no time stepping
cymsim simulate my_run.yaml                          # run; writes <prefix>_rayleigh.wav, _unbaffled.wav, _result.npz, _cascade.png
cymsim simulate my_run.yaml --linear --duration 0.5  # linear reference run
cymsim run my_run.yaml -o run.cymsim --save-every 60 # also write a .cymsim file, updated every minute of wall time
cymsim run my_run.yaml -o run.cymsim --record-acceleration   # include the audio-rate normal acceleration of every node
cymsim run my_run.yaml --resume run.cymsim --duration 4 -o run4.cymsim   # continue a saved run to 4 s
cymsim info run.cymsim                               # summarise a .cymsim file
cymsim cache-key my_run.yaml --show                  # the run's cache key (independent of the duration) and what it hashes
cymsim run my_run.yaml --cache https://artifact-cache.tempory.net/api/apps/cymsim   # take the run from the run cache, or continue a shorter cached run

With --cache URL (or CYMSIM_CACHE_URL set), a run is looked up in a run cache under its key (cymsim cache-key), which leaves out the duration and the output naming. The cache holds the longest run of each key so far as a .cymsim file without the acceleration record: a run it covers is cut from it without building the model, and a longer run continues from it (--resume), identical to an uninterrupted run on the same device. Downloads are kept in ~/.cache/cymsim (CYMSIM_CACHE_DIR) and revalidated by ETag. With the cache app's passcode in CYMSIM_CACHE_KEY, a run that was computed (from rest or continued) is uploaded, at the end and as a partial run every 10 minutes of wall time (--upload-every), so that a killed job continues from its last upload; nothing replaces an entry that meanwhile holds at least as much. Without the passcode the cache is read-only. The entry's metadata records the device, jax version, commit and host of each segment of integration. See cache.py.

A .cymsim file is an HDF5 file holding the configuration, the mesh, the listener signals, displacement frames at a low rate, optionally the normal acceleration of every node at the audio rate, and the integrator state; the layout is specified in docs/format.md. It is meant for taking the shell's motion into other programs (other listeners, rooms, acoustic solvers) and is the file the web companion cymsimweb saves and loads. A partial file written during a run is a consistent prefix of the complete one.

The same from Python:

from cymsim import SimulationConfig, Hit, StickExciter, simulate

cfg = SimulationConfig.from_yaml("examples/crash_mallet.yaml")
cfg.hits.append(Hit(time=0.8, r=0.19, phi=2.0, velocity=7.0, exciter=StickExciter()))
cfg.output.record_acceleration = True      # off by default: about 0.4 GB per simulated second at the default mesh
result = simulate(cfg)
result.write_wav("crash")
result.save("crash.cymsim")
print(result.hits)          # peak force, contact time and rebound velocity of each hit
print(result.energy_log)    # kinetic / membrane / bending / exciter energy and max|w|/h over time
a = result.acceleration.as_float(0, 4410)   # normal acceleration [m/s^2], first 0.1 s, shape (4410, n_nodes)
w = result.displacement.w                   # transverse displacement at 60 Hz, shape (n_frames, n_nodes)

from cymsim import load_cymsim
back = load_cymsim("crash.cymsim")          # the same SimulationResult, from the file
cfg.numerics.duration = 4.0
longer = simulate(cfg, resume=back)         # continue it to 4 s; identical to a 4 s run on the same device

A run is described by one SimulationConfig made of Material, Profile, Imperfections, MeshConfig, a list of Hits (each with a StickExciter, a MalletExciter, or a ForceExciter for a prescribed force pulse), Listener, Numerics and Output. The YAML file mirrors the dataclass fields; omitted fields take the defaults, which reproduce an 18 inch medium-thin B20 crash. Units are SI throughout. See examples/ for a mallet stroke, a stick crash, a train of four hits and a quick CPU run.

Layout#

prototype.py is the original single-file prototype that this package reorganizes; it is kept for reference and is not used by the package.

Tests#

pytest

The tests check the mesher (manifold, orientation, quality), the DKT element (rigid modes, constant curvature, twist), the membrane strains, the assembled shell (mass, rigid-mode annihilation, force = minus energy gradient, dissipative damping), the configuration round trip, the decimation kernel and streaming decimator, short coarse simulations with one and two hits, and the .cymsim file (round trip, partial files, and that the baffled listener signal is recovered from the stored accelerations alone).