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)[2025-07-23 21:12:04,717] INFO: Creating mesh. Hang on. [2025-07-23 21:12:04,781] INFO: Submitting job array with 5 jobs ...
True
Now we do exactly the same thing, but we'll use a homogeneous initial model.
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),
),
)
p.simulations.launch(
simulation_configuration="initial_model",
events=p.events.list(),
site_name=SALVUS_FLOW_SITE_NAME,
ranks_per_job=1,
)
p.simulations.query(block=True)[2025-07-23 21:12:09,160] INFO: Creating mesh. Hang on. [2025-07-23 21:12:09,197] INFO: Submitting job array with 5 jobs ...
True
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
),
)# 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",
)[2025-07-23 21:12:13,468] INFO: Adding new iteration #0. [2025-07-23 21:12:13,473] INFO: Resuming iteration #0. [2025-07-23 21:12:13,474] INFO: 1 new tasks have been issued. [2025-07-23 21:12:13,474] INFO: Processing task `misfit_and_gradient` [2025-07-23 21:12:13,530] INFO: The following events have been simulated before, but checkpoints are not available for this combination of `site_name` and `ranks_per_job` and wavefield compression settings. They will be run again: ['event_0', 'event_1', 'event_2', 'event_3', 'event_4'] [2025-07-23 21:12:13,550] INFO: Submitting job array with 5 jobs ... [2025-07-23 21:12:13,633] INFO: Launched simulations for 5 events. Please check again to see if they are finished. [2025-07-23 21:12:13,634] INFO: Some tasks of iteration #0 are still running. Please check again later. [2025-07-23 21:12:15,635] INFO: Processing task `misfit_and_gradient` [2025-07-23 21:12:15,737] INFO: Some tasks of iteration #0 are still running. Please check again later. [2025-07-23 21:12:17,738] INFO: Processing task `misfit_and_gradient` [2025-07-23 21:12:20,307] INFO: Submitting job array with 5 jobs ... [2025-07-23 21:12:20,353] INFO: Launched adjoint simulations for 5 events. Please check again to see if they are finished. [2025-07-23 21:12:20,354] INFO: Some tasks of iteration #0 are still running. Please check again later. [2025-07-23 21:12:22,355] INFO: Processing task `misfit_and_gradient` [2025-07-23 21:12:22,628] INFO: Some tasks of iteration #0 are still running. Please check again later. [2025-07-23 21:12:24,630] INFO: Processing task `misfit_and_gradient` [2025-07-23 21:12:25,236] INFO: Iteration 0: Number of events: 5 chi = 0.015278803721797369 ||g|| = 0.01996765797717116 pred = --- ared = --- norm_update = --- tr_radius = --- [2025-07-23 21:12:25,236] INFO: 1 new tasks have been issued. [2025-07-23 21:12:25,237] INFO: Processing task `preconditioner` [2025-07-23 21:12:25,297] INFO: Some tasks of iteration #0 are still running. Please check again later. [2025-07-23 21:12:27,306] INFO: Processing task `preconditioner` [2025-07-23 21:12:27,427] INFO: 1 new tasks have been issued. [2025-07-23 21:12:27,427] INFO: Processing task `misfit` [2025-07-23 21:12:27,467] INFO: Submitting job array with 5 jobs ... [2025-07-23 21:12:27,550] INFO: Launched simulations for 5 events. Please check again to see if they are finished. [2025-07-23 21:12:27,551] INFO: Some tasks of iteration #0 are still running. Please check again later. [2025-07-23 21:12:29,566] INFO: Processing task `misfit` [2025-07-23 21:12:29,627] INFO: Some tasks of iteration #0 are still running. Please check again later. [2025-07-23 21:12:31,646] INFO: Processing task `misfit` [2025-07-23 21:12:32,499] INFO: old misfit control group: 0.015278803721797369 new misfit control group: 0.005913133008434076 predicted reduction control group: -0.007919783452962292 actual reduction control group: -0.009365670713363293 5 out of 5 event(s) improved the misfit. [2025-07-23 21:12:32,500] INFO: Model update accepted. [2025-07-23 21:12:32,500] INFO: 1 new tasks have been issued. [2025-07-23 21:12:32,500] INFO: Processing task `finalize_iteration` [2025-07-23 21:12:32,533] INFO: ... searching for obsolete files in project_full_waveform_inversion/INVERSIONS/my_inversion/00000 [2025-07-23 21:12:32,541] INFO: Freed up 613.0 KB of space. [2025-07-23 21:12:32,541] INFO: Successfully completed iteration #0. [2025-07-23 21:12:32,542] INFO: Adding new iteration #1. [2025-07-23 21:12:32,546] INFO: Resuming iteration #1. [2025-07-23 21:12:32,546] INFO: 1 new tasks have been issued. [2025-07-23 21:12:32,547] INFO: Processing task `gradient` [2025-07-23 21:12:32,725] INFO: Submitting job array with 5 jobs ... [2025-07-23 21:12:32,772] INFO: Launched adjoint simulations for 5 events. Please check again to see if they are finished. [2025-07-23 21:12:32,773] INFO: Some tasks of iteration #1 are still running. Please check again later. [2025-07-23 21:12:34,774] INFO: Processing task `gradient` [2025-07-23 21:12:34,964] INFO: Some tasks of iteration #1 are still running. Please check again later. [2025-07-23 21:12:36,965] INFO: Processing task `gradient` [2025-07-23 21:12:37,463] INFO: Iteration 1: Number of events: 5 chi = 0.005913133008434076 ||g|| = 0.00934055110656381 pred = -0.007919783452962292 ared = -0.009365670713363293 norm_update = 0.8813276753908115 tr_radius = 0.8813277085125916 [2025-07-23 21:12:37,472] INFO: 1 new tasks have been issued. [2025-07-23 21:12:37,472] INFO: Processing task `preconditioner` [2025-07-23 21:12:37,542] INFO: Some tasks of iteration #1 are still running. Please check again later. [2025-07-23 21:12:39,560] INFO: Processing task `preconditioner` [2025-07-23 21:12:39,686] INFO: 1 new tasks have been issued. [2025-07-23 21:12:39,686] INFO: Processing task `misfit` [2025-07-23 21:12:39,725] INFO: Submitting job array with 5 jobs ... [2025-07-23 21:12:39,809] INFO: Launched simulations for 5 events. Please check again to see if they are finished. [2025-07-23 21:12:39,810] INFO: Some tasks of iteration #1 are still running. Please check again later. [2025-07-23 21:12:41,836] INFO: Processing task `misfit` [2025-07-23 21:12:41,899] INFO: Some tasks of iteration #1 are still running. Please check again later. [2025-07-23 21:12:43,928] INFO: Processing task `misfit` [2025-07-23 21:12:44,578] INFO: old misfit control group: 0.005913133008434076 new misfit control group: 0.004217191511153765 predicted reduction control group: -0.0008834076033963356 actual reduction control group: -0.001695941497280311 5 out of 5 event(s) improved the misfit. [2025-07-23 21:12:44,579] INFO: Model update accepted. [2025-07-23 21:12:44,579] INFO: 1 new tasks have been issued. [2025-07-23 21:12:44,579] INFO: Processing task `finalize_iteration` [2025-07-23 21:12:44,627] INFO: ... searching for obsolete files in project_full_waveform_inversion/INVERSIONS/my_inversion/00001 [2025-07-23 21:12:44,734] INFO: Freed up 3.6 MB of space. [2025-07-23 21:12:44,735] INFO: Successfully completed iteration #1. [2025-07-23 21:12:44,736] INFO: Adding new iteration #2.
p.viz.nb.inversion(inverse_problem_configuration="my_inversion")
PAGE CONTENTS