REQ-ML

REQ-ML is MATLAB research software for estimating local shear-wave speed (SWS) from harmonic wavefields using the Radial Energy-Quantile (REQ) method.

REQ-ML takes a complex harmonic wavefield as input and returns spatial maps of the estimated REQ quantile and shear-wave speed.

complex harmonic wavefield
          |
          v
 wavefield_sample.mat
          |
          v
        REQ-ML
          |
          +--> Q map
          |
          +--> SWS map

REQ-ML analyzes wavefields; it does not require a simulation backend at inference time.

The companion shear-wave-simulation-framework can generate synthetic, projected-3D Eikonal, and k-Wave wavefields for simulation studies and examples:

shear-wave-simulation-framework
              |
              v
       wavefield_sample.mat
              |
              v
            REQ-ML
              |
              v
           SWS map

The companion repository is optional when analyzing appropriately formatted experimental data.

REQ-ML is research software and is not intended for clinical use.

Requirements

REQ-ML has been validated with MATLAB R2025a.

Required for prediction with the released bagged-tree Q0 model:

• MATLAB
• Statistics and Machine Learning Toolbox

Optional:

• Parallel Computing Toolbox
• shear-wave-simulation-framework, only when generating example or simulated wavefields

Installation

Clone REQ-ML:

git clone https://github.com/gsara798/REQ-ML.git
cd REQ-ML

Start MATLAB from the repository root and initialize the project:

setup_reqml;

Install the REQ Q0 model

The trained model bundle is too large for normal Git history and is distributed separately as a GitHub Release asset.

The model can be provided in any of three ways:

1. Place it at

   models/current/model_bundle.mat
   

2. Set the environment variable

   export REQML_Q0_MODEL=/path/to/model_bundle.mat

3. Pass it explicitly to reqml.predictSWS:

   result = reqml.predictSWS( ...
       sample_file, ...
       Model="/path/to/model_bundle.mat", ...
       M=2);

The expected file size, SHA-256 checksum, and model provenance are recorded in models/current/model_manifest.json.

See models/README.md for model-distribution details.

Quick start: analyze a wavefield

For an existing wavefield_sample.mat:

setup_reqml;

result = reqml.predictSWS( ...
    "path/to/wavefield_sample.mat", ...
    M=2);

imagesc(result.x_mm, result.z_mm, result.cs_map);
axis image;
colorbar;
xlabel("x (mm)");
ylabel("z (mm)");
title("REQ Q0 shear-wave speed");

The main outputs are:

• result.cs_map — estimated shear-wave-speed map in m/s
• result.q_map — predicted local REQ quantile
• result.valid_mask — valid prediction locations
• result.x_mm, result.z_mm — map coordinates
• result.metadata — model and processing metadata

The current public model supports M=2 and M=3.

Input data

The public prediction API expects a wavefield_sample.mat file following the REQ-ML wavefield contract.

The sample contains:

• a complex 2-D harmonic wavefield
• x and z coordinates and spatial sampling
• harmonic frequency
• wavefield component, quantity, and units
• provenance and validation metadata

Simulation-generated samples may also contain ground-truth material information for validation. Ground truth is optional for public inference and is not used by reqml.predictSWS to compute the SWS estimate.

Run the public examples

Simulation examples require the companion shear-wave-simulation-framework. Place it beside REQ-ML or set:

export SWSIM_ROOT=/path/to/shear-wave-simulation-framework

Install the released model at models/current/model_bundle.mat or set REQML_Q0_MODEL as described above. Each public example uses a local, human-readable JSON file and prints its resolved repositories, inputs, model, parallel status, wavefield sample, and output directories.

swsynth examples

Run the compact projected-3D Eikonal simulations:

run("examples/swsynth/homogeneous/run_example.m")
run("examples/swsynth/inclusion/run_example.m")
run("examples/swsynth/cartesian_sweep/run_campaign.m")
run("examples/swsynth/short_campaign/run_campaign.m")

The homogeneous example demonstrates the simplest single simulation. The inclusion example uses a visible circular-inclusion material definition. The Cartesian example independently varies SWS, frequency, and seed and expands a compact 2 x 2 x 2 sweep into eight deterministic runs. The short campaign compares directional, intermediate, and diffuse fields while holding the medium and frequency fixed. swsynth simulations use the internal parallelism enabled in each JSON config.

3D k-Wave examples

Run the full-wave examples:

run("examples/kwave/homogeneous/run_example.m")
run("examples/kwave/short_campaign/run_campaign.m")

