Skip to content

Salvus 2026.X

Updating Guide from Salvus 2025.1.x to Salvus 2026.x

Versioning

Starting with 2026.5.0, Salvus uses date-based version numbers of the form YYYY.M.P, where YYYY is the year, M is the month of the release (not zero-padded), and P is the patch level. For example, 2026.5.0 is the initial May 2026 release, and 2026.5.1 would be a subsequent patch to that release.

This replaces the previous YYYY.N.P scheme (e.g. 2025.1.x), where N was a sequential release counter rather than a calendar month. The new scheme makes it immediately clear when a version was released and simplifies planning around Salvus updates.

Backwards compatibility is ensured between releases unless explicitly stated otherwise.

Users Who Should not Update (yet)

Both, Salvus API and SalvusProject remain fully compatible when transitioning from Salvus 2025.1.x to Salvus 2026.x.

However, we have updated the minimum requirements for some of Salvus’ first-level Python dependencies such as numpy>=2.2.0 or sqlalchemy>2.0. In case you cannot update these packages, we recommend continuing with the maintenance release 2025.1.3.

Updating Guide

Nothing special needs to be done for the SalvusCompute binaries. Just running the Mondaic downloader will update them.

The Python installation requires a bit more work, as, starting with Salvus 2026.5, Salvus now requires Numpy version >=2.2 and SQLAlchemy > 2.0. Therefore, we strongly recommend creating a new Python environment for Salvus 2026.X and backing up the old one:

mamba create --name salvus_backup --clone salvus
mamba remove --name salvus --all

Once this is done, please follow the usual installation instructions to set up a new environment.

Required Python Code Changes

Salvus’ Python API remains compatible between Salvus 2025.1.x and Salvus 2026.5.0, but a couple of functions have been flagged for depreciation in a future release.

Releases

All Changes

Salvus 2026.10.0

SRF-File Slip Rate Source Fixes

Improved the handling of SRF (Standard Rupture Format) files when creating sources. Slip-rate series are now parsed as floats, subfaults slipping in both the u1 (along-rake) and u2 (in-plane, rake + 90 deg) directions are emitted as separate double-couple moment-tensor sources, and unsupported u3 (fault-normal / tensile) slip is skipped with a clear warning. Slip-rate series shorter than 10 samples are consistently excluded from the simulation, and the associated warnings now accurately reflect which sources are ignored.

ASDF Backend Submicrosecond Trim Fix

Fixed EventData.get_waveform_data_xarray’s ASDF backend silently dropping trailing samples when the sampling interval is sub-microsecond.

Improved Jupyter Mesh Widget

Updated and improved mesh widget in Jupyter notebooks.

  • Supports Mesh objects in addition to UnstructuredMesh objects.
  • Visualize continuous and multi-block meshes.
  • Visualize missing data.
  • Fully new design, layout, and organization.
  • Rulers and grids.
  • Resizeable canvas.
  • Full-screen support.
  • Toggle between perspective and orthographic cameras in 3-D.
  • Optional Studio lighting, shaded markers, and a theme-aware backdrop.
  • Configurable edge color.
  • Live color previews while adjusting color pickers.
  • Sphere markers with visibility, size, and color controls in a dedicated panel.
  • More intuitive and improved scale editor.

Thomsen Hexagonal Materials

Improved support for acoustic and elastic materials defined with Thomsen parameters.

Use salvus.material.reduce_to_plane_strain to convert a 3-D Thomsen material to 2-D in the x-z plane. The symmetry axis must lie in that plane. Use salvus.material.to_general_tensor to convert materials to tensor form with their orientation and attenuation included.

The acoustic solver supports only elliptical anisotropy (epsilon = delta). Acoustic Thomsen materials with epsilon != delta now produce a warning because the solver does not simulate the specified material. Use salvus.material.anelliptic.to_elliptical_thomsen to create an elliptical approximation, or use an elastic material with the elastic solver.

Elastic Triclinic Meshes

API CHANGE experimental

With experimental.use_new_materials, the solver reads all 21 stiffness components of a 3-D elastic triclinic TensorComponents mesh.

Breaking:

  • Such a mesh used to be read as hexagonal from its C11, C12, C13, C33 and C44 fields alone, so a non-hexagonal stiffness simulated a different medium without error.

Material Extensions as Fields

API CHANGE

