Skip to content

Ray tracers

Ray tracers calculate the travel times from every node of the search volume to every station. ray_tracers is a list: every phase description in the phase_map of the image function needs one ray tracer that provides it.

Ray tracer Velocity model Phases Use for
ConstantVelocityTracer Constant velocity One per tracer, e.g. constant:P Tests and small volumes
FastMarching 1D layered fm:P, fm:S Most searches in 1D models
CakeTracer 1D layered Pyrocko phase definitions, e.g. cake:P Specific phases of 1D models
FastMarching3D 3D One per tracer, e.g. fm3d:P Complex geology
Ray tracers for the P and S phases of a 1D model
"ray_tracers": [
  {
    "tracer": "FastMarching",
    "velocity_model": {"filename": "velocity-model.nd"},
    "phases": ["fm:P", "fm:S"]
  }
]

Constant velocity

The travel time is the distance \(d\) divided by the velocity:

\[ t = \frac{d}{v} \]

Each tracer provides one phase. Add one tracer for P and one for S.

ConstantVelocityTracer
{
  "tracer": "ConstantVelocityTracer",
  "phase": "constant:P",
  "velocity": 5000.0
}

ConstantVelocityTracer pydantic-model

Bases: RayTracer

Travel times for a constant velocity: the distance divided by the velocity.

Useful for testing and for small volumes with little velocity variation.

Fields:

phase pydantic-field

phase: PhaseDescription = 'constant:P'

Phase description of the travel times, e.g. "constant:P". The image function maps its phases to this description.

velocity pydantic-field

velocity: PositiveFloat = 5000.0

Constant velocity of the phase in m/s.

1D layered velocity model

Two ray tracers calculate travel times in 1D layered models. Both read the velocity model from a file in the Pyrocko Cake .nd format or the HYPOSAT format, or from a CRUST2.0 profile. Without a model, Qseek uses a default model and warns.

LayeredEarthModel1D
{
  "format": "nd",
  "crust2_profile": ""
}

LayeredEarthModel1D pydantic-model

Bases: Model

Config:

  • ignored_types: (cached_property,)

Fields:

filename pydantic-field

filename: FilePath | None = DEFAULT_VELOCITY_MODEL_FILE

Path to velocity model.

format pydantic-field

format: Literal['nd', 'hyposat'] = 'nd'

Format of the velocity model. nd or hyposat is supported.

crust2_profile pydantic-field

crust2_profile: Annotated[str, StringConstraints(to_upper=True)] | tuple[float, float] = ''

Crust2 profile name or [lat, lon] coordinates.

raw_file_data pydantic-field

raw_file_data: str | None = None

Raw .nd file data.

fortify

fortify() -> None

Fortify the model for faster access.

save_plot

save_plot(filename: Path) -> None

Plot the layered model and save the figure to a file.

Parameters:

Name Type Description Default
filename Path

The path to save the figure.

required

Fast marching

The fast marching method solves the Eikonal equation for the first arrivals on a grid. It is faster than Pyrocko Cake for large numbers of stations and nodes.

Fast Marching Concept

Travel times from a station at the surface (yellow triangle) to every point of a heterogeneous subsurface, calculated with the fast marching method. One calculation yields the travel times of a station to all possible source locations.

FastMarchingTracer
{
  "tracer": "FastMarching",
  "velocity_model": {
    "format": "nd",
    "crust2_profile": ""
  },
  "interpolation_method": "linear",
  "nthreads": 0,
  "phases": [
    "fm:P",
    "fm:S"
  ]
}

FastMarchingTracer pydantic-model

Bases: RayTracer

Travel times in a 1D layered velocity model from the fast marching method.

The fast marching method solves the Eikonal equation for the first arrivals on a grid. It is faster than the Pyrocko Cake ray tracer for large numbers of stations and nodes.

Fields:

velocity_model pydantic-field

velocity_model: LayeredEarthModel1D | None

Velocity model for the ray tracer.

interpolation_method pydantic-field

interpolation_method: InterpolationMethod = 'linear'

Interpolation of the travel times between the grid points.

nthreads pydantic-field

nthreads: int = 0

Number of threads for the travel time calculation. 0 uses twice the number of CPU cores.

implementation pydantic-field

implementation: Literal['eikonalfm'] = 'eikonalfm'

Implementation of the fast marching method. Only eikonalfm remains; the field is kept so that older configurations load.

phases pydantic-field

phases: tuple[Phase, ...] = ('fm:P', 'fm:S')

Phases to calculate.

get_travel_time_table

get_travel_time_table(location: Location, phase: str) -> StationTravelTimeTable

Get the travel time table for a given station and phase.

prepare async

prepare(octree: Octree, stations: StationInventory, rundir: Path | None = None) -> None

