Updating Guide from Salvus 0.12.x to Salvus 2024.1.x

Users Who Should not Update (yet)

Salvus 2024.1.0 contains major improvements and changes in all areas of Salvus. We took great care to maintain backwards compatibility and most users should be able to safely update. Nonetheless, a few users should be careful when updating:

• Meshing functionality for SmoothieSEM and simulating gravity has been temporarily disabled due to changes in our underlying meshing routines but we plan to enable it again before too long. Until that point, please keep using Salvus 0.12.x.
• The chunked meshing interface has been removed. This has always been a bit tricky to use and we might bring it back with a different interface in the future.
• Users with big, ongoing inversions and an active SalvusProject. While we believe upgrading these should not result in any problems, things can always break at scale so we advise some caution. Please feel free to reach out to our support team to assist with this.

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 2024.1.0, Salvus now requires Python 3.11. We recommend to create a new conda environment for Salvus 2024.1.0, while backing up the old one:

Copy
conda create --name salvus_backup --clone salvus
conda remove --name salvus --all

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

Required Python Code Changes

By and large, Salvus 2024.1.0 is fully compatible with projects and scripts created with older versions of Salvus. However, there are a few important changes to note:

• A new module salvus.material has been added, which for now only contains utilities for handling attenuation. In the future more functionality to handle material properties will be added or moved to here.

• Dealing with attenuation has been streamlined. For defining a standard linear solids model (SLS) using default arguments, the recommended way is to specify the LinearSolids as part of the ModelConfiguration. The former class LinearSolid in salvus.mesh has been removed, but it is still possible to compute a tailored least-squares fit to the Q-factor model using the functionality in salvus.material.attenuation.

• The meshing backend has undergone a major overhaul. While we strive for compatibility of the stable API, some rarely used advanced features have been moved or depreacted. When in doubt if this would affect you, please have a look at the current tutorials or reach out for support.

• We started versioning the project files and directory structure on disk to facilitate migration steps in the future. The first time to try to load a project created with an older version of Salvus, you will see a message like this

Just to make sure you are not accidentially submitting the wrong answer, it will ask you again to confirm.

Required changes for expert use of the UnstructuredMesh class

The core fields of the UnstructuredMesh class can no longer be directly assigned. Most workflows should likely create new mesh objects instead. Please see the following collection of migration examples:

Copy
mesh = sn.UnstructuredMesh(...)

# No longer works:
mesh.points = points
mesh.connectivity = connectivity
# Instead use:
mesh = sn.UnstructuredMesh(points=points, connectivity=connectivity, ...)

# No longer works:
mesh.points *= 1.1
# Instead use:
mesh.points[:] *= 1.1

# No longer works:
mesh.elemental_fields = {}
mesh.side_sets = {}
# Instead use:
mesh.elemental_fields.clear()
mesh.side_sets.clear()
# Or create a new mesh object:
mesh = sn.UnstructuredMesh(..., elemental_fields={}, side_sets={})