The homogeneous case is a computationally compact 3D smoke example. The campaign follows the current IUS validation conventions with a 7 cm x-z simulation extent, a 2.5 cm diameter spherical inclusion, and fixed 2/4 m/s background/inclusion SWS. Wave propagation is simulated in 3D; the standardized REQ-ML sample is extracted from the central x-z acquisition plane. The campaign compares directional, intermediate, and diffuse 3D source banks while holding the medium and frequency fixed. It dry-runs all cases and prints the estimated grid memory before solver execution. The 3D campaign is substantially more expensive than swsynth.

Choose the simulation workflow

1. Single simulation -- config.json. Use one backend config when there is only one condition:

config.json -> backend CLI -> wavefield_sample.mat -> reqml.predictSWS -> figures

2. Cartesian study -- campaign with sweep. Use sweep dimensions when parameters vary independently:

base_config.json + campaign.json with sweep
  -> simcampaigns.expandCampaign -> Cartesian product
  -> validateCampaign -> runCampaign -> wavefield samples -> REQ-ML

3. Named or paired scenarios -- campaign with runs. Use explicit runs when several parameters must remain coupled:

base_config.json + campaign.json with runs
  -> simcampaigns.expandCampaign -> declared scenarios
  -> validateCampaign -> runCampaign -> wavefield samples -> REQ-ML

simcampaigns.expandCampaign is the canonical materialization step for both campaign forms. Users author the compact scientific definition, not its manual expansion. The cartesian_sweep example demonstrates independent SWS x frequency x seed variation. The two short_campaign examples deliberately use explicit runs because their directional, intermediate, and diffuse parameters are physically paired.

Campaign simulations run sequentially. REQ-ML parallelizes extraction across prediction windows, and the Q0 model is loaded once per campaign.

The matched field anchors are:

Regime	Directions / vibrators	In-plane	Solid angle
directional	1	1	0.01 sr
intermediate	16	4	pi sr
diffuse	32	8	4*pi sr

Directional is a narrowly supported field, intermediate is partially distributed in 3D, and diffuse uses full-sphere angular support.

Generated files are written below:

outputs/examples/swsynth/
outputs/examples/kwave/

See examples/README.md for the complete example matrix, runtime guidance, and output layout. examples/run_all.m runs only the two compact swsynth single-simulation examples; campaigns and k-Wave examples are intentionally explicit commands.

Scientific validation workflows

The examples/ tree demonstrates how to call REQ-ML. Scientific validation workflows instead evaluate model performance under a controlled design and write machine-readable metrics under outputs/validation/.

The public Q0 angular-aperture validation tests robustness of the released Q0 model as projected-3D angular support changes. It holds the homogeneous medium, 500 Hz frequency, 0.5 mm sampling, 2,000 requested directions, and 20 requested in-plane directions fixed while varying:

• true SWS: 2 and 3 m/s;
• normalized solid-angle support: 19 values from approximately 0.000796 to 1;
• REQ window multiplier: M=2 and M=3.

Every SWS/aperture condition has three controlled realizations using seeds 84002, 84003, and 84004. The same three simulation seeds are reused across all angular supports and both SWS values, providing controlled stochastic pairing while angular support and true SWS are varied. The model is loaded once, prediction uses StepPixels=2, and REQ window extraction is parallel.

Set SWSIM_ROOT and install the released Q0 model as described above, then run:

addpath("scripts/validation/angular_aperture")
result = run_q0_angular_aperture_v1();

To rebuild the generic summary tables from existing patch results without rerunning simulations or prediction:

addpath("scripts/validation/angular_aperture")
analysis = analyze_q0_angular_aperture_v1();

To prepare the reusable feature summaries and publication-quality figures from the completed validation outputs (without rerunning simulations or model inference):

features = extract_q0_angular_aperture_features_v1();
figures = plot_q0_angular_aperture_v1();

The feature preparation reuses the 114 existing wavefield_sample.mat files, checks patch alignment against the saved predictions, and stores raw selected features plus compact condition summaries. The plotting script has a clearly marked user-configuration section and writes PNG/PDF figures under outputs/validation/q0_angular_aperture_v1/figures/. It also computes angular_aperture_paper_summary.csv directly from the current condition summary; no manuscript metrics are hard-coded.

Two compact Cartesian sweep campaigns and their local base configurations are under configs/validation/q0_angular_aperture_v1. Each campaign fixes SWS and expands 19 angular supports x 3 paired seeds into 57 deterministic runs through simcampaigns.expandCampaign (114 combined). Simulation, patch-level, per-run, per-condition, angular-support, M, and SWS outputs are written below:

