Skip to content

relocate

Science

relocate runs a NonLinLoc global-search location on a referenced phase set. NonLinLoc treats the hypocentre as a posterior probability density over a spatial grid: an oct-tree importance sampler explores the volume, and the returned origin is a summary of that density (maximum-likelihood or expectation, with an ellipsoid drawn from the same PDF). The likelihood is an equal-differential-time (EDT) form, so a few large residuals do not automatically dominate the fit the way a least-squares L2 misfit would.

The caller does not invent a velocity model or a grid definition. Those are frozen. What is enumerated is the experiment: grid × depth_mode.

grid Floor Use
shallow 65 km Regional crustal and uppermost-mantle trials
deep 250 km Intermediate-depth trials; also the usual catalogue grid
depth_mode Meaning
free Depth is a searched parameter
fixed_5, fixed_10, fixed_15 Depth held at 5, 10 or 15 km

A first call on the subject needs no hypothesis. A later call that changes grid or depth_mode is a repeat and, on profiles that require it, must state what the new configuration is testing. The point of the menu is to run a named experiment, not to hunt for the smallest RMS.

Four-phase floor

NonLinLoc will not write a hypocentre file with fewer than four accepted phases (LOCMETH minNumberPhases). That floor is a property of the locator, not a soft preference. phase_set: p_only on a three-station event is below it and returns E_TOOL_FAILED. Changing grid or depth_mode does not add phases. Do not spend another budget slot on a different configuration of the same three-P set.

How to read a result

A converged solution is not a correct one. Read these together:

Azimuthal gap. gap_deg is the largest azimuth sector without a station. A gap above 180° is warned as large_gap: the epicentre is poorly closed and can slide along the open sector. A small gap on few stations is still underdetermined.

Depth versus the grid boundary. The PDF piles up where the grid stops. A depth within 5 km of 0 km or of the grid floor (65 or 250) raises depth_at_grid_boundary, and quality.grid_boundary_hit reports whether the search touched the edge. A 249 km depth on the deep grid is a candidate artefact; the matching experiment is grid: shallow or a fixed_* depth, stated as a hypothesis — not a second try “to see if it looks better”.

Residual pattern. residuals[] is observed minus predicted, with distance and azimuth. A random scatter around zero is consistent with picking and model error (a few tenths of a second is normal on a regional 1-D model). A trend with distance, a first-azimuthal-harmonic swing, or two clusters of residuals is information about the pattern, not about the size of RMS. render_residuals plots the same numbers.

RMS after removing a pick. Dropping a phase almost always lowers RMS. That is expected: the misfit has one fewer term. It is not evidence that the remaining solution is better, and it is not a reason to iterate relocate until the RMS is pretty. Use jackknife_location when the question is dependence on a station.

Uncertainties come from the locator's origin-uncertainty and statistics lines when the search converged; they are null when it did not. The solution is referenceable downstream as { "kind": "solution", "tool_call_id": "…" }.

References

Contract

Generated from the live registry (ToolSpec). Field names, types and defaults come from the input and payload models; they are not hand-typed.
Group solution
Class 3
Tool version 1.1.1
Highest declared tier E
Timeout 60 s
Budget key relocate
readOnlyHint true
idempotentHint false

Input

Field Type Required Notes
picks object yes The phase set a solution tool works on.
picks.base object (kind catalog | none | solution) yes discriminated on kind
picks.phase_set string ∈ {all, p_only} yes
picks.exclude_pick_ids array[integer] no
picks.add_picks array[object] no
picks.add_picks[].tool_call_id string yes
picks.add_picks[].pick_index integer yes
grid string ∈ {shallow, deep} yes
depth_mode string ∈ {free, fixed_5, fixed_10, fixed_15} yes
hypothesis string | null no default null

Payload

