SurfATT v1.0: Reproducible code for "Topography-Incorporated Adjoint-State Surface Wave Traveltime Tomography for Azimuthally Anisotropic Media"

# SurfATT [](https://github.com/topics/fortran) This is an innovative package for **Surf**ace wave **A**djoint **T**ravel-time **T**omography driven by modern fortran with highlights: - Inversion for **isotropic** or **azimuthal anisotropic** media (Hao et al., 2026, in preparation) - Calculation of surface wave travel time based on **Eikonal equation** with fast sweeping method ([Tong, 2021a](https://doi.org/10.1029/2021JB021818)) - Computation of isotropic and anisotropic sensitivity kernels through **adjoint method** ([Tong, 2021b](https://doi.org/10.1029/2021JB022365)) - **Multi-grid model parametrization** utilization in optimization ([Tong et al., 2019](https://doi.org/10.1093/gji/ggz151)) - Consideration of **surface topography** ([Hao et al., 2024a](https://doi.org/10.1029/2023JB027454)) ## Installation ### Dependencies - git - Fortran (intel fortran or gfortran>=11) - hdf5 (serial version) - C++ - CMake (3.8 or higher) - MPI (3.0 or higher) ### Install dependencies #### On local computer - For Ununtu/Debian users ``` sudo apt install build-essential gfortran cmake libopenmpi-dev openmpi-bin libhdf5-dev ``` - For Centos/Fedora users ``` sudo dnf install gcc gcc-gfortran gcc-c++ cmake openmpi-devel hdf5-devel ``` - For MacOS users ``` brew install gcc cmake open-mpi hdf5 ``` - Using Conda Installation through Conda is recommended and has been tested on both Ubuntu and macOS. ``` conda create -n surfatt -c conda-forge openmpi cxx-compiler fortran-compiler cmake hdf5 yaml-cpp conda activate surfatt ``` If a compilation error related to the h5fortran library occurs, it may be due to an incompatibility with the hdf5 package installed via the conda-forge channel. In such cases, try to remove the hdf5 package from the Conda environment and utilize the hdf5 library integrated within h5fortran. #### On HPC Installation through Conda is recommended ``` module load miniforge3 conda create -n surfatt -c conda-forge openmpi cxx-compiler fortran-compiler cmake hdf5 yaml-cpp conda activate surfatt ``` ## Download and Compile SurfATT ### Clone the source codes ``` git clone --recursive https://github.com/MIGG-NTU/SurfATT ``` `--recursive` is required in this command, because dependence of `yaml-cpp` will be download automatically. ### Compile source codes with cmake ``` mkdir build && cd build cmake .. && make -j4 ``` For MacOS users or if you have manually installed compilers, you can specify path to compile by add following options before cmake: ``` CC=gcc-12 CXX=g++-12 FC=gfortran-12 MPIFC=mpif90 cmake .. make -j4 ``` For users who opt for a manual installation of `hdf5`, the local `hdf5` directory should be specified before running `cmake`. ``` CC=gcc CXX=g++ FC=gfortran MPIFC=mpif90 HDF5_ROOT=$(pwd)/../external_libs/local_hdf5 cmake .. make -j4 ``` ## How to use SurfATT The executable file `bin/surfatt_tomo` for inverting surface dispersion data for S-wave velocity can be run with `mpirun` as: ``` mpirun -np 4 bin/surfatt_tomo -i input_params.yml ``` ### A quick example A case named `test/00_checkerboard_iso` presents an example of inversion for 2x3x2 checkers using ambient noise surface wave data from 25 stations. execute run_this_example.sh to run this example under 5 processors.