API, exported functions

EikonalSolvers

EikonalSolvers module, 2D and 3D traveltime and gradient computations in Cartesian and spherical coordinates. Computes seismic traveltimes by solving the eikonal equation in two and three dimensions with the possibility of computing the gradient of the misfit function with respect to the velocity model. Both forward and gradient computations are parallelised using Julia's distributed computing functions and the parallelisation is "by source", distributing calculations for different sources to different processors.

Exports

• EikonalProbSrcLoc
• EikonalProbVel
• EikonalProbVelAndSrcLoc
• ExtraParams
• Grid2DCart
• Grid2DSphere
• Grid3DCart
• Grid3DSphere
• GridRefinementPars
• eikgradient
• eiktraveltime
• eikttimemisfit
• savemodelvtk
• tracerays

struct Grid2DCart <: EikonalSolvers.AbstractGridEik2D

A structure holding the 2D grid parameters, geometry and size.

• hgrid::Float64: Spacing of the grid nodes

• cooinit::Tuple{Float64, Float64}: Origin of the coodinates of the grid

• cooend::Tuple{Float64, Float64}: End of the coodinates of the grid

• grsize::Tuple{Int64, Int64}: Number of grid nodes along x and y

• x::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: x coordinates of the grid nodes

• y::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: y coordinates of the grid nodes

The constructor requires three arguments (see the example):

• hgrid: spacing of the grid nodes
• cooinit: origin of the coordinate system
• grsize: number of grid nodes along x and y

Example

julia> Grid2DCart(hgrid=5.0,cooinit=(0.0,0.0),grsize=(300,250))

struct Grid3DCart <: EikonalSolvers.AbstractGridEik3D

A structure holding the 3D grid parameters, geometry and size.

Fields

• hgrid::Float64: Spacing of the grid nodes

• cooinit::Tuple{Float64, Float64, Float64}: Origin of the coodinates of the grid

• cooend::Tuple{Float64, Float64, Float64}: End of the coodinates of the grid

• grsize::Tuple{Int64, Int64, Int64}: Number of grid nodes along x, y and z

• x::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: x coordinates of the grid nodes

• y::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: y coordinates of the grid nodes

• z::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: z coordinates of the grid nodes

The constructor requires three arguments (see the example):

• hgrid: spacing of the grid nodes
• cooinit: origin of the coordinate system
• grsize: number of grid nodes along x, y and z

Example

julia> Grid3DCart(hgrid=5.0,cooinit=(0.0,0.0,0.0),grsize=(60,60,40))

A structure holding the 2D SPHERICAL grid parameters, geometry and size.

• Δr::Float64: Spacing of the grid nodes along the radius (r)

• Δθ::Float64: Spacing of the grid nodes along the angle θ

• cooinit::Tuple{Float64, Float64}: Origin of the coodinates of the grid

• cooend::Tuple{Float64, Float64}: End of the coodinates of the grid

• grsize::Tuple{Int64, Int64}: Number of grid nodes along r and θ

• r::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: r coordinates of the grid nodes

• θ::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: θ coordinates of the grid nodes

The fields are:

• Δr: spacing of the grid nodes along the radial coordinate r
• Δθ: spacing of the grid nodes along the θ coordinate
• cooinit: origin of the coordinate system
• grsize: number of grid nodes along r and θ

Example

julia> Grid2DSphere(Δr=15.0,Δθ=2.0,grsize=(10,15),cooinit=(500.0,0.0))

A structure holding the 3D SPHERICAL grid parameters, geometry and size.

• Δr::Float64: Spacing of the grid nodes along the radius (r)

• Δθ::Float64: Spacing of the grid nodes along the angle θ

• Δφ::Float64: Spacing of the grid nodes along the angle φ

• cooinit::Tuple{Float64, Float64, Float64}: Origin of the coodinates of the grid

• cooend::Tuple{Float64, Float64, Float64}: End of the coodinates of the grid

• grsize::Tuple{Int64, Int64, Int64}: Number of grid nodes along r, θ and φ

• r::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: r coordinates of the grid nodes

• θ::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: θ coordinates of the grid nodes

