Salvus 2026.10.0
This is a minor release that brings a broad set of new features, performance improvements, and quality-of-life enhancements across the Salvus ecosystem.
The highlight of this release is a completely redesigned mesh widget for
Jupyter notebooks. It now supports Salvus’ native Mesh objects in addition
to UnstructuredMesh, and can visualize continuous and multi-block meshes as
well as missing data. The new layout adds rulers and grids, a resizeable
canvas with full-screen support, perspective and orthographic cameras in 3-D,
optional studio lighting, and a more intuitive scale editor.
SalvusProject now exposes time-reduced outputs through the
extra_output_configuration of p.simulations.launch(). The solver can track
quantities such as the peak pressure over the entire simulation and write a
single snapshot at the end of the run, which is dramatically cheaper than
storing the full wavefield and reducing it afterwards. The results can be
retrieved with EventData.get_time_reduced_output() and plug directly into the
existing wavefield output tooling. On that note, sn.wavefield_output_to_xarray()
is now much faster thanks to multi-threaded C++ interpolation.
On the meshing side, the new optimize_time_step_globally and
optimize_time_step_locally functions in salvus.mesh.algorithms.improve
optimize the CFL time step itself, taking the local wave speed into account.
Exodus files with second-order elements, e.g. from Coreform Cubit, can now be
read and written, and lateral refinements are back for SmoothieSEM meshes.
For inversions, SalvusOpt gains a built-in reverse_time_migration misfit,
explicit Tikhonov and total variation regularization terms, and a unified
implementation of inner products and norms that no longer requires carrying
along mass matrices during an inversion.
Please note that previously deprecated time step estimation functions have
been removed in favor of UnstructuredMesh.compute_time_step, and that the
canonical hash of materials with attenuation or orientation extensions has
changed.
For the full list of changes, please refer to the detailed changelog below.
Changes
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
Meshobjects in addition toUnstructuredMeshobjects. - 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.
Material Extensions as Fields
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.
Fixed Broken Links
Fixed some broken links in the documentation.
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.
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
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
Removed the following previously deprecated functions:
salvus.mesh.algorithms.unstructured_mesh.metrics.estimate_time_stepand theUnstructuredMesh.estimate_time_stepmethod. UseUnstructuredMesh.compute_time_stepinstead, which correctly accounts for deformed higher-order elements and thus closely matches the time step SalvusCompute actually uses.UnstructuredMesh.compute_resolved_frequency. UseUnstructuredMesh.estimate_resolved_frequencyinstead, 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 ofestimate_time_stepthat is removed together with it. UseUnstructuredMesh.compute_time_stepinstead.
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.
Changes to Experimental Features
Elastic Triclinic Meshes
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,C33andC44fields alone, so a non-hexagonal stiffness simulated a different medium without error.
SmoothieSEM Lateral Refinements
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.