3Explicit 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](docs/model.md).
5## Installation
7```
e30c940save .cymsim fileJeremy Magland 8pip install -e ".[dev]" # numpy, scipy, jax (CPU), pyyaml, h5py, pytest, matplotlib
71e94accymsim: nonlinear FEM cymbal simulation packageJeremy Magland 9pip install "jax[cuda12]" # optional: run the time loop on a GPU
10```
42c1bf8Time step from the global stability bound (power iteration), with numerics.stability_bound to keep the element boundJeremy Magland 12Runs 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`.
71e94accymsim: nonlinear FEM cymbal simulation packageJeremy Magland 13
14## Usage
16```
17cymsim example-config my_run.yaml --exciter mallet # write a default config
18cymsim check my_run.yaml # mesh, time step, element self-tests, no time stepping
19cymsim simulate my_run.yaml # run; writes <prefix>_rayleigh.wav, _unbaffled.wav, _result.npz, _cascade.png
20cymsim simulate my_run.yaml --linear --duration 0.5 # linear reference run
e30c940save .cymsim fileJeremy Magland 21cymsim run my_run.yaml -o run.cymsim --save-every 60 # also write a .cymsim file, updated every minute of wall time
22cymsim run my_run.yaml -o run.cymsim --record-acceleration # include the audio-rate normal acceleration of every node
23cymsim info run.cymsim # summarise a .cymsim file
e30c940save .cymsim fileJeremy Magland 26A `.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](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.
30```python
31from cymsim import SimulationConfig, Hit, StickExciter, simulate
33cfg = SimulationConfig.from_yaml("examples/crash_mallet.yaml")
34cfg.hits.append(Hit(time=0.8, r=0.19, phi=2.0, velocity=7.0, exciter=StickExciter()))
e30c940save .cymsim fileJeremy Magland 35cfg.output.record_acceleration = True # off by default: about 0.4 GB per simulated second at the default mesh
37result.write_wav("crash")
71e94accymsim: nonlinear FEM cymbal simulation packageJeremy Magland 39print(result.hits) # peak force, contact time and rebound velocity of each hit
40print(result.energy_log) # kinetic / membrane / bending / exciter energy and max|w|/h over time
e30c940save .cymsim fileJeremy Magland 41a = result.acceleration.as_float(0, 4410) # normal acceleration [m/s^2], first 0.1 s, shape (4410, n_nodes)
42w = result.displacement.w # transverse displacement at 60 Hz, shape (n_frames, n_nodes)
44from cymsim import load_cymsim
45back = load_cymsim("crash.cymsim") # the same SimulationResult, from the file
e19a540Add a prescribed-force exciter and point probes of the normal acceleration; accept Python 3.9 in the YAML loaderJeremy Magland 48A run is described by one `SimulationConfig` made of `Material`, `Profile`, `Imperfections`, `MeshConfig`, a list of `Hit`s (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/](examples/) for a mallet stroke, a stick crash, a train of four hits and a quick CPU run.
71e94accymsim: nonlinear FEM cymbal simulation packageJeremy Magland 49
50## Layout
52| module | contents |
53|---|---|
54| [config.py](src/cymsim/config.py) | configuration dataclasses, YAML load/save, validation |
55| [geometry.py](src/cymsim/geometry.py) | mid-surface height z0(x, y) and thickness h(x, y), seeded imperfections |
56| [mesh.py](src/cymsim/mesh.py) | numpy disk mesher (concentric rings, angular stitching, smoothing), CST operators |
57| [elements.py](src/cymsim/elements.py) | DKT bending stiffness, Marguerre-von Karman membrane strains, element energies |
58| [shell.py](src/cymsim/shell.py) | assembled shell: lumped mass, rigid modes, internal force by autodiff, stability bound |
59| [exciter.py](src/cymsim/exciter.py) | contact patches, power-law contact law, schedule of hits |
60| [radiation.py](src/cymsim/radiation.py) | Rayleigh integral and the unbaffled (rim-diffraction) approximation |
e30c940save .cymsim fileJeremy Magland 61| [decimation.py](src/cymsim/decimation.py) | the anti-aliasing kernel that takes accelerations and pressure from the sub-step rate to the audio rate |
62| [simulate.py](src/cymsim/simulate.py) | leapfrog time loop, block compilation, acceleration and displacement records, result container |
63| [cymsim_file.py](src/cymsim/cymsim_file.py) | the .cymsim HDF5 file: streaming writer, loader, summary |
71e94accymsim: nonlinear FEM cymbal simulation packageJeremy Magland 64| [diagnostics.py](src/cymsim/diagnostics.py) | band envelopes, onset times, spectral centroid, cascade plot |
e30c940save .cymsim fileJeremy Magland 65| [cli.py](src/cymsim/cli.py) | `cymsim simulate` (`run`), `cymsim check`, `cymsim info`, `cymsim example-config` |
71e94accymsim: nonlinear FEM cymbal simulation packageJeremy Magland 66
67`prototype.py` is the original single-file prototype that this package reorganizes; it is kept for reference and is not used by the package.
69## Tests
71```
72pytest
73```
e30c940save .cymsim fileJeremy Magland 75The 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).