Attenuation and orientation are now stored in the material’s extensions field. Adding either no longer changes the material’s type. Unsupported extensions now cause an error.

Content hashes change for materials with extensions and for models and mesh blocks that use them. Materials without extensions keep their existing hashes.

Attenuation can still be read from mesh blocks saved with earlier versions. Materials saved with orientation in the old format can no longer be loaded.

Reliably Close SQLite3 Databases

More reliably close SQLite3 databases across operating systems.

Owned Python MPI Communicators

Added explicit MPI communicator duplication, group creation, and freeing bindings, with Python context managers for scoped ownership. These allow embedded workflows to isolate communication from their MPI host.

Print MPI Executor Time Step Statistics

The MPI executors now log mean/min/max statistics of the time step and the number of time steps across all ranks after each set of forward or forward + adjoint simulations, mirroring the existing per-wave element count and mesh extent statistics.

MPI Python Bindings Release the GIL

The MPI Python bindings now release the GIL while blocking in MPI calls. This prevents deadlocks in multithreaded host applications embedding Python, where another thread could hold the GIL while a rank waits inside an MPI collective.

Reverse Time Migration Misfit

Add a built-in reverse_time_migration misfit function. Its adjoint source is the observed data, so the gradient computed with it is effectively a reverse time migration (RTM) image. To support this, misfit functions may now opt out of receiving synthetic data by not accepting a data_array_synthetic argument or by defaulting it to None.

SmoothieSEM Lateral Refinements

experimental

Bring back lateral refinements for SmoothieSEM meshes, which were previously discontinued after Salvus version 0.12.16. The experimental create_smoothiesem_mesh now accepts lateral_refinements, a list of SmoothiesemLateralRefinement regions defined by epicentral distance, azimuth and radius in the reference frame of the source, in each of which the number of lateral elements is tripled. Dictionaries from the previous SmoothieSEM interface can be converted with SmoothiesemLateralRefinement.from_legacy_dict(). Refinements are kept away from the central cylinder, and nested refinements after the first one currently need to span all azimuths.

Explicit Regularization Terms

Add explicit regularization terms to SalvusOpt in salvus.opt.regularization: ZeroOrderTikhonov (damping), FirstOrderTikhonov (smoothing), SecondOrderTikhonov (curvature penalty) and TotalVariation. Each computes a penalty and its gradient for a model, optionally relative to a reference model, with a weight that is either a scalar or another model holding point-wise values. The derivative based terms support UnstructuredModel and return gradients that are continuous across element boundaries. The terms are not yet wired into the inverse problem configuration.

Exodus Second-Order Elements

UnstructuredMesh.from_exodus() can now read second-order QUAD9, SHELL9 and HEX27 elements, e.g. as exported by Coreform Cubit. These are converted to Salvus meshes with a shape order of 2, retaining the curved element geometry. Correspondingly, UnstructuredMesh.write_exodus() now writes meshes with a shape order of 2 as QUAD9 or HEX27 elements.

Change Tensor Order Outer Radial Limit

change_tensor_order and refine_locally can now confine the spherical and cylindrical interpolation to a radial shell.

The radial blend between slerp and bi/trilinear interpolation used to be one sided: bi/trilinear below r0, tapering up to r1, and fully slerped for every radius above r1. That is the right behaviour for a global mesh, but for a curved feature embedded in an otherwise cartesian domain it bows the entire far field around the origin.

The new interpolation_kwargs keys r2_spherical / r3_spherical (and their _cylindrical counterparts) add the mirror image at the outer end, so slerp is applied in full only within [r1, r2] and tapers back to bi/trilinear interpolation over [r2, r3]. Setting r3 alone starts the taper at r1.

Both new radii default to infinity, which reproduces the previous behaviour exactly.

Wavefield Output to Xarray Speedup

sn.wavefield_output_to_xarray() is now much faster. Both the enclosing element search and the interpolation itself are performed by the same multi-threaded C++ routines that back sn.extract_model_to_regular_grid(), replacing a per-point Python loop over the element search and a set of hand-rolled tensor contractions. It also gained a keyword-only number_of_threads argument, which defaults to the smaller of the number of cores on the system and 120.

As a consequence the mode and verbose arguments no longer do anything: there is a single extraction path and no Python-level loop left to report progress on. They are still accepted, and passing either now raises a DeprecationWarning.