outputs/validation/q0_angular_aperture_v1/

See docs/validation/q0_angular_aperture_v1.md for the complete scientific contract and output schema.

Common parameters

M

REQ window-width multiplier.

The released model supports:

M = 2 or 3

Frequency

Harmonic wave frequency.

The frozen Q0 model was trained over:

200–600 Hz

Field regimes

Example wavefield angular complexity:

"directional"
"intermediate"
"diffuse"

Prediction step

Spatial interval, in input pixels, between neighboring REQ evaluations.

For example:

StepPixels=1

evaluates REQ at every valid window position and produces the densest output map. Larger values reduce computation by evaluating a sparser set of window centers; for example, StepPixels=4 evaluates every four input pixels.

StepPixels controls the sampling density of the output map. It does not change the physical REQ window size and should not be interpreted as the intrinsic spatial resolution of the estimator.

The public examples choose the step explicitly. The 3D k-Wave field-regime campaign uses StepPixels=1 for dense inclusion maps.

Current REQ Q0 model

The public model is referred to as the REQ Q0 model.

It was scientifically frozen from the internal homogeneous_cartesian_q0_v2 experiment. That internal identifier is retained in manifests and scientific documentation for reproducibility, but is not part of the public user-facing model name.

The model:

• supports M=2 and M=3
• was trained over SWS values from 1 to 4 m/s
• was trained over frequencies from 200 to 600 Hz
• includes controlled angular support from near-directional to diffuse fields
• uses deployment-observable spectral features
• does not use true SWS as a predictor

Model provenance and checksum information are documented under models/current/.

Scientific methodology

REQ computes a local radial spatial-frequency energy distribution.

For each analysis window, the method forms the cumulative radial spectral-energy curve

E_cum(k)

and determines the radial wavenumber k_q satisfying

E_cum(k_q) = q.

The released Q0 model predicts the operational quantile q from local wavefield-derived spectral features.

Shear-wave speed is then estimated from

c_s = 2*pi*f0/k_q.

The full scientific methodology and frozen-model development are documented in docs/methodology/homogeneous_cartesian_q0_v2.md.

Validation summary

The frozen model was evaluated across internal generalization tests and independent simulation backends.

Approximate homogeneous SWS errors were:

• ~2% MAPE for in-domain evaluation
• ~3% MAPE when alternating SWS levels were held out
• ~3% MAPE when alternating angular-support levels were held out
• ~2% MAPE on external homogeneous Eikonal simulations
• ~3% MAPE on external homogeneous k-Wave simulations

An independent spatial-sampling validation at 0.30 mm produced approximately 2% MAPE.

External heterogeneous cases were also evaluated as transfer tests. Errors are generally larger near interfaces and in locally complex wavefields than in homogeneous regions.

These values describe the frozen scientific evaluation scope and are not clinical performance claims.

Interpretation and limitations

REQ is a local spectral estimator. Its effective spatial resolution depends on the physical analysis-window size, which depends on frequency, spatial sampling, M, and the deployment configuration.

Important limitations include:

• mixed-material and interface patches are more difficult than homogeneous patches
• highly complex local interference can increase estimation error
• localized k-Wave hotspot/outlier structures have been observed even when global homogeneous estimates remain accurate
• experimental inputs should remain within a scientifically appropriate deployment domain
• the currently released model was trained on simulated harmonic wavefields; experimental validation is separate from the simulation-based validation summarized above
• the software is not clinically validated

Repository structure

src/       reusable MATLAB packages and public API
examples/  canonical end-to-end examples
configs/   active and reproducible scientific configurations
models/    model-distribution metadata; large bundles are excluded from Git
docs/      methodology, validation, and release documentation
tests/     unit, integration, and regression tests
archive/   retained legacy research provenance
scripts/   maintained workflow helpers
outputs/   generated local artifacts; excluded from Git

Research and legacy workflows

The recommended public v0.1.0 interface is:

reqml.predictSWS(...)

The compatibility helper reqml.examples.runExample(...) is retained for internal and older callers, but the recommended public simulation path is the visible JSON-plus-script architecture under examples/.

Older v1 workflows are retained under archive/legacy_v1/ for scientific provenance.

Adaptive and scientific-5D code is retained as research infrastructure and is not required for normal use of the released Q0 model.

Citation

Please cite this repository using CITATION.cff.

Licensed under the Apache License 2.0.

Maintainer: Sara Gomez-Ramirez (@gsara798).