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 theloadVelocityModel()
method. This Grid object remains in memory until theSlbmInterface
destructor is called.SlbmInterface
also maintains a single instance of a GreatCircle object which is instantiated with a call tocreateGreatCircle()
. Once instantiated, many methods can retrieve information from it, such asgetTravelTime()
,getTravelTimeComponents()
,getWeights()
, and more. The GreatCircle can be interrogated until it is replaced with another GreatCircle by a subsequent call tocreateGreatCircle()
, or it is deleted byclear()
.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.
Clear all active nodes.
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.
Retrieve the weight assigned to each active node that was touched by the GreatCircle.
Retrieve the weight assigned to each active node for the receiver CrustalProfile.
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.
Returns the size of a DataBuffer object required to store this
SlbmInterface
object’s model data.getCHMax
()Retrieve the current value of CH_MAX.
Retrieve a table that lists the number of instances of various RSTT classes that are currently instantiated.
Retrieve the value of step change in depth used to compute depth derivatives
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.
Retrieve the source-receiver separation.
Retrieve the fraction of the path length of the current GreatCircle object that is within the currently-defined active region.
Retrieve information about the great circle path.
Retrieve the latitudes, longitudes and depths of all the profile positions along the headwave interface.
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.
Retrieve the angular distance traveled by the ray below the headwave interface.
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.
Retrieve the type of interpolator currently in use; either “LINEAR” or “NATURAL_NEIGHBOR”.
Retrieve the current value for the maximum source depth.
Retrieve the current value for the maximum source-receiver separation.
Return the path to the RSTT model.
Calls
toString()
on the RSTT model.Retrieve the number of active nodes in the Grid.
Retrieve the number of Grid nodes in the Earth model.
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.
Retrieve the current value of the spacing of great circle nodes along the head wave interface.
Retrieve information about Pg/Lg travel time calculations.
getPhase
()Retrieve the phase specified in last call to
createGreatCircle()
.Retrieve the location of the Moho pierce point below the receiver.
Retrieve the location of the Moho pierce point below the source.
Retrieve the ray parameter.
Retrieve horizontal offset below the receiver.
Retrieve the horizontal slowness (i.e., the derivative of travel time with respect to receiver-source distance).
Retrieve uncertainty of the horizontal slowness using the phase and distance specified in last call to
getGreatCircle()
.Retrieve horizontal offset below the source.
Retrieve the tessellation ID of the model currently in memory.
Retrieve the total travel time for the GreatCircle.
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
Returns the path-independent travel time uncertainty (PIU), in seconds
getTravelTimeUncertaintyPDU
([useRandomError])Returns the path-dependent travel time uncertainty (PDU), in seconds
Returns the path-independent travel time uncertainty (PIU), in seconds
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.
Returns the RSTT version number.
Retrieve the weight assigned to each grid node that was touched by the GreatCircle.
Retrieve the node IDs and the interpolation coefficients for the receiver CrustalProfile.
Retrieve the node IDs and the interpolation coefficients for the source CrustalProfile.
Retrieve some of the parameters that contribute to the calculation of total travel time using the Zhao algorithm.
Retrieve the derivative of travel time with respect to source depth.
Retrieve the horizontal slowness, i.e., the derivative of travel time with respect to receiver-source distance.
Retrieve the derivative of travel time with respect to source latitude.
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. WhencreateGreatCircle()
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 whenclear()
is called. The implications of all this is that applications that loop over many calls tocreateGreatCircle()
will see a performance improvement ifclear()
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 callclear()
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
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)[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
TypeError – nodeId 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
TypeError – nodeId 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
TypeError – nodeId 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
TypeError – nodeId 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 0SWAVE
, 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
- 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 currentSlbmInterface
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
TypeError – nodeId 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 thegetWeights()
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
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
- 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
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
- 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
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
- 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
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
- 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
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)[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
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)[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:
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.
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.
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.
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
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)[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 0SWAVE
, 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)[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 currentSlbmInterface
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)[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
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)[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
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)[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
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)[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
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)[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
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)[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
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)[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.
Nothing, an empty string is returned
Total distance and travel time summary
Gradient correction information for Pn/Sn, nothing for Pg/Lg
Source and receiver CrustalProfile information
Grid node weights
Head wave interface profiles
Interpolation coefficients for great circle nodes on the head wave interface
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
- Return type
str