SimCore Wave

Controlled 2.5D shear-wave simulation and ultrasound-readout modeling for elastography research

SimCore Wave is an open-source MATLAB toolbox for generating controlled shear-wave fields and REQ-ready measurements. It combines an Eikonal first-arrival phase model, frequency-dependent shear attenuation, configurable material maps, and a phenomenological ultrasound readout model.

The toolbox is designed for methodological studies, controlled sensitivity experiments, and validation of shear-wave-speed estimators. It is not a full elastodynamic solver, an RF beamforming simulator, or a clinically validated model.

Scope

SimCore Wave separates the simulation into distinct physical and numerical layers:

1. material and geometry definition;
2. source configuration;
3. shear-wave phase and attenuation;
4. optional propagation disturbances;
5. ultrasound depth and acoustic-loss modeling;
6. temporal readout noise;
7. REQ-ready output generation.

This separation makes assumptions explicit and allows individual modules to be enabled, disabled, or tested independently.

Baseline model

The recommended baseline uses:

• Phase: Eikonal first-arrival travel time.
• Shear attenuation: ray-path integral, exp(-integral(alpha_shear ds)).
• Ultrasound readout: temporal tracking noise with acoustic- and depth-dependent SNR weighting.
• Amplitude normalization: a fixed reference amplitude for comparisons across conditions.

Optional interface-transmission and phenomenological shadow modules are available for sensitivity studies but are disabled by default.

Main capabilities

• Homogeneous and heterogeneous 2D material maps.
• Frequency-dependent shear-wave speed and attenuation.
• Kelvin-Voigt and empirical power-law material descriptions.
• Point and finite lateral sources.
• Straight-ray and Eikonal phase models.
• Ray-path shear attenuation.
• Optional interface transmission and shadow sensitivity modules.
• Ultrasound depth loss and heterogeneous acoustic attenuation.
• Boukraa-inspired temporal readout noise.
• Fixed-reference noise normalization across simulations.
• Reliability, phase-error, and tracking-SNR maps.
• Stable adapter for Adaptive REQ workflows.
• Controlled liver-stage-like research presets.
• Smoke tests for key numerical components.

Installation

Clone the repository and add its src folder to the MATLAB path:

git clone https://github.com/gsara798/simcore-wave.git
cd simcore-wave

In MATLAB:

addpath("src");

No machine-specific absolute path is required.

Quick start

addpath("src");

cfg = simcore.config.defaultConfig();
cfg.Name = "quick_start";
cfg.f0 = 300;

out = simcore.pipelines.runREQReadySimulation(cfg);

The returned structure contains the measured and reference wavefields together with material, geometry, attenuation, SNR, and reliability metadata.

Important output fields include:

U
U_clean
U_shear_physical
true_SWS
x, z
dx, dz
f0
tracking_snr_db
readout_reliability
phase_error_vs_clean_cycles

Readout noise

For cross-condition comparisons, use a fixed displacement reference:

cfg.Noise.AmplitudeNormalization = "fixed_reference";
cfg.Noise.ReferenceAmplitude = referenceAmplitude;
cfg.Noise.IncludeShearAmplitudeSNR = false;

Noise presets are available:

cfg = simcore.readout.noisePreset("soft", cfg);
cfg = simcore.readout.noisePreset("medium", cfg);
cfg = simcore.readout.noisePreset("hard", cfg);

IncludeShearAmplitudeSNR is intentionally disabled by default. It should be enabled only as an explicit stress test.

Material models

Stage-like liver materials can be generated using:

mat = simcore.materials.liverStage("F2", ...
    "Model", "kelvin_voigt");

mat = simcore.materials.liverStage("F2", ...
    "Model", "empirical_power_law");

Supported labels are Normal/F0, F1, F2, F3, and F4.

These are controlled research presets. They are not universal clinical thresholds and should not be interpreted as diagnostic staging values.

REQ-ready interface

The stable public adapter is:

out = simcore.pipelines.runREQReadySimulation(cfg);

A compatibility wrapper is also retained:

out = simcore.runREQReadySimulation(cfg);

The stable adapter is the recommended entry point for external projects.

Example

The liver-stage readout example is:

run examples/check_liver_stages_REQ_ready_readout_2p5d.m

The example demonstrates:

• frequency-dependent material resolution;
• clean and attenuated shear fields;
• fixed-reference readout noise;
• tracking-SNR and phase-error diagnostics;
• compact REQ-ready outputs.

Tests

Run the current smoke tests from the repository root:

run tests/test_liver_stage_materials.m
run tests/test_makeSource2p5D_weights.m
run tests/test_fixed_reference_noise.m
run tests/test_rayPathIntegral2D_homogeneous.m

The tests cover material construction, source weighting, fixed-reference noise, and homogeneous ray-path integration.

Repository structure

src/
  +simcore/
    +config/       Configuration and parameter resolution
    +materials/    Material definitions and frequency dependence
    +geometry/     Spatial material and property maps
    +sources/      Point and finite-source construction
    +shear/        Phase, propagation, and attenuation
    +ultrasound/   Acoustic readout loss and SNR
    +noise/        Noise weighting
    +readout/      Temporal readout simulation
    +pipelines/    Stable public entry points

examples/          Reproducible simulation examples
tests/             Smoke and numerical validation tests
docs/              Architecture and model documentation
outputs/           Generated outputs; excluded from version control

Scientific limitations

• The propagation model is phenomenological and does not solve the full elastodynamic equations.
• Eikonal phase represents first-arrival propagation and does not reproduce all interference, mode conversion, diffraction, or multiple scattering.
• Interface-shadow and transmission modules are controlled approximations.
• The ultrasound layer models displacement-readout degradation, not full RF acquisition and beamforming.
• Liver-stage presets are research scenarios rather than clinical constants.
• Simulated realism should be evaluated against experiments and higher-fidelity solvers before drawing biological conclusions.

Relationship to Adaptive REQ

SimCore Wave can generate standardized outputs for the Adaptive REQ project. The projects remain separate so that wavefield generation and estimator development can be tested and versioned independently.

Contributing

Bug reports, numerical validation cases, documentation improvements, and well-scoped pull requests are welcome. See CONTRIBUTING.md.

Citation

If you use this software in research, cite the repository using CITATION.cff. Cite any external methods, datasets, or physical models used in your specific workflow separately.

License

This project is distributed under the Apache License 2.0.

Maintainer

Sara Gómez — @gsara798