Full-Waveform Inversion

Part 5 - Extensions

%matplotlib inline

# This notebook will use this variable to determine which
# remote site to run on.
import os
import numpy as np
import salvus.namespace as sn

SALVUS_FLOW_SITE_NAME = os.environ.get("SITE_NAME", "local")

p = sn.Project(path="project")

Step 9: Additional prior knowledge

Only update within a region of interest

In a typical USCT setup, there is always enough space between the ultrasound transducers and the phantom. What if we include that information as prior knowledge into our problem formulation?

An easy way of doing this, is to define a region of interest and restrict the reconstruction to this area.

To keep it simple, we just define a sphere with a radius of 6.5 cm as the target region.

mesh = p.simulations.get_mesh(simulation_configuration="initial_model")
# define the region of interest
roi = np.zeros_like(mesh.connectivity)
mask = np.linalg.norm(mesh.points[mesh.connectivity], axis=2) < 0.065
roi[mask] = 1.0
mesh.attach_field("region_of_interest", roi)

Let’s see if this helps with the iterations. To be able to compare the results, we just create a new inverse problem within the same project, initialize the region of interest, and start iterating.

p.add_to_project(
    sn.InverseProblemConfiguration(
        name="my_second_inversion",
        prior_model="initial_model",
        events=p.events.list(),
        mapping=sn.Mapping(
            scaling="absolute",
            inversion_parameters=["VP", "RHO"],
            region_of_interest=mesh,
        ),
        preconditioner=sn.ConstantSmoothing({"VP": 0.01, "RHO": 0.01}),
        method=sn.TrustRegion(initial_trust_region_linf=10.0),
        misfit_configuration="L2",
        wavefield_compression=sn.WavefieldCompression(
            forward_wavefield_sampling_interval=10
        ),
        job_submission=sn.SiteConfig(
            site_name=SALVUS_FLOW_SITE_NAME, ranks_per_job=4
        ),
    )
)

p.inversions.iterate(
    inverse_problem_configuration="my_second_inversion",
    timeout_in_seconds=360,
    ping_interval_in_seconds=10,
    delete_disposable_files="all",
)

[2026-10-12 21:09:36,178] INFO: Adding new iteration #0.
[2026-10-12 21:09:36,194] INFO: Resuming iteration #0.

[2026-10-12 21:09:36,197] INFO: 1 new tasks have been issued.
[2026-10-12 21:09:36,198] INFO: Processing task `misfit_and_gradient`
[2026-10-12 21:09:36,669] INFO: 
Iteration 0: Number of events: 5	 chi = 0.016385616624463036	 ||g|| = 0.015225055151621663
pred = ---	ared = ---	norm_update = ---	tr_radius = ---
[2026-10-12 21:09:36,682] INFO: 1 new tasks have been issued.
[2026-10-12 21:09:36,687] INFO: Processing task `preconditioner`

[2026-10-12 21:09:37,233] INFO: Some tasks of iteration #0 are still running. Please check again later.
[2026-10-12 21:09:47,269] INFO: Processing task `preconditioner`
[2026-10-12 21:09:47,609] INFO: 1 new tasks have been issued.
[2026-10-12 21:09:47,619] INFO: Processing task `misfit`
[2026-10-12 21:09:47,681] INFO: Submitting job array with 5 jobs ...

[2026-10-12 21:09:48,417] INFO: Launched simulations for 5 events. Please check again to see if they are finished.
[2026-10-12 21:09:48,425] INFO: Some tasks of iteration #0 are still running. Please check again later.
[2026-10-12 21:09:58,499] INFO: Processing task `misfit`
[2026-10-12 21:09:59,713] INFO: 
old misfit control group: 0.016385616624463036
new misfit control group: 0.006849571955600872
predicted reduction control group: -0.005146099961393702
actual reduction control group: -0.009536044668862164
5 out of 5 event(s) improved the misfit.
[2026-10-12 21:09:59,716] INFO: 
Model update accepted.
[2026-10-12 21:09:59,721] INFO: 1 new tasks have been issued.
[2026-10-12 21:09:59,723] INFO: Processing task `finalize_iteration`
[2026-10-12 21:09:59,787] INFO: ... searching for obsolete files in project/INVERSIONS/my_second_inversion/00000
[2026-10-12 21:09:59,807] INFO: Freed up 613.0 KB of space.
[2026-10-12 21:09:59,808] INFO: Successfully completed iteration #0.
[2026-10-12 21:09:59,811] INFO: Adding new iteration #1.