wavefield_output_enclosing_elements(), in salvus.toolbox.helpers.wavefield_output, now returns the reference coordinates of each point within its enclosing element rather than a dense array of interpolation coefficients, and flags points which are outside the output with an element index of -1. Tuples returned by it can still be passed straight back into sn.wavefield_output_to_xarray() via enclosing_elements, but code which inspected the second element of the tuple has to be adapted.

Time-Reduced Outputs in SalvusProject

Expose time-reduced outputs through the extra_output_configuration of p.simulations.launch(). In addition to the solver’s explicit reductions list, a shorthand mirroring the other output types is accepted:

p.simulations.launch(
    ...,
    extra_output_configuration={
        "time_reduced_data": {
            "fields": ["stress"],
            "reduction": "max",
            "criterion": "pressure",
        },
    },
)

This has the solver track the peak value of a field over the entire simulated time range per degree of freedom and write a single snapshot at the end of the run, which is dramatically cheaper than writing the full wavefield and reducing it afterwards.

The resulting file can be read back with the new WavefieldOutput.from_time_reduced_file() and inspected with list_time_reduced_datasets(), both in salvus.toolbox.helpers.wavefield_output, or via the new EventData.get_time_reduced_output(). The returned object plugs into the existing wavefield output tooling, e.g. sn.wavefield_output_to_xarray().

Also fixes the discovery of the XDMF files accompanying the outputs that are written once at the end of a run (time_reduced_data, final_time_data and frequency_domain), which previously raised a KeyError in EventData.get_remote_extra_output_filenames().

Optimize Time Step Refactoring

API CHANGE

Improved the performance and usability of mesh smoothing algorithms that optimize the time step of a particular mesh under the CFL criterion. These functions are available as salvus.mesh.algorithms.improve.optimize_time_step_globally and salvus.mesh.algorithms.improve.optimize_time_step_locally. These new functions supersede the previous salvus.mesh.optimize_dt.optimize_dt and salvus.mesh.optimize_dt.optimize_dt_locally functions, which are now deprecated.

from salvus.mesh.algorithms import improve

# Optimize all free nodes of the mesh.
mesh_smoothed = improve.optimize_time_step_globally(mesh)

# Or only the worst elements and a halo around them, which is much cheaper
# for large meshes.
mesh_smoothed = improve.optimize_time_step_locally(
    mesh, worst_element_count=100
)

The new functions additionally weight every element with its own wave speed, taken from the material fields attached to the mesh. The quantity being optimized is therefore the CFL time step itself - the smallest distance between two GLL points anywhere in the mesh over the local wave speed - rather than that distance alone, as the deprecated functions did. On a heterogeneous mesh this concentrates the effort on the elements that actually limit the time step, and a mesh without material fields is optimized on its geometry as before.

Note that these functions currently only support first-order meshes.

Remove Deprecated Time Step Computation Functions

API CHANGE

Removed the following previously deprecated functions:

  • salvus.mesh.algorithms.unstructured_mesh.metrics.estimate_time_step and the UnstructuredMesh.estimate_time_step method. Use UnstructuredMesh.compute_time_step instead, which correctly accounts for deformed higher-order elements and thus closely matches the time step SalvusCompute actually uses.
  • UnstructuredMesh.compute_resolved_frequency. Use UnstructuredMesh.estimate_resolved_frequency instead, which is the same function under a name that better reflects that it estimates the resolved frequency rather than computing it precisely.
  • UnstructuredMesh.compute_dt, a previous compatibility alias of estimate_time_step that is removed together with it. Use UnstructuredMesh.compute_time_step instead.

Fix for Database Path Names on Windows

Fix creating or migrating the job database failing with invalid interpolation syntax when its path contains %, either literally or through percent-encoding in the database URL, as happens on Windows with SQLAlchemy>=2.1.1.

Linear Algebra for Model Classes

Add a unified implementation of inner products and norms in SalvusOpt and integrate it into inversion workflows.

For models defined on unstructured meshes this alleviates the need to carry along the FemMassMatrix and Valence during an inversion. Those quantities are now computed on the fly instead allowing for a better separation of models and meshes.

Update PETSc and HDF5

Update dependencies to use PETSc 3.25.4 and HDF5 2.2.

Salvus 2026.8.0

GLL Surface Patch Interface Reinterpolation

Improved the algorithm for band-limited interface reinterpolation for high-order (>1) meshes.