Prepare the tracer for a given set of stations.

add_travel_time_table

add_travel_time_table(table: StationTravelTimeTable) -> None

Add a travel time slice to the tracer.

get_travel_times async

get_travel_times(phase: Phase, nodes: Sequence[Node], stations: Sequence[Station]) -> ndarray

Get travel times for a phase from a source to a set of stations.

Parameters:

Name Type Description Default
phase Phase

Phase name.

required
nodes Sequence[Node]

Nodes to get traveltime for.

required
stations Sequence[Station]

Stations to calculate travel times to.

required

Returns:

Type Description
ndarray

np.ndarray: Array of shape (n_nodes, n_stations) with travel times in seconds.

Pyrocko Cake

The Pyrocko Cake ray tracer calculates the arrivals of phases given by Pyrocko phase definitions. "P,p" is the first P arrival, either the down-going P or the up-going p. The keys of phases are the phase descriptions, e.g. "cake:P".

Pyrocko Cake Ray Tracer

Rays of the Pyrocko Cake ray tracer in a 1D layered model.

CakeTracer
{
  "tracer": "CakeTracer",
  "phases": {
    "cake:P": {
      "definition": "P,p"
    },
    "cake:S": {
      "definition": "S,s"
    }
  },
  "earthmodel": {
    "format": "nd",
    "crust2_profile": ""
  }
}

CakeTracer pydantic-model

Bases: RayTracer

Travel times in a 1D layered velocity model from the Pyrocko Cake ray tracer.

The phases are Pyrocko timing definitions, e.g. P,p for the first P arrival.

Fields:

phases pydantic-field

phases: dict[PhaseDescription, Timing] = {'cake:P': Timing(definition='P,p'), 'cake:S': Timing(definition='S,s')}

Dictionary of phases and timings to calculate.

earthmodel pydantic-field

earthmodel: LayeredEarthModel1D

Earth model to calculate travel times for.

clear_cache

clear_cache() -> None

Clear cached SPTreeModels from user's cache.

3D velocity model

The 3D tracer calculates first arrivals with the fast marching method in a 3D velocity model. Each tracer provides one phase from one velocity model: add one tracer for P with a P-velocity model and one for S. Three velocity models are available:

  • A NonLinLoc 3D velocity grid.
  • A 1D layered model, extended to 3D.
  • A constant velocity, mainly for testing.

The Utah FORGE example of the playground searches in a 3D NonLinLoc model.

FastMarching3DTracer
{
  "tracer": "FastMarching3D",
  "phase": "fm3d:P",
  "interpolation_method": "linear",
  "nthreads": 0,
  "velocity_model": {
    "model": "Constant3DVelocityModel",
    "grid_spacing": "octree",
    "velocity": 5000.0
  },
  "implementation": "eikonalfm"
}

FastMarching3DTracer pydantic-model

Bases: RayTracer

3D velocity model travel time calculation using fast marching method.

Fields:

interpolation_method pydantic-field

interpolation_method: InterpolationMethod = 'linear'

Interpolation method for travel times in the volume. Choose from nearest, linear or cubic. Nodes and locations outside the volume have no travel time.

nthreads pydantic-field

nthreads: int = 0

Number of threads to use for travel time. If set to 0, cpu_count*2 will be used.

velocity_model pydantic-field

velocity_model: VelocityModels

Velocity model for the ray tracer.

implementation pydantic-field

implementation: FMMImplementation = 'eikonalfm'

Implementation of the fast marching method, only eikonalfm (second order, factored).

NonLinLocVelocityModel pydantic-model

Bases: VelocityModelFactory

Fields:

header_file pydantic-field

header_file: FilePath

Path to NonLinLoc model header file file. The file should be in the format of a NonLinLoc velocity model header file. Binary data has to have the same name and .buf suffix.

grid_spacing pydantic-field

grid_spacing: PositiveFloat | Literal['octree', 'input'] = 'input'

Grid spacing in meters. If 'octree' defaults to smallest octreee node size. If 'input' uses the grid spacing from the NonLinLoc header file.

interpolation pydantic-field

interpolation: Literal['nearest', 'linear', 'cubic'] = 'cubic'

Interpolation method for resampling the grid for the fast-marching method. Choose from nearest, linear or cubic.

reference_location pydantic-field

reference_location: Location | None = None

Geographic origin of the NonLinLoc model's coordinates (required). The grid's origin from the header is applied as shifts to this location; NonLinLoc's z is relative to its elevation.

Visualize 3D models

For quality control, Qseek exports all 3D velocity models and travel time volumes as .vti files into the 3d-models/ folder of the run directory. Inspect them with ParaView.

Velocity model FORGE

3D velocity model of the Utah FORGE geothermal test site, visualized in ParaView.