• φ::StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: φ coordinates of the grid nodes

The fields are:

• Δr: spacing of the grid nodes along the radial coordinate r
• Δθ: spacing of the grid nodes along the θ coordinate
• Δφ: spacing of the grid nodes along the θ coordinate
• cooinit: origin of the coordinate system
• grsize: number of grid nodes along r, θ and φ

Example

julia> Grid3DSphere(Δr=15.0,Δθ=2.0,Δφ=1.5,grsize=(10,15,12),cooinit=(500.0,20.0,0.0))

eiktraveltime(
    vel::Array{Float64, N},
    grd::EikonalSolvers.AbstractGridEik,
    coordsrc::Matrix{Float64},
    coordrec::Vector{Matrix{Float64}};
    returntt,
    extraparams
) -> Any

Calculate the traveltime for 2D or 3D velocity models at requested receivers locations. Optionally return the array(s) of traveltime on the entire gridded model.

Arguments

• vel: the 2D or 3D velocity model
• grd: a struct specifying the geometry and size of the model (e.g., Grid3DCart)
• coordsrc: the coordinates of the source(s) (x,y), a 2-column array
• coordrec: the coordinates of the receiver(s) (x,y) for each single source, a vector of 2-column arrays
• returntt: a boolean (default false) specifying whether to retur the array(s) of traveltime on the entire gridded model or not
• extraparams (optional): a struct containing some "extra" parameters, namely
  • parallelkind: serial, Threads or Distributed run? (:serial, :sharedmem, :distribmem)
  • refinearoundsrc: whether to perform a refinement of the grid around the source location
  • grdrefpars: refined grid around the source parameters (downscalefactor and noderadius)
  • radiussmoothgradsrc: radius for smoothing each individual gradient only around the source. Zero means no smoothing.
  • smoothgradkern: smooth the final gradient with a kernel of size smoothgradkern (in grid nodes). Zero means no smoothing.
  • manualGCtrigger: trigger garbage collector (GC) manually at selected points.

Returns

• A vector of vectors containing traveltimes at the receivers for each source
• If returntt==true, additionally returns the array(s) of traveltime on the entire gridded model

eikgradient(
    vel::Array{Float64, N},
    grd::EikonalSolvers.AbstractGridEik,
    coordsrc::Matrix{Float64},
    coordrec::Vector{Matrix{Float64}},
    pickobs::Vector{Vector{Float64}},
    stdobs::Vector{Vector{Float64}},
    whichgrad::Symbol;
    extraparams
) -> Union{Nothing, Tuple{Any, Any}, Tuple{Any, Any, Any}}

Calculate the gradient of the misfit function w.r.t. either velocity or source location (or both) using the adjoint state method for 2D or 3D problems.

The computations may be run in parallel depending on the value of extraparams.parallelkind.

Arguments

• vel: the 2D or 3D velocity model
• grd: a struct specifying the geometry and size of the model (e.g., Grid3DCart)
• coordsrc: the coordinates of the source(s) (x,y), a 2-column array
• coordrec: the coordinates of the receiver(s) (x,y) for each single source, a vector of 2-column arrays
• pickobs: observed traveltime picks
• stdobs: standard deviation of error on observed traveltime picks, an array with same shape than pickobs
• whichgrad: one of :gradvel, :gradsrcloc, :gradvelandsrcloc, specifies which gradient should be computed
• extraparams (optional): a struct containing some "extra" parameters, namely
  • parallelkind: serial, Threads or Distributed run? (:serial, :sharedmem, :distribmem)
  • refinearoundsrc: whether to perform a refinement of the grid around the source location
  • grdrefpars: refined grid around the source parameters (downscalefactor and noderadius)
  • radiussmoothgradsrc: radius for smoothing each individual gradient only around the source. Zero means no smoothing.
  • smoothgradkern: smooth the final gradient with a kernel of size smoothgradkern (in grid nodes). Zero means no smoothing.
  • manualGCtrigger: trigger garbage collector (GC) manually at selected points.

Returns

