Home

Awesome

GrowClust3D.jl

This repository hosts a Julia implementation of the GrowClust program for relative relocation of earthquake hypocenters based on waveform cross-correlation data. The vision for this program is to provide more flexibility and 3D velocity model capabilities than the original Fortran90 source code. Complete documentation is available here https://github.com/dttrugman/GrowClust3D/wiki/Documentation.

If you use this code in your research, please cite the following paper describing the new code and its application:

Daniel T. Trugman, Calum J. Chamberlain, Alexandros Savvaidis, Anthony Lomax; GrowClust3D.jl: A Julia Package for the Relative Relocation of Earthquake Hypocenters Using 3D Velocity Models. Seismological Research Letters 2022; doi: https://doi.org/10.1785/0220220193

The (unregistered) package can be installed using the Julia Pkg manager:

pkg> add https://github.com/dttrugman/GrowClust3D.jl

The example scripts use additional functionality from the DataFrames external package, so it is recommended to add it via the package manager to complete the install:

pkg> add DataFrames

Once installed, please do run the test set that checks your installation by running a suite of test problems:

pkg> test GrowClust3D

Note: The GrowClust3D software was finalized using Julia v1.8. It is recommended to use at least v1.6 or later as there can be compatibility issues with the packages GrowClust3D depends on. For example, Proj.jl requires v1.6 or later at present writing.

The examples/ directory has two different Julia (.jl) "run/driver" scripts: run_growclust3D.jl as a reference example for typical usage on a single processor, and run_growclust3D-MP.jl which is similar in spirit but designed for multiprocessing on multiple cores. These two .jl scripts can be copied and reused as examples for any generic GrowClust3D problem with little/no modification. These example scripts, along with the rest of the repository, can be downloaded via git clone https://github.com/dttrugman/GrowClust3D.jl or equivalent.

The primary way to tailor GrowClust3D to your dataset is by modifying the input files. With this in mind, in examples/ there are four different example input (.inp) files related to the Spanish Springs, Nevada earthquake sequence. Any of the input files can be paired with either of the two run scripts.

The example input files are summarized as follows:

  1. example.trace1D.inp: example raytracing a 1D velocity model
  2. example.nllgrid1D.inp: example using precomputed (NonLinLoc) 1D travel time grid
  3. example.nllgrid3D.inp: example using precomputed (NonLinLoc) 3D travel time grid (see note below)
  4. example.nboot100.inp: example with bootstrapping (e.g. to test parallelization)

Example 1 uses internal ray-tracing codes and emulates the classic GrowClust example from the original Trugman and Shearer (2017) publication. Examples 2 and 3 use 1D and (quasi)-3D travel-time grids generated by NonLinLoc (https://github.com/alomax/NonLinLoc) from an equivalent velocity model. Example 4 is identical to Example 1 but with bootstrapping turned on. This is useful for testing the parallelization described below.

Note: To run Example 3, you will first need to generate the 3D travel time grids. If NonLinLoc is installed and its source files added to your path, simply navigate to the examples/ directory and run the driver script:

julia make_nllgrids.jl

This can also be used to regenerate the grids for Example 2. The reason why the 3D grids needed for Example 3 are not on the repo is that they take up a lot of memory, making it hard to pull or sync the repository.

The central difference between the two example run (.jl) scripts is in their mode of parallelization. The run_growclust3D.jl script can use multithreading on a single computational core to accelerate bootstrap uncertainty analysis. This is useful but limited to the number of threads accessible. The run_growclust3D-MP.jl script can use multiprocessing to further accelerate these calculations in cases where multiple cores are available (e.g., runs on a computing cluster). Generally, if sufficient resources are available, multiprocessing will be faster than multithreading (especially for large datasets) due to memory considerations. For most use cases, the computational overhead in transferring data to the additional processors is negligible compared to additional compute power. Below are some example use cases of the codes:

Simple examples without bootstrapping (good for testing):

julia run_growclust3D.jl example.serial1D.inp

julia run_growclust3D.jl example.nllgrid1D.inp

julia run_growclust3D.jl example.nllgrid3D.inp

Multithreading and Multiprocessing examples:

julia -t4 run_growclust3D.jl example.nboot100.inp

julia -p10 run_growclust3D-MP.jl example.nboot100.inp

In the first case above, I request 4 total threads. In the second, I request 10 processes (in addition to main). In either case, the user must request additional threads or processes to invoke parallelization.