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,
  "implementation": "eikonalfm",
  "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: FMMImplementation = 'eikonalfm'

Implementation of the Fast Marching Method. Pyrocko only supports first-order FMM for now.

phases pydantic-field 

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

Phases to calculate.

get_travel_time_table 

get_travel_time_table(
    location: Location, phase: Phase
) -> 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.
FastMarching3DTracer
{
  "tracer": "FastMarching3D",
  "phase": "fm3d:P",
  "interpolation_method": "cubic",
  "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 = 'cubic'

Interpolation method for travel times in the volume. Choose from nearest, linear or cubic.

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. Pyrocko only supports first-order FMM for now.

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

Reference location/geographic origin of the NonLinLoc model, this is required for models with relative coordinates.The relative shifts are applied to the reference location.

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.