Skip to main content
The acoustic signal modeling module is a virtual computational laboratory for fluid mechanics. It lets you synthetically construct complex heterogeneous media using graph adjacency matrices or geostatistical spatial covariance models, simulate acoustic wave propagation through them, record signals at virtual sensors positioned anywhere around the domain, and then apply Spec2Vec to the resulting waveforms. The workflow bridges physics-based forward modeling with interpretable signal characterization, making it useful for controlled experiments on how elastic wave propagation interacts with structural complexity.

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 jwave, jax, and jaxlib dependencies that are not installed as part of the core Spec2Vec environment. Install them before proceeding:
Refer to the Installation guide for hardware-specific JAX installation instructions, particularly if you plan to run simulations on GPU.

Core Workflow

1

Define a domain

Create a 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.
The first tuple sets the grid size in pixels (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 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.
Setting 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 compiled_simulator_sources(). This propagates the stimulant through the heterogeneous medium and records the pressure field at each sensor for every time step.
If your source is a pressure field (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

The Simulator supports two fundamentally different approaches to constructing a heterogeneous medium. Choose the one that best matches the physical structure you want to model.
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

The acoustic_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.