When a layered mesh is built at model order greater than one (or locally refined), its interface side sets are re-snapped to the true interface geometry. Aliasing of the interface topography by surrounding elements could result in pinched / inverted elements with invalid Jacobians. To remedy this, the target interface is now evaluated through a standalone GllPatch that samples the interface on the side-set facet GLL nodes and reconstructs it through those facets’ Lagrange basis. Several performance improvements now make this viable for general meshes:

  • A new deduplication algorithm more aggressively deduplicates horizontal points, resulting in fewer queries to the high-order interpolation routines
  • Horizontal queries of a deep mesh with vertical-only deformation can now use only the 1st order element edges for the reference coordinate calculation and enclosing element search, while still interpolating through the full high-order facets

Together we expect these developments to result in more robust handling of meshes in the presence of aliased boundary topography, decreasing the occurrence of sporadic “invalid Jacobian” error messages.

Bugfix Spatial Gradients 2-D

Corrects the computation of spatial gradients on 2-D meshes in the case where the element geometry was irregular.

Flux No Abbreviated Options

Fix job array submissions to Flux sites. Recent Flux releases no longer accept abbreviated command line options, so all options are now spelled out in full.

Trace Consistency Hardening

Hardened the consistency checks around observed-vs-synthetic waveform traces so that mismatched data surfaces as an immediate, actionable error instead of silently corrupting or aborting a workflow late.

Improved Large Event Count Inversion

Speed up hashing and caching for inversion workflows. By making the internal bookkeeping more efficient, this should help with querying events, misfits or gradients in an inversion workflow.

The speedups are most notable for inversions with many events.

Fix Mesh Widget Side Set Plotting

Fixed a bug that was causing 3-D meshes to disappear in the mesh visualization widget when attempting to plot their side sets.

Laplacian and Centroidal Mesh Smoothing

Add functions for performing Laplacian and centroidal smoothing on meshes. These mesh smoothing routines are available under salvus.mesh.algorithms.improve and offer a computationally inexpensive way of improving the mesh quality for discretizations that contain strongly deformed elements.

Scaled Jacobian Mesh Metric

Added the scaled Jacobian as a mesh quality metric. This metric returns a value between -1.0 and 1.0 for each element in the mesh. In order for the mesh to be used in the solver, all elements must have a scaled Jacobian that is greater than 0.0.

Here’s an example of its usage:

import salvus.namespace as sn

m = sn.UnstructuredMesh(...)
scaled_jacobians = m.compute_mesh_quality("scaled_jacobian")

Fix Exodus Side Set Importing

Fixed a bug that was causing side sets to be incorrectly assigned for Exodus meshes when some of the side sets in the .e file were unnamed.

Spherical Interpolation Radial Scaling Fix

Spherical volume models provided as Xarray datasets that have geospatial_vertical_units of km are now reliably rescaled to base SI units during interpolation.

Compute Minimum Time Step across Meshes

Add a function to compute the minimum time step across multiple meshes. This is useful for ensuring that simulations are discretized on the same time axis. Here’s an example:

import salvus.namespace as sn
from salvus.mesh.algorithms.unstructured_mesh.metrics import (
    compute_minimum_time_step_across_meshes,
)

# A list of meshes for which to compute the minimum time step.
meshes = [
    sn.UnstructuredMesh(...),
    sn.UnstructuredMesh(...),
]

# Compute the minimum time step across the various meshes
time_step = compute_minimum_time_step_across_meshes(meshes=meshes)

Specify Wavefield Snapshot Sampling Interval

Add the ability to specify the number of wavefield snapshots to output for a surface or volume wavefield. For example, suppose that one would want to output 300 snapshots for a wavefield animation. The user can specify the approximate number of output wavefield snapshots using the number_of_snapshots argument:

p.simulations.launch(
    ...,
    extra_output_configuration={
        "volume_data": {
            "number_of_snapshots": 300,
            "fields": ["displacement"],
        },
    },
)

Src-Rec Widget Size Slider

Add a slider to mesh visualization widgets that allows for the size of sources and receivers to be modified.

Event Dependent Configuration in Task Chains

Allow event-dependent event configuration in task chains.

Time-Reduced Outputs

