Release v2.0.0

Highlights

SurfATT v2.0.0 is the first release in the 2.x series and a major redesign of the package. The application and most numerical components have been reimplemented in modern C++, while selected established Fortran routines remain wrapped behind C++ interfaces. The new codebase preserves the adjoint-state, topography-aware, low-memory, and MPI-parallel workflow from v1 while extending the supported surface-wave physics and inversion workflow.

The main additions are:

• azimuthal-anisotropy inversion from Rayleigh-wave phase-velocity travel times;
• radial-anisotropy inversion from joint Rayleigh- and Love-wave phase-velocity travel times;
• independent or joint phase- and group-velocity inversion for isotropic Rayleigh or Love waves;
• spherical-coordinate PDE smoothing for model regularization;
• L-BFGS optimization with a Wolfe-condition line search;
• a modular CMake build, typed YAML configuration, structured logging, and a broader automated test suite; and
• new HDF5/XDMF outputs and checkerboard utilities for isotropic and anisotropic models.

New inversion capabilities

Isotropic, azimuthal, and radial anisotropy

The model_para_type parameter now selects one of three model parameterizations:

For azimuthal anisotropy, SurfATT inverts the isotropic S-wave velocity together with the cosine and sine anisotropy components (gc and gs). The HDF5 model writer also exports anisotropy magnitude (g0) and fast-axis direction (theta) for visualization.

For radial anisotropy, SurfATT jointly processes Rayleigh and Love waves and updates vertical and horizontal S-wave velocities. Model files contain vsv, vsh, the RMS S-wave velocity Vs, and the radial-anisotropy ratio zeta. The checkerboard forward tool accepts -r for radial-anisotropy tests and -a for azimuthal-anisotropy tests. Radial-anisotropy support and its worked example were completed on the v2 main branch in #19 .

Unified wave and velocity data configuration

Rayleigh/Love and phase/group datasets are configured independently:

data:
  src_rec_file_rl_ph: rayleigh_phase.csv
  src_rec_file_rl_gr: rayleigh_group.csv
  src_rec_file_lv_ph: love_phase.csv
  src_rec_file_lv_gr: love_group.csv
  wave_type: [true, false] # [Rayleigh, Love]
  vel_type: [true, true]   # [phase, group]
  weights: [0.5, 0.5]      # [phase, group]

SurfATT validates the selected data/model combination before the inversion starts and reports incompatible configurations early. In particular, group velocity is currently limited to isotropic inversion, azimuthal anisotropy uses Rayleigh phase velocity, and radial anisotropy requires both Rayleigh and Love phase-velocity datasets.

Surface-wave dispersion and sensitivity kernels

The dispersion and depth-kernel layer has been refactored behind a common C++ interface for Rayleigh and Love waves. It computes phase- and group-velocity sensitivities and activates only the kernels required by the chosen model parameterization. The main dispersion calculation was migrated from the former Fortran API to C++ in 3f2234a .

Regularization and optimization

PDE smoothing in spherical coordinates

SurfATT v2 adds kernel smoothing by solving a 3-D diffusion equation. The implementation uses the spherical Laplace-Beltrami operator in longitude, latitude, and depth, including the latitude metric and radial correction. Users set separate horizontal and vertical smoothing scales with sigma; the solver chooses a stable number of diffusion steps automatically.

The existing multiple-grid parameterization remains available as an alternative regularization method. Isotropic and anisotropic parameters can use independent smoothing settings through independent_smooth_ani.

L-BFGS with Wolfe-condition line search

The optimizer now provides:

• steepest descent with an adaptive step length; and
• limited-memory BFGS with a Wolfe-condition line search.

The L-BFGS implementation stores recent model/gradient pairs, uses a steepest-descent fallback for the first iteration, and restarts when the search direction is no longer a reliable descent direction. The line search exposes the Armijo and curvature coefficients as c1 and c2, together with step_length and max_sub_niter. The initial implementation is documented in 68f928e .

Kernel-density preconditioning and the optional vpvs_ratio_range constraint can be used to stabilize updates in poorly illuminated regions and keep multi-parameter models within a configured range.

Architecture, parallelism, and I/O

• Modern C++ architecture. Core workflow components are separated into model, surface-grid, source-receiver, preprocessing, postprocessing, optimization, parallel, logging, and I/O modules. CMake builds the libraries, executables, and optional tests.
• MPI and shared memory. Source-level parallelism is combined with spatial domain decomposition. Large model and observation arrays use MPI shared-memory windows within a node, while local tensors and halo exchange support distributed kernel smoothing and inversion.
• Selectable precision. Double precision is the default. Configure with -DUSE_SINGLE_PRECISION=ON to build the project with single-precision model and kernel arrays.
• Flexible initial models. The initial model can be a linear 1-D profile, a 1-D profile estimated from the observations, or an external 3-D HDF5 model. External models are interpolated onto the active inversion grid when their coordinate axes differ but cover the target domain.
• HDF5 and XDMF output. Final and intermediate models are stored in HDF5. model_iter.xdmf indexes model and gradient snapshots for direct inspection in XDMF-compatible visualization tools. Iteration-aware XDMF output was added in 4bea787 .
• Structured diagnostics. The new spdlog-based logger records module-aware messages, residual statistics, objective-function evolution, line-search decisions, and total elapsed time.

Commands and examples

The v2 build produces the following executables:

The source tree includes worked examples for isotropic checkerboard inversion, radial-anisotropy checkerboard inversion, and topography-aware modelling. Unit tests cover YAML parsing, MPI communication, logging, CSV and HDF5 I/O, interpolation, dispersion kernels, the Eikonal solver, and retained numerical routines. GitHub Actions also builds on Linux and macOS and runs 17 integration test cases.

Performance and validation

In the reference CPU benchmark supplied with the v2 development results, the same workflow decreased from 455.7 s in v1 to 344.2 s in v2, a 24.5% reduction in elapsed time or approximately 1.32x speed-up. This number describes that benchmark only; the gain for another dataset depends on the compiler, MPI layout, hardware, model size, and active inversion parameters.

The v2 workflow was also exercised on a western-US experiment with 7,454 virtual sources, 689 stations, and 1,824,336 model grid points. Isotropic and azimuthal-anisotropy checkerboard tests recover the target patterns in map view and vertical cross-sections, and the regional inversion shows a sustained reduction in normalized travel-time misfit.

Migration notes for v1 users

v2 is a major-version upgrade. Existing projects should review the following changes before reusing a v1 configuration:

• rebuild SurfATT from the v2 CMake project and update the dependency stack to include a C++ compiler, Eigen3, yaml-cpp, and spdlog in addition to MPI, HDF5, and a Fortran compiler for retained numerical routines;
• update scripts to use the uppercase SURFATT_* executable names produced by CMake;
• migrate the YAML file to the sectioned v2 schema and replace the old source-receiver keys with the wave/velocity-specific src_rec_file_* keys;
• set wave_type, vel_type, weights, and model_para_type explicitly;
• review the new postproc.smooth_method_* and L-BFGS line-search settings; and
• update postprocessing scripts for the v2 HDF5 field names, especially g0 / theta for azimuthal anisotropy and vsv / vsh / Vs / zeta for radial anisotropy.

The v2 source is maintained in the TomoATT/SurfATT repository.