Mondaic DocumentationThis micro-tutorial demonstrates how to set up a first full waveform inversion with Salvus.
The simulations are very light and do not require any serious resources.
Some familiary with Python as well as knowledge of how to set up forward simulations with Salvus is assumed.
For an in-depth tutorial of running full waveform inversions with Salvus, please have a look at one of our other tutorials.
import os
import numpy as np
import xarray as xr
import salvus.namespace as sn
SALVUS_FLOW_SITE_NAME = os.environ.get("SITE_NAME", "local")We'll generate a ring of transducers, five of which act as sources. This mimics an acquisition setup common in medical devices.
# Generate a ring with 5 scalar sources.
sources = sn.simple_config.source.cartesian.collections.ScalarPoint2DRing(
x=0, y=0, radius=0.09, count=5, f=1.0
)
events = []
# Use the same receiver ring for each but mask out the receivers close to each
# source.
for i, s in enumerate(sources._sources):
all_receivers = (
sn.simple_config.receiver.cartesian.collections.RingPoint2D(
x=0, y=0, radius=0.09, count=100, fields=["phi"]
)
)
receivers = [
r
for r in all_receivers._receivers
if np.sqrt(
(s.location[0] - r.location[0]) ** 2
+ (s.location[1] - r.location[1]) ** 2
)
> 0.03
]
events.append(
sn.Event(event_name=f"event_{i}", sources=s, receivers=receivers)
)For FWI we'll need something to invert for. For most applications this will be recorded data from some real world setting. Here we'll define a synthetic inversion target and generate our own data.
def get_spherical_inclusion() -> xr.Dataset:
nx, ny = 200, 200
x = np.linspace(-0.1, +0.1, nx)
y = np.linspace(-0.1, +0.1, ny)
xx, yy = np.meshgrid(x, y, indexing="ij")
# Add 3 spherical inclusions
vp = 1500.0 * np.ones_like(xx)
rho = 980.0 * np.ones_like(xx)
mask = np.sqrt(xx**2 + yy**2) < 0.05
vp[mask] = 1480.0
rho[mask] = 1000.0
mask = np.sqrt(xx**2 + (yy - 0.025) ** 2) < 0.015
vp[mask] = 1550.0
rho[mask] = 1040.0
mask = np.sqrt(xx**2 + (yy + 0.025) ** 2) < 0.015
vp[mask] = 1460.0
rho[mask] = 1010.0
ds = xr.Dataset(
data_vars={
"vp": (["x", "y"], vp),
"rho": (["x", "y"], rho),
},
coords={"x": x, "y": y},
)
return ds
true_model = get_spherical_inclusion()
ax = true_model.vp.T.plot(figsize=(10, 6))
ax.axes.set_aspect("equal")
# Use the volume model to set up the project.
volume_model = sn.model.volume.cartesian.GenericModel(
name="true_model", data=true_model
)
p = sn.Project.from_volume_model(
path="project_full_waveform_inversion",
volume_model=volume_model,
load_if_exists=True,
)
# Add the events.
for event in events:
p.add_to_project(event)
p.visualizations.notebook.domain()
# Generate the data for the target model.
wsc = sn.WaveformSimulationConfiguration(end_time_in_seconds=0.00015)
ec = sn.EventConfiguration(
waveform_simulation_configuration=wsc,
wavelet=sn.simple_config.stf.Ricker(center_frequency=50000.0),
)
p += sn.SimulationConfiguration(
name="true_model_100kHz",
elements_per_wavelength=2,
tensor_order=4,
max_frequency_in_hertz=100000.0,
model_configuration=sn.ModelConfiguration(
background_model=None, volume_models="true_model"
),
event_configuration=ec,
)
p.simulations.launch(
simulation_configuration="true_model_100kHz",
events=p.events.list(),
site_name=SALVUS_FLOW_SITE_NAME,
ranks_per_job=1,
)
p.simulations.query(block=True)[2026-06-02 23:36:57,369] INFO: Creating mesh. Hang on. [2026-06-02 23:36:57,505] INFO: Submitting job array with 5 jobs ...
True
We can use a similar strategy for defining the initial model. Note that we aren't required to launch the simulations here for the initial model as this will be taken care of automatically once we start the inversion.
bm = sn.model.background.homogeneous.IsotropicAcoustic(vp=1500.0, rho=980.0)
mc = sn.ModelConfiguration(background_model=bm)
wsc = sn.WaveformSimulationConfiguration(end_time_in_seconds=0.00015)
p += sn.SimulationConfiguration(
name="initial_model",
elements_per_wavelength=2,
tensor_order=2,
max_frequency_in_hertz=100000.0,
model_configuration=mc,
event_configuration=sn.EventConfiguration(
waveform_simulation_configuration=wsc,
wavelet=sn.simple_config.stf.Ricker(center_frequency=50000.0),
),
)Salvus allows for a lot of control and flexibility in how exactly inverse problems are tackled. Things like data processing, window selection, custom weighting schemes, data normalization, bound constraints, wavelength dependent smoothing, and many more are supported but we don't show them in this micro-tutorial. Please refer to some advanced tutorials for more information.
In all cases, an inverse problem requires the definition of a misfit, e.g. the optimization target, as well the actual configuration of the inverse problem.
# The misfit configuration defines how synthetics are compared to observed data.
p += sn.MisfitConfiguration(
name="L2",
# Could be observed data. Here we compare to the synthetic target.
observed_data="true_model_100kHz",
# Salvus comes with a variety of misfit functions. You can
# also define your own.
misfit_function="L2",
# This is an acoustic simulation so we'll use recordings of phi.
receiver_field="phi",
)
# Now we define the actual inverse problem
p += sn.InverseProblemConfiguration(
name="my_inversion",
# Starting model.
prior_model="initial_model",
# The events to use.
events=p.events.list(),
# What parameters to invert for.
mapping=sn.Mapping(scaling="absolute", inversion_parameters=["VP", "RHO"]),
# The smoothing.
preconditioner=sn.ConstantSmoothing({"VP": 0.01, "RHO": 0.01}),
# The inversion method.
method=sn.TrustRegion(initial_trust_region_linf=10.0),
# The misfit configuration we defined above.
misfit_configuration="L2",
# Compress the forward wavefield by subsampling in time.
wavefield_compression=sn.WavefieldCompression(
forward_wavefield_sampling_interval=10
),
# Job submission settings.
job_submission=sn.SiteConfig(
site_name=SALVUS_FLOW_SITE_NAME, ranks_per_job=1
),
)[2026-06-02 23:37:00,877] INFO: Creating mesh. Hang on.
# Lastly we perform two iterations, and have a look at the results.
for i in range(2):
p.inversions.iterate(
inverse_problem_configuration="my_inversion",
timeout_in_seconds=360,
ping_interval_in_seconds=2,
delete_disposable_files="all",
)[2026-06-02 23:37:00,969] INFO: Adding new iteration #0. [2026-06-02 23:37:00,992] INFO: Resuming iteration #0. [2026-06-02 23:37:00,997] INFO: 1 new tasks have been issued. [2026-06-02 23:37:00,997] INFO: Processing task `misfit_and_gradient` [2026-06-02 23:37:01,179] INFO: Submitting job array with 5 jobs ... [2026-06-02 23:37:01,373] INFO: Launched simulations for 5 events. Please check again to see if they are finished. [2026-06-02 23:37:01,378] INFO: Some tasks of iteration #0 are still running. Please check again later. [2026-06-02 23:37:03,380] INFO: Processing task `misfit_and_gradient` [2026-06-02 23:37:03,501] INFO: Some tasks of iteration #0 are still running. Please check again later. [2026-06-02 23:37:05,507] INFO: Processing task `misfit_and_gradient` [2026-06-02 23:37:09,009] INFO: Submitting job array with 5 jobs ... [2026-06-02 23:37:09,150] INFO: Launched adjoint simulations for 5 events. Please check again to see if they are finished. [2026-06-02 23:37:09,153] INFO: Some tasks of iteration #0 are still running. Please check again later. [2026-06-02 23:37:11,156] INFO: Processing task `misfit_and_gradient` [2026-06-02 23:37:11,625] INFO: Some tasks of iteration #0 are still running. Please check again later. [2026-06-02 23:37:13,627] INFO: Processing task `misfit_and_gradient` [2026-06-02 23:37:15,265] INFO: Iteration 0: Number of events: 5 chi = 0.015278809366937164 ||g|| = 0.01996766071007446 pred = --- ared = --- norm_update = --- tr_radius = --- [2026-06-02 23:37:15,266] INFO: 1 new tasks have been issued. [2026-06-02 23:37:15,268] INFO: Processing task `preconditioner` [2026-06-02 23:37:15,513] INFO: Some tasks of iteration #0 are still running. Please check again later. [2026-06-02 23:37:17,535] INFO: Processing task `preconditioner` [2026-06-02 23:37:17,778] INFO: 1 new tasks have been issued. [2026-06-02 23:37:17,781] INFO: Processing task `misfit` [2026-06-02 23:37:17,866] INFO: Submitting job array with 5 jobs ... [2026-06-02 23:37:18,116] INFO: Launched simulations for 5 events. Please check again to see if they are finished. [2026-06-02 23:37:18,119] INFO: Some tasks of iteration #0 are still running. Please check again later. [2026-06-02 23:37:20,151] INFO: Processing task `misfit` [2026-06-02 23:37:21,261] INFO: old misfit control group: 0.015278809366937162 new misfit control group: 0.005913131187795305 predicted reduction control group: -0.007919777905044612 actual reduction control group: -0.009365678179141856 5 out of 5 event(s) improved the misfit. [2026-06-02 23:37:21,262] INFO: Model update accepted. [2026-06-02 23:37:21,262] INFO: 1 new tasks have been issued. [2026-06-02 23:37:21,262] INFO: Processing task `finalize_iteration` [2026-06-02 23:37:21,313] INFO: ... searching for obsolete files in project_full_waveform_inversion/INVERSIONS/my_inversion/00000 [2026-06-02 23:37:21,331] INFO: Freed up 613.0 KB of space. [2026-06-02 23:37:21,332] INFO: Successfully completed iteration #0. [2026-06-02 23:37:21,334] INFO: Adding new iteration #1. [2026-06-02 23:37:21,340] INFO: Resuming iteration #1. [2026-06-02 23:37:21,341] INFO: 1 new tasks have been issued. [2026-06-02 23:37:21,342] INFO: Processing task `gradient` [2026-06-02 23:37:21,568] INFO: Submitting job array with 5 jobs ... [2026-06-02 23:37:21,674] INFO: Launched adjoint simulations for 5 events. Please check again to see if they are finished. [2026-06-02 23:37:21,683] INFO: Some tasks of iteration #1 are still running. Please check again later. [2026-06-02 23:37:23,688] INFO: Processing task `gradient` [2026-06-02 23:37:23,957] INFO: Some tasks of iteration #1 are still running. Please check again later. [2026-06-02 23:37:25,960] INFO: Processing task `gradient` [2026-06-02 23:37:26,745] INFO: Iteration 1: Number of events: 5 chi = 0.005913131187795306 ||g|| = 0.009340556997480898 pred = -0.007919777905044612 ared = -0.009365678179141856 norm_update = 0.8813270007035139 tr_radius = 0.8813270316788413 [2026-06-02 23:37:26,762] INFO: 1 new tasks have been issued. [2026-06-02 23:37:26,763] INFO: Processing task `preconditioner` [2026-06-02 23:37:26,996] INFO: Some tasks of iteration #1 are still running. Please check again later. [2026-06-02 23:37:29,029] INFO: Processing task `preconditioner` [2026-06-02 23:37:29,201] INFO: 1 new tasks have been issued. [2026-06-02 23:37:29,202] INFO: Processing task `misfit` [2026-06-02 23:37:29,267] INFO: Submitting job array with 5 jobs ... [2026-06-02 23:37:30,114] INFO: Launched simulations for 5 events. Please check again to see if they are finished. [2026-06-02 23:37:30,116] INFO: Some tasks of iteration #1 are still running. Please check again later. [2026-06-02 23:37:32,145] INFO: Processing task `misfit` [2026-06-02 23:37:33,325] INFO: old misfit control group: 0.005913131187795305 new misfit control group: 0.00421719228761969 predicted reduction control group: -0.0008834066261442786 actual reduction control group: -0.0016959389001756147 5 out of 5 event(s) improved the misfit. [2026-06-02 23:37:33,326] INFO: Model update accepted. [2026-06-02 23:37:33,328] INFO: 1 new tasks have been issued. [2026-06-02 23:37:33,329] INFO: Processing task `finalize_iteration` [2026-06-02 23:37:33,389] INFO: ... searching for obsolete files in project_full_waveform_inversion/INVERSIONS/my_inversion/00001 [2026-06-02 23:37:33,516] INFO: Freed up 3.2 MB of space. [2026-06-02 23:37:33,519] INFO: Successfully completed iteration #1. [2026-06-02 23:37:33,523] INFO: Adding new iteration #2.
p.viz.nb.inversion(inverse_problem_configuration="my_inversion")
PAGE CONTENTS