Field Type Required Notes
solution object yes
solution.origin_time_utc string yes
solution.latitude_deg number yes
solution.longitude_deg number yes
solution.depth_km number yes
solution.depth_fixed boolean yes
solution.rms_s number | null yes
solution.gap_deg number | null yes
solution.num_phases integer yes
solution.num_stations integer yes
solution.min_distance_km number | null yes
solution.uncertainty object | null yes
solution.uncertainty.horizontal_km number | null yes
solution.uncertainty.min_horizontal_km number | null yes
solution.uncertainty.max_horizontal_km number | null yes
solution.uncertainty.azimuth_max_horizontal_deg number | null yes
solution.uncertainty.depth_km number | null yes
solution.uncertainty.ellipsoid object | null yes
solution.uncertainty.ellipsoid.len1_km number | null yes
solution.uncertainty.ellipsoid.az1_deg number | null yes
solution.uncertainty.ellipsoid.dip1_deg number | null yes
solution.uncertainty.ellipsoid.len2_km number | null yes
solution.uncertainty.ellipsoid.az2_deg number | null yes
solution.uncertainty.ellipsoid.dip2_deg number | null yes
solution.uncertainty.ellipsoid.len3_km number | null yes
solution.quality object yes
solution.quality.converged boolean yes
solution.quality.grid_boundary_hit boolean yes
solution.quality.grid string yes
solution.quality.grid_floor_km number yes
residuals array[object] yes
residuals[].pick_ref object (kind catalog | repick) yes discriminated on kind
residuals[].station_id string yes
residuals[].phase string yes
residuals[].residual_s number yes
residuals[].weight number | null yes
residuals[].distance_km number | null yes
residuals[].azimuth_deg number | null yes
picks_used array[object (kind catalog | repick)] yes
picks_rejected array[object] yes
picks_rejected[].pick_ref object (kind catalog | repick) yes discriminated on kind
picks_rejected[].reason string ∈ {no_grid, no_station_coords, duplicate} yes
config object yes
config.grid string yes
config.depth_mode string yes
config.phase_set string yes
config.template_digest string | null no default null
nll_control_digest string yes

Example request

{
  "picks": {
    "base": {
      "kind": "catalog",
      "event_id": 1001
    },
    "phase_set": "all",
    "exclude_pick_ids": [],
    "add_picks": []
  },
  "grid": "deep",
  "depth_mode": "free",
  "hypothesis": "testing whether a 249 km depth is a grid artefact"
}

Example payload

{
  "solution": {
    "origin_time_utc": "2024-06-15T08:12:03.410Z",
    "latitude_deg": 47.152,
    "longitude_deg": 24.497,
    "depth_km": 12.4,
    "depth_fixed": false,
    "rms_s": 0.24,
    "gap_deg": 108.0,
    "num_phases": 9,
    "num_stations": 6,
    "min_distance_km": 18.3,
    "uncertainty": {
      "horizontal_km": 2.1,
      "min_horizontal_km": 1.4,
      "max_horizontal_km": 3.2,
      "azimuth_max_horizontal_deg": 42.0,
      "depth_km": 4.8,
      "ellipsoid": null
    },
    "quality": {
      "converged": true,
      "grid_boundary_hit": false,
      "grid": "deep",
      "grid_floor_km": 250.0
    }
  },
  "residuals": [
    {
      "pick_ref": {
        "kind": "catalog",
        "pick_id": 20001
      },
      "station_id": "XX.STA1",
      "phase": "P",
      "residual_s": -0.09,
      "weight": 1.0,
      "distance_km": 41.2,
      "azimuth_deg": 212.0
    }
  ],
  "picks_used": [
    {
      "kind": "catalog",
      "pick_id": 20001
    }
  ],
  "picks_rejected": [],
  "config": {
    "grid": "deep",
    "depth_mode": "free",
    "phase_set": "all",
    "template_digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "nll_control_digest": "sha256:abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
}

What this tool does not tell you

What this tool does not tell you: that a converged solution is a correct one. Check the gap, whether the depth sits on a grid boundary, and whether the residual pattern is random. A lower RMS after removing a pick is expected, not evidence. NLLoc will not locate with fewer than 4 accepted phases (LOCMETH minNumberPhases); phase_set: p_only on a 3-station event is below that floor and returns E_TOOL_FAILED. Do not retry on another grid.

Warnings named for this tool

Code When
depth_at_grid_boundary solution depth is within 5 km of 0 or the grid floor
few_phases fewer than 6 phases were used
no_s_phases no S phase was used
large_gap azimuthal gap is greater than 180°
partial_result a truncated hyp PHASE ID matches more than one used station

Errors named for this tool

Code When
E_TOOL_FAILED locator error, or fewer than 4 accepted phases so no .hyp is written
E_TIMEOUT the domain call exceeded the tool timeout
E_BUSY the locator queue wait would exceed the configured limit
E_UNKNOWN_REF a pick or origin reference is not in this session