Let’s see if the region of interest was considered when the model was updated.

p.viz.nb.inversion(inverse_problem_configuration="my_second_inversion")

Indeed, outside of the pre-defined sphere, the model is still constant and has the same values as the initial model.

Let’s do a few more iterations and see what the reconstruction will be.

for i in range(2):
    p.inversions.iterate(
        inverse_problem_configuration="my_second_inversion",
        timeout_in_seconds=360,
        ping_interval_in_seconds=10,
        delete_disposable_files="all",
    )
p.viz.nb.inversion(inverse_problem_configuration="my_second_inversion")

[2026-10-12 21:10:06,364] INFO: Resuming iteration #1.

[2026-10-12 21:10:06,365] INFO: 1 new tasks have been issued.
[2026-10-12 21:10:06,365] INFO: Processing task `gradient`
[2026-10-12 21:10:06,553] INFO: Submitting job array with 5 jobs ...

[2026-10-12 21:10:06,692] INFO: Launched adjoint simulations for 5 events. Please check again to see if they are finished.
[2026-10-12 21:10:06,697] INFO: Some tasks of iteration #1 are still running. Please check again later.
[2026-10-12 21:10:16,704] INFO: Processing task `gradient`
[2026-10-12 21:10:17,480] INFO: 
Iteration 1: Number of events: 5	 chi = 0.006849571955600872	 ||g|| = 0.007636974220347543
pred = -0.005146099961393702	ared = -0.009536044668862164	norm_update = 0.6986523494085921	tr_radius = 0.6986522209328783
[2026-10-12 21:10:17,502] INFO: 1 new tasks have been issued.
[2026-10-12 21:10:17,505] INFO: Processing task `preconditioner`

[2026-10-12 21:10:17,691] INFO: Some tasks of iteration #1 are still running. Please check again later.
[2026-10-12 21:10:27,716] INFO: Processing task `preconditioner`
[2026-10-12 21:10:27,991] INFO: 1 new tasks have been issued.
[2026-10-12 21:10:27,992] INFO: Processing task `misfit`
[2026-10-12 21:10:28,038] INFO: Submitting job array with 5 jobs ...

[2026-10-12 21:10:28,264] INFO: Launched simulations for 5 events. Please check again to see if they are finished.
[2026-10-12 21:10:28,272] INFO: Some tasks of iteration #1 are still running. Please check again later.
[2026-10-12 21:10:38,337] INFO: Processing task `misfit`
[2026-10-12 21:10:39,449] INFO: 
old misfit control group: 0.006849571955600872
new misfit control group: 0.0036732389533484454
predicted reduction control group: -0.0023949316514517704
actual reduction control group: -0.003176333002252427
5 out of 5 event(s) improved the misfit.
[2026-10-12 21:10:39,450] INFO: 
Model update accepted.
[2026-10-12 21:10:39,454] INFO: 1 new tasks have been issued.
[2026-10-12 21:10:39,457] INFO: Processing task `finalize_iteration`
[2026-10-12 21:10:39,531] INFO: ... searching for obsolete files in project/INVERSIONS/my_second_inversion/00001
[2026-10-12 21:10:39,652] INFO: Freed up 3.3 MB of space.
[2026-10-12 21:10:39,655] INFO: Successfully completed iteration #1.
[2026-10-12 21:10:39,661] INFO: Adding new iteration #2.
[2026-10-12 21:10:39,676] INFO: Resuming iteration #2.

[2026-10-12 21:10:39,680] INFO: 1 new tasks have been issued.
[2026-10-12 21:10:39,681] INFO: Processing task `gradient`
[2026-10-12 21:10:40,670] INFO: Submitting job array with 5 jobs ...

