Inversionson

There exists an open-access paper about Inversionson. If you use Inversionson, please consider citing it:

@misc{thrastarson2021inversionson,
  title={Inversionson: Fully Automated Seismic Waveform Inversions},
  author={Thrastarson, Solvi and van Herwaarden, Dirk-Philip and Fichtner, Andreas},
  year={2021},
  publisher={EarthArXiv},
  doi = {10.31223/X5F31V},
  url = {https://doi.org/10.31223/X5F31V}
}

Inversionson is a workflow manager which automatically performs a Full-waveform inversion(FWI) of seismic data. It has built in support for various types of FWI workflows:

A standard workflow like for example in Krischer et al, 2018
The dynamic mini-batch workflow described by van Herwaarden et al, 2020
The wavefield-adapted mesh workflow described by Thrastarson et al, 2020
A combination of dynamic mini-batches and wavefield adapted meshes.

It has built in support for using a validation dataset, which is a dataset that is not explicitly a part of the inversion but is reserved for monitoring the inversion procedure with an independent dataset. The validation dataset can be used to tune regularization for example. There is also support for reserving a test dataset to compute misfit for at the end of the inversion process.

The inversion will be automatically documented in an easily readable MarkDown file. By setting some environment variables regarding Twilio, Inversionson can send you a WhatsApp message after each iteration.

Central Libraries

Inversionson is not a standalone package but rather a wrapper around a few key FWI software. It is thus important to have these software installed and available if one is interested in using Inversionson. The main, non-standard software packaged that Inversionson requires are LASIF, MultiMesh and Salvus. The recommended way of installing Inversionson is to follow the installation instructions of LASIF, cloning the MultiMesh repository and installing that one, do the same thing with Inversionson, and finally install Salvus into the same environment.

Usage

Using Inversionson may seem a bit complicated at first, but once you get it working, it tends to run pretty smoothly. There are plans to make initializing an Inversionson project a much smoother process but that has not been done yet. The following is a description of how one can start an automatic FWI, using Inversionson.

A process which should get your project going:

Create the directory where you want to host your project.
Use LASIF to initialize a LASIF project or copy an existing project in here.
- Finish setting up the LASIF project (define domain, download data, define frequency range of synthetics)
Create a directory called SALVUS_OPT inside the Inversionson project directory
- This directory is where the L-BFGS optimization routine will be carried out.
- Move into this directory
Inside the SALVUS_OPT directory you need to run this code:
```
<Path to your Salvus binary> invert -x $PWD
```
where <Path to your Salvus binary> is the path to the Salvus core binary (typically ~/Salvus/bin/salvus), not the salvus command available in PATH which is typically SalvusFlow. If you do
```
~/Salvus/bin/salvus --help
```
you should get
```
...
Subcommands:
compute                     Run a simulation
invert                      Solve an inverse problem
```
Salvus opt should now have created some files. The most important for now is inversion.toml which you need to edit a bit:
- You need to fill in some fields there, like initial model, parameters to invert for and whether you want to use batches of data or full gradients.
- It's hard to assist with this file as it really depends on what you want to do but feel free to contact me if you are having troubles.
- An important aspect is that there are commented fields which you need to uncomment when using the mini-batch method. You need to give information on control group ratio and initial batch size and then you need to give the name of one of the events in your project at the bottom of the file.
- Make sure to check the path to the model file (the initial-model key).
Now create a file called run_salvus_opt.sh which has only one line in it:
```
<Path to your Salvus binary> invert -i ./inversion.toml
```
Now run
```
sh run_salvus_opt.sh
```

Now go back to the folder of the Inversionson project and run:

python <Path to inversionson code>/inversionson/create_dummy_info_file.py

Fill in the relevant fields in the inversion_info.toml file properly. The file contains comments to explain the fields but some of them will be further explained here.
- inversion_mode: Can be either "mini-batch" (dynamic mini-batches) or "mono-batch" (full gradients)
- meshes: Can be either "multi-mesh" (wavefield adapted meshes) or "mono-mesh" (same mesh for every simulation, defined by LASIF domain file)
- interpolation_mode: If you use "multi-mesh" this makes your interpolations happen either "local" or "remote". "remote" is the faster option.
- inversion_parameters: Parameters to invert for. Make sure these are the same ones as in the inversion.toml file in the SALVUS_OPT directory.
- modelling_parameters: The parameters on the meshes you use for simulations.
- random_event_fraction: Only relevant for "mini-batch" mode. Describes how many of the events selected in each batch are random, vs how many are selected based on spatial coverage.
- Meshing.ocean_loading.use: Make True if you have ocean loading on your mesh. If you are using multi-mesh, you also need to supply a file and a parameter name to use.
- min_ctrl_group_size: The minimum number of events used in control group, again only relevant for "mini-batch" mode.
- max_angular_change: Used to decide how many events make it to the control group for the coming iteration in "mini-batch" mode.
- dropout_probability: A form of regularization. Events in control group can be randomly dropped out with this probability so they don't get stuck there.
- initial_batch_size: Make sure it's the same as in inversion.toml in "mini-batch" mode.
- cut_source_region_from_gradient_in_km: Gradients become unphysical next to the source and it can be good to cut the region out.
- cut_receiver_region_from_gradient_in_km: The same except receivers, and not nearly as bad of an unphysical effect. This is currently quite slow and I would recommend just putting 0.0 here.
- clip_gradient: You can clip gradient at some percentile so that the highest/lowest values are removed. 1.0 doesn't clip at all.
- absorbing_boundaries: This is only a True/False flag, the actual absorbing boundaries are configured in the lasif_config.toml
- elements_per_azimuthal_quarter: Only relevant for "multi-mesh". Decides how many elements are used to sample the azimuthal dimension. See paper.
- smoothing_mode: isotropic or anisotropic. It's always model dependent and can be either direction dependent or not.
- smoothing_lengths: How many wavelengths to smooth. If anisotropic the three values are: radial, lat, lon. For isotropic, only input one value.
- iterations_between_validation_checks: When using a validation dataset, this decides with how many iterations are between each validation check. The models between checks are averaged. 0 means no check.
- validation_dataset: Just a list of events in your LASIF project that you want to reserve for validation checks and will not be used in the inversion. Input event names.
- test_dataset: Same principle as with the validation_dataset
- HPC.wave_propagation: Settings regarding wavefield simulations. Inversionson asks for double that walltime in adjoint runs as they are more expensive
- HPC.diffusion_equation: Settings regarding the smoothing computations.
- HPC.interpolation: Settings regarding remote interpolations
As the file is configured you should be able to start running Inversionson.
- I would recommend running Inversionson with tmux as it keeps your shell running although you loose a connection with your computer or accidentally close your terminal window.
Run Inversionson with this command:
```
python -m inversionson.autoinverter
```

For any questions feel free to contact soelvi.thrastarson@erdw.ethz.ch

chenzbao/Inversionson

Inversionson

Central Libraries

Usage