Add output.time_reduced_data — a new output group that computes per-DOF max/min reductions over the entire simulation time range and writes a single snapshot at the end of the run. Each entry names a field, a reduction, a required criterion (signed/abs, or a field-kind-specific functional such as vonmises, frobenius, l2, pressure, volumetric), and an optional record list (value/time/state). signed/abs on vector or tensor fields reduce every stored component independently (“componentwise”); all other criteria are scalar functionals defining a single extremal instant, optionally with the full field snapshotted at that instant (state). Works for both primary fields (displacement, velocity, phi, …) and derived fields (strain, stress, gradient-of-displacement, …) across coupled acoustic-elastic simulations. Results are written as multi-component HDF5 datasets (component order recorded as metadata) rather than per-component suffixed scalars. format (hdf5/hdf5-minimal/ hdf5-full) is required and follows the same convention as final_time_data: unless hdf5-minimal, an XDMF sidecar is written alongside the HDF5 file for direct ParaView consumption. GPU (CUDA) is not yet supported and will raise an error at setup.

Time Loop Receiver Output Performance

Significantly reduce the I/O cost of point (receiver) output during the time loop. The receivers HDF5 file is now kept open across periodic flushes instead of being re-opened and closed each time (closing forced a synchronous writeback of the whole file), and per-receiver interpolation weights are computed once instead of per flush. On receiver-dense simulations this removes orders of magnitude of write amplification.

Fix Rejected Trial Model L-BFGS Data

Fix an error that could have aborted an inversion when a trial model was rejected in any iteration but the first, reported as “Error during L-BFGS computation. Unexpected state of precomputed L-BFGS data.”.

Threaded Side Set Elevations Search

Determine the number of threads when searching the side set elevation based on the user-defined execution policy.

The spherical branch of get_side_set_elevations located points with a k-d tree whose queries were handed every available core, regardless of the parallelism the caller had asked for. It now uses the thread count from the execution policy it is given, as the rest of the routine already did.

Remove OR-Tools Dependency

Replace the dependency on ortools with built-in solutions.

The two integer optimization problems in the layered mesher that used it are now solved directly either via a closed-form solution of a shortest path problem or via dynamic programming. Both replacements are exact, and reproduce the previous results apart from a small number of cases in which several solutions are equally good and a different one of them may now be chosen.

Scalar ASDF Time Attributes

Write the starttime and sampling_rate attributes of ASDF receiver output as the scalar attributes the format requires.

They used to be written as one-dimensional attributes of length one. Recent versions of numpy refuse to convert those to a scalar, which made such files unreadable through pyasdf. Files written by earlier versions of Salvus remain readable with pyasdf>=0.8.3.

Attenuation in Distributed Meshes

Ensure that the linear solids get (re-)attached when interpolating the model on a mesh chunk of a distributed mesh.

This fixes a bug where the attenuation parameters were not properly attached during the mesh building and subsequently caused the model validation to fail.

Suppress Cython IPython Traceback

Suppress cython source message in IPython/Jupyter notebooks.

An exception raised when running Salvus in a notebook can result in a traceback that contains messages like: ‘Could not get source, probably due dynamically evaluated source code.’ (sic). This distracts from the actual error message and is not useful to the user. This change patches the IPython traceback formatter to suppress this message.

Fix Auto Bandwidth in Linear Solids

Improve the logic for the built-in computation of the bandwidth for the linear solid approximation. If the frequency is not specified by the user, the automated bandwidth computation is now considering the reference frequency of the Q factor model and the mesh frequency to ensure both are covered.

Previously, this might have caused an error in constructing the linear solid for non-monotonic bounds in cases where the reference frequency of the linear solids significantly varies from the frequencies resolved by the mesh.

Salvus 2026.5.0

Layered Model Plotly Visualization

Add interactive Plotly visualizations for realized LayeredModel instances. The two new functions produce 2-D cross-section figures for 1-D interface models and 3-D surface figures for 2-D interface models:

from salvus.mesh.layered_meshing.layered_model import plot, plot_interfaces

# Plot from a realized LayeredModel directly:
fig = plot(model)
fig.show()

# Or from a sequence of realized interfaces:
fig = plot_interfaces(model.interfaces)
fig.show()

Note: visualization of spherical models is not yet supported.

Class Serialization

Improve class and function serialization logic.

Layered Model Serialization

experimental

Add experimental de/serialization routines to meshing protocols, layered models, and materials.

import salvus.namespace as sn
from salvus.mesh.layered_meshing.serialization import (
    read_from_h5,
    write_to_h5,
)