• The gradient w.r.t. velocity as a 2D or 3D array and the gradient w.r.t source location. In case only one of them is requested with whichgrad, the other one will not be returned.
• The value of the misfit functional for the given input velocity model.

eikttimemisfit(
    velmod::Array{Float64, N},
    grd::EikonalSolvers.AbstractGridEik,
    coordsrc::AbstractMatrix,
    coordrec::AbstractVector{<:AbstractArray},
    ttpicksobs::AbstractArray,
    stdobs::AbstractArray;
    extraparams
) -> Float64

Calculate the Gaussian misfit functional

\[ S = \dfrac{1}{2} \sum_i \dfrac{\left( \mathbf{u}_i^{\rm{calc}}(\mathbf{v})-\mathbf{u}_i^{\rm{obs}} \right)^2}{\sigma_i^2} \, .\]

Arguments

• velmod: velocity model, either a 2D or 3D array.
• grd: the struct holding the information about the grid, one of Grid2D,Grid3D,Grid2Dsphere,Grid3Dsphere
• coordsrc: the coordinates of the source(s) (x,y), a 2-column array
• coordrec: the coordinates of the receiver(s) (x,y) for each single source, a vector of 2-column arrays
• ttpicksobs: a vector of vectors of the traveltimes at the receivers.
• stdobs: a vector of vectors standard deviations representing the error on the measured traveltimes.
• extraparams (optional): a struct containing some "extra" parameters, namely
  • parallelkind: serial, Threads or Distributed run? (:serial, :sharedmem, :distribmem)
  • refinearoundsrc: whether to perform a refinement of the grid around the source location
  • grdrefpars: refined grid around the source parameters (downscalefactor and noderadius)
  • manualGCtrigger: trigger garbage collector (GC) manually at selected points.

Returns

The value of the misfit functional (L2-norm), the same used to compute the gradient with adjoint methods.

struct ExtraParams

Fields

• refinearoundsrc::Bool: refine grid around source?

• manualGCtrigger::Bool: trigger GC manually at selected points

• parallelkind::Symbol: Serial, Threads or Distributed run? Either :serial, :sharedmem or :distribmem

• radiussmoothgradsrc::Int64: Radius for smoothing the gradient around the source. Zero means no smoothing.

• smoothgradkern::Int64: Smooth the gradient with a kernel of size (in pixels). Zero means no smoothing.

• grdrefpars::GridRefinementPars: Downscaling factor and node radius for refined grid creation

struct GridRefinementPars

Fields

• downscalefactor::Int64: Downscaling factor for refined grid around the source

• noderadius::Int64: Number of (coarse) grid nodes (radius) within which to refine the grid

tracerays(
    grd::EikonalSolvers.AbstractGridEik,
    ttime::Vector{Array{Float64}},
    coordsrc::Matrix{Float64},
    coordrec::Vector{Matrix{Float64}};
    steplen
) -> Vector{Vector{Matrix{Float64}}}

Ray tracing utility. Given a traveltime grid and source and receiver positions, trace the rays.

HMCtraveltimes

A convenience module to facilitate the use of EikonalSolvers within the framework of Hamiltonian Monte Carlo inversion by employing the package HMCsampler.

Exports

• EikonalProbSrcLoc
• EikonalProbVel
• EikonalProbVelAndSrcLoc

struct EikonalProbVel

Fields

• grd::Union{Grid2DCart, Grid3DCart}

• dobs::Vector{Vector{Float64}}

• stdobs::Vector{Vector{Float64}}

• coordsrc::Matrix{Float64}

• coordrec::Vector{Matrix{Float64}}

• whichgrad::Symbol

• logVel::Bool

• extraparams::Union{Nothing, ExtraParams}

struct EikonalProbSrcLoc

Fields

• grd::Union{Grid2DCart, Grid3DCart}

• dobs::Vector{Vector{Float64}}

• stdobs::Vector{Vector{Float64}}

• coordrec::Vector{Matrix{Float64}}

• velmod::Matrix{Float64}

• whichgrad::Symbol

• extraparams::Union{Nothing, ExtraParams}

This function requires the package WriteVTK to be loaded first in order to work.