[2026-10-12 21:10:40,835] INFO: Launched adjoint simulations for 5 events. Please check again to see if they are finished.
[2026-10-12 21:10:40,838] INFO: Some tasks of iteration #2 are still running. Please check again later.
[2026-10-12 21:10:50,842] INFO: Processing task `gradient`
[2026-10-12 21:10:51,600] INFO: 
Iteration 2: Number of events: 5	 chi = 0.003673238953348446	 ||g|| = 0.003914570451121825
pred = -0.0023949316514517704	ared = -0.003176333002252427	norm_update = 0.6666858443114032	tr_radius = 1.3973044418657565
[2026-10-12 21:10:51,634] INFO: 1 new tasks have been issued.
[2026-10-12 21:10:51,635] INFO: Processing task `preconditioner`

[2026-10-12 21:10:51,785] INFO: Some tasks of iteration #2 are still running. Please check again later.
[2026-10-12 21:11:01,803] INFO: Processing task `preconditioner`
[2026-10-12 21:11:01,962] INFO: 1 new tasks have been issued.
[2026-10-12 21:11:01,963] INFO: Processing task `misfit`
[2026-10-12 21:11:02,028] INFO: Submitting job array with 5 jobs ...

[2026-10-12 21:11:02,206] INFO: Launched simulations for 5 events. Please check again to see if they are finished.
[2026-10-12 21:11:02,208] INFO: Some tasks of iteration #2 are still running. Please check again later.
[2026-10-12 21:11:12,244] INFO: Processing task `misfit`
[2026-10-12 21:11:13,532] INFO: 
old misfit control group: 0.0036732389533484454
new misfit control group: 0.0030209278361615017
predicted reduction control group: -0.0003006636945883656
actual reduction control group: -0.0006523111171869438
5 out of 5 event(s) improved the misfit.
[2026-10-12 21:11:13,535] INFO: 
Model update accepted.
[2026-10-12 21:11:13,536] INFO: 1 new tasks have been issued.
[2026-10-12 21:11:13,536] INFO: Processing task `finalize_iteration`
[2026-10-12 21:11:13,596] INFO: ... searching for obsolete files in project/INVERSIONS/my_second_inversion/00002
[2026-10-12 21:11:13,668] INFO: Freed up 3.3 MB of space.
[2026-10-12 21:11:13,675] INFO: Successfully completed iteration #2.
[2026-10-12 21:11:13,684] INFO: Adding new iteration #3.

This looks better, so the prior knowledge was indeed helpful.

Box constraints

Alternatively, we could specify point-wise lower and upper bounds on the model parameters. In the example below, we allow deviations of +/- 20% in both VP and RHO, except for the previously selected region of interest, where we restrict VP updates to +/- 1 m/s.

Note that the mapping function does not contain a region of interest in this case.

p.add_to_project(
    sn.InverseProblemConfiguration(
        name="my_third_inversion",
        prior_model="initial_model",
        events=p.events.list(),
        mapping=sn.Mapping(
            scaling="absolute",
            inversion_parameters=["VP", "RHO"],
        ),
        preconditioner=sn.ConstantSmoothing({"VP": 0.01, "RHO": 0.01}),
        method=sn.TrustRegion(initial_trust_region_linf=10.0),
        misfit_configuration="L2",
        wavefield_compression=sn.WavefieldCompression(
            forward_wavefield_sampling_interval=10
        ),
        job_submission=sn.SiteConfig(
            site_name=SALVUS_FLOW_SITE_NAME, ranks_per_job=4
        ),
    )
)

mesh = p.simulations.get_mesh("initial_model")
lb = mesh.copy()
ones = np.ones_like(lb.elemental_fields["VP"])
lb.elemental_fields["VP"] *= 0.8
lb.elemental_fields["RHO"] *= 0.8
lb.elemental_fields["VP"][roi < 0.5] = 1501.0

ub = mesh.copy()
ub.elemental_fields["VP"] *= 1.2
ub.elemental_fields["RHO"] *= 1.2
ub.elemental_fields["VP"][roi < 0.5] = 1502.0

p.inversions.set_constraints(
    inverse_problem_configuration="my_third_inversion",
    constraints={
        "lower_bounds": lb,
        "upper_bounds": ub,
    },
)
p.inversions.iterate(
    "my_third_inversion", timeout_in_seconds=360, delete_disposable_files="all"
)
p.viz.nb.inversion(inverse_problem_configuration="my_third_inversion")

