When to Use This Module
This module is well suited for three broad use cases:- Investigating elastic wave behavior — systematically vary medium properties (discontinuity density, spatial correlation length, graph topology) and measure how those changes manifest in Spec2Vec feature space
- Generating physics-informed synthetic training data — produce large batches of labeled waveforms with known medium properties to pre-train or benchmark downstream classifiers
- Inverse modeling studies — compare observed sensor waveforms against a library of simulations to infer subsurface structure from surface recordings
Prerequisites
This module requires the optional Refer to the Installation guide for hardware-specific JAX installation instructions, particularly if you plan to run simulations on GPU.
jwave, jax, and jaxlib dependencies that are not installed as part of the core Spec2Vec environment. Install them before proceeding:Core Workflow
1
Define a domain
Create a The first tuple sets the grid size in pixels
Domain object that specifies the grid dimensions and spatial resolution of your simulation. The domain controls how much physical space the simulation covers and at what granularity the wavefield is computed.(width, height). The second tuple sets the spatial resolution (dx, dy) in meters per pixel.2
Initialize the Simulator
Instantiate the
Simulator class with your domain and set the medium construction parameters. The base_density and defect_density arguments define the wave speed through intact and damaged material, respectively. The pml_size controls the thickness of the absorbing boundary layer that prevents wraparound reflections, and num_air_grid adds an air layer outside the medium to allow coda wave capture.3
Configure and run the simulation
Call Setting
run_basic_setup() to assemble all components — medium field, stimulant source, and sensor array — and prepare the forward simulation. Set use_p0=False to use a Gaussian time pulse as the source (rather than a pressure field). Adjust sensor_locations to place receiver arrays along the edges of your domain.add_sensor_at_source=True places an additional receiver near the source, which is useful for capturing the direct wave and performing source normalization during inversion.4
Record waveforms
Run the forward simulation by calling If your source is a pressure field (
compiled_simulator_sources(). This propagates the stimulant through the heterogeneous medium and records the pressure field at each sensor for every time step.use_p0=True), use compiled_simulator_sensors() instead.5
Apply Spec2Vec
Feed the recorded sensor waveforms through the Spec2Vec pipeline. Convert each 1D trace to a spectrogram with
stft_basic_spectogram(), then extract spectral fingerprints for all sensors in a single compute_pointwise_metrics_from_spec() call. The returned DataFrame has one row per sensor and one column per named Spec2Vec metric.Medium Types
TheSimulator supports two fundamentally different approaches to constructing a heterogeneous medium. Choose the one that best matches the physical structure you want to model.
- Graph Medium
- Spatial Covariance Medium
Graph-based media represent structural discontinuities as a network of nodes and edges overlaid on the simulation grid. Each connected component becomes a region with
defect_density wave speed, while unconnected regions retain base_density. This produces sharp, binary contrasts — ideal for modeling fractured rock, jointed materials, or damaged infrastructure.Set simulator.graph_type to any of the following options before calling run_basic_setup():Control overall discontinuity density with
simulator.p_vals (range 0–1). Higher values produce more connected, more heavily damaged media. Use simulator.epsilon (range 0–1) to tune deviation from the graph’s ideal deterministic structure toward fully random topology.Notebook Reference
Theacoustic_signal_modeling/example_generate_waveform_models.ipynb notebook contains a diverse set of worked examples covering different medium types, source configurations, and sensor placements. Start there to see practical demonstrations of all the parameters described above before designing your own experiments.