lm = sn.layered_meshing.LayeredModel(
    [
        sn.material.from_params(rho=2000.0, vp=2000.0),
        sn.layered_meshing.interface.Hyperplane.at(
            sn.layered_meshing.interface.Depth(500.0)
        ),
        sn.material.from_params(rho=2500.0, vp=3000.0, vs=2200.0),
        sn.layered_meshing.interface.Hyperplane.at(
            sn.layered_meshing.interface.Depth(1000.0)
        ),
        sn.material.from_params(rho=3000.0, vp=4000.0, vs=3300.0),
    ]
)

write_to_h5(filename="layered_model.h5", model=lm)

lm_2 = read_from_h5(filename="layered_model.h5")

Chunked Meshing Format

experimental

Add a new experimental chunked representation of a mesh on disk.

This allows building a mesh in parallel and building meshes that are larger than the available memory.

import pathlib
import xarray as xr
import salvus.namespace as sn

from salvus.project.tools.task_chains.prebuilt_workflows.mesh_from_domain_distributed.distributed_mesh_building import (  # NOQA
    mesh_from_domain_distributed,
)

domain = sn.domain.dim3.BoxDomain.unit()

model = sn.layered_meshing.LayeredModel(
    [
        sn.material.from_params(
            rho=xr.DataArray([0.0, 1.0], [("x", [0.0, 1.0])]), vp=1.0
        ),
        sn.layered_meshing.interface.Curve(
            xr.DataArray(
                [-0.1, +0.1],
                [("x", [0.0, 1.0])],
                attrs={"reference_elevation": 0.8},
            )
        ),
        sn.material.from_params(
            rho=xr.DataArray([0.0, 1.0], [("x", [1.0, 0.0])]), vp=2.0
        ),
    ]
)
mesh_resolution = sn.MeshResolution(
    reference_frequency=25.0, elements_per_wavelength=1.1, model_order=4
)

chunked_mesh = mesh_from_domain_distributed(
    output_folder=pathlib.Path("chunked_mesh"),
    domain=domain,
    model=model,
    mesh_resolution=mesh_resolution,
    sites=None,
    min_number_of_chunks=16
)

print(chunked_mesh)
ChunkedMesh
  File size: 57.3 MB
  Folder: chunked_mesh
  Number of mesh chunks: 16
  Number of elements: 10976
  Model order: 4

An optional mesh_postprocessing_callback_function can be passed to mesh_from_domain_distributed to modify each chunk and the embedding mesh after meshing for custom workflows.

The chunked meshing uses shared memory to pass the embedding between multiple runners on a single machine.

Vars in Additional srun Vars

Allow using variables in the the additional_srun_arguments Slurm configuration. Available variables are {NODES}, {RANKS}, and {TASKS_PER_NODE}, which will be filled automatically.

Proper Type Stubs

Include type hints in the distributed wheel builds. This improves the type checking and usage experience of the Salvus Python library.

A good example is tab completion and docstring display in VSCode.

Degree of Freedom Stacking along Chords

Add support for the stacking of degrees of freedom (DOFs) along a chord of elements. Stacking in this context refers to re-indexing degrees of freedom within each element into tangent planes or lines. This functionality is supported by stack_along_chord method in the salvus.mesh.mesh.algorithms.dual module. This function returns two indexing arrays, which contain local and global re-indexing arrays respectively. See the function’s docstring for more information.

Enhanced Mesh Duality

Add support for computing dual graphs of quad and hex meshes as sparse adjacency matrices, along with new chord-analysis utilities. See salvus.mesh.algorithms.unstructured_mesh.dual for more details.

Chunked Meshing Smoothing

Distributed smoothing for chunked meshes using a halo region.

# Smoothing configuration.
sc = sn.ConstantSmoothing(
    smoothing_lengths_in_meters={"VP": (20, 20, 20), "RHO": (30, 30, 20)}
)
smoothed_chunked_mesh = smooth_chunked_mesh(
    output_folder=tmp_path / "smoothed_chunked_mesh",
    chunked_mesh=chunked_mesh,
    smoothing_config=sc,
    # Halo width around each chunk in meters.
    halo_width_in_meters=150.0,
    sites={"my_site": task_chain_site_config},
)

Use Multi Threading in Solver from Task Chains

Forward settings for multi-threading per rank to the solver in task chains.

When using a TaskChainSiteConfig each MPI rank will now use max_threads_per_worker / ranks_per_salvus_simulation threads.

