MASWavesPy

MASWavesPy (maswavespy) is a Python package for processing and inverting MASW data, developed at the Faculty of Civil and Environmental Engineering, University of Iceland.

About MASWavesPy
Installation
Quick Start Guide (for Windows)
Known Issues

About MASWavesPy

The maswavespy package consists of four primary modules: wavefield, dispersion, combination and inversion, and two supplementary modules: dataset and select_dc.

The wavefield module provides methods to import recorded shot gathers as RecordMC objects. The phase shift method (1) is used to transform each shot gather into the frequency-phase velocity domain. The dataset module can be used to import a set of shot gathers in the form of a Dataset object through a .csv file.

The dispersion module, along with the supplementary select_dc module, provides methods for visualization of the phase velocity spectrum and dispersion curve (DC) identification using a GUI (Graphical User Interface). An ElementDC object stores the frequency-phase velocity domain representation of a given RecordMC and the corresponding DC (referred to as an elementary DC).

The combination module provides methods to combine elementary DCs obtained from multiple shot gathers into a composite DC (2) (a CombineDCs object) and to assess and view the spread in the dispersion data, either as a function of frequency or wavelength. A Dataset object can contain multiple pairs of RecordMC and ElementDC objects (one pair for each shot gather) and provides routines for initializing a CombineDCs for the set of records or a particular subset of records.

The inversion module provides methods to evaluate the shear wave velocity profile of the tested site. The inversion methods, along with routines for post-processing of the inversion results, are defined on an InvertDC object that is initialized using an experimental DC. The fast delta matrix algorithm (3) is used for forward computations and a Monte-Carlo global search algorithm (4) for searching the solution space for the optimal set of model parameters.

A more comprehensive description is provided in (5).

Referencing MASWavesPy

Referencing the MASWavesPy package and a paper related to its development is highly appreciated.

Olafsdottir, E.A., Bessason, B., Erlingsson, S., Kaynia, A.M. (2024). A Tool for Processing and Inversion of MASW Data and a Study of Inter-Session Variability of MASW. Accepted for publication in Geotechnical Testing Journal (in press).

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Acknowledgements

This work was supported by the Icelandic Research Fund [grant numbers 206793-052 and 218149-051], the University of Iceland Research Fund, the Icelandic Road and Coastal Administration and the Energy Research Fund of the National Power Company of Iceland.

(1) Park, C.B., Miller, R.D., Xia, J. (1998). Imaging dispersion curves of surface waves on multi-channel record. In SEG Technical Program Expanded Abstracts 1998, New Orleans, Louisiana, pp. 1377–1380. https://doi.org/10.1190/1.1820161

(2) Olafsdottir, E.A., Bessason, B., Erlingsson, S. (2018a). Combination of dispersion curves from MASW measurements. Soil Dynamics and Earthquake Engineering, 113, pp. 473–487. https://doi.org/10.1016/j.soildyn.2018.05.025

(3) Buchen, P.W., Ben-Hador, R. (1996). Free-mode surface-wave computations. Geophysical Journal International, 124(3), pp. 869–887. https://doi.org/10.1111/j.1365-246X.1996.tb05642.x

(4) Olafsdottir, E.A., Erlingsson, S., Bessason, B. (2020). Open-Source MASW Inversion Tool Aimed at Shear Wave Velocity Profiling for Soil Site Explorations, Geosciences, 10(8), 322. https://doi.org/10.3390/geosciences10080322

(5) Olafsdottir, E.A., Bessason, B., Erlingsson, S., Kaynia, A.M. (2024). A Tool for Processing and Inversion of MASW Data and a Study of Inter-Session Variability of MASW. Accepted for publication in Geotechnical Testing Journal (in press).

Installation

A Quick Start Guide describing the recommended workflow for Windows users is provided below.

General installation using pip

The MASWavesPy package is installed using pip.

pip install maswavespy

Wheels for Windows, Linux and Mac distributions can also be downloaded from PyPI.

Recommendations

We recommend to install the MASWavesPy package into an isolated Python environment. If using Anaconda, create a virtual environment using conda create. Alternatively, virtualenv can be used to install this package into an isolated Python environment. Virtualenvwrapper is a tool to simplify the creation and management of local virtualenvs.

The use of a Python IDE (Integrated Development Environment) is strongly recommended for using MASWavesPy (as opposed to running commands in the Windows terminal/cmd environment).

MASWavesPy is developed using the Anaconda distribution. Hence Anaconda and the Spyder IDE (included with Anaconda) are recommended for running the Quick Start Guide.

Requirements

To build the package on Windows you need Microsoft C++ Build Tools. You can download an installer from Microsoft at this link. Otherwise you will see an error:

error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/

For more information you can view this Stackoverflow [answer](error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/)

This is required because the package uses Cython for some of its calculations.

Quick Start Guide

Applies for Windows Users.

Setup and create a virtual environment, recommended

(If required) Download and install Anaconda.
(If required) Install Microsoft C++ Build Tools. The Microsoft C++ Build Tools are required for building the package on Windows.
(Recommended) Create a virtual environment to install the package into an isolated Python environment. A brief guide is provided below.
- Start Anaconda Prompt from the Start menu.
- Verify that conda is installed in your path by typing conda -V
- Navigate to the anaconda3 directory.
- Make sure that the newest version of conda is installed. Update conda by typing conda update conda.
- Navigate back to the previous folder.
- Get your python version (3.x.yy) by typing python -V.
- Set up a virtual environment (here named testenv) by typing conda create --name testenv python=3.x (where 3.x is replaced by the python version that you have/want to use).
- Activate the virtual environment by typing conda activate testenv. To see a list of available environments, type conda info --envs.
- Install Spyder into the virtual environment by typing conda install spyder.

Install MASWavesPy

The package is installed using pip.

(If required) Start Anaconda Prompt.
Type pip install maswavespy to install the package.
Check if the package has been successfully installed by inspecting the last lines that are displayed in the Anaconda Prompt console.

Test MASWavesPy

Download the contents of the examples directory (i.e., the four example .py files and the directory Data) to a folder destination of your choice.
- The four example files (with .py endings) test different parts/commands of the MASWavesPy package.
- The example files use the data from the examples/Data directory as inputs.
Launch the Spyder (testenv) app [i.e., Spyder (name of your virtual environment)] from the Start menu.
- Spyder (testenv) is found in the folder Anaconda3 in the Start menu (for the latest versions of Anaconda).
Set the directory that contains the example .py files and the Data directory as the working directory in Spyder (testenv).
- The working directory is set in

Maswavespy

Install / Use

README