# slbminterface

class SlbmInterface(earth_radius=None)

  `SlbmInterface` is the primary interface to the RSTT C++ library.

  `SlbmInterface` is the primary interface to the RSTT C++ library, providing access to all supported functionality. It maintains a cpp:class:Grid object which is loaded into memory with the `loadVelocityModel()` method. This Grid object remains in memory until the `SlbmInterface` destructor is called.

  `SlbmInterface` also maintains a single instance of a GreatCircle object which is instantiated with a call to `createGreatCircle()`. Once instantiated, many methods can retrieve information from it, such as `getTravelTime()`, `getTravelTimeComponents()`, `getWeights()`, and more. The GreatCircle can be interrogated until it is replaced with another GreatCircle by a subsequent call to `createGreatCircle()`, or it is deleted by `clear()`.

  Examples

      >>> slbm = SlbmInterface()

      >>> slbm = SlbmInterface(6371.)

  Notes

  By default earth_radius is not set, and `SlbmInterface` uses the values from the model file.

  Parameters:

    earth_radius (float, optional) – Constant radius of the Earth in kilometers

  srcLat

    Source latitude (radians) passed to `createGreatCircle()` the last time it was called

    Type:

      float

  srcLon

    Source longitude (radians) passed to `createGreatCircle()` the last time it was called

    Type:

      float

  srcDep

    Source depth (km) passed to `createGreatCircle()` the last time it was called

    Type:

      float

  rcvLat

    Receiver latitude (radians) passed to `createGreatCircle()` the last time it was called

    Type:

      float

  rcvLon

    Receiver longitude (radians) passed to `createGreatCircle()` the last time it was called

    Type:

      float

  rcvDep

    Receiver depth (km) passed to `createGreatCircle()` the last time it was called

    Type:

      float

  valid

    True if the current GreatCircle object has been instantiated and is ready to be interrogated.

    Type:

      bool

  CH_MAX

    c is the Zhao c parameter, and h is the turning depth of the ray below the Moho. The Zhao method only valid for \(c*h << 1\). When \(c*h > CH_MAX\), then RSTT will throw an Exception.

    Type:

      float

  Methods

  `clear`() | Delete the current GreatCircle object from memory and clear the pool of stored CrustalProfile objects.
  `clearActiveNodes`() | Clear all active nodes.
  `clearNodeHitCount`() | Clear the node hit count by setting the hit count of every node to zero.
  `createGreatCircle`(phase, srcLatRad, ...) | Instantiate a new GreatCircle between two locations.
  `getActiveNodeData`(nodeId) | Retrieve information associated with a specified active node in the velocity grid.
  `getActiveNodeId`(nodeId) | Retrieve the active node ID that corresponds to a specified grid node ID.
  `getActiveNodeNeighborInfo`(nodeId) | Retrieve information about the nodes that surround the specified active node.
  `getActiveNodeNeighbors`(nodeId) | Retrieve the active node IDs of the active nodes that surround the specified active node.
  `getActiveNodeWeights`() | Retrieve the weight assigned to each active node that was touched by the GreatCircle.
  `getActiveNodeWeightsReceiver`() | Retrieve the weight assigned to each active node for the receiver CrustalProfile.
  `getActiveNodeWeightsSource`() | Retrieve the weight assigned to each active node for the source CrustalProfile.
  `getAverageMantleVelocity`(waveType) | Retrieve the average P or S wave mantle velocity that is specified in the model input file.
  `getBufferSize`() | Returns the size of a DataBuffer object required to store this `SlbmInterface` object's model data.
  `getCHMax`() | Retrieve the current value of CH_MAX.
  `getClassCount`() | Retrieve a table that lists the number of instances of various RSTT classes that are currently instantiated.
  `getDelDepth`() | Retrieve the value of step change in depth used to compute depth derivatives
  `getDelDistance`() | Retrieve the value of step change in distance used to compute horizontal derivatives
  `getDistAz`(lat1Rad, lon1Rad, lat2Rad, lon2Rad) | Compute distance and azimuth between two points.
  `getDistance`() | Retrieve the source-receiver separation.
  `getFractionActive`() | Retrieve the fraction of the path length of the current GreatCircle object that is within the currently-defined active region.
  `getGreatCircleData`() | Retrieve information about the great circle path.
  `getGreatCircleLocations`() | Retrieve the latitudes, longitudes and depths of all the profile positions along the headwave interface.
  `getGreatCircleNodeInfo`() | Retrieve information about the interpolated points along the headwave path.
  `getGreatCirclePoints`(lat1Rad, lon1Rad, ...) | Retrieve an array of latitude/longitude points along a great circle path between two specified points.
  `getGreatCirclePointsOnCenters`(lat1Rad, ...) | Retrieve an array of latitude/longitude points along a great circle path between two specified points.
  `getGridData`(nodeId) | Retrieve information associated with a specified node in the velocity grid.
  `getGridNodeId`(activeNodeId) | Retrieve the grid node ID that corresponds to a specified active node ID.
  `getHeadwaveDistance`() | Retrieve the angular distance traveled by the ray below the headwave interface.
  `getHeadwaveDistanceKm`() | Retrieve the horizontal distance traveled by the ray below the headwave interface.
  `getInterpolatedPoint`(lat, lon) | Retrieve interpolated data from the earth model at a single specified latitude/longitude.
  `getInterpolatedTransect`(lat, lon) | Retrieve interpolated data from the earth model along a transec defined by equal sized, 1D arrays of latitude and longitude.
  `getInterpolatorType`() | Retrieve the type of interpolator currently in use; either "LINEAR" or "NATURAL_NEIGHBOR".
  `getMaxDepth`() | Retrieve the current value for the maximum source depth.
  `getMaxDistance`() | Retrieve the current value for the maximum source-receiver separation.
  `getModelPath`() | Return the path to the RSTT model.
  `getModelString`() | Calls `toString()` on the RSTT model.
  `getNActiveNodes`() | Retrieve the number of active nodes in the Grid.
  `getNGridNodes`() | Retrieve the number of Grid nodes in the Earth model.
  `getNHeadWavePoints`() | Retrieve the number of LayerProfile objects positioned along the head wave interface.
  `getNodeAzimuth`(node1, node2) | Retrieve the azimuth from node1 to node2.
  `getNodeHitCount`(nodeId) | Retrieve the number of times that the specified node has been 'touched' by a GreatCircle object.
  `getNodeNeighborInfo`(nodeId) | Retrieve the IDs of the nodes that surround the specified node.
  `getNodeNeighbors`(nodeId) | Retrieve the IDs of the nodes that surround the specified node.
  `getNodeSeparation`(node1, node2) | Retrieve the angular separation of two grid nodes.
  `getPathIncrement`() | Retrieve the current value of the spacing of great circle nodes along the head wave interface.
  `getPgLgComponents`() | Retrieve information about Pg/Lg travel time calculations.
  `getPhase`() | Retrieve the phase specified in last call to `createGreatCircle()`.
  `getPiercePointReceiver`() | Retrieve the location of the Moho pierce point below the receiver.
  `getPiercePointSource`() | Retrieve the location of the Moho pierce point below the source.
  `getRayParameter`() | Retrieve the ray parameter.
  `getReceiverDistance`() | Retrieve horizontal offset below the receiver.
  `getSlowness`() | Retrieve the horizontal slowness (i.e., the derivative of travel time with respect to receiver-source distance).
  `getSlownessUncertainty`() | Retrieve uncertainty of the horizontal slowness using the phase and distance specified in last call to `getGreatCircle()`.
  `getSourceDistance`() | Retrieve horizontal offset below the source.
  `getTessId`() | Retrieve the tessellation ID of the model currently in memory.
  `getTravelTime`() | Retrieve the total travel time for the GreatCircle.
  `getTravelTimeComponents`() | Retrieve the total travel time and the four components that contribute to it for the current GreatCircle.
  `getTravelTimeUncertainty`([useRandomError]) | Returns the path-dependent travel time uncertainty (PDU), in seconds
  `getTravelTimeUncertainty1D`() | Returns the path-independent travel time uncertainty (PIU), in seconds
  `getTravelTimeUncertaintyPDU`([useRandomError]) | Returns the path-dependent travel time uncertainty (PDU), in seconds
  `getTravelTimeUncertaintyPIU`() | Returns the path-independent travel time uncertainty (PIU), in seconds
  `getTurningRadius`() | Retrieve the turning radius of the ray.
  `getUncertaintyFileFormat`(phase, attribute) | Return path-independent uncertainty information related to the specified phase and attribute in the format of an ASCII model.
  `getUncertaintyTable`(phase, attribute) | Return path-independent uncertainty information related to the specified phase and attribute in a table format.
  `getVersion`() | Returns the RSTT version number.
  `getWeights`() | Retrieve the weight assigned to each grid node that was touched by the GreatCircle.
  `getWeightsReceiver`() | Retrieve the node IDs and the interpolation coefficients for the receiver CrustalProfile.
  `getWeightsSource`() | Retrieve the node IDs and the interpolation coefficients for the source CrustalProfile.
  `getZhaoParameters`() | Retrieve some of the parameters that contribute to the calculation of total travel time using the Zhao algorithm.
  `get_dtt_ddepth`() | Retrieve the derivative of travel time with respect to source depth.
  `get_dtt_ddist`() | Retrieve the horizontal slowness, i.e., the derivative of travel time with respect to receiver-source distance.
  `get_dtt_dlat`() | Retrieve the derivative of travel time with respect to source latitude.
  `get_dtt_dlon`() | Retrieve the derivative of travel time with respect to source longitude.
  `initializeActiveNodes`(latMinRad, lonMinRad, ...) | Set grid nodes within a latitude/longitude range as active nodes.
  `isEqual`(other) | Compares the model and/or great circle loaded into this and another SlbmInteface.
  `isValid`() | Returns true if a GreatCircle object has been instantiated and is ready to be interrogated.
  `loadVelocityModel`(model_path) | Load the velocity model into memory from the specified file or directory
  `modelsEqual`(model_path1, model_path2) | Check whether two models are equal
  `movePoint`(lat1, lon1, distance, azimuth) | Find point B that is the specified distance and azimuth from point A.
  `saveVelocityModel`(modelFileName[, modelFormat]) | Save the velocity model currently in memory to the specified file or directory.
  `setActiveNodeData`(nodeId, depths, pvelocity, ...) | Modify the depth, velocity and gradient information associated with a specified active node in the Grid.
  `setAverageMantleVelocity`(waveType, velocity) | Set the average P or S wave mantle velocity.
  `setCHMax`(CH_MAX) | Set the current value of CH_MAX.
  `setDelDepth`(delDepth) | Change the value of step change in depth used to compute depth derivatives.
  `setDelDistance`(delDistance) | Change the value of step change in distance used to compute horizontal derivatives.
  `setGridData`(nodeId, depths, pvelocity, ...) | Modify the depth, velocity and gradient information associated with a specified node in the Grid.
  `setInterpolatorType`(interpolatorType) | Specify the interpolation type to use.
  `setMaxDepth`(maxDepth) | Set the maximum source depth for Pn/Sn phase.
  `setMaxDistance`(maxDistance) | Set the maximum source-receiver separation for Pn/Sn phase.
  `setPathIncrement`(pathIncrement) | Set the desired spacing of great circle nodes along the head wave interface.
  `toString`([verbosity]) | Returns a human-readable string representation of the GreatCircle

  clear()

    Delete the current GreatCircle object from memory and clear the pool of stored CrustalProfile objects.

    The Grid object owned by `SlbmInterface` stores a vector of map objects which associates the phase and Location of a CrustalProfile object with a pointer to the instance of the CrustalProfile. When `createGreatCircle()` is called with a latitude, longitude, and depth which has been used before, the Grid object will return a pointer to the existing CrustalProfile object, thereby enhancing performance. This vector of maps is cleared when `clear()` is called. The implications of all this is that applications that loop over many calls to `createGreatCircle()` will see a performance improvement if `clear()` is not called within the loop. However, for problems with a huge number of sources and or receivers, if memory becomes an issue, applications could call `clear()` within the loop to save memory.

    Return type:

      `None`

    Examples

        >>> slbm.clear()

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  clearActiveNodes()

    Clear all active nodes.

    Return type:

      `None`

    Examples

        >>> slbm.clearActiveNodes()

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  clearNodeHitCount()

    Clear the node hit count by setting the hit count of every node to zero.

    Return type:

      `None`

    Examples

        >>> slbm.clearNodeHitCount()

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  createGreatCircle(phase, srcLatRad, srcLonRad, srcDepKm, rcvLatRad, rcvLonRad, rcvDepKm)

    Instantiate a new GreatCircle between two locations.

    Instantiate a new GreatCircle objecr between a source and a receiver. Source and receiver locations are given in latitude/longitude with units of radians. Depths are given in kilometers. The phase can be given either as a string or an integer. Accepted values are:

    > - Pn or 0

    > - Sn or 1

    > - Pg or 2

    > - Lg or 3

    Examples

        >>> slbm.createGreatCircle("Lg", srcLatRad, srcLonRad, srcDepKm, rcvLatRad, rcvLonRad, rcvDepKm)
        >>> slbm.createGreatCircle(3, srcLatRad, srcLonRad, srcDepKm, rcvLatRad, rcvLonRad, rcvDepKm)

    Parameters:

      - phase (str or int) –

        A phase name, or associated number. Accepted values are

          - Pn or 0

          - Sn or 1

          - Pg or 2

          - Lg or 3

      - srcLatRad (float) – Source latitude, in radians

      - srcLonRad (float) – Source longitude, in radians

      - srcDepKm (float) – Source depth, in kilometers

      - rcvLatRad (float) – Receiver latitude, in radians

      - rcvLonRad (float) – Receiver longitude, in radians

      - rcvDepKm (float) – Receiver depth, in kilometers

    Raises:

      - TypeError – phase isn’t an int or a str, or source/receiver locations aren’t all float

      - ValueError – An inappropriate phase was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  getActiveNodeData(nodeId)

    Retrieve information associated with a specified active node in the velocity grid.

    Retrieve the latitude, longitude, interface depths, P and S wave interval velocities and P and S mantle gradient information associated with a specified active node in the velocity grid.

    Examples

        >>> slbm.getActiveNodeData(1001)

    Parameters:

      nodeId (int) – Active node in the grid

    Return type:

      `Tuple`[`float`, `float`, `Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - latitude (float) – Latitude of the active node, in radians

      - longitude (float) – Longitude of the active node, in radians

      - depth (tuple of floats) – Depths of all the model interfaces, in kilometers

      - pvelocity (tuple of floats) – P velocities of the intervals at the active node, in kilometers per second

      - svelocity (tuple of floats) – S velocities of the intervals at the active node, in kilometers per second

      - gradient (tuple of floats) – P and S velocity gradients in the mantle, in 1/second

    Raises:

      - TypeError – nodeId isn’t an int

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getActiveNodeId(nodeId)

    Retrieve the active node ID that corresponds to a specified grid node ID.

    Examples

        >>> slbm.getActiveNodeId(1001)

    Parameters:

      nodeId (int) – Node in the grid

    Returns:

      Active node ID

    Return type:

      int

    Raises:

      - TypeError – nodeId isn’t an int

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getActiveNodeNeighborInfo(nodeId)

    Retrieve information about the nodes that surround the specified active node.

    Examples

        >>> slbm.getActiveNodeNeighborInfo(11)

    Parameters:

      nodeId (int) – Active node in the grid

    Return type:

      `Tuple`[`Tuple`[`int`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - tuple of ints – Active node neighbors of the specified active node

      - tuple of floats – Distance of active node neighbors relative to specified active node

      - tuple of floats – Azimuth of active node neighbors relative to specified active node

    Raises:

      - TypeError – nodeId isn’t an int

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getActiveNodeNeighbors(nodeId)

    Retrieve the active node IDs of the active nodes that surround the specified active node.

    Examples

        >>> slbm.getActiveNodeNeighbors(11)

    Parameters:

      nodeId (int) – Active node in the grid

    Returns:

      Active node IDs of the active nodes that surround the specified active node

    Return type:

      tuple of ints

    Raises:

      - TypeError – nodeId isn’t an int

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getActiveNodeWeights()

    Retrieve the weight assigned to each active node that was touched by the GreatCircle.

    Only nodes touched by this GreatCircle are included in the output. Each grid node is included only once, even though more than one LayerProfile object may have contributed some weight to it. The sum of all the weights will equal the horizontal distance traveled by the ray along the head wave interface, from the source pierce point to the receiver pierce point, in kilometers.

    Examples

        >>> slbm.getActiveNodeWeights()

    Return type:

      `Tuple`[`Tuple`[`int`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - tuple of ints – Active node IDs touched by this GreatCircle

      - tuple of floats – Weights of the touched active nodes, in kilometers

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getActiveNodeWeightsReceiver()

    Retrieve the weight assigned to each active node for the receiver CrustalProfile.

    > For linear interpolation, the returned number of weights will equal 3, but for natural neighbor interpolation it will be variable and less than 10.

    Examples

        >>> slbm.getActiveNodeWeightsReceiver()

    Return type:

      `Tuple`[`Tuple`[`int`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - tuple of ints – Active node IDs for the receiver CrustalProfile

      - tuple of floats – Weights of the active nodes, in kilometers

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getActiveNodeWeightsSource()

    Retrieve the weight assigned to each active node for the source CrustalProfile.

    > For linear interpolation, the returned number of weights will equal 3, but for natural neighbor interpolation it will be variable and less than 10.

    Examples

        >>> slbm.getActiveNodeWeightsReceiver()

    Return type:

      `Tuple`[`Tuple`[`int`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - tuple of ints – Active node IDs for the source CrustalProfile

      - tuple of floats – Weights of the active nodes, in kilometers

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getAverageMantleVelocity(waveType)

    Retrieve the average P or S wave mantle velocity that is specified in the model input file.

    Examples

        >>> slbm.getAverageMantleVelocity('P')

    Parameters:

      waveType (str or int) –

      Seismic wave type. Accepted values are

        - `PWAVE`, P, or 0

        - `SWAVE`, S, or 1

    Returns:

      Average mantle velocity, in kilometers per second

    Return type:

      float

    Raises:

      - TypeError – waveType isn’t an int or a str

      - ValueError – An inappropriate waveType was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getBufferSize()

    Returns the size of a DataBuffer object required to store this `SlbmInterface` object’s model data.

    Examples

        >>> slbm.getBufferSize()

    Returns:

      Size required to store this `SlbmInterface` object’s model data, in bytes

    Return type:

      int

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getCHMax()

    Retrieve the current value of CH_MAX.

    This call retrieves global parameter `CH_MAX`. Alternatively, this parameter may be retrieved by calling it as an attribute of the current `SlbmInterface` object.

    c is the Zhao c parameter, and h is the turning depth of the ray below the Moho. The Zhao method only valid for c*h << 1. When c*h > CH_MAX, then RSTT will throw an exception.

    Examples

        >>> slbm.getCHMax()

        >>> slbm.CH_MAX

    Returns:

      Global `CH_MAX` parameter

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getClassCount()

    Retrieve a table that lists the number of instances of various RSTT classes that are currently instantiated.

    Very useful for debugging memory leaks.

    Examples

        >>> slbm.getClassCount()

    Returns:

      Table that lists the number of currently-initiated classes

    Return type:

      str

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getDelDepth()

    Retrieve the value of step change in depth used to compute depth derivatives

    Examples

        >>> slbm.getDelDepth()

    Returns:

      Del depth, in kilometers

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getDelDistance()

    Retrieve the value of step change in distance used to compute horizontal derivatives

    Examples

        >>> slbm.getDelDistance()

    Returns:

      Del distance, in radians

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getDistAz(lat1Rad, lon1Rad, lat2Rad, lon2Rad)

    Compute distance and azimuth between two points.

    Computed distance will range between 0 and pi, and azimuth will range from -pi to pi.

    Examples

        >>> slbm.getDistAz(0.1, 0., 0.082, 0.)

    Parameters:

      - lat1Rad (float) – Latitude of starting location, in radians

      - lon1Rad (float) – Longitude of starting location, in radians

      - lat2Rad (float) – Latitude of ending location, in radians

      - lon2Rad (float) – Longitude of ending location, in radians

    Return type:

      `Tuple`[`float`, `float`]

    Returns:

      - distance (float) – Distance between the two specified locations, in radians

      - azimuth (float) – Azimuth between the two specified locations, in radians

    Raises:

      - TypeError – Specified Lat/lon locations aren’t all float

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getDistance()

    Retrieve the source-receiver separation.

    Examples

        >>> slbm.getDistance()

    Returns:

      The Source-receiver separation, in radians

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getFractionActive()

    Retrieve the fraction of the path length of the current GreatCircle object that is within the currently-defined active region.

    Examples

        >>> slbm.getFractionActive()

    Returns:

      Fraction of path length in active region

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getGreatCircleData()

    Retrieve information about the great circle path.

    Retrieve information about the great circle path including the interface depths at source and receiver, the velocity profiles at the source and receiver, and mantle velocity and velocity gradient at points along the great circle path from source pierce point to receiver pierce point.

    The first horizontal segment starts at the source, the last horizontal segment ends at the receiver, and each one is of size actual_path_increment. The head wave velocities are interpolated at the center of each of these horizontal segments, just below the head wave interface.

    Examples

        >>> slbm.getGreatCircleData()

    Return type:

      `Tuple`[`str`, `float`, `Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `int`, `Tuple`[`float`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - phase (str) – The phase supported by the current GreatCircle

      - actual_path_increment (float) – Horizontal separation of the LayerProfile objects along the head wave interface, in radians

      - sourceDepth (tuple of floats) – Depths of all the model interfaces below the source, in kilometers

      - sourceVelocity (tuple of floats) – P or S velocity of each interval below the source, in kilometers per second

      - receiverDepth (tuple of floats) – Depths of all the model interfaces below the receiver, in kilometers

      - receiverVelocity (tuple of floats) – P or S velocity of each interval below the receiver, in kilometers per second

      - npoints (int) – Nunber of points along the headwave path where velocity and gradient values are interpolated

      - headWaveVelocity (tuple of floats) – P or S velocity at the center of each horizontal segment between the source and the receiver, in kilometers per seconds

      - gradient (tuple of floats) – P or S velocity gradient in the mantle at the center of each horizontal segment of the head wave, in 1/seconds

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getGreatCircleLocations()

    Retrieve the latitudes, longitudes and depths of all the profile positions along the headwave interface.

    Profile positions are located at the center of each segment of the head wave interface between the source and receiver. The first position is located actual_path_increment/2 radians from the source, the last profile position is located actual_path_increment/2 radians from the receiver, and the others are spaced actual_path_increment radians apart.

    Examples

        >>> slbm.getGreatCircleLocations()

    Return type:

      `Tuple`[`Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - latitude (tuple of floats) – Latitude at the center of each headwave segment, in radians

      - longitude (tuple of floats) – Longitude at the center of each headwave segment, in radians

      - depth (tuple of floats) – Depth of the headwave interface at the center of each headwave segment, in kilometers

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getGreatCircleNodeInfo()

    Retrieve information about the interpolated points along the headwave path.

    Examples

        >>> slbm.getGreatCircleNodeInfo()

    Return type:

      `Tuple`[`Tuple`[`Tuple`[`int`, `...`], `...`], `Tuple`[`Tuple`[`float`, `...`], `...`]]

    Returns:

      - neighbors (tuple of tuples of ints) – Ragged 2D array of ints with dimensions npoints x nnodes containing the nodeIds of the neighboring grid nodes used to derive the interpolated data at each head wave profile

      - coefficients (tuple of tuples of doubles) – Ragged 2D array of doubles with dimensions npoints x nnodes containing the interpolation coefficients applied to each element of neighbors

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getGreatCirclePoints(lat1Rad, lon1Rad, lat2Rad, lon2Rad, npoints)

    Retrieve an array of latitude/longitude points along a great circle path between two specified points.

    The great circle path between the two points is divided into npoints-1 equal size cells and the computed points are located at the boundaries of those cells. First point will coincide with the startnig point and last point with the ending point.

    Examples

        >>> slbm.getGreatCirclePoints(0.1, 0., 0.082, 0., 10)

    Parameters:

      - lat1Rad (float) – Latitude of starting location, in radians

      - lon1Rad (float) – Longitude of starting location, in radians

      - lat2Rad (float) – Latitude of ending location, in radians

      - lon2Rad (float) – Longitude of ending location, in radians

      - npoints (int) – The desired number of points along the great circle

    Return type:

      `Tuple`[`Tuple`[`float`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - latitudes (tuple of floats) – The latitudes of the points along the great circle, in radians

      - longitudes (tuple of floats) – The longitudes of the points along the great circle, in radians

    Raises:

      - TypeError – Specified Lat/lon locations aren’t all float

      - ValueError – An inappropriate number of points was requested

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getGreatCirclePointsOnCenters(lat1Rad, lon1Rad, lat2Rad, lon2Rad, npoints)

    Retrieve an array of latitude/longitude points along a great circle path between two specified points.

    The great circle path between the two points is divided into npoints-1 equal size cells and the computed points are located at the centers of those cells. First point will coincide with the startnig point and last point with the ending point.

    Examples

        >>> slbm.getGreatCirclePointsOnCenters(0.1, 0., 0.082, 0., 10)

    Parameters:

      - lat1Rad (float) – Latitude of starting location, in radians

      - lon1Rad (float) – Longitude of starting location, in radians

      - lat2Rad (float) – Latitude of ending location, in radians

      - lon2Rad (float) – Longitude of ending location, in radians

      - npoints (int) – The desired number of points along the great circle

    Return type:

      `Tuple`[`Tuple`[`float`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - latitudes (tuple of floats) – The latitudes of the points along the great circle, in radians

      - longitudes (tuple of floats) – The longitudes of the points along the great circle, in radians

    Raises:

      - TypeError – Specified Lat/lon locations aren’t all float

      - ValueError – An inappropriate number of points was requested

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getGridData(nodeId)

    Retrieve information associated with a specified node in the velocity grid.

    Retrieve the latitude, longitude, interface depths, P and S wave interval velocities and P and S mantle gradient information associated with a specified node in the velocity grid.

    Examples

        >>> slbm.getGridData(1001)

    Parameters:

      nodeId (int) – Node ID of the grid point in the model (zero based index)

    Return type:

      `Tuple`[`float`, `float`, `Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - latitude (float) – Latitude of the active node, in radians

      - longitude (float) – Longitude of the active node, in radians

      - depth (tuple of floats) – Depths of all the model interfaces, in kilometers

      - pvelocity (tuple of floats) – P velocities of the intervals at the active node, in kilometers per second

      - svelocity (tuple of floats) – S velocities of the intervals at the active node, in kilometers per second

      - gradient (tuple of floats) – P and S velocity gradients in the mantle, in 1/second

    Raises:

      - TypeError – nodeId isn’t an int

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getGridNodeId(activeNodeId)

    Retrieve the grid node ID that corresponds to a specified active node ID.

    Examples

        >>> slbm.getGridNodeId(11)

    Returns:

      Grid node ID

    Return type:

      int

    Raises:

      - TypeError – Provided node ID isn’t int

      - ValueError – An inappropriate node ID was requested

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getHeadwaveDistance()

    Retrieve the angular distance traveled by the ray below the headwave interface.

    This is the total distance minus the horizontal offsets below the source and receiver. `getSourceDistance()` + `getReceiverDistance()` + `getHeadwaveDistance()` = `getDistance()`.

    Examples

        >>> slbm.getHeadwaveDistance()

    Returns:

      Angular distance traveled by the ray below the headwave interface, in radians

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getHeadwaveDistanceKm()

    Retrieve the horizontal distance traveled by the ray below the headwave interface.

    This is the sum of actual_path_increment(i) * R(i) where actual_path_increment(i) is the angular distance traveled by the ray in each angular distance increment along the head wave interface, and R(i) is the radius of the head wave interface in that same horizontal increment.

    Examples

        >>> slbm.getHeadwaveDistanceKm()

    Returns:

      Horizontal distance traveled by the ray below the headwave interface, in kilometers

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getInterpolatedPoint(lat, lon)

    Retrieve interpolated data from the earth model at a single specified latitude/longitude.

    Examples

        >>> slbm.getInterpolatedPoint(0.1, 0.2)

    Parameters:

      - lat (float) – Latitude where information is to be interpolated, in radians

      - lon (float) – Longitude where information is to be interpolated, in radians

    Return type:

      `Tuple`[`Tuple`[`int`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `float`, `float`]

    Returns:

      - nodeIds (tuple of ints) – Node IDs of the grid nodes that were involved in the interpolation

      - coefficients (tuple of floats) – Interpolation coefficients that were applied to the information from the neighboring grid nodes

      - depth (tuple of floats) – Depths of the tops of all the model interfaces, in kilometers

      - pvelocity (tuple of floats) – P velocities of each layer of the model, in kilometers per second

      - svelocity (tuple of floats) – S velocities of each layer of the model, in kilometers per second

      - pgradient (float) – P velocity gradient in the mantle, in 1/second

      - sgradient (float) – S velocity gradient in the mantle, in 1/second

    Raises:

      - TypeError – Latitude/longitude aren’t type float

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getInterpolatedTransect(lat, lon)

    Retrieve interpolated data from the earth model along a transec defined by equal sized, 1D arrays of latitude and longitude.

    Examples

        >>> slbm.getInterpolatedTransect()

    Parameters:

      - lat (tuple of floats) – Latitudes along the transect, in radians

      - lon (tuple of floats) – Longitudes along the transect, in radians

    Return type:

      `Tuple`[`Tuple`[`Tuple`[`int`, `...`]], `Tuple`[`Tuple`[`float`, `...`]], `Tuple`[`Tuple`[`float`, `...`]], `Tuple`[`Tuple`[`float`, `...`]], `Tuple`[`Tuple`[`float`, `...`]], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`], `int`]

    Returns:

      - nodeId (tuple of tuple of ints) – Node IDs of the grid nodes that were involved in the interpolations

      - coefficients (tuple of tuple of floats) – Interpolation coefficients that were applied to the information from the neighboring grid nodes

      - depth (tuple of tuple of floats) – Depth of the tops of the interfaces in the model, in kilometers

      - pvelocity (tuple of tuple of floats) – P velocities of each layer of the model, in kilometers per second

      - svelocity (tuple of tuple of floats) – S velocities of each layer of the model, in kilometers per second

      - pgradient (tuple of floats) – Mantle P velocity gradient, in 1/seconds

      - sgradient (tuple of floats) – Mantle S velocity gradient, in 1/sec

      - nInvalid (int) – Number of points that were out of the model range

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getInterpolatorType()

    Retrieve the type of interpolator currently in use; either “LINEAR” or “NATURAL_NEIGHBOR”.

    Examples

        >>> slbm.getInterpolatorType()

    Returns:

      Type of interpolator currently in use

    Return type:

      str

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getMaxDepth()

    Retrieve the current value for the maximum source depth.

    Examples

        >>> slbm.getMaxDepth()

    Returns:

      Maximum source depth, in kilometers

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getMaxDistance()

    Retrieve the current value for the maximum source-receiver separation.

    Examples

        >>> slbm.getMaxDistance()

    Returns:

      Maximum source-receiver separation, in radians

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getModelPath()

    Return the path to the RSTT model.

    Examples

        >>> slbm.getModelPath()

    Returns:

      Path to the RSTT model

    Return type:

      str

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getModelString()

    Calls `toString()` on the RSTT model.

    Examples

        >>> slbm.getModelString()

    Returns:

      Human-readable string representation of the RSTT model

    Return type:

      str

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getNActiveNodes()

    Retrieve the number of active nodes in the Grid.

    Examples

        >>> slbm.getNActiveNodes()

    Returns:

      Number of active nodes in the Grid

    Return type:

      int

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getNGridNodes()

    Retrieve the number of Grid nodes in the Earth model.

    Examples

        >>> slbm.getNGridNodes()

    Returns:

      Returns something

    Return type:

      str

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getNHeadWavePoints()

    Retrieve the number of LayerProfile objects positioned along the head wave interface.

    Examples

        >>> slbm.getNHeadWavePoints()

    Returns:

      Number of LayerProfile objects positioned along the head wave interface

    Return type:

      int

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getNodeAzimuth(node1, node2)

    Retrieve the azimuth from node1 to node2.

    Examples

        >>> slbm.getNodeAzimuth(123, 1001)

    Parameters:

      - node1 (int) – ID of starting node

      - node2 (int) – ID of ending node

    Returns:

      Azimuth from node1 to node2

    Return type:

      float

    Raises:

      - TypeError – Specified node IDs aren’t type int

      - ValueError – Inappropriate node IDs were supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getNodeHitCount(nodeId)

    Retrieve the number of times that the specified node has been ‘touched’ by a GreatCircle object.

    The hit count of each node is initialized in the `loadVelocityModel()` method. Every time the `getWeights()` method is called for a particular GreatCircle object, all the nodeIds that contribute any weight to that GreatCircle object have their hit count incremented by one.

    Examples

        >>> slbm.getNodeHitCount(1001)

    Parameters:

      nodeId (int) – Node for which to query the hit count

    Returns:

      Number of times that the specified node has been ‘touched’

    Return type:

      int

    Raises:

      - TypeError – Specified node ID isn’t type int

      - ValueError – Inappropriate node ID was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getNodeNeighborInfo(nodeId)

    Retrieve the IDs of the nodes that surround the specified node.

    Examples

        >>> slbm.getNodeNeighborInfo(1001)

    Return type:

      `Tuple`[`Tuple`[`int`, `...`], `Tuple`[`float`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - neighbors (tuple of ints) – Neighbors of the specified node

      - distance (tuple of floats) – Distance of the neighbors to the specified node

      - azimuth (tuple of floats) – Azimuth of the neighbors to the specified node

    Raises:

      - TypeError – Specified node ID isn’t type int

      - ValueError – Inappropriate node ID was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getNodeNeighbors(nodeId)

    Retrieve the IDs of the nodes that surround the specified node.

    Examples

        >>> slbm.getNodeNeighbors(1001)

    Returns:

      Returns something

    Return type:

      int

    Raises:

      - TypeError – Specified node ID isn’t type int

      - ValueError – Inappropriate node ID was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getNodeSeparation(node1, node2)

    Retrieve the angular separation of two grid nodes.

    Examples

        >>> slbm.getNodeSeparation(123, 1001)

    Returns:

      Angular separation of node1 and node2, in radians

    Return type:

      float

    Raises:

      - TypeError – Specified node IDs aren’t type int

      - ValueError – Inappropriate node IDs were supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getPathIncrement()

    Retrieve the current value of the spacing of great circle nodes along the head wave interface.

    The actual spacing will be reduced from the requested value in order that an integral number of equally spaced LayerProfile objects will exactly span the source-receiver separation.

    The default value is 0.1 degrees.

    Examples

        >>> slbm.getPathIncrement()

    Returns:

      Spacing of the great circle nodes along the head wave interface, in radians

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getPgLgComponents()

    Retrieve information about Pg/Lg travel time calculations.

    This method only returns useful information when the phase is Pg or Lg.

    tTotal will be exactly equal to the lesser of tTaup or tHeadwave.

    Examples

        >>> slbm.getPgLgComponents()

    Returns:

      - tTotal (float) – Total travel time, in seconds

      - tTaup (float) – TauP travel time, in seconds

      - tHeadwave (float) – Headwave travel time, in seconds

      - pTaup (float) – TauP ray parameter

      - pHeadwave (float) – Headwave ray parameter

      - trTaup (float) – Radius at which the taup ray turned, in kilometers

      - trHeadwave (float) – Radius at which the headwave ray turned, in kilometers

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getPhase()

    Retrieve the phase specified in last call to `createGreatCircle()`.

    Examples

        >>> slbm.getPhase()

    Returns:

      The phase specified in last call to `createGreatCircle()`

    Return type:

      str

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getPiercePointReceiver()

    Retrieve the location of the Moho pierce point below the receiver.

    For Pg, Lg an exception is thrown.

    Examples

        >>> slbm.getPiercePointReceiver()

    Return type:

      `Tuple`[`float`, `float`, `float`]

    Returns:

      - latitude (float) – Latitude of the Moho pierce point below the receiver, in radians

      - longitude (float) – Longitude of the Moho pierce point below the receiver, in radians

      - depth (float) – Depth of the Moho pierce point below the receiver, in kilometers

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getPiercePointSource()

    Retrieve the location of the Moho pierce point below the source.

    For Pg, Lg an exception is thrown.

    Examples

        >>> slbm.getPiercePointReceiver()

    Returns:

      - latitude (float) – Latitude of the Moho pierce point below the source, in radians

      - longitude (float) – Longitude of the Moho pierce point below the source, in radians

      - depth (float) – Depth of the Moho pierce point below the source, in kilometers

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getRayParameter()

    Retrieve the ray parameter.

    Examples

        >>> slbm.getRayParameter()

    Returns:

      Ray parameter

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getReceiverDistance()

    Retrieve horizontal offset below the receiver.

    This is the angular distance between the location of the receiver and the receiver pierce point where the ray impinged on the headwave interface.

    Examples

        >>> slbm.getReceiverDistance()

    Returns:

      Horizontal offset below the receiver, in radians

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getSlowness()

    Retrieve the horizontal slowness (i.e., the derivative of travel time with respect to receiver-source distance).

    Examples

        >>> slbm.getSlowness()

    Returns:

      Horizontal slownessm in seconds/radian

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getSlownessUncertainty()

    Retrieve uncertainty of the horizontal slowness using the phase and distance specified in last call to `getGreatCircle()`.

    Examples

        >>> slbm.getSlownessUncertainty()

    Returns:

      Uncertainty of the horizontal slowness, in seconds per radian

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getSourceDistance()

    Retrieve horizontal offset below the source.

    This is the angular distance between the location of the source and the source pierce point where the ray impinged on the headwave interface.

    Examples

        >>> slbm.getSourceDistance()

    Returns:

      Horizontal offset below the source, in radians

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getTessId()

    Retrieve the tessellation ID of the model currently in memory.

    Examples

        >>> slbm.getTessId()

    Returns:

      Tessellation ID of the model currently in memory

    Return type:

      str

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getTravelTime()

    Retrieve the total travel time for the GreatCircle.

    Examples

        >>> slbm.getTravelTime()

    Returns:

      Total travel time for the GreatCircle, in seconds

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getTravelTimeComponents()

    Retrieve the total travel time and the four components that contribute to it for the current GreatCircle.

    Examples

        >>> slbm.getTravelTimeComponents()

    Return type:

      `Tuple`[`float`, `float`, `float`, `float`, `float`]

    Returns:

      - tTotal (float) – Total travel time, in seconds

      - tSource (float) – Crustal travel time below the source, in seconds

      - tReceiver (float) – Crustal travel time below the receiver, in seconds

      - tHeadwave (float) – Head wave travel time, in seconds

      - tGradient (float) – Zhao gradient correction term, in seconds

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getTravelTimeUncertainty(useRandomError=False)

    Returns the path-dependent travel time uncertainty (PDU), in seconds

    Returns the path-dependent travel time uncertainty (PDU) for the GreatCircle, in seconds. Path-dependent uncertainty is computed with model error, bias, and (optionally) random error (Begnaud et al., 2020). By default, random error is not used in the computation.

    Examples

        >>> slbm.getTravelTimeUncertainty()
        3.9911

    Use the random error values in the uncertainty calculation

        >>> slbm.getTravelTimeUncertainty(True)
        4.0463

    Parameters:

      useRandomError (bool) – Determines whether or not random error is used in the travel time uncertainty computation.

    Returns:

      Returns the path-dependent travel time uncertainty (PDU), in seconds

    Return type:

      float

    Raises:

      - TypeError – useRandomError is not a a bool, or too many arguments were supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getTravelTimeUncertainty1D()

    Returns the path-independent travel time uncertainty (PIU), in seconds

    Returns the path-independent travel time uncertainty (PIU) for the GreatCircle, in seconds. This was the standard uncertainty computation prior to RSTT v3.1.0.

    Examples

        >>> slbm.getTravelTimeUncertainty()
        1.1542

    Returns:

      Returns the path-independent travel time uncertainty (PIU), in seconds

    Return type:

      float

    Raises:

      - TypeError – Too many arguments were supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getTravelTimeUncertaintyPDU(useRandomError=False)

    Returns the path-dependent travel time uncertainty (PDU), in seconds

    Returns the path-dependent travel time uncertainty (PDU) for the GreatCircle, in seconds. Path-dependent uncertainty is computed with model error, bias, and (optionally) random error (Begnaud et al., 2020). By default, random error is not used in the computation.

    Examples

        >>> slbm.getTravelTimeUncertainty()
        3.9911

    Use the random error values in the uncertainty calculation

        >>> slbm.getTravelTimeUncertainty(True)
        4.0463

    Parameters:

      useRandomError (bool) – Determines whether or not random error is used in the travel time uncertainty computation.

    Returns:

      Returns the path-dependent travel time uncertainty (PDU), in seconds

    Return type:

      float

    Raises:

      - TypeError – useRandomError is not a a bool, or too many arguments were supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getTravelTimeUncertaintyPIU()

    Returns the path-independent travel time uncertainty (PIU), in seconds

    Returns the path-independent travel time uncertainty (PIU) for the GreatCircle, in seconds. This was the standard uncertainty computation prior to RSTT v3.1.0.

    Examples

        >>> slbm.getTravelTimeUncertainty()
        1.1542

    Returns:

      Returns the path-independent travel time uncertainty (PIU), in seconds

    Return type:

      float

    Raises:

      - TypeError – Too many arguments were supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getTurningRadius()

    Retrieve the turning radius of the ray.

    Examples

        >>> slbm.getTurningRadius()

    Returns:

      Turning radius of the ray

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getUncertaintyFileFormat(phase, attribute)

    Return path-independent uncertainty information related to the specified phase and attribute in the format of an ASCII model.

    Examples

        >>> slbm.getUncertaintyFileFormat(0, 1)

        >>> slbm.getUncertaintyFileFormat('Pn', 'SH')

    Parameters:

      - phase (int or str) –

        A phase name, or associated number. Accepted values are

          - Pn or 0

          - Sn or 1

          - Pg or 2

          - Lg or 3

      - attribute (int or str) –

        An attribute name, or associated number. Accepted values are

          - TT or 0

          - SH or 1

          - AZ or 2

    Returns:

      Path-independent uncertainty information related to the specified phase and attribute.

    Return type:

      str

    Raises:

      - TypeError – phase or attribute aren’t an int or a str

      - ValueError – An inappropriate phase or attribute was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getUncertaintyTable(phase, attribute)

    Return path-independent uncertainty information related to the specified phase and attribute in a table format.

    Examples

        >>> slbm.getUncertaintyTable(0, 1)

        >>> slbm.getUncertaintyTable('Pn', 'SH')

    Parameters:

      - phase (int or str) –

        A phase name, or associated number. Accepted values are

          - Pn or 0

          - Sn or 1

          - Pg or 2

          - Lg or 3

      - attribute (int or str) –

        An attribute name, or associated number. Accepted values are

          - TT or 0

          - SH or 1

          - AZ or 2

    Returns:

      Path-independent uncertainty information related to the specified phase and attribute.

    Return type:

      str

    Raises:

      - TypeError – phase or attribute aren’t an int or a str

      - ValueError – An inappropriate phase or attribute was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getVersion()

    Returns the RSTT version number.

    Examples

        >>> slbm.getVersion()

    Returns:

      The RSTT version number

    Return type:

      str

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getWeights()

    Retrieve the weight assigned to each grid node that was touched by the GreatCircle.

    Each grid node is included only once, even though more than one LayerProfile object may have contributed some weight to it. The sum of all the weights will equal the horizontal distance traveled by the ray along the head wave interface, from the source pierce point to the receiver pierce point, in kilometers.

    Note: This method returns active node IDs, not grid node IDs. if a grid node has weight but is not an active node, the node ID will be -1.

    Examples

        >>> slbm.getWeights()

    Return type:

      `Tuple`[`Tuple`[`int`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - nodeId (tuple of ints) – Active node IDs of all the grid nodes touched by the current GreatCircle

      - weights (tuple of floats) – Weights of all the grid nodes touched by the current GreatCircle

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getWeightsReceiver()

    Retrieve the node IDs and the interpolation coefficients for the receiver CrustalProfile.

    For linear interpolation the number of weights will equal 3, but for natural neighbor interpolation it will be variable but less than 10. The sum of the weights will equal 1.

    Examples

        >>> slbm.getWeightsReceiver()

    Return type:

      `Tuple`[`Tuple`[`int`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - nodeId (tuple of ints) – Active node IDs of all the grid nodes touched by the current GreatCircle

      - weights (tuple of floats) – Weights of all the grid nodes touched by the current GreatCircle

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getWeightsSource()

    Retrieve the node IDs and the interpolation coefficients for the source CrustalProfile.

    For linear interpolation the number of weights will equal 3, but for natural neighbor interpolation it will be variable but less than 10. The sum of the weights will equal 1.

    Examples

        >>> slbm.getWeightsSource()

    Return type:

      `Tuple`[`Tuple`[`int`, `...`], `Tuple`[`float`, `...`]]

    Returns:

      - nodeId (tuple of ints) – Active node IDs of all the grid nodes touched by the current GreatCircle

      - weights (tuple of floats) – Weights of all the grid nodes touched by the current GreatCircle

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  getZhaoParameters()

    Retrieve some of the parameters that contribute to the calculation of total travel time using the Zhao algorithm.

    This method only returns meaningful results for phases Pn and Sn.

    Examples

        >>> slbm.getZhaoParameters()

    Return type:

      `Tuple`[`float`, `float`, `float`, `float`, `float`, `int`]

    Returns:

      - Vm (float) – Velocity at the top of the mantle, averaged along the Moho between the source and receiver pierce points

      - Gm (float) – Velocity gradient at the top of the mantle, averaged along the Moho between the source and receiver pierce points

      - H (float) – Turning depth of the ray relative to the Moho

      - C (float) – Constant whose product with V0 gives the mantle velocity gradient for a flat Earth (V0 is the velocity of the top of the mantle averaged over the whole model)

      - Cm (float) – Constant whose product with Vm gives the mantle velocity gradient for a flat Earth

      - udSign (int) –

        Value indicates:

          - 0, the source is in the crust

          - +1, the ray leaves a mantle source in the downgoing direction

          - -1, the ray leaves a mantle source in an upgoing direction

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  get_dtt_ddepth()

    Retrieve the derivative of travel time with respect to source depth.

    Long description

    Examples

        >>> slbm.get_dtt_ddepth()

    Returns:

      Derivative of travel time with respect to source depth, in seconds per kilometer

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  get_dtt_ddist()

    Retrieve the horizontal slowness, i.e., the derivative of travel time with respect to receiver-source distance.

    Long description

    Examples

        >>> slbm.get_dtt_ddepth()

    Returns:

      Horizontal slowness, in seconds per radian

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  get_dtt_dlat()

    Retrieve the derivative of travel time with respect to source latitude.

    Examples

        >>> slbm.get_dtt_dlat()

    Returns:

      Derivative of travel time with respect to source latitude, in seconds per radian

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  get_dtt_dlon()

    Retrieve the derivative of travel time with respect to source longitude.

    Examples

        >>> slbm.get_dtt_dlon()

    Returns:

      Derivative of travel time with respect to source longitude, in seconds per radian

    Return type:

      float

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  initializeActiveNodes(latMinRad, lonMinRad, latMaxRad, lonMaxRad)

    Set grid nodes within a latitude/longitude range as active nodes.

    Active nodes are defined as follows: for each triangle in the tessellation, if any of the 3 nodes that define the triangle is within the range specified by this method, then all 3 nodes are defined to be active nodes. Lats and lons must be specified in radians.

    Examples

        >>> slbm.initializeActiveNodes(0., 0., 0.1, 0.1)

    Parameters:

      - latMinRad (float) – Minimum latitude, in radians

      - lonMinRad (float) – Minimum longitude, in radians

      - latMaxRad (float) – Maximum latitude, in radians

      - lonMaxRad (float) – Maximum longitude, in radians

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  isEqual(other)

    Compares the model and/or great circle loaded into this and another SlbmInteface.

    This is functionally equivalent, and maps, to the overloaded == operator which tests whether the model and/or great circle loaded by the current instantiation of SlbmInterface is equal to that of another SlbmInterface.

    Examples

        >>> slbm1 = SlbmInterface()
        >>> slbm2 = SlbmInterface()
        >>> slbm1.loadVelocityModel("example.geotess")
        >>> slbm2.loadVelocityModel("example.geotess")
        >>> slbm1.isEqual(slbm2)
        True
        >>> slbm1.createGreatCircle("Pn", ...)
        >>> slbm2.createGreatCircle("Pg", ...)
        >>> slbm1.isEqual(slbm2)
        False

    Parameters:

      other (SlbmInterface) – The other SlbmInterface from which to compare its model and great circle.

    Returns:

      Returns whether or not the model and (if applicable) great circle attached to the other SlbmInterface is equal to the existing one

    Return type:

      bool

    Raises:

      - TypeError – Something other than an SlbmInterface was passed to other

      - RuntimeError – The RSTT C++ library raised an exception

  isValid()

    Returns true if a GreatCircle object has been instantiated and is ready to be interrogated.

    Examples

        >>> slbm.isValid()

    Returns:

      True if a GreatCircle object has been instantiated and is ready to be interrogated.

    Return type:

      bool

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  loadVelocityModel(model_path)

    Load the velocity model into memory from the specified file or directory

    Load the velocity model into memory from the specified file or directory.

    Examples

        >>> slbm.loadVelocityModel("../models/example.geotess")

    Parameters:

      model_path (str) – Path to RSTT model, e.g., /path/to/modelfile.geotess. Relative path names are accepted.

    Raises:

      - TypeError – model_path is not a str, or too many arguments were supplied

      - FileNotFoundError – The specified model_path was not found

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  classmethod modelsEqual(model_path1, model_path2)

    Check whether two models are equal

    Examples

        >>> slbm.modelsEqual("../models/example.geotess", "../models/example.geotess")
        True

    This is also a classmethod and can be used without instantiating a new SlbmInterface object.

        >>> rstt.SlbmInterface.modelsEqual("../models/example.geotess", "../models/example.geotess")
        True

    Parameters:

      - model_path1 (str) – Path to RSTT model, e.g., /path/to/modelfile.geotess. Relative path names are accepted.

      - model_path2 (str) – Path to RSTT model, e.g., /path/to/modelfile.geotess. Relative path names are accepted.

    Raises:

      - TypeError – model_path is not a str, or too many arguments were supplied

      - FileNotFoundError – The specified model_path was not found

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `bool`

  movePoint(lat1, lon1, distance, azimuth)

    Find point B that is the specified distance and azimuth from point A.

    Examples

        >>> slbm.movePoint(0., 0., .1, 0.)

    Parameters:

      - lat1 (float) – Latitude of point A, in radians

      - lon1 (float) – longitude of point A, in radians

      - distance (float) – Angular distance from point A to point B, in radians

      - azimuth (float) – Azimuth from pointA to point B, clockwise from north, in radians

    Return type:

      `Tuple`[`float`, `float`]

    Returns:

      - lat2 (float) – Latitude of point B, in radians

      - lon2 (float) – longitude of point B, in radians

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

  saveVelocityModel(modelFileName, modelFormat=4)

    Save the velocity model currently in memory to the specified file or directory.

    The following formats are supported:

    > 1. SLBM version 1 ascii file. All model information is output to a single file in ascii format. This format was available in SLBM version 2, but never used.

    > 2. SLBM version 2 directory format. Model information is output to a number of different files and directories, mostly in binary format. This format was used almost exclusively in SLBM version 2.

    > 3. SLBM version 3 directory format. Model information is output to a number of different files and directories, mostly in binary format. This format is very similar to format 2 with the difference being that the model tessellation and values are stored in GeoTess format instead of the custom SLBM format.

    > 4. SLBM version 4 single-file format. This is the default and preferred format. All model information is written to a single file. If the modelFileName extension is .ascii the file is written in ascii format, otherwise it is written in binary format.

    See SLBM_Design.pdf in the main documentation directory for detailed information about model output formats. Models stored in SLBM version 1 and 2 formats (formats 1 and 2) only support linear interpolation. Models stored in SLBM version 3 formats (formats 3 and 4) support both linear and natural neighbor interpolation.

    Examples

        >>> slbm.saveVelocityModel("example.geotess")

        >>> slbm.saveVelocityModel("example.geotess", 4)

    Parameters:

      - modelFileName (str) – Full or relative path to the file or directory to which the earth model is to be written

      - modelFormat (int) – File format version of the output (default = 4)

    Raises:

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  setActiveNodeData(nodeId, depths, pvelocity, svelocity, gradient)

    Modify the depth, velocity and gradient information associated with a specified active node in the Grid.

    Examples

        >>> slbm.setActiveNodeData(11, [-2.7, ..., 36.2], [1.5, ..., 8.1],
                                       [9e-5, ..., 4.5], [0.0017, 0.0017])

    Parameters:

      - nodeId (int) – Node number of the grid point in the model

      - depths (tuple of floats) – Depths of the tops of the layers, in kilometers

      - pvelocity (tuple of floats) – P velocities of all the intervals at the specified grid node, in kilometers per second

      - svelocity (tuple of floats) – S velocities of all the intervals at the specified grid node, in kilometers per second

      - gradient (tuple of floats) – P and S velocity gradients in the mantle, in 1/second

    Raises:

      - TypeError – nodeId is not an int or remaining parameters are not lists/tuples of floats

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  setAverageMantleVelocity(waveType, velocity)

    Set the average P or S wave mantle velocity.

    Examples

        >>> slbm.setAverageMantleVelocity('P', 8.1)

        >>> slbm.setAverageMantleVelocity(0, 8.1)

    Parameters:

      - waveType (str or int) –

        Seismic wave type. Accepted values are

          - `PWAVE`, P, or 0

          - `SWAVE`, S, or 1

      - velocity (float) – P or S wave velocity that is to be set, in kilometers per second

    Raises:

      - TypeError – waveType isn’t an int or a str

      - ValueError – An inappropriate waveType was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  setCHMax(CH_MAX)

    Set the current value of CH_MAX.

    This call sets the global parameter `CH_MAX`. Alternatively, this parameter may be set by calling it as an attribute of the current `SlbmInterface` object.

    c is the Zhao c parameter, and h is the turning depth of the ray below the Moho. The Zhao method only valid for c*h << 1. When c*h > CH_MAX, then RSTT will throw an exception.

    Examples

        >>> slbm.setCHMax(0.2)

        >>> slbm.CH_MAX = 0.2

    Parameters:

      CH_MAX (float) – Global `CH_MAX` parameter

    Raises:

      - TypeError – CH_MAX isn’t a float

      - ValueError – An inappropriate CH_MAX was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  setDelDepth(delDepth)

    Change the value of step change in depth used to compute depth derivatives.

    Examples

        >>> slbm.setDelDepth(0.1)

    Parameters:

      delDepth (float) – Step change in depth, in kilometers

    Raises:

      - TypeError – delDepth isn’t a float

      - ValueError – An inappropriate delDepth was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  setDelDistance(delDistance)

    Change the value of step change in distance used to compute horizontal derivatives.

    Examples

        >>> slbm.setDelDistance(0.1)

    Parameters:

      delDistance (float) – Step change in distance, in radians

    Raises:

      - TypeError – delDistance isn’t a float

      - ValueError – An inappropriate delDistance was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  setGridData(nodeId, depths, pvelocity, svelocity, gradient)

    Modify the depth, velocity and gradient information associated with a specified node in the Grid.

    Examples

        >>> slbm.setGridData(11, [-2.7, ..., 36.2], [1.5, ..., 8.1],
                                 [9e-5, ..., 4.5], [0.0017, 0.0017])

    Parameters:

      - nodeId (int) – Node number of the grid point in the model

      - depths (tuple of floats) – Depths of the tops of the layers, in kilometers

      - pvelocity (tuple of floats) – P velocities of all the intervals at the specified grid node, in kilometers per second

      - svelocity (tuple of floats) – S velocities of all the intervals at the specified grid node, in kilometers per second

      - gradient (tuple of floats) – P and S velocity gradients in the mantle, in 1/second

    Raises:

      - TypeError – nodeId is not an int or remaining parameters are not lists/tuples of floats

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  setInterpolatorType(interpolatorType)

    Specify the interpolation type to use.

    With models loaded in the old RSTT formats 1 and 2, ‘linear’ is the only option allowed.

    Examples

        >>> slbm.setInterpolatorType('natural_neighbor')

    Parameters:

      interpolatorType (str) –

      Interpolation type, accepted values are:

        - linear

        - natural_neighbor

    Raises:

      - TypeError – interpolatorType is not a str, or too many arguments were supplied

      - ValueError – An inappropriate interpolatorType value was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  setMaxDepth(maxDepth)

    Set the maximum source depth for Pn/Sn phase.

    Examples

        >>> slbm.setMaxDepth(200.)

    Parameters:

      maxDepth (float) – Maximum source depth for Pn/Sn phase, in kilometers

    Raises:

      - TypeError – maxDepth is not a float, or too many arguments were supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  setMaxDistance(maxDistance)

    Set the maximum source-receiver separation for Pn/Sn phase.

    Examples

        >>> slbm.setMaxDistance(0.261)

    Parameters:

      maxDistance (float) – Maximum source-receiver separation for Pn/Sn phase, in radians

    Raises:

      - TypeError – maxDistance is not a float, or too many arguments were supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  setPathIncrement(pathIncrement)

    Set the desired spacing of great circle nodes along the head wave interface.

    The actual spacing will be reduced from the requested value in order that an integral number of equally spaced LayerProfile objects will exactly span the source-receiver separation.

    Defaults to 0.1 degrees if not specified.

    Examples

        >>> slbm.setPathIncrement(0.00174)

    Parameters:

      pathIncrement (float) – Desired spacing of great circle nodes along the head wave interface, in radians

    Raises:

      - TypeError – Provided path increment isn’t float

      - ValueError – An inappropriate path increment was requested

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred

    Return type:

      `None`

  toString(verbosity=999)

    Returns a human-readable string representation of the GreatCircle

    Returns a human-readable string representation of the currently-instantiated GreatCircle object. The amount of information that is to be included in the return string is given by the verbosity parameter. Each verbosity level includes all information in preceeding levels.

    > 0. Nothing, an empty string is returned

    > 1. Total distance and travel time summary

    > 2. Gradient correction information for Pn/Sn, nothing for Pg/Lg

    > 3. Source and receiver CrustalProfile information

    > 4. Grid node weights

    > 5. Head wave interface profiles

    > 6. Interpolation coefficients for great circle nodes on the head wave interface

    > 7. Node hit count and node neighbors for every node touched by any GreatCircle instantiated by this instance of SlbmInterface

    Examples

        >>> slbm.toString()
        >>> slbm.toString(3)

    Parameters:

      verbosity (int) – Specifies the amount of information that is to be included in the return string. Each verbosity level includes all information in preceeding verbosity levels.

    Returns:

      Returns a human-readable string representation of the currently-instantiated GreatCircle object

    Return type:

      str

    Raises:

      - TypeError – verbosity is not an int, or too many arguments were supplied

      - ValueError – An inappropriate verbosity value was supplied

      - RuntimeError – The RSTT C++ library raised an exception

      - Exception – An unknown exception occurred