Assuming a machine with 4 GPUs, the following configuration will run one parallel simulation on each GPU, each using one MPI rank and 10 threads.

tcsc = TaskChainSiteConfig(
    ...
    number_of_parallel_workers=4,
    ranks_per_salvus_simulation=1,
    max_threads_per_worker=10,
    ...
)

Serialize Mappings

Add the ability to serialize custom mapping classes into an InverseProblemConfiguration.

This allows users to define their own mapping classes to transform between physical and inversion spaces:

from salvus.opt.mappings import Mapping

class MyCustomMapping(Mapping):
    def __init__(self, *args, **kwargs):
        print("In init")
        super().__init__(*args, **kwargs)

p += sn.InverseProblemConfiguration(
   mapping=MyCustomMapping(
       scaling="absolute",
       inversion_parameters=["VP", "RHO"]
    ),
    ...
)

Experimental Support for Flux

experimental

Add a new executor to run Salvus on the Flux framework: https://flux-framework.readthedocs.io/en/latest/.

Force Interactive Authentication

If an interactive SSH login is requested, Salvus will now ensure it happens, even if the initial connection attempt succeeded.

Add Exodus Writer

Implement mesh writer for exporting Salvus meshes in the Exodus file format (.e).

Plot Attenuation Model

New salvus.material.attenuation.plot_q_model() function to visualize attenuation models.

Speedup Find Surface

Speed up the find_surface algorithm in salvus.mesh.algorithms.unstructured_mesh.side_sets by using a new algorithm based on a mesh’s facet dual graph.

Handling Corrupted Gradient Files

Add a mitigation for corrupted gradient files in the HDF5 output.

The new measure will detect corrupted gradient files and move them to a quarantine folder inside the project attachments. The failing events are resubmitted during the inversion workflow by default, so the inversion can continue without interruption.

Only if the same event/model combination fails again, the user is required to manually investigate or remove the files from quarantine.

Improve Project Dir Detection

Improve the detection logic of a project directory. It will now raise a useful error message when passing the wrong path as a project directory instead of suggesting to migrate to another project revision.

Enable Empty Control Groups

Enable empty control groups in an inversion when using a custom event batch selection. Note that this will not enfore a monotonically decreasing misfit function, and it will neither modify the trust region radius after the first iteration, because an actual reduction is not available in this case.

Example:

import typing
import salvus.namespace as sn
def my_custom_event_selection(
    inverse_problem_configuration: sn.InverseProblemConfiguration,
    current_iteration_id: int,
) -> typing.Sequence[str] | dict[str, typing.Sequence[str]]:

    # Always use all events, but disable the control group.
    return {
        "events": inverse_problem_configuration.events,
        "control_group": []
    }


p.add_to_project(
    sn.InverseProblemConfiguration(
        ...,
        event_batch_selection=my_custom_event_selection,
    )
)

Run Mesh QC in Project

Add the ability to run an automated quality control on UnstructuredMesh objects when they are added to a project via an UnstructuredMeshSimulationConfiguration. This should allow users to catch potential issues with the mesh early on before running potentially expensive simulations that might fail at a later stage. The same checks are now performed when a mesh is first created using the internal Salvus mesher using the function mesh_from_domain(). Use the skip_validation=False flag to enable the mesh QC step.

Receiver Data Rotation on Output

Enables using the rotation_on_output argument on normal Point2D and Point3D objects.

Add Memory Estimation Tool

Added an experimental memory estimation tool that can be used to estimate the required memory usage of a simulation before running it.

Speed Up Time Step Computation

Speed up the time step computation in both the solver and the mesher by binding the minimum distance computation to a C++ implementation.

Timing for Adjoint Runs

Add more detailed timing statistics to adjoint runs.

Timing as JSON

Add JSON timing output to a simulation’s meta.json file for simplified downstream reporting.

Parallel Jacobian Computation

Add a new experimental group "num_threads_per_rank" to the SalvusCompute, which controls the maximum number of threads that may be spawned from each MPI rank. If set, threading will be used to parallelize the computation of the Jacobian during simulation startup, which can result in significant speedups.

Better Startup Timing

Add experimental support for more detailed timing of simulations in SalvusCompute.

Hessian on the Fly

Reduce the memory consumption of the L-BFGS scheme and reduce the required disk space. Only models and gradients that are needed to compute the approximate Hessian are retained in memory. Model and gradient differences are now computed on the fly.