[2026-10-12 21:11:15,954] INFO: Adding new iteration #0.
[2026-10-12 21:11:15,972] INFO: Resuming iteration #0.

[2026-10-12 21:11:15,973] INFO: 1 new tasks have been issued.
[2026-10-12 21:11:15,974] INFO: Processing task `misfit_and_gradient`
[2026-10-12 21:11:16,278] INFO: 
Iteration 0: Number of events: 5	 chi = 0.016385616624463036	 ||g|| = 0.020187598686424082
pred = ---	ared = ---	norm_update = ---	tr_radius = ---
[2026-10-12 21:11:16,281] INFO: 1 new tasks have been issued.
[2026-10-12 21:11:16,282] INFO: Processing task `preconditioner`

[2026-10-12 21:11:16,449] INFO: Some tasks of iteration #0 are still running. Please check again later.
[2026-10-12 21:11:16,466] INFO: Processing task `preconditioner`
[2026-10-12 21:11:16,579] INFO: Some tasks of iteration #0 are still running. Please check again later.
[2026-10-12 21:11:18,000] INFO: 1 new tasks have been issued.
[2026-10-12 21:11:18,046] INFO: Submitting job array with 5 jobs ...

[2026-10-12 21:11:18,861] INFO: Launched simulations for 5 events. Please check again to see if they are finished.
[2026-10-12 21:11:18,898] INFO: Processing task `misfit`
[2026-10-12 21:11:19,017] INFO: Some tasks of iteration #0 are still running. Please check again later.
[2026-10-12 21:11:24,102] INFO: 
old misfit control group: 0.016385616624463036
new misfit control group: 0.007810959979827929
predicted reduction control group: -0.004854352629990899
actual reduction control group: -0.008574656644635106
5 out of 5 event(s) improved the misfit.
[2026-10-12 21:11:24,103] INFO: 
Model update accepted.
[2026-10-12 21:11:24,103] INFO: 1 new tasks have been issued.
[2026-10-12 21:11:24,175] INFO: ... searching for obsolete files in project/INVERSIONS/my_third_inversion/00000
[2026-10-12 21:11:24,195] INFO: Freed up 613.0 KB of space.
[2026-10-12 21:11:24,196] INFO: Successfully completed iteration #0.
[2026-10-12 21:11:24,199] INFO: Adding new iteration #1.

The example above is just meant to demonstrate the use of box constraints. For cases where lower and upper bounds are (almost) equal, we recommend using a region of interest instead.

Postprocessing model updates

It is sometimes helpful to let prior knowledge influence the model updates. There are inherent differences in the sensitivity with respect to the magnitude of some parameters, but we might use physical knowledge such as scaling relations between the parameters to tweak the proposed models. This can be achieved by a callback within the mapping function. In the following example, we only invert for VP, but use the following scaling relation for soft tissues to update RHO:

def scaling_relation_density(
    prior_model: sn.UnstructuredMesh,
    proposed_model: sn.UnstructuredMesh,
) -> sn.UnstructuredMesh:

    # Here we directly apply a scaling relation to the density model.
    # We don't need the prior model in this case.

    new_model = proposed_model.copy()
    new_model.elemental_fields["RHO"] = (
        0.893 * new_model.elemental_fields["VP"] - 349.0
    )

    return new_model

This callback will modify proposed model updates before recomputing the misfits. Strictly speaking, this results in inconsistent gradients, because we neglect density as an inversion parameter but because of the low sensitivity to density amplitudes, this does not impact the trust region algorithm much.

p.add_to_project(
    sn.InverseProblemConfiguration(
        name="my_fourth_inversion",
        prior_model="initial_model",
        events=p.events.list(),
        mapping=sn.Mapping(
            scaling="absolute",
            inversion_parameters=[
                "VP",
            ],
            postprocess_model_update=scaling_relation_density,
        ),
        preconditioner=sn.ConstantSmoothing({"VP": 0.01}),
        method=sn.TrustRegion(initial_trust_region_linf=10.0),
        misfit_configuration="L2",
        wavefield_compression=sn.WavefieldCompression(
            forward_wavefield_sampling_interval=10
        ),
        job_submission=sn.SiteConfig(
            site_name=SALVUS_FLOW_SITE_NAME, ranks_per_job=4
        ),
    )
)