Mondaic DocumentationThis documentation is not for the latest stable Salvus version.
%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")
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-05-01 14:58:15,448] INFO: Adding new iteration #0. [2026-05-01 14:58:15,454] INFO: Resuming iteration #0. [2026-05-01 14:58:15,455] INFO: 1 new tasks have been issued. [2026-05-01 14:58:15,455] INFO: Processing task `misfit_and_gradient` [2026-05-01 14:58:15,617] INFO: Iteration 0: Number of events: 5 chi = 0.016385616624463036 ||g|| = 0.015225054673727976 pred = --- ared = --- norm_update = --- tr_radius = --- [2026-05-01 14:58:15,618] INFO: 1 new tasks have been issued. [2026-05-01 14:58:15,618] INFO: Processing task `preconditioner` [2026-05-01 14:58:15,754] INFO: Some tasks of iteration #0 are still running. Please check again later. [2026-05-01 14:58:25,763] INFO: Processing task `preconditioner` [2026-05-01 14:58:25,884] INFO: 1 new tasks have been issued. [2026-05-01 14:58:25,884] INFO: Processing task `misfit` [2026-05-01 14:58:25,926] INFO: Submitting job array with 5 jobs ... [2026-05-01 14:58:26,174] INFO: Launched simulations for 5 events. Please check again to see if they are finished. [2026-05-01 14:58:26,175] INFO: Some tasks of iteration #0 are still running. Please check again later. [2026-05-01 14:58:36,191] INFO: Processing task `misfit` [2026-05-01 14:58:36,790] INFO: old misfit control group: 0.016385616624463036 new misfit control group: 0.0068495715397390525 predicted reduction control group: -0.005146099961393702 actual reduction control group: -0.009536045084723983 5 out of 5 event(s) improved the misfit. [2026-05-01 14:58:36,790] INFO: Model update accepted. [2026-05-01 14:58:36,790] INFO: 1 new tasks have been issued. [2026-05-01 14:58:36,791] INFO: Processing task `finalize_iteration` [2026-05-01 14:58:36,823] INFO: ... searching for obsolete files in project/INVERSIONS/my_second_inversion/00000 [2026-05-01 14:58:36,835] INFO: Freed up 613.0 KB of space. [2026-05-01 14:58:36,836] INFO: Successfully completed iteration #0. [2026-05-01 14:58:36,837] 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-05-01 14:58:39,639] INFO: Resuming iteration #1. [2026-05-01 14:58:39,640] INFO: 1 new tasks have been issued. [2026-05-01 14:58:39,640] INFO: Processing task `gradient` [2026-05-01 14:58:39,752] INFO: Submitting job array with 5 jobs ... [2026-05-01 14:58:39,803] INFO: Launched adjoint simulations for 5 events. Please check again to see if they are finished. [2026-05-01 14:58:39,804] INFO: Some tasks of iteration #1 are still running. Please check again later. [2026-05-01 14:58:49,806] INFO: Processing task `gradient` [2026-05-01 14:58:50,213] INFO: Iteration 1: Number of events: 5 chi = 0.0068495715397390525 ||g|| = 0.007636973282506061 pred = -0.005146099961393702 ared = -0.009536045084723983 norm_update = 0.6986523494085921 tr_radius = 0.6986522209328783 [2026-05-01 14:58:50,222] INFO: 1 new tasks have been issued. [2026-05-01 14:58:50,222] INFO: Processing task `preconditioner` [2026-05-01 14:58:50,293] INFO: Some tasks of iteration #1 are still running. Please check again later. [2026-05-01 14:59:00,302] INFO: Processing task `preconditioner` [2026-05-01 14:59:00,439] INFO: 1 new tasks have been issued. [2026-05-01 14:59:00,440] INFO: Processing task `misfit` [2026-05-01 14:59:00,480] INFO: Submitting job array with 5 jobs ... [2026-05-01 14:59:00,569] INFO: Launched simulations for 5 events. Please check again to see if they are finished. [2026-05-01 14:59:00,570] INFO: Some tasks of iteration #1 are still running. Please check again later. [2026-05-01 14:59:10,589] INFO: Processing task `misfit` [2026-05-01 14:59:11,178] INFO: old misfit control group: 0.0068495715397390525 new misfit control group: 0.0036732410562075645 predicted reduction control group: -0.0023949299470586993 actual reduction control group: -0.003176330483531488 5 out of 5 event(s) improved the misfit. [2026-05-01 14:59:11,179] INFO: Model update accepted. [2026-05-01 14:59:11,179] INFO: 1 new tasks have been issued. [2026-05-01 14:59:11,179] INFO: Processing task `finalize_iteration` [2026-05-01 14:59:11,213] INFO: ... searching for obsolete files in project/INVERSIONS/my_second_inversion/00001 [2026-05-01 14:59:11,278] INFO: Freed up 3.3 MB of space. [2026-05-01 14:59:11,279] INFO: Successfully completed iteration #1. [2026-05-01 14:59:11,280] INFO: Adding new iteration #2. [2026-05-01 14:59:11,285] INFO: Resuming iteration #2. [2026-05-01 14:59:11,286] INFO: 1 new tasks have been issued. [2026-05-01 14:59:11,286] INFO: Processing task `gradient` [2026-05-01 14:59:11,381] INFO: Submitting job array with 5 jobs ... [2026-05-01 14:59:11,438] INFO: Launched adjoint simulations for 5 events. Please check again to see if they are finished. [2026-05-01 14:59:11,439] INFO: Some tasks of iteration #2 are still running. Please check again later. [2026-05-01 14:59:21,441] INFO: Processing task `gradient` [2026-05-01 14:59:22,075] INFO: Iteration 2: Number of events: 5 chi = 0.0036732410562075645 ||g|| = 0.003914571177171008 pred = -0.0023949299470586993 ared = -0.003176330483531488 norm_update = 0.6666855264629865 tr_radius = 1.3973044418657565 [2026-05-01 14:59:22,089] INFO: 1 new tasks have been issued. [2026-05-01 14:59:22,090] INFO: Processing task `preconditioner` [2026-05-01 14:59:22,158] INFO: Some tasks of iteration #2 are still running. Please check again later. [2026-05-01 14:59:32,166] INFO: Processing task `preconditioner` [2026-05-01 14:59:32,286] INFO: 1 new tasks have been issued. [2026-05-01 14:59:32,287] INFO: Processing task `misfit` [2026-05-01 14:59:32,323] INFO: Submitting job array with 5 jobs ... [2026-05-01 14:59:32,414] INFO: Launched simulations for 5 events. Please check again to see if they are finished. [2026-05-01 14:59:32,415] INFO: Some tasks of iteration #2 are still running. Please check again later. [2026-05-01 14:59:42,431] INFO: Processing task `misfit` [2026-05-01 14:59:43,000] INFO: old misfit control group: 0.0036732410562075645 new misfit control group: 0.0030209278134020927 predicted reduction control group: -0.0003006637195994699 actual reduction control group: -0.0006523132428054718 5 out of 5 event(s) improved the misfit. [2026-05-01 14:59:43,000] INFO: Model update accepted. [2026-05-01 14:59:43,001] INFO: 1 new tasks have been issued. [2026-05-01 14:59:43,001] INFO: Processing task `finalize_iteration` [2026-05-01 14:59:43,037] INFO: ... searching for obsolete files in project/INVERSIONS/my_second_inversion/00002 [2026-05-01 14:59:43,100] INFO: Freed up 3.3 MB of space. [2026-05-01 14:59:43,101] INFO: Successfully completed iteration #2. [2026-05-01 14:59:43,103] INFO: Adding new iteration #3.
This looks better, so the prior knowledge was indeed helpful.
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-05-01 14:59:44,010] INFO: Adding new iteration #0. [2026-05-01 14:59:44,016] INFO: Resuming iteration #0. [2026-05-01 14:59:44,017] INFO: 1 new tasks have been issued. [2026-05-01 14:59:44,017] INFO: Processing task `misfit_and_gradient` [2026-05-01 14:59:44,206] INFO: Iteration 0: Number of events: 5 chi = 0.016385616624463036 ||g|| = 0.020187599407258453 pred = --- ared = --- norm_update = --- tr_radius = --- [2026-05-01 14:59:44,207] INFO: 1 new tasks have been issued. [2026-05-01 14:59:44,207] INFO: Processing task `preconditioner` [2026-05-01 14:59:44,267] INFO: Some tasks of iteration #0 are still running. Please check again later. [2026-05-01 14:59:44,275] INFO: Processing task `preconditioner` [2026-05-01 14:59:44,304] INFO: Some tasks of iteration #0 are still running. Please check again later. [2026-05-01 14:59:44,852] INFO: 1 new tasks have been issued. [2026-05-01 14:59:44,890] INFO: Submitting job array with 5 jobs ... [2026-05-01 14:59:44,987] INFO: Launched simulations for 5 events. Please check again to see if they are finished. [2026-05-01 14:59:45,003] INFO: Processing task `misfit` [2026-05-01 14:59:45,040] INFO: Some tasks of iteration #0 are still running. Please check again later. [2026-05-01 14:59:47,127] INFO: old misfit control group: 0.016385616624463036 new misfit control group: 0.00781096178545235 predicted reduction control group: -0.0048543526499997824 actual reduction control group: -0.008574654839010685 5 out of 5 event(s) improved the misfit. [2026-05-01 14:59:47,127] INFO: Model update accepted. [2026-05-01 14:59:47,127] INFO: 1 new tasks have been issued. [2026-05-01 14:59:47,158] INFO: ... searching for obsolete files in project/INVERSIONS/my_third_inversion/00000 [2026-05-01 14:59:47,168] INFO: Freed up 613.0 KB of space. [2026-05-01 14:59:47,168] INFO: Successfully completed iteration #0. [2026-05-01 14:59:47,170] 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_modelThis 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
),
)
)
PAGE CONTENTS