rstt.slbminterface

class SlbmInterface(earth_radius=None)[source]

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()[source]

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.

Examples

>>> slbm.clear()
Raises
  • RuntimeError – The RSTT C++ library raised an exception

  • Exception – An unknown exception occurred

Return type

None

clearActiveNodes()[source]

Clear all active nodes.

Examples

>>> slbm.clearActiveNodes()
Raises
  • RuntimeError – The RSTT C++ library raised an exception

  • Exception – An unknown exception occurred

Return type

None

clearNodeHitCount()[source]

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

Examples

>>> slbm.clearNodeHitCount()
Raises
  • RuntimeError – The RSTT C++ library raised an exception

  • Exception – An unknown exception occurred

Return type

None

createGreatCircle(phase, srcLatRad, srcLonRad, srcDepKm, rcvLatRad, rcvLonRad, rcvDepKm)[source]

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
  • TypeErrorphase 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)[source]

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

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
  • TypeErrornodeId isn’t an int

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

  • Exception – An unknown exception occurred

Return type

Tuple[float, float, Tuple[float, …], Tuple[float, …], Tuple[float, …], Tuple[float, …]]

getActiveNodeId(nodeId)[source]

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
  • TypeErrornodeId isn’t an int

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

  • Exception – An unknown exception occurred

Return type

int

getActiveNodeNeighborInfo(nodeId)[source]

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

Examples

>>> slbm.getActiveNodeNeighborInfo(11)
Parameters

nodeId (int) – Active node in the grid

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
  • TypeErrornodeId isn’t an int

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

  • Exception – An unknown exception occurred

Return type

Tuple[Tuple[int, …], Tuple[float, …], Tuple[float, …]]

getActiveNodeNeighbors(nodeId)[source]

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
  • TypeErrornodeId isn’t an int

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

  • Exception – An unknown exception occurred

Return type

Tuple[int, …]

getActiveNodeWeights()[source]

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()
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

Return type

Tuple[Tuple[int, …], Tuple[float, …]]

getActiveNodeWeightsReceiver()[source]

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()
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

Return type

Tuple[Tuple[int, …], Tuple[float, …]]

getActiveNodeWeightsSource()[source]

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()
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

Return type

Tuple[Tuple[int, …], Tuple[float, …]]

getAverageMantleVelocity(waveType)[source]

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
  • TypeErrorwaveType 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

float

getBufferSize()[source]

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

Return type

int

getCHMax()[source]

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

Return type

float

getClassCount()[source]

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

Return type

str

getDelDepth()[source]

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

Return type

float

getDelDistance()[source]

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

Return type

float

getDistAz(lat1Rad, lon1Rad, lat2Rad, lon2Rad)[source]

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

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

Return type

Tuple[float, float]

getDistance()[source]

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

Return type

float

getFractionActive()[source]

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

Return type

float

getGreatCircleData()[source]

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()
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

Return type

Tuple[str, float, Tuple[float, …], Tuple[float, …], Tuple[float, …], Tuple[float, …], int, Tuple[float, …], Tuple[float, …]]

getGreatCircleLocations()[source]

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()
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

Return type

Tuple[Tuple[float, …], Tuple[float, …], Tuple[float, …]]

getGreatCircleNodeInfo()[source]

Retrieve information about the interpolated points along the headwave path.

Examples

>>> slbm.getGreatCircleNodeInfo()
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

Return type

Tuple[Tuple[Tuple[int, …], …], Tuple[Tuple[float, …], …]]

getGreatCirclePoints(lat1Rad, lon1Rad, lat2Rad, lon2Rad, npoints)[source]

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

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

Return type

Tuple[Tuple[float, …], Tuple[float, …]]

getGreatCirclePointsOnCenters(lat1Rad, lon1Rad, lat2Rad, lon2Rad, npoints)[source]

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

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

Return type

Tuple[Tuple[float, …], Tuple[float, …]]

getGridData(nodeId)[source]

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)

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
  • TypeErrornodeId isn’t an int

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

  • Exception – An unknown exception occurred

Return type

Tuple[float, float, Tuple[float, …], Tuple[float, …], Tuple[float, …], Tuple[float, …]]

getGridNodeId(activeNodeId)[source]

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

Return type

int

getHeadwaveDistance()[source]

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

Return type

float

getHeadwaveDistanceKm()[source]

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

Return type

float

getInterpolatedPoint(lat, lon)[source]

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

Examples

>>> slbm.getInterpolatedPoint(0.1, 0.2)
Parameters
  • latRad (float) – Latitude where information is to be interpolated, in radians

  • lonRad (float) – Longitude where information is to be interpolated, in radians

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

Return type

