Package: maswavespy
MASWavesPyMASWavesPy (maswavespy) is a Python package for processing and inverting MASW data, developed at the Faculty of Civil and Environmental Engineering, University of Iceland.Table of contentsAbout MASWavesPyReferencing MASWavesPyLicenseAcknowledgementsInstallationGeneral installation using pipRecommendationsRequirementsQuick Start Guide(for Windows)Setup and create a virtual environment (recommended)Install MASWavesPyTest MASWavesPyDeactivate the virtual environmentKnown IssuesAbout MASWavesPyThemaswavespypackage consists of four primary modules:wavefield,dispersion,combinationandinversion, and two supplementary modules:datasetandselect_dc.Thewavefieldmodule provides methods to import recorded shot gathers asRecordMCobjects. The phase shift method (1) is used to transform each shot gather into the frequency-phase velocity domain. Thedatasetmodule can be used to import a set of shot gathers in the form of aDatasetobject through a .csv file.Thedispersionmodule, along with the supplementaryselect_dcmodule, provides methods for visualization of the phase velocity spectrum and dispersion curve (DC) identification using a GUI (Graphical User Interface). AnElementDCobject stores the frequency-phase velocity domain representation of a givenRecordMCand the corresponding DC (referred to as an elementary DC).Thecombinationmodule provides methods to combine elementary DCs obtained from multiple shot gathers into a composite DC (2) (aCombineDCsobject) and to assess and view the spread in the dispersion data, either as a function of frequency or wavelength. ADatasetobject can contain multiple pairs ofRecordMCandElementDCobjects (one pair for each shot gather) and provides routines for initializing aCombineDCsfor the set of records or a particular subset of records.Theinversionmodule 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 anInvertDCobject 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 MASWavesPyReferencing 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 inGeotechnical Testing Journal(in press).LicenseThis 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, seehttps://www.gnu.org/licenses/.AcknowledgementsThis 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. InSEG 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 inGeotechnical Testing Journal(in press).InstallationAQuick Start Guidedescribing the recommended workflow for Windows users is provided below.General installation using pipThe MASWavesPy package is installed using pip.pip install maswavespyWheels for Windows, Linux and Mac distributions can also be downloaded fromPyPI.RecommendationsWe recommend to install the MASWavesPy package into an isolated Python environment. If using Anaconda, create a virtual environment usingconda create. Alternatively,virtualenvcan be used to install this package into an isolated Python environment.Virtualenvwrapperis 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 theAnaconda distribution. Hence Anaconda and the Spyder IDE (included with Anaconda) are recommended for running the Quick Start Guide.RequirementsTo build the package on Windows you need Microsoft C++ Build Tools. You can download an installer from Microsoft at thislink. 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 usesCythonfor some of its calculations.Quick Start GuideApplies for Windows Users.Setup and create a virtual environment, recommended(If required) Download and installAnaconda.(If required) InstallMicrosoft 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 thatcondais installed in your path by typingconda -VNavigate to theanaconda3directory.Make sure that the newest version ofcondais installed. Update conda by typingconda update conda.Navigate back to the previous folder.Get your python version (3.x.yy) by typingpython -V.Set up a virtual environment (here namedtestenv) by typingconda 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 typingconda activate testenv. To see a list of available environments, typeconda info --envs.InstallSpyderinto the virtual environment by typingconda install spyder.Install MASWavesPyThe package is installed usingpip.(If required) Start Anaconda Prompt.Typepip install maswavespyto 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 MASWavesPyDownload the contents of theexamplesdirectory (i.e., the four example.pyfiles and the directoryData) to a folder destination of your choice.The four example files (with.pyendings) test different parts/commands of the MASWavesPy package.The example files use the data from theexamples/Datadirectory as inputs.Launch theSpyder (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.pyfiles and theDatadirectory as the working directory inSpyder (testenv).The working directory is set in the top right corner of the Spyder IDE window.Open and runMASWavesPy_Dispersion_test1.pyto test the basic methods of thewavefieldanddispersionmodules using a single data file.Please note that all four example files are written to be run one cell at a time using the keyboard shortcut (Ctrl+Enter), Run > Run cell, or the Run cell button in the toolbar.Information on specific methods/commands is provided in each example file.Open and runMASWavesPy_Dispersion_test2.pyto test the methods of thewavefieldanddispersionmodules using aDatasetobject.Open and runMASWavesPy_Combination_test.pyto test thecombinationmodule.Open and runMASWavesPy_Inversion_test.pyto test theinversionmodule.Deactivate the virtual environmentApplies if a virtual environment has been created.(If required) Close the Spyder IDE.(If required) Start Anaconda Prompt.Close the virtual environmenttestenvby typingconda deactivate.If required, the virtual environmenttestenvcan be deleted with the following commandconda remove --name testenv --all.Known IssuesMatplotlib should use TkAgg on MacMaswavesPy depends on matplotlib. If you are on mac you need to ensure matplotlib usesTkAgg. Below is a workaround that is used in our examples.if sys_pf == 'darwin':
    import matplotlib
    matplotlib.use("TkAgg")Tkinter not found on MacOn mac you might run intoModuleNotFoundError: No module named '_tkinter'error, even after successfully installingmaswavespythat hasTkinteras one of its listed dependencies. This might be because your python3 installation did not have Tkinter correctly set up. Below is an example of how it can be installed with brew.brew install python-tkblosc2~=2.0.0 not installedWhen installingmaswavespyinto the Anaconda environment, you might encounter the following error, even thoughmaswavespyis successfully installed.ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
tables 3.8.0 requires blosc2~=2.0.0, which is not installed.Themaswavespypackage does not requireblosc2 2.0.0. Therefore, this error message can be ignored.The error can be prevented by installingCython(required for installingblosc2 2.0.0) andblosc2 2.0.0prior to installingmaswavespy. Below is an example of how these two packages can be installedconda install -c conda-forge cython
pip install blosc2==2.0.0