Tuple[Tuple[int, …], Tuple[float, …], Tuple[float, …], Tuple[float, …], Tuple[float, …], float, float]

getInterpolatedTransect(lat, lon)[source]

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

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

Return type

Tuple[Tuple[Tuple[int, …]], Tuple[Tuple[float, …]], Tuple[Tuple[float, …]], Tuple[Tuple[float, …]], Tuple[Tuple[float, …]], Tuple[float, …], Tuple[float, …], int]

getInterpolatorType()[source]

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

Return type

str

getMaxDepth()[source]

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

Return type

float

getMaxDistance()[source]

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

Return type

float

getModelPath()[source]

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

Return type

str

getModelString()[source]

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

Return type

str

getNActiveNodes()[source]

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

Return type

int

getNGridNodes()[source]

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

Return type

int

getNHeadWavePoints()[source]

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

Return type

int

getNodeAzimuth(node1, node2)[source]

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

Return type

float

getNodeHitCount(nodeId)[source]

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

Return type

int

getNodeNeighborInfo(nodeId)[source]

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

Examples

>>> slbm.getNodeNeighborInfo(1001)
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

Return type

Tuple[Tuple[int, …], Tuple[float, …], Tuple[float, …]]

getNodeNeighbors(nodeId)[source]

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

Return type

Tuple[int, …]

getNodeSeparation(node1, node2)[source]

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

Return type

float

getPathIncrement()[source]

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

Return type

float

getPgLgComponents()[source]

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()[source]

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

Return type

str

getPiercePointReceiver()[source]

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

For Pg, Lg an exception is thrown.

Examples

>>> slbm.getPiercePointReceiver()
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

Return type

Tuple[float, float, float]

getPiercePointSource()[source]

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()[source]

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

Return type

float

getReceiverDistance()[source]

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

Return type

float

getSlowness()[source]

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

Return type

float

getSlownessUncertainty()[source]

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

Return type

float

getSourceDistance()[source]

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

Return type

float

getTessId()[source]

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

Return type

str

getTravelTime()[source]

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

Return type

float

getTravelTimeComponents()[source]

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

Examples

>>> slbm.getTravelTimeComponents()
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

Return type

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

getTravelTimeUncertainty(useRandomError=False)[source]

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
  • TypeErroruseRandomError is not a a bool, or too many arguments were supplied

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

  • Exception – An unknown exception occurred

Return type

float

getTravelTimeUncertainty1D()[source]

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

Return type

float

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
  • TypeErroruseRandomError is not a a bool, or too many arguments were supplied

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

  • Exception – An unknown exception occurred

Return type

float

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

Return type

float

getTurningRadius()[source]

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

Return type

float

getUncertaintyFileFormat(phase, attribute)[source]

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
  • TypeErrorphase 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

Return type

str

getUncertaintyTable(phase, attribute)[source]

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
  • TypeErrorphase 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

Return type

str

getVersion()[source]

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

Return type

str

getWeights()[source]

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()
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

Return type

Tuple[Tuple[int, …], Tuple[float, …]]

getWeightsReceiver()[source]

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()
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

Return type

Tuple[Tuple[int, …], Tuple[float, …]]

getWeightsSource()[source]

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()
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

Return type

Tuple[Tuple[int, …], Tuple[float, …]]

getZhaoParameters()[source]

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()
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

Return type

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

get_dtt_ddepth()[source]

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

Return type

float

get_dtt_ddist()[source]

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

Return type

float

get_dtt_dlat()[source]

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

Return type

float

get_dtt_dlon()[source]

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

Return type

float

initializeActiveNodes(latMinRad, lonMinRad, latMaxRad, lonMaxRad)[source]

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)[source]

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

Return type

bool

isValid()[source]

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

Return type

bool

loadVelocityModel(model_path)[source]

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
  • TypeErrormodel_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)[source]

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
  • TypeErrormodel_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)[source]

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

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

Return type

Tuple[float, float]

saveVelocityModel(modelFileName, modelFormat=4)[source]

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)[source]

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
  • TypeErrornodeId 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)[source]

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
  • TypeErrorwaveType 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)[source]

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
  • TypeErrorCH_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)[source]

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
  • TypeErrordelDepth 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)[source]

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
  • TypeErrordelDistance 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)[source]

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
  • TypeErrornodeId 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)[source]

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
  • TypeErrorinterpolatorType 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)[source]

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
  • TypeErrormaxDepth 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)[source]

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
  • TypeErrormaxDistance 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)[source]

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)[source]

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.

  1. Nothing, an empty string is returned

  2. Total distance and travel time summary

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

  4. Source and receiver CrustalProfile information

  5. Grid node weights

  6. Head wave interface profiles

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

  8. 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
  • TypeErrorverbosity 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

Return type

str