RSTT: rstt/SLBM_C_shell/include/slbm_C_shell.h File Reference

RSTT 3.1.0 Regional Seismic Travel Time

Macros | Functions
slbm_C_shell.h File Reference

Go to the source code of this file.

## Macros
#define | SLBM_LIB
#define | WATER 0
#define | SEDIMENT1 1
#define | SEDIMENT2 2
#define | SEDIMENT3 3
#define | UPPER_CRUST 4
#define | MIDDLE_CRUST_N 5
#define | MIDDLE_CRUST_G 6
#define | LOWER_CRUST 7
#define | MANTLE 8
#define | NLAYERS 9

## Functions
SLBM_LIB int | slbm_shell_getVersion (char *str)
| Retrieve the SLBM Version number. More...
SLBM_LIB int | slbm_shell_getErrorMessage (char *str)
| Retrieve last error message. More...
SLBM_LIB int | slbm_shell_create ()
| Instantiate a SLBM Interface object. More...
SLBM_LIB int | slbm_shell_create_fixedEarthRadius (double *radius)
| Instantiate a SLBM Interface object with fixed earth radius. More...
SLBM_LIB int | slbm_shell_delete ()
| Deletes the SlbmInterface object instantiated with the call slbm_shell_create(). More...
SLBM_LIB int | slbm_shell_loadVelocityModelBinary (const char *modelDirectory)
| Load the velocity model into memory from the specified file or directory. This method automatically determines the format of the model. More...
SLBM_LIB int | slbm_shell_specifyOutputDirectory (const char *directoryName)
| Deprecated. Use saveVelocityModel() instead. Specify the directory into which the model that is currently in memory should be written the next time that saveVelocityModelBinary() is called. More...
SLBM_LIB int | slbm_shell_saveVelocityModelBinary ()
| Deprecated. Use saveVelocityModel() instead. Write the model in format 3 to directory previously specified with a call to specifyOutputDirectory(). More...
SLBM_LIB int | slbm_shell_loadVelocityModel (const char *modelPath)
| Load the velocity model into memory from the specified file or directory. This method automatically determines the format of the model. More...
SLBM_LIB int | slbm_shell_saveVelocityModelFormat (const char *modelFileName, int format)
| Save the velocity model currently in memory to the specified file or directory. More...
SLBM_LIB int | slbm_shell_saveVelocityModel (const char *modelFileName)
| Save the velocity model currently in memory to the specified file. More...
SLBM_LIB int | slbm_shell_createGreatCircle (char *phase, double *sourceLat, double *sourceLon, double *sourceDepth, double *receiverLat, double *receiverLon, double *receiverDepth)
| Instantiate a new GreatCircle object between two locations. More...
SLBM_LIB int | slbm_shell_isValid ()
| Returns true if the current GreatCirlce object has been instantiated and is ready to be interrogated. More...
SLBM_LIB int | slbm_shell_clear ()
| Delete the current GreatCircle object from memory and clear the pool of stored CrustalProfile objects. The model Grid is not deleted and remains accessible. More...
SLBM_LIB int | slbm_shell_getDistance (double *dist)
| Retrieve the source-receiver separation, in radians. More...
SLBM_LIB int | slbm_shell_getSourceDistance (double *dist)
| Retrieve horizontal offset below the source, in radians. More...
SLBM_LIB int | slbm_shell_getReceiverDistance (double *dist)
| Retrieve horizontal offset below the receiver, in radians. More...
SLBM_LIB int | slbm_shell_getHeadwaveDistance (double *dist)
| Retrieve angular distance traveled by the ray below the headwave interface, in radians. More...
SLBM_LIB int | slbm_shell_getHeadwaveDistanceKm (double *dist)
| Retrieve horizontal distance traveled by the ray below the headwave interface, in radians. More...
SLBM_LIB int | slbm_shell_getTravelTime (double *travelTime)
| Retrieve the total travel time for the GreatCircle, in seconds. More...
SLBM_LIB int | slbm_shell_getTravelTimeComponents (double *tTotal, double *tSource, double *tReceiver, double *tHeadwave, double *tGradient)
| Retrieve the total travel time and the 4 components that contribute to it for the current GreatCircle. More...
SLBM_LIB int | slbm_shell_getWeights (int nodeId[], double weight[], int *nWeights)
| Retrieve the weight assigned to each grid node that was touched by the GreatCircle. More...
SLBM_LIB int | slbm_shell_getWeightsSource (int nodeids[], double weights[], int *nWeights)
| Retrieve the node IDs and the interpolation coefficients for the source CrustalProfile. More...
SLBM_LIB int | slbm_shell_getWeightsReceiver (int nodeids[], double weights[], int *nWeights)
| Retrieve the node IDs and the interpolation coefficients for the receiver CrustalProfile. More...
SLBM_LIB int | slbm_shell_toString (char *str, int verbosity)
| Returns a human-readable string representation of the GreatCircle object. More...
SLBM_LIB int | slbm_shell_getNGridNodes (int *numGridNodes)
| Retrieve the number of Grid nodes in the Earth model. More...
SLBM_LIB int | slbm_shell_getNHeadWavePoints (int *npoints)
| Retrieve the number of LayerProfile objects positioned along the head wave interface. More...
SLBM_LIB int | slbm_shell_getGridData (int *nodeId, double *latitude, double *longitude, double *depth, double *pvelocity, double *svelocity, double *gradient)
| Retrieve the lat (radians), lon (radians), interface depths (km), P and S wave interval velocities (km/sec) and P and S mantle gradient (1/sec) information associated with a specified node in the velocity grid. More...
SLBM_LIB int | slbm_shell_setGridData (int *nodeId, double *depth, double *pvelocity, double *svelocity, double *gradient)
| Modify the velocity and gradient information associated with a specified node in the Grid. More...
SLBM_LIB int | slbm_shell_getGreatCircleData (char *phase, double *path_increment, double sourceDepth[], double sourceVelocity[], double receiverDepth[], double receiverVelocity[], int *npoints, double headWaveVelocity[], double gradient[])
| Retrieve the data required for input to the travel time calculation, for the current GreatCircle object. More...
SLBM_LIB int | slbm_shell_getGreatCircleNodeInfo (int **neighbors, double **coefficients, const int *maxpoints, const int *maxnodes, int *npoints, int *nnodes)
| Retrieve information about the interpolated points along the headwave path, including the number of points, the indexes of the grid nodes that contributed to interpolation of values at the points, and the interpolation coefficients used to calculate values at the points. More...
SLBM_LIB int | slbm_shell_getInterpolatedPoint (double *lat, double *lon, int *nodeIds, double *coefficients, int *nnodes, double *depth, double *pvelocity, double *svelocity, double *pgradient, double *sgradient)
| Retrieve interpolated data from the earth model at a single specified latitude, longitude. More...
SLBM_LIB int | slbm_shell_getInterpolatedTransect (double lat[], double lon[], int *nLatLon, int **nodeId, double **coefficients, int *nNodes, double depth[][NLAYERS], double pvelocity[][NLAYERS], double svelocity[][NLAYERS], double pgradient[NLAYERS], double sgradient[NLAYERS], int *nInvalid)
| Retrieve interpolated data from the earth model along a transect defined by equal sized, 1 dimensional arrays of latitude and longitude. More...
SLBM_LIB int | slbm_shell_initializeActiveNodes (double *latmin, double *lonmin, double *latmax, double *lonmax)
| Specify the latitude and longitude range in radians for active nodes. More...
SLBM_LIB int | slbm_shell_initActiveNodesFile (char *polygonFileName)
| Specify the name of a file that contains a list of points that define a polygon that enclose the set of grid nodes that are to be considered active nodes. More...
SLBM_LIB int | slbm_shell_initActiveNodesPoints (double *lat, double *lon, int *npoints, int *inDegrees)
| Specify a list of points that define a polygon that enclose the set of grid nodes that are to be considered active nodes. More...
SLBM_LIB int | slbm_shell_getNActiveNodes (int *nNodes)
| Retrieve the number of active nodes in the Grid. More...
SLBM_LIB int | slbm_shell_clearActiveNodes ()
| Clear all active nodes. Clear all active nodes. More...
SLBM_LIB int | slbm_shell_getGridNodeId (int activeNodeId, int *gridNodeId)
| Retrieve the grid node ID that corresponds to a specified active node ID. More...
SLBM_LIB int | slbm_shell_getActiveNodeId (int gridNodeId)
| Retrieve the active node ID that corresponds to a specified grid node ID. More...
SLBM_LIB int | slbm_shell_getNodeHitCount (int *nodeId, int *hitCount)
| Retrieve the number of times that node has been 'touched' by a GreatCircle object. More...
SLBM_LIB int | slbm_shell_getNodeNeighbors (int *nid, int neighbors[], int *nNeighbors)
| Retrieve the node IDs of the nodes that surround the specified node. More...
SLBM_LIB int | slbm_shell_getNodeNeighborInfo (int *nid, int neighbors[], double distance[], double azimuth[], int *nNeighbors)
| Retrieve the node IDs of the nodes that surround the specified node. More...
SLBM_LIB int | slbm_shell_getNodeSeparation (int *node1, int *node2, double *distance)
| Retrieve the angular separation of two grid nodes, in radians. More...
SLBM_LIB int | slbm_shell_getNodeAzimuth (int *node1, int *node2, double *azimuth)
| Retrieve the azimuth from grid node1 to grid node2, radians. More...
SLBM_LIB int | slbm_shell_getTravelTimeUncertainty (int *phase, double *distance, double *uncertainty)
| Retrieve the travel time uncertainty in sec for specified phase, distance. More...
SLBM_LIB int | slbm_shell_getTTUncertainty (double *uncertainty)
| Retrieve travel time uncertainty in sec. This function will call either the path-dependent or 1D uncertainty, depending on the model file being used. More...
SLBM_LIB int | slbm_shell_getTTUncertainty_useRandErr (double *uncertainty)
| Retrieve travel time uncertainty in sec. This function will call either the path-dependent or 1D uncertainty, depending on the model file being used. This function includes randomError in the computation. More...
SLBM_LIB int | slbm_shell_getTTUncertainty1D (double *uncertainty)
| Retrieve travel time uncertainty in sec. This function will return the non-path-dependent 1D uncertainty regardless of the model in use. More...
SLBM_LIB int | slbm_shell_getSlownessUncertainty (int *phase, double *distance, double *uncert)
| Retrieve the slowness uncertainty in sec/radian for specified phase, distance. More...
SLBM_LIB int | slbm_shell_getSHUncertainty (double *slownessUncertainty)
| Retrieve uncertainty of the horizontal slowness, in seconds/radian using the phase and distance specified in last call to getGreatCircle(). More...
SLBM_LIB int | slbm_shell_getZhaoParameters (double *Vm, double *Gm, double *H, double *C, double *Cm, int *udSign)
| Retrieve some of the parameters that contribute to the calculation of of total travel time using the Zhao algorithm. More...
SLBM_LIB int | slbm_shell_getActiveNodeWeights (int nodeId[], double weight[], int *nWeights)
| Retrieve the weight assigned to each active node that was touched by the GreatCircle. More...
SLBM_LIB int | slbm_shell_getActiveNodeWeightsSource (int nodeids[], double weights[], int *nWeights)
| Retrieve the active node IDs and the interpolation coefficients for the source CrustalProfile. More...
SLBM_LIB int | slbm_shell_getActiveNodeWeightsReceiver (int nodeids[], double weights[], int *nWeights)
| Retrieve the active node IDs and the interpolation coefficients for the receiver CrustalProfile. More...
SLBM_LIB int | slbm_shell_getActiveNodeNeighbors (int *nid, int neighbors[], int *nNeighbors)
| Retrieve the node IDs of the nodes that surround the specified node. More...
SLBM_LIB int | slbm_shell_getActiveNodeNeighborInfo (int *nid, int neighbors[], double distance[], double azimuth[], int *nNeighbors)
| Retrieve the node IDs of the nodes that surround the specified node. More...
SLBM_LIB int | slbm_shell_getActiveNodeData (int *nodeId, double *latitude, double *longitude, double depth[NLAYERS], double pvelocity[NLAYERS], double svelocity[NLAYERS], double gradient[2])
| Retrieve the lat (radians), lon (radians), interface depths (km), P and S wave interval velocities (km/sec) and P and S mantle gradient (1/sec) information associated with a specified active node in the velocity grid. More...
SLBM_LIB int | slbm_shell_setActiveNodeData (int *nodeId, double depth[NLAYERS], double pvelocity[NLAYERS], double svelocity[NLAYERS], double gradient[2])
| Modify the velocity and gradient information associated with a specified active node in the Grid. More...
SLBM_LIB int | slbm_shell_setCHMax (double *chMax)
| Set the value of chMax. c is the zhao c parameter and h is the turning depth of the ray below the moho. Zhao method only valid for c*h << 1. When c*h > chMax, then slbm will throw an exception. More...
SLBM_LIB int | slbm_shell_getCHMax (double *chMax)
| Retrieve the current value of chMax. c is the zhao c parameter and h is the turning depth of the ray below the moho. Zhao method only valid for c*h << 1. When c*h > chMax, then slbm will throw an exception. More...
SLBM_LIB int | slbm_shell_getAverageMantleVelocity (int *type, double *velocity)
| Retrieve the average P or S wave mantle velocity that is specified in the model input file, in km/sec. More...
SLBM_LIB int | slbm_shell_setAverageMantleVelocity (int *type, double *velocity)
| Set the average P or S wave mantle velocity that is recorded in the model input file, in km/sec. More...
SLBM_LIB int | slbm_shell_getTessId (char *tessId)
| Retrieve the tessellation ID of the model currently in memory. More...
SLBM_LIB int | slbm_shell_getFractionActive (double *fractionActive)
| Retrieve the fraction of the path length of the current GreatCircle object that is within the currently defined active region. More...
SLBM_LIB int | slbm_shell_setMaxDistance (const double *maxDistance)
| Set the maximum source-receiver separation for Pn/Sn phase, in radians. More...
SLBM_LIB int | slbm_shell_getMaxDistance (double *maxDistance)
| Retrieve the current value for the maximum source-receiver separation, in radians. More...
SLBM_LIB int | slbm_shell_setMaxDepth (const double *maxDepth)
| Set the maximum source depth for Pn/Sn phase, in km. More...
SLBM_LIB int | slbm_shell_getMaxDepth (double *maxDepth)
| Retrieve the current value for the maximum source depth, in km. More...
SLBM_LIB int | slbm_shell_getPgLgComponents (double *tTotal, double *tTaup, double *tHeadwave, double *pTaup, double *pHeadwave, double *trTaup, double *trHeadwave)
| Retrieve information about Pg/Lg travel time calculations. More...
SLBM_LIB int | slbm_shell_getSlowness (double *slowness)
| Retrieve the horizontal slowness, i.e., the derivative of travel time wrt to receiver-source distance, in seconds/radian. More...
SLBM_LIB int | slbm_shell_get_dtt_dlat (double *dtt_dlat)
| Retrieve the derivative of travel time wrt to source latitude, in seconds/radian. More...
SLBM_LIB int | slbm_shell_get_dtt_dlon (double *dtt_dlon)
| Retrieve the derivative of travel time wrt to source longitude, in seconds/radian. More...
SLBM_LIB int | slbm_shell_get_dtt_ddepth (double *dtt_ddepth)
| Retrieve the derivative of travel time wrt to source depth, in seconds/km. More...
SLBM_LIB int | slbm_shell_getDistAz (double aLat, double aLon, double bLat, double bLon, double *distance, double *azimuth, double naValue)
| compute distance and azimuth between two points, A and B (all quantities are in radians). More...
SLBM_LIB int | slbm_shell_movePoint (double aLat, double aLon, double distance, double azimuth, double *bLat, double *bLon)
| Find point B that is the specified distance and azimuth from point A. All quantities are in radians. More...
SLBM_LIB int | slbm_shell_getGreatCircleLocations (double latitude[], double longitude[], double depth[], int *npoints)
| Retrieve the latitudes, longitudes and depths of all the profile positions along the moho. More...
SLBM_LIB int | slbm_shell_getGreatCirclePoints (double aLat, double aLon, double bLat, double bLon, int npoints, double latitude[], double longitude[])
| Retrieve an array of lat, lon points along a great circle path between two specified points, a and b. More...
SLBM_LIB int | slbm_shell_getGreatCirclePointsOnCenters (double aLat, double aLon, double bLat, double bLon, int npoints, double latitude[], double longitude[])
| Retrieve an array of lat, lon points along a great circle path between two specified points, a and b. More...
SLBM_LIB int | slbm_shell_getPiercePointSource (double *lat, double *lon, double *depth)
| Retrieve the latitude and longitude of the moho pierce point below the source, in radians. More...
SLBM_LIB int | slbm_shell_getPiercePointReceiver (double *lat, double *lon, double *depth)
| Retrieve the latitude and longitude of the moho pierce point below the receiver, in radians. More...
SLBM_LIB int | slbm_shell_getDelDistance (double *delDistance)
| Retrieve del_distance in radians. More...
SLBM_LIB int | slbm_shell_setDelDistance (double delDistance)
| Set the value of del_distance, radians. More...
SLBM_LIB int | slbm_shell_getDelDepth (double *delDepth)
| Retrieve del_depth in km. More...
SLBM_LIB int | slbm_shell_setDelDepth (double delDepth)
| Set the value of del_depth, in km. More...
SLBM_LIB int | slbm_shell_getRayParameter (double *rayParameter)
| Retrieve the ray parameter in sec/km. More...
SLBM_LIB int | slbm_shell_getTurningRadius (double *turningRadius)
| Retrieve turning radius in km. More...
SLBM_LIB int | slbm_shell_setPathIncrement (double pathIncrement)
| Set the desired spacing of great circle nodes along the head wave interface, in radians. More...
SLBM_LIB int | slbm_shell_getPathIncrement (double *pathIncrement)
| Retrieve the current value of the spacing of great circle nodes along the head wave interface, in radians. More...
SLBM_LIB int | slbm_shell_setInterpolatorType (char *interpolatorType)
| Specify the interpolation type to use, either 'linear' or 'natural_neighbor'. More...
SLBM_LIB int | slbm_shell_getInterpolatorType (char *interpolatorType)
| Retrieve the type of interpolator currently in use; either "LINEAR" or "NATUTAL_NEIGHBOR". More...
SLBM_LIB int | slbm_shell_getModelString (char *modelString, int *allocatedSize)
| Retrieve a string describing the contents of the model. Retrieve a string describing the contents of the model. More...
SLBM_LIB int | slbm_shell_getUncertaintyTable (int *phaseIndex, int *attributeIndex, char *uncertaintyTable, int *allocatedSize)
| Retrieve a conveniently formated table of the uncertainty values for the specified phaseIndex and attributeIndex. More...
SLBM_LIB int | slbm_shell_getUncertaintyTableFileFormat (int *phaseIndex, int *attributeIndex, char *uncertaintyTable, int *allocatedSize)
| Retrieve an inconveniently formated table of the uncertainty values for the specified phaseIndex and attributeIndex. More...

## Detailed Description

FILE slbm_C_shell.h

DESCRIPTION
Proto types for the SLBM C Shell Interface

A "C" Interface to the SLBM C++ library, providing access to all supported functionality.

The slbm_C_shell Interface (C++) manages a connection to the C++ SLBM library and provides C compatible functions. To make this work, 4 conditions must be met:
1) The C++ shared objects libslbm.so and libslbmCshell.so must both be accessible via the LD_LIBRARY_PATH.
2) The C application must be linked to libslbm.so and libslbmCshell.so
3) The C application must execute the command: slbm_shell_create();
4) The C application must execute the command: slbm_shell_loadVelocityModelBinary();

If all of these conditions are successfully met, then the the C application can use the slbm_C_shell interface through the shared object library libslbmCshell.so to access all the methods described in this document.

Almost all functions in the C interface return an integer error code that will be 0 if the function completed successfully or a positive error code if the function generated some sort of error. Applications should check the value of the returned error code after each function call. If the returned error code is > 0 then function slbm_shell_getErrorMessage() can be called to retrieve an errorMessage that provides information about the error. Some of the most important error codes are listed in the followng table.

Code | Function | Message
106 | Grid::reaDataBuffererFromFile | Could not open velocity model file.
200 | GreatCircle_Xg constructor | Pg/Lg not valid because source or receiver is below the Moho.
201 | GreatCircle_Xn::computeTravelTime | Source-receiver separation exceeds maximum value.
202 | GreatCircle_Xn::computeTravelTime | Source depth exceeds maximum value.
203 | GreatCircle_Xn::computeTravelTimeCrust | Horizontal offset below the source plus horizontal offset below the receiver is greater than the source-receiver separation
300 | GreatCircle_Xn::computeTravelTimeCrust | nIterations == 10000
301 | GreatCircle_Xn::computeTravelTimeCrust | c*H is greater than ch_max.
302 | GreatCircle_Xn::computeTravelTimeMantle | Could not converge on stable ray parameter.
303 | GreatCircle_Xn::computeTravelTimeMantle | search for minimum H failed.
304 | GreatCircle_Xn::computeTravelTimeMantle | c*H > ch_max.
305 | GreatCircle_Xn::brent | Too many iterations.
400 | GreatCircle_Xg::computeTravelTime | computeTravelTimeTaup() and computeTravelTimeHeadwave() both returned NA_VALUE.
401 | GreatCircle_Xn::computeTravelTime | Receiver depth below Moho is illegal.
402 | GreatCircle_Xn::computeTravelTimeCrust | Source is too close to the receiver.

The libslbmCshell.so maintains a C++ Grid object, which manages interaction with the Earth model. The Earth model is loaded by calling the loadVelocityModel(String) method, described below. This Grid object remains in memory until deleted with the command slbm_shell_delete(), or a different Earth model is loaded with another call to loadVelocityModel(String).

libslbmCshell.so also maintains a single instance of a C++ GreatCircle object which is instantiated with a call to createGreatCircle(). Once instantiated, many slbm_C_shell methods can retrieve information from this GreatCircle object, such as getTravelTime(), getWeights(), toString(int), and more. Once instantiated, the GreatCircle can be interrogated until it is replaced with another GreatCircle by a subsequent call to createGreatCircle(), or is deleted by clear().

The Grid object 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 where the number of sources and/or receivers is so large that memory becomes an issue, applications could call clear() within the loop to save memory.

All calculations assume the Earth is defined by a GRS80 ellipsoid. For a description of how points along a great circle are calculated see geovectors.pdf

Company: Sandia National Laboratories

Author: Sandy Ballard

Definition in file slbm_C_shell.h.

## Macro Definition Documentation

## ◆ LOWER_CRUST

#define LOWER_CRUST 7

Definition at line 194 of file slbm_C_shell.h.

## ◆ MANTLE

#define MANTLE 8

Definition at line 195 of file slbm_C_shell.h.

## ◆ MIDDLE_CRUST_G

#define MIDDLE_CRUST_G 6

Definition at line 193 of file slbm_C_shell.h.

## ◆ MIDDLE_CRUST_N

#define MIDDLE_CRUST_N 5

Definition at line 192 of file slbm_C_shell.h.

## ◆ NLAYERS

#define NLAYERS 9

Definition at line 196 of file slbm_C_shell.h.

## ◆ SEDIMENT1

#define SEDIMENT1 1

Definition at line 188 of file slbm_C_shell.h.

## ◆ SEDIMENT2

#define SEDIMENT2 2

Definition at line 189 of file slbm_C_shell.h.

## ◆ SEDIMENT3

#define SEDIMENT3 3

Definition at line 190 of file slbm_C_shell.h.

## ◆ SLBM_LIB

#define SLBM_LIB

Definition at line 134 of file slbm_C_shell.h.

## ◆ UPPER_CRUST

#define UPPER_CRUST 4

Definition at line 191 of file slbm_C_shell.h.

## ◆ WATER

#define WATER 0

Definition at line 187 of file slbm_C_shell.h.

## Function Documentation

## ◆ slbm_shell_clear()

SLBM_LIB int slbm_shell_clear | ( |  | ) |

Delete the current GreatCircle object from memory and clear the pool of stored CrustalProfile objects. The model Grid is not deleted and remains accessible.

Delete the current GreatCircle object from memory and clear the pool of stored CrustalProfile objects. The model Grid is not deleted and remains accessible.

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 SlbmInterface::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.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_clearActiveNodes()

SLBM_LIB int slbm_shell_clearActiveNodes | ( |  | ) |

Clear all active nodes. Clear all active nodes.

## ◆ slbm_shell_create()

SLBM_LIB int slbm_shell_create | ( |  | ) |

Instantiate a SLBM Interface object.

Instantiate a SLBM Interface object.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_create_fixedEarthRadius()

SLBM_LIB int slbm_shell_create_fixedEarthRadius | ( | double * | radius | ) |

Instantiate a SLBM Interface object with fixed earth radius.

Instantiate a SLBM Interface object fixing the earth radius to the double value passed in argument list.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_createGreatCircle()

SLBM_LIB int slbm_shell_createGreatCircle | ( | char * | phase,
|  | double * | sourceLat,
|  | double * | sourceLon,
|  | double * | sourceDepth,
|  | double * | receiverLat,
|  | double * | receiverLon,
|  | double * | receiverDepth
| ) |  |

Instantiate a new GreatCircle object between two locations.

Instantiate a new GreatCircle object between two locations.

Parameters

  phase | the phase that this GreatCircle is to support. Recognized phases are Pn, Sn, Pg and Lg.
  sourceLat | the geographic latitude of the source in radians.
  sourceLon | the longitude of source in radians.
  sourceDepth | the depth of the source in km.
  receiverLat | the geographic latitude of the receiver in radians.
  receiverLon | the longitude of the receiver in radians.
  receiverDepth | the depth of the receiver in km.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_delete()

SLBM_LIB int slbm_shell_delete | ( |  | ) |

Deletes the SlbmInterface object instantiated with the call slbm_shell_create().

Deletes the SlbmInterface object instaniated with the call slbm_shell_create().

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_get_dtt_ddepth()

SLBM_LIB int slbm_shell_get_dtt_ddepth | ( | double * | dtt_ddepth | ) |

Retrieve the derivative of travel time wrt to source depth, in seconds/km.

Retrieve the derivative of travel time wrt to source depth, in seconds/km.

Parameters

  dtt_ddepth | the derivative of travel time wrt to source depth.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_get_dtt_dlat()

SLBM_LIB int slbm_shell_get_dtt_dlat | ( | double * | dtt_dlat | ) |

Retrieve the derivative of travel time wrt to source latitude, in seconds/radian.

Retrieve the derivative of travel time wrt to source latitude, in seconds/radian.

Parameters

  dtt_dlat | the derivative of travel time wrt to source latitude.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_get_dtt_dlon()

SLBM_LIB int slbm_shell_get_dtt_dlon | ( | double * | dtt_dlon | ) |

Retrieve the derivative of travel time wrt to source longitude, in seconds/radian.

Retrieve the derivative of travel time wrt to source longitude, in seconds/radian.

Parameters

  dtt_dlon | the derivative of travel time wrt to source longitude.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getActiveNodeData()

SLBM_LIB int slbm_shell_getActiveNodeData | ( | int * | nodeId,
|  | double * | latitude,
|  | double * | longitude,
|  | double | depth[NLAYERS],
|  | double | pvelocity[NLAYERS],
|  | double | svelocity[NLAYERS],
|  | double | gradient[2]
| ) |  |

Retrieve the lat (radians), lon (radians), interface depths (km), P and S wave interval velocities (km/sec) and P and S mantle gradient (1/sec) information associated with a specified active node in the velocity grid.

Retrieve the interface depth, velocity and gradient information associated with a specified active node in the velocity grid.

Parameters

  nodeId | the active node ID of the grid point in the model (zero based index).
  latitude | the latitude of the grid node in radians.
  longitude | the longitude of the grid node in radians.
  depth | the depths of all the model interfaces, in km.
  pvelocity | an array containing the P velocities of all the intervals at the specified grid node, in km/sec.
  svelocity | an array containing the S velocities of all the intervals at the specified grid node, in km/sec.
  gradient | a 2-element array containing the P and S velocity gradients in the mantle, in 1/sec.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getActiveNodeId()

SLBM_LIB int slbm_shell_getActiveNodeId | ( | int | gridNodeId | ) |

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

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

## ◆ slbm_shell_getActiveNodeNeighborInfo()

SLBM_LIB int slbm_shell_getActiveNodeNeighborInfo | ( | int * | nid,
|  | int | neighbors[],
|  | double | distance[],
|  | double | azimuth[],
|  | int * | nNeighbors
| ) |  |

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

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

The caller must supply int array neighbors which is dimensioned large enough to hold the maximum number of neighbors that a node can have, which is 8. The actual number of neighbors is returned in nNeighbors.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getActiveNodeNeighbors()

SLBM_LIB int slbm_shell_getActiveNodeNeighbors | ( | int * | nid,
|  | int | neighbors[],
|  | int * | nNeighbors
| ) |  |

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

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

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getActiveNodeWeights()

SLBM_LIB int slbm_shell_getActiveNodeWeights | ( | int | nodeId[],
|  | double | weight[],
|  | int * | nWeights
| ) |  |

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

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

A map which associates an instance of a GridProfile object with a double weight is initialized. Then every LayerProfile on the head wave interface between the source and receiver is visited and the angular distance, d, that the ray traveled in the horizontal segment is retrieved. If d > 0, then the neighboring GridProfile objects that contributed to the interpolated value of the LayerProfile are visited. The product of d * R * C is added to the weight associated with that GridProfile object, where R is the radius of the head wave interface for the LayerProfile object being evaluated, and C is the interpolation coefficient for the GridProfile - LayerProfile pair under consideration. Then, all the GridProfile objects in the map are visited, the grid node IDs extracted into int array nodeId, and the weight extracted into double array weight.

Note: Only grid 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 km.

Parameters

  nodeId | the active node IDs of all the grid nodes touched by the current GreatCircle.
  weight | the weights of all the grid nodes touched by the current GreatCircle. Calling application must dimension this array large enough to handle any possible size.
  nWeights | the number of elements in nodeId and weight. Calling application must dimension this array large enough to handle any possible size.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getActiveNodeWeightsReceiver()

SLBM_LIB int slbm_shell_getActiveNodeWeightsReceiver | ( | int | nodeids[],
|  | double | weights[],
|  | int * | nWeights
| ) |  |

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

Retrieve the active node IDs and the interpolation coefficients for the receiver CrustalProfile. The sum of the weights will equal 1.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getActiveNodeWeightsSource()

SLBM_LIB int slbm_shell_getActiveNodeWeightsSource | ( | int | nodeids[],
|  | double | weights[],
|  | int * | nWeights
| ) |  |

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

Retrieve the active node IDs and the interpolation coefficients for the source CrustalProfile. The sum of the weights will equal 1.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getAverageMantleVelocity()

SLBM_LIB int slbm_shell_getAverageMantleVelocity | ( | int * | type,
|  | double * | velocity
| ) |  |

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

Retrieve the average P or S wave mantle velocity that is specified in the model input file. This value is used in the calculation of the Zhao c parameter.

Parameters

  type | specify either BaseObject::PWAVE or BaseObject::SWAVE.
  velocity | the P or S wave velocity is returned in this parameter, in km/sec.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getCHMax()

SLBM_LIB int slbm_shell_getCHMax | ( | double * | chMax | ) |

Retrieve the current value of chMax. c is the zhao c parameter and h is the turning depth of the ray below the moho. Zhao method only valid for c*h << 1. When c*h > chMax, then slbm will throw an exception.

Retrieve the current value of chMax. c is the zhao c parameter and h is the turning depth of the ray below the moho. Zhao method only valid for c*h << 1. When c*h > chMax, then slbm will throw an exception. This call retrieves global parameter BaseObject::ch_max

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getDelDepth()

SLBM_LIB int slbm_shell_getDelDepth | ( | double * | delDepth | ) |

Retrieve del_depth in km.

Retrieve current value of del_depth, in km. This is the vertical separation between two points used to compute the derivative of travel time with respect to depth.

Parameters

  delDepth | vertical separation in km.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getDelDistance()

SLBM_LIB int slbm_shell_getDelDistance | ( | double * | delDistance | ) |

Retrieve del_distance in radians.

Retrieve current value of del_distance, in radians. This is the horizontal separation between two points used to compute horizontal slowness and the derivative of travel time with respect to lat and lon.

Parameters

  delDistance | horizontal separation in radians.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getDistance()

SLBM_LIB int slbm_shell_getDistance | ( | double * | dist | ) |

Retrieve the source-receiver separation, in radians.

Retrieve the source-receiver separation, in radians.

Parameters

  dist | the source-receiver separation is returned in distance. If the GreatCircle is invalid, distance will equal BaseObject::NA_VALUE.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getDistAz()

SLBM_LIB int slbm_shell_getDistAz | ( | double | aLat,
|  | double | aLon,
|  | double | bLat,
|  | double | bLon,
|  | double * | distance,
|  | double * | azimuth,
|  | double | naValue
| ) |  |

compute distance and azimuth between two points, A and B (all quantities are in radians).

compute distance and azimuth between two points, A and B (all quantities are in radians). Computed distance will range between 0 and PI and azimuth will range from -PI to PI. If distance is zero, or if A is located at north or south pole, azimuth will be set to naValue.

Parameters

  aLat | the latitude of the first specified point, in radians.
  aLon | the longitude of the first specified point, in radians.
  bLat | the latitude of the second specified point, in radians.
  bLon | the longitude of the second specified point, in radians.
  distance | from point A to point B, in radians.
  azimuth | from point A to point B, in radians.
  naValue | value to return if result is invalid, in radians.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getErrorMessage()

SLBM_LIB int slbm_shell_getErrorMessage | ( | char * | str | ) |

Retrieve last error message.

Retrieves last error message. This method should be called following any function call that returns a "1" indicating an error has occurred. The string is populated with the text obtained from the SLBMException::emessage attribute.

Parameters

  str | a char pointer to contain the err message. NOTE: user should allocate storage for approximately 500 chars.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getFractionActive()

SLBM_LIB int slbm_shell_getFractionActive | ( | double * | fractionActive | ) |

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

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

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getGreatCircleData()

SLBM_LIB int slbm_shell_getGreatCircleData | ( | char * | phase,
|  | double * | path_increment,
|  | double | sourceDepth[],
|  | double | sourceVelocity[],
|  | double | receiverDepth[],
|  | double | receiverVelocity[],
|  | int * | npoints,
|  | double | headWaveVelocity[],
|  | double | gradient[]
| ) |  |

Retrieve the data required for input to the travel time calculation, for the current GreatCircle object.

Retrieve the data required for input to the travel time calculation, for the current GreatCircle object.

Parameters

  phase | the phase supported by the current GreatCircle. Will be one of Pn, Sn, Pg, Lg.
  path_increment | the actual horizontal separation of the LayerProfile objects along the head wave interface, in radians. The actual separation will be reduced from the value requested in the call to createGreatCircle() in order that some number of equal sized increments will exactly fit between the source and receiver.
  sourceDepth | the depths of all the model interfaces below the source, in km.
  sourceVelocity | the P or S velocity of each interval below the source, in km/sec.
  receiverDepth | the depths of all the model interfaces below the receiver, in km.
  receiverVelocity | the P or S velocity of each interval below the receiver, in km/sec.
  npoints | the number of horizontal increments sampled along the head wave interface. To discover this number before calling this method call getNHeadWavePoints().
  headWaveVelocity | the P or S velocity at the center of each horizontal segment between the source and the receiver, in km/sec. The first horizontal segment starts at the source, the last horizontal segment ends at the receiver, and each one is of size path_increment. The head wave velocities are interpolated at the center of each of these horizontal segments, just below the head wave interface.
  gradient | the P or S velocity gradient in the mantle at the center of each horizontal segment of the head wave, in 1/sec. For Pg and Lg, the values will be BaseObject::NA_VALUE.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getGreatCircleLocations()

SLBM_LIB int slbm_shell_getGreatCircleLocations | ( | double | latitude[],
|  | double | longitude[],
|  | double | depth[],
|  | int * | npoints
| ) |  |

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

Retrieve the latitudes, longitudes and depths of all the profile positions along the moho. 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 path_increment/2 radians from the source, the last profile position is located path_increment/2 radians from the receiver, and the others are spaced path_increment radians apart.

Parameters

  latitude | the latitude at the center of each headwave segment, in radians.
  longitude | the longitude at the center of each headwave segment, in radians.
  depth | the depth below surface of ellipsoid of the headwave interface at the center of each headwave segment, in km.
  npoints | the number of horizontal increments sampled along the head wave interface.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getGreatCircleNodeInfo()

SLBM_LIB int slbm_shell_getGreatCircleNodeInfo | ( | int ** | neighbors,
|  | double ** | coefficients,
|  | const int * | maxpoints,
|  | const int * | maxnodes,
|  | int * | npoints,
|  | int * | nnodes
| ) |  |

Retrieve information about the interpolated points along the headwave path, including the number of points, the indexes of the grid nodes that contributed to interpolation of values at the points, and the interpolation coefficients used to calculate values at the points.

Retrieve information about the interpolated points along the headwave path, including the number of points, the indexes of the grid nodes that contributed to interpolation of values at the points, and the interpolation coefficients used to calculate values at the points.

The caller must supply all of the array required by this method and retains ownership of those arrays. This method assumes the arrays have been allocated with sufficient memory to hold the requested information and simply populates the supplied arrays.

Parameters

  neighbors | a 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 | a ragged 2D array of doubles with dimensions npoints x nnodes containing the interpolation coefficients applied to each element of neighbors.
  maxpoints | the maximum size of the first dimension of arrays neighbors and coefficients. If npoints exceeds this value, an exception is thrown. 200 is a good estimate.
  maxnodes | the maximum size of the second dimension of arrays neighbors and coefficients. If any value of nnodes exceeds this value, an exception is thrown. 5 is a good estimate.
  npoints | the number of horizontal increments sampled along the head wave interface.
  nnodes | an int array of length npoints containing the number of nodes that contributed to the interpolation of information at the center of each horizontal segment of the ray path.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getGreatCirclePoints()

SLBM_LIB int slbm_shell_getGreatCirclePoints | ( | double | aLat,
|  | double | aLon,
|  | double | bLat,
|  | double | bLon,
|  | int | npoints,
|  | double | latitude[],
|  | double | longitude[]
| ) |  |

Retrieve an array of lat, lon points along a great circle path between two specified points, a and b.

Retrieve an array of lat, lon points along a great circle path between two specified points. The great circle path between a and b 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 point a and last point with point b.

Parameters

  aLat | the latitude of the first specified point, in radians.
  aLon | the longitude of the first specified point, in radians.
  bLat | the latitude of the second specified point, in radians.
  bLon | the longitude of the second specified point, in radians.
  npoints | the desired number of points along the great circle, in radians.
  latitude | the latitudes of the points along the great circle, in radians.
  longitude | the longitudes of the points along the great circle, in radians.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getGreatCirclePointsOnCenters()

SLBM_LIB int slbm_shell_getGreatCirclePointsOnCenters | ( | double | aLat,
|  | double | aLon,
|  | double | bLat,
|  | double | bLon,
|  | int | npoints,
|  | double | latitude[],
|  | double | longitude[]
| ) |  |

Retrieve an array of lat, lon points along a great circle path between two specified points, a and b.

Retrieve an array of lat, lon points along a great circle path between two specified points. The great circle path between a and b is divided into npoints equal size cells and the computed points are located at the centers of those cells.

Parameters

  aLat | the latitude of the first specified point, in radians.
  aLon | the longitude of the first specified point, in radians.
  bLat | the latitude of the second specified point, in radians.
  bLon | the longitude of the second specified point, in radians.
  npoints | the desired number of points along the great circle
  latitude | the latitudes of the points along the great circle, in radians.
  longitude | the longitudes of the points along the great circle, in radians.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getGridData()

SLBM_LIB int slbm_shell_getGridData | ( | int * | nodeId,
|  | double * | latitude,
|  | double * | longitude,
|  | double * | depth,
|  | double * | pvelocity,
|  | double * | svelocity,
|  | double * | gradient
| ) |  |

Retrieve the lat (radians), lon (radians), interface depths (km), P and S wave interval velocities (km/sec) and P and S mantle gradient (1/sec) information associated with a specified node in the velocity grid.

Retrieve the interface depth, velocity and gradient information associated with a specified node in the velocity grid.

Parameters

  nodeId | the node ID of the grid point in the model (zero based index).
  latitude | the latitude of the grid node in radians.
  longitude | the longitude of the grid node in radians.
  depth | the depths of all the model interfaces, in km.
  pvelocity | an array containing the P velocities of all the intervals at the specified grid node, in km/sec.
  svelocity | an array containing the S velocities of all the intervals at the specified grid node, in km/sec.
  gradient | a 2-element array containing the P and S velocity gradients in the mantle, in 1/sec.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getGridNodeId()

SLBM_LIB int slbm_shell_getGridNodeId | ( | int | activeNodeId,
|  | int * | gridNodeId
| ) |  |

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

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

## ◆ slbm_shell_getHeadwaveDistance()

SLBM_LIB int slbm_shell_getHeadwaveDistance | ( | double * | dist | ) |

Retrieve angular distance traveled by the ray below the headwave interface, in radians.

Retrieve the angular distance traveled by the ray below the headwave interface, in radians. This is the total distance minus the horizontal offsets below the source and receiver. getSourceDistance() + getReceiverDistance() + getHeadwaveDistance() = getDistance().

Parameters

  dist | the angular distance traveled by the ray below the headwave interface, in radians.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getHeadwaveDistanceKm()

SLBM_LIB int slbm_shell_getHeadwaveDistanceKm | ( | double * | dist | ) |

Retrieve horizontal distance traveled by the ray below the headwave interface, in radians.

Retrieve horizontal distance traveled by the ray below the headwave interface, in km. This is the sum of path_increment(i) * R(i) where 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.

Parameters

  dist | the horizontal distance traveled by the ray below the headwave interface, in km.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getInterpolatedPoint()

SLBM_LIB int slbm_shell_getInterpolatedPoint | ( | double * | lat,
|  | double * | lon,
|  | int * | nodeIds,
|  | double * | coefficients,
|  | int * | nnodes,
|  | double * | depth,
|  | double * | pvelocity,
|  | double * | svelocity,
|  | double * | pgradient,
|  | double * | sgradient
| ) |  |

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

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

Parameters

  lat | the latitude where information is to be interpolated, in radians.
  lon | the longitude where information is to be interpolated, in radians.
  nodeIds | the nodeIds of the grid nodes that were involved in the interpolation.
  coefficients | the interpolation coefficients that were applied to the information from the neighboring grid nodes.
  nnodes | an integer value specifying number of grid nodes that contributed to interpolation of values at this point.
  depth | the depths of the tops of the interfaces in the Earth model, in km. There will be one of these for each layer of the model.
  pvelocity | the P velocities of each layer of the model, in km/sec.
  svelocity | the S velocities of each layer of the model, in km/sec.
  pgradient | the mantle P velocity gradient, in 1/sec.
  sgradient | the mantle S velocity gradient, in 1/sec.

Returns
  true if successful. If not successful, nodeIds are all -1 and all other returned arrays are populated with BaseObject::NA_VALUE.
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getInterpolatedTransect()

SLBM_LIB int slbm_shell_getInterpolatedTransect | ( | double | lat[],
|  | double | lon[],
|  | int * | nLatLon,
|  | int ** | nodeId,
|  | double ** | coefficients,
|  | int * | nNodes,
|  | double | depth[][NLAYERS],
|  | double | pvelocity[][NLAYERS],
|  | double | svelocity[][NLAYERS],
|  | double | pgradient[NLAYERS],
|  | double | sgradient[NLAYERS],
|  | int * | nInvalid
| ) |  |

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

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

Parameters

  lat | the latitudes along the transect, in radians.
  lon | the longitudes along the transect, in radians.
  nLatLon | the number of interpolated points along the transect.
  nodeId | a 2D array of ints with at least nLatLon x 5 elements that will be populated with the nodeIds of the grid nodes that were involved in the interpolations.
  coefficients | a 2D array of doubles with at least nLatLon x 5 elements that will be populated with the interpolation coefficients that were applied to the information from the neighboring grid nodes.
  nNodes | a 1D array of ints with at least nLatLon elements that will be populated with the number of nodes that contributes to each nodeId, coefficients.
  depth | the depths of the tops of the interfaces in the Earth model, in km.
  pvelocity | the P velocities of each layer of the model, in km/sec.
  svelocity | the S velocities of each layer of the model, in km/sec.
  pgradient | the mantle P velocity gradient, in 1/sec.
  sgradient | the mantle S velocity gradient, in 1/sec.
  nInvalid | the number of points that were out of model range. For any points outside of the model range, nodeIds are all -1 and all other returned arrays are populated with BaseObject::NA_VALUE.

Returns
  "0" if all points were in model range (nInvalid == 0).

## ◆ slbm_shell_getInterpolatorType()

SLBM_LIB int slbm_shell_getInterpolatorType | ( | char * | interpolatorType | ) |

Retrieve the type of interpolator currently in use; either "LINEAR" or "NATUTAL_NEIGHBOR".

Returns
  the type of interpolator currently in use; either "LINEAR" or "NATUTAL_NEIGHBOR".

## ◆ slbm_shell_getMaxDepth()

SLBM_LIB int slbm_shell_getMaxDepth | ( | double * | maxDepth | ) |

Retrieve the current value for the maximum source depth, in km.

Retrieve the current value for the maximum source depth, in km.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getMaxDistance()

SLBM_LIB int slbm_shell_getMaxDistance | ( | double * | maxDistance | ) |

Retrieve the current value for the maximum source-receiver separation, in radians.

Retrieve the current value for the maximum source-receiver separation, in radians.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getModelString()

SLBM_LIB int slbm_shell_getModelString | ( | char * | modelString,
|  | int * | allocatedSize
| ) |  |

Retrieve a string describing the contents of the model. Retrieve a string describing the contents of the model.

Parameters

  modelString | char* big enough to hold answer.
  allocatedSize | size of modelString. If not big enough to hold the answer, error is returned.

## ◆ slbm_shell_getNActiveNodes()

SLBM_LIB int slbm_shell_getNActiveNodes | ( | int * | nNodes | ) |

Retrieve the number of active nodes in the Grid.

Retrieve the number of active nodes in the Grid.

## ◆ slbm_shell_getNGridNodes()

SLBM_LIB int slbm_shell_getNGridNodes | ( | int * | numGridNodes | ) |

Retrieve the number of Grid nodes in the Earth model.

Retrieve the number of Grid nodes in the Earth model.

Parameters

  numGridNodes | the number of elements in the grid

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getNHeadWavePoints()

SLBM_LIB int slbm_shell_getNHeadWavePoints | ( | int * | npoints | ) |

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

Retrieve the number of LayerProfile objects positioned along the head wave interface. It is useful to call this method before calling getGreatCircleData() since the value returned by this method will be the number of elements that will be populated in parameters headWaveVelocity[], neighbors[] and coefficients[].

Parameters

  npoints | number of LayerProfle objects.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getNodeAzimuth()

SLBM_LIB int slbm_shell_getNodeAzimuth | ( | int * | node1,
|  | int * | node2,
|  | double * | azimuth
| ) |  |

Retrieve the azimuth from grid node1 to grid node2, radians.

Retrieve the azimuth from grid node1 to grid node2, radians.

## ◆ slbm_shell_getNodeHitCount()

SLBM_LIB int slbm_shell_getNodeHitCount | ( | int * | nodeId,
|  | int * | hitCount
| ) |  |

Retrieve the number of times that node has been 'touched' by a GreatCircle object.

Retrieve the number of times that node has been 'touched' by a GreatCircle object.

## ◆ slbm_shell_getNodeNeighborInfo()

SLBM_LIB int slbm_shell_getNodeNeighborInfo | ( | int * | nid,
|  | int | neighbors[],
|  | double | distance[],
|  | double | azimuth[],
|  | int * | nNeighbors
| ) |  |

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

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

The caller must supply int array neighbors which is dimensioned large enough to hold the maximum number of neighbors that a node can have, which is 8. The actual number of neighbors is returned in nNeighbors.

## ◆ slbm_shell_getNodeNeighbors()

SLBM_LIB int slbm_shell_getNodeNeighbors | ( | int * | nid,
|  | int | neighbors[],
|  | int * | nNeighbors
| ) |  |

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

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

The caller must supply int array neighbors which is dimensioned large enough to hold the maximum number of neighbors that a node can have, which is 8. The actual number of neighbors is returned in nNeighbors.

## ◆ slbm_shell_getNodeSeparation()

SLBM_LIB int slbm_shell_getNodeSeparation | ( | int * | node1,
|  | int * | node2,
|  | double * | distance
| ) |  |

Retrieve the angular separation of two grid nodes, in radians.

Retrieve the angular separation of two grid nodes, in radians.

## ◆ slbm_shell_getPathIncrement()

SLBM_LIB int slbm_shell_getPathIncrement | ( | double * | pathIncrement | ) |

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

Retrieve the current value of the spacing of great circle nodes along the head wave interface, in radians. 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.

Parameters

  pathIncrement | the current value of the spacing of great circle nodes along the head wave interface, in radians.

## ◆ slbm_shell_getPgLgComponents()

SLBM_LIB int slbm_shell_getPgLgComponents | ( | double * | tTotal,
|  | double * | tTaup,
|  | double * | tHeadwave,
|  | double * | pTaup,
|  | double * | pHeadwave,
|  | double * | trTaup,
|  | double * | trHeadwave
| ) |  |

Retrieve information about Pg/Lg travel time calculations.

Retrieve information about Pg/Lg travel time calculations. This method only returns useful information when the phase is Pg or Lg. For Pn and Sn, all information is returned as SLBMGlobals::NA_VALUE.

Parameters

  tTotal | is the total travel time in seconds. It will be exactly equal to the lesser of tTaup or tHeadwave, except that if tTaup is equal to SLBMGlobals::NA_VALUE, then tTotal will equal tHeadwave.
  tTaup | is the taup travel time in seconds. If this value is equal to SLBMGlobals::NA_VALUE, it means that the taup calculation failed for some reason (shadow zones, etc.).
  tHeadwave | is the headwave travel time in secods
  pTaup | TauP ray parameter.
  pHeadwave | headwave ray parameter.
  trTaup | is the radius at which the taup ray turned, in km.
  trHeadwave | is the radius at which the headwave ray turned, in km.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getPiercePointReceiver()

SLBM_LIB int slbm_shell_getPiercePointReceiver | ( | double * | lat,
|  | double * | lon,
|  | double * | depth
| ) |  |

Retrieve the latitude and longitude of the moho pierce point below the receiver, in radians.

Retrieve the latitude and longitude of the moho pierce point below the receiver, in radians. For Pg, Lg an exception is thrown.

Parameters

  lat | the latitude of the receiver pierce point, in radians.
  lon | the longitude of the receiver pierce point, in radians.
  depth | moho depth in km below sea level

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getPiercePointSource()

SLBM_LIB int slbm_shell_getPiercePointSource | ( | double * | lat,
|  | double * | lon,
|  | double * | depth
| ) |  |

Retrieve the latitude and longitude of the moho pierce point below the source, in radians.

Retrieve the latitude and longitude of the moho pierce point below the source, in radians. For Pg, Lg and sources in the mantle an exception is thrown.

Parameters

  lat | the latitude of the source pierce point, in radians.
  lon | the longitude of the source pierce point, in radians.
  depth | moho depth in km below sea level

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getRayParameter()

SLBM_LIB int slbm_shell_getRayParameter | ( | double * | rayParameter | ) |

Retrieve the ray parameter in sec/km.

Retrieve the ray parameter in sec/km.

Parameters

  rayParameter | in sec/km

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getReceiverDistance()

SLBM_LIB int slbm_shell_getReceiverDistance | ( | double * | dist | ) |

Retrieve horizontal offset below the receiver, in radians.

Retrieve horizontal offset below the receiver, in radians. This is the angular distance between the location of the receiver and the receiver pierce point where the ray impinged on the headwave interface.

Parameters

  dist | the horizontal offset below the receiver, in radians.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getSHUncertainty()

SLBM_LIB int slbm_shell_getSHUncertainty | ( | double * | slownessUncertainty | ) |

Retrieve uncertainty of the horizontal slowness, in seconds/radian using the phase and distance specified in last call to getGreatCircle().

Retrieve uncertainty of the horizontal slowness, in seconds/radian, using the phase and distance specified in last call to getGreatCircle().

Parameters

  slownessUncertainty | uncertainty of the horizontal slowness, in seconds/radian.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getSlowness()

SLBM_LIB int slbm_shell_getSlowness | ( | double * | slowness | ) |

Retrieve the horizontal slowness, i.e., the derivative of travel time wrt to receiver-source distance, in seconds/radian.

Retrieve the horizontal slowness, in seconds/radian.

Parameters

  slowness | the derivative of travel time wrt to source latitude.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getSlownessUncertainty()

SLBM_LIB int slbm_shell_getSlownessUncertainty | ( | int * | phase,
|  | double * | distance,
|  | double * | uncert
| ) |  |

Retrieve the slowness uncertainty in sec/radian for specified phase, distance.

Retrieve the slowness uncertainty in sec/radian for specified phase, distance.

Parameters

  phase | Pn, Sn, Pg or Lg
  distance | source-receiver separation in radians.
  uncert | returns the uncertainty in sec/radian

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getSourceDistance()

SLBM_LIB int slbm_shell_getSourceDistance | ( | double * | dist | ) |

Retrieve horizontal offset below the source, in radians.

Retrieve horizontal offset below the source, in radians. This is the angular distance between the location of the source and the source pierce point where the ray impinged on the headwave interface.

Parameters

  dist | the horizontal offset below the source, in radians.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getTessId()

SLBM_LIB int slbm_shell_getTessId | ( | char * | tessId | ) |

Retrieve the tessellation ID of the model currently in memory.

Retrieve the tessellation ID of the model currently in memory.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getTravelTime()

SLBM_LIB int slbm_shell_getTravelTime | ( | double * | travelTime | ) |

Retrieve the total travel time for the GreatCircle, in seconds.

Retrieve the total travel time for the GreatCircle, in seconds.

Parameters

  travelTime | the total travel time in seconds is returned in travelTime. If the GreatCircle is invalid, travelTime will equal BaseObject::NA_VALUE.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getTravelTimeComponents()

SLBM_LIB int slbm_shell_getTravelTimeComponents | ( | double * | tTotal,
|  | double * | tSource,
|  | double * | tReceiver,
|  | double * | tHeadwave,
|  | double * | tGradient
| ) |  |

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

Retrieve the total travel time and the 4 components that contribute to it for the current GreatCircle. If the greatCircle is invalid, tTotal and all the components will equal BaseObject::NA_VALUE.

Parameters

  tTotal | the total travel time, in seconds.
  tSource | the crustal travel time below the source, in seconds.
  tReceiver | the crustal travel time below the receiver, in seconds.
  tHeadwave | the head wave travel time, in seconds.
  tGradient | the Zhao gradient correction term, in seconds. For GreatCircle objects that support Pg and Lg, this is always 0.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getTravelTimeUncertainty()

SLBM_LIB int slbm_shell_getTravelTimeUncertainty | ( | int * | phase,
|  | double * | distance,
|  | double * | uncertainty
| ) |  |

Retrieve the travel time uncertainty in sec for specified phase, distance.

Retrieve the travel time uncertainty in sec for specified phase, distance.

Parameters

  phase | Pn, Sn, Pg or Lg
  distance | source-receiver separation in radians.
  uncertainty | returns the uncertainty in sec

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getTTUncertainty()

SLBM_LIB int slbm_shell_getTTUncertainty | ( | double * | uncertainty | ) |

Retrieve travel time uncertainty in sec. This function will call either the path-dependent or 1D uncertainty, depending on the model file being used.

Retrieve travel time uncertainty in sec. This function will call either the path-dependent or 1D uncertainty, depending on the model file being used.

Parameters

  uncertainty | uncertainty of the travel time in seconds.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getTTUncertainty1D()

SLBM_LIB int slbm_shell_getTTUncertainty1D | ( | double * | uncertainty | ) |

Retrieve travel time uncertainty in sec. This function will return the non-path-dependent 1D uncertainty regardless of the model in use.

Retrieve travel time uncertainty in sec using the phase and distance specified in last call to getGreatCircle(). This function will return the non-path-dependent 1D uncertainty regardless of the model in use.

Parameters

  uncertainty | uncertainty of the travel time in seconds.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getTTUncertainty_useRandErr()

SLBM_LIB int slbm_shell_getTTUncertainty_useRandErr | ( | double * | uncertainty | ) |

Retrieve travel time uncertainty in sec. This function will call either the path-dependent or 1D uncertainty, depending on the model file being used. This function includes randomError in the computation.

Retrieve travel time uncertainty in sec. This function will call either the path-dependent or 1D uncertainty, depending on the model file being used. This function includes randomError in the computation.

Parameters

  uncertainty | uncertainty of the travel time in seconds.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getTurningRadius()

SLBM_LIB int slbm_shell_getTurningRadius | ( | double * | turningRadius | ) |

Retrieve turning radius in km.

Retrieve turning radius in km

Parameters

  turningRadius | in km.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getUncertaintyTable()

SLBM_LIB int slbm_shell_getUncertaintyTable | ( | int * | phaseIndex,
|  | int * | attributeIndex,
|  | char * | uncertaintyTable,
|  | int * | allocatedSize
| ) |  |

Retrieve a conveniently formated table of the uncertainty values for the specified phaseIndex and attributeIndex.

Retrieve a conveniently formated table of the uncertainty values for the specified phaseIndex and attributeIndex.

Parameters

  phaseIndex | 0:Pn, 1:Sn, 2:Pg, 3:Lg
  attributeIndex | 0:TT, 1:AZ, 2:SH
  uncertaintyTable | a char* array big enough to hold the results. 1000 characters should do it.
  allocatedSize | the size of the supplied char*. If the required size is bigger than the allocatedSize, a zero length string is returned, return value is -1, and errorMessage will indicate how much space was required.

## ◆ slbm_shell_getUncertaintyTableFileFormat()

SLBM_LIB int slbm_shell_getUncertaintyTableFileFormat | ( | int * | phaseIndex,
|  | int * | attributeIndex,
|  | char * | uncertaintyTable,
|  | int * | allocatedSize
| ) |  |

Retrieve an inconveniently formated table of the uncertainty values for the specified phaseIndex and attributeIndex.

Retrieve a inconveniently formated table of the uncertainty values for the specified phaseIndex and attributeIndex.

Parameters

  phaseIndex | 0:Pn, 1:Sn, 2:Pg, 3:Lg
  attributeIndex | 0:TT, 1:AZ, 2:SH
  uncertaintyTable | a char* array big enough to hold the results. 1000 characters should do it.
  allocatedSize | the size of the supplied char*. If the required size is bigger than the allocatedSize, a zero length string is returned, return value is -1, and errorMessage will indicate how much space was required.

## ◆ slbm_shell_getVersion()

SLBM_LIB int slbm_shell_getVersion | ( | char * | str | ) |

Retrieve the SLBM Version number.

Retrieve the SLBM Version number.

Parameters

  str | a char pointer to contain the version number. NOTE: user should allocate storage for approximately 10 chars.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getWeights()

SLBM_LIB int slbm_shell_getWeights | ( | int | nodeId[],
|  | double | weight[],
|  | int * | nWeights
| ) |  |

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

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

A map which associates an instance of a GridProfile object with a double weight is initialized. Then every LayerProfile on the head wave interface between the source and receiver is visited and the angular distance, d, that the ray traveled in the horizontal segment is retrieved. If d > 0, then the neighboring GridProfile objects that contributed to the interpolated value of the LayerProfile are visited. The product of d * R * C is added to the weight associated with that GridProfile object, where R is the radius of the head wave interface for the LayerProfile object being evaluated, and C is the interpolation coefficient for the GridProfile - LayerProfile pair under consideration. Then, all the GridProfile objects in the map are visited, the grid node IDs extracted into int array nodeId, and the weight extracted into double array weight.

Note: Only grid 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 km.

Parameters

  nodeId | the node IDs of all the grid nodes touched by the current GreatCircle.
  weight | the weights of all the grid nodes touched by the current GreatCircle. Calling application must dimension this array large enough to handle any possible size.
  nWeights | the number of elements in nodeId and weight. Calling application must dimension this array large enough to handle any possible size.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getWeightsReceiver()

SLBM_LIB int slbm_shell_getWeightsReceiver | ( | int | nodeids[],
|  | double | weights[],
|  | int * | nWeights
| ) |  |

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

Retrieve the node IDs and the interpolation coefficients for the receiver CrustalProfile. The sum of the weights will equal 1.

Parameters

  nodeids[] | the nodeIds that influenced the interpolated values at the receiver.
  weights[] | the interpolation coefficients applied to the grid nodes that influenced the interpolated values at the receiver.
  nWeights | the size of nodeids and weights (max value is 5).

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getWeightsSource()

SLBM_LIB int slbm_shell_getWeightsSource | ( | int | nodeids[],
|  | double | weights[],
|  | int * | nWeights
| ) |  |

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

Retrieve the node IDs and the interpolation coefficients for the source CrustalProfile. There will be as many as 5 of each. The sum of the weights will equal 1.

Parameters

  nodeids[] | the nodeIds that influenced the interpolated values at the source.
  weights[] | the interpolation coefficients applied to the grid nodes that influenced the interpolated values at the source.
  nWeights | the size of nodeids and weights (max value is 5).

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_getZhaoParameters()

SLBM_LIB int slbm_shell_getZhaoParameters | ( | double * | Vm,
|  | double * | Gm,
|  | double * | H,
|  | double * | C,
|  | double * | Cm,
|  | int * | udSign
| ) |  |

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

Retrieve some of the parameters that contribute to the calculation of of total travel time using the Zhao algorithm. This method only returns meaningful results for phases Pn and Sn. For Pg and Lg, all the parameters of type double are returned with values BaseObject::NA_VALUE and udSign is returned with value of -999.

Parameters

  Vm | the velocity at the top of the mantle averaged along the Moho between the source and receiver pierce points.
  Gm | the velocity gradient at the top of the mantle averaged along the Moho between the source and receiver pierce points.
  H | the turning depth of the ray relative to the Moho
  C | a 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 | a constant whose product with Vm gives the mantle velocity gradient for a flat Earth.
  udSign | a value of 0 indicates the source is in the crust. +1 indicates the ray leaves a mantle source in the downgoing direction. -1 indicates the ray leaves a mantle source in an upgoing direction.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_initActiveNodesFile()

SLBM_LIB int slbm_shell_initActiveNodesFile | ( | char * | polygonFileName | ) |

Specify the name of a file that contains a list of points that define a polygon that enclose the set of grid nodes that are to be considered active nodes.

Specify the name of a file that contains a list of points that define a polygon that enclose the set of grid nodes that are to be considered 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 polygon specified by this method, then all 3 nodes are defined to be active nodes.

If the last point and first point are not coincident, then the polygon is 'closed' by connecting the first and last point by an edge.

Parameters

  polygonFileName | the name of a file that contains a list of points that define a polygon that enclose the set of grid nodes that are to be considered active nodes.

## ◆ slbm_shell_initActiveNodesPoints()

SLBM_LIB int slbm_shell_initActiveNodesPoints | ( | double * | lat,
|  | double * | lon,
|  | int * | npoints,
|  | int * | inDegrees
| ) |  |

Specify a list of points that define a polygon that enclose the set of grid nodes that are to be considered active nodes.

Specify a list of points that define a polygon that enclose the set of grid nodes that are to be considered 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 polygon specified by this method, then all 3 nodes are defined to be active nodes.

If the last point and first point are not coincident, then the polygon is 'closed' by connecting the first and last point by an edge.

Parameters

  lat | a 1D array of doubles specifying the latitudes of the points that define the polygon. Whether units are degrees or radians depends on parameter inDegrees.
  lon | a 1D array of doubles specifying the longitudes of the points that define the polygon. Whether units are degrees or radians depends on parameter inDegrees.
  npoints | a single integer value specifying the number of latitude and longitude points defined.
  inDegrees | if true, latitudes and longitudes are assumed to be in degrees, if false, they are assumed to be in radians.

## ◆ slbm_shell_initializeActiveNodes()

SLBM_LIB int slbm_shell_initializeActiveNodes | ( | double * | latmin,
|  | double * | lonmin,
|  | double * | latmax,
|  | double * | lonmax
| ) |  |

Specify the latitude and longitude range in radians for active nodes.

Specify the latitude and longitude range in radians for 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 latitude longitude range specified by this method, then all 3 nodes are defined to be active nodes. Lats and lons must be specified in radians.

Parameters

  latmin | minimum latitude in radians
  lonmin | minimum longitude in radians
  latmax | maximum latitude in radians
  lonmax | maximum longitude in radians

## ◆ slbm_shell_isValid()

SLBM_LIB int slbm_shell_isValid | ( |  | ) |

Returns true if the current GreatCirlce object has been instantiated and is ready to be interrogated.

Returns true if the current GreatCirlce object has been instantiated and is ready to be interrogated.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_loadVelocityModel()

SLBM_LIB int slbm_shell_loadVelocityModel | ( | const char * | modelPath | ) |

Load the velocity model into memory from the specified file or directory. This method automatically determines the format of the model.

Load the velocity model into memory from the specified file or directory. This method automatically determines the format of the model and hence is able to load all model formats.

Parameters

  modelPath | the path to the file or directory that contains the model.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_loadVelocityModelBinary()

SLBM_LIB int slbm_shell_loadVelocityModelBinary | ( | const char * | modelDirectory | ) |

Load the velocity model into memory from the specified file or directory. This method automatically determines the format of the model.

Load the velocity model into memory from the specified file or directory. This method automatically determines the format of the model and hence is able to load all model formats.

This method is deprecated in SLBM versions 3 and higher and is provided only for backward compatibility with previous versions of SLBM. It simply calls loadVelocityModel(modelPath).

Parameters

  modelDirectory | the path to the file or directory that contains the model.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_movePoint()

SLBM_LIB int slbm_shell_movePoint | ( | double | aLat,
|  | double | aLon,
|  | double | distance,
|  | double | azimuth,
|  | double * | bLat,
|  | double * | bLon
| ) |  |

Find point B that is the specified distance and azimuth from point A. All quantities are in radians.

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

Parameters

  aLat | the latitude of the first specified point, in radians.
  aLon | the longitude of the first specified point, in radians.
  distance | from point A to point B, in radians.
  azimuth | from point A to point B, in radians.
  bLat | the latitude of the second specified point, in radians.
  bLon | the longitude of the second specified point, in radians.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_saveVelocityModel()

SLBM_LIB int slbm_shell_saveVelocityModel | ( | const char * | modelFileName | ) |

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

Save the velocity model currently in memory to the specified file. Attempting to save the model to the same file from which the model was originally read will result in an exception. If the file already exists, it will be overwritten without warning or backup.

Parameters

  modelFileName | the full or relative path plus file name of the file to which the earth model is to be written.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_saveVelocityModelBinary()

SLBM_LIB int slbm_shell_saveVelocityModelBinary | ( |  | ) |

Deprecated. Use saveVelocityModel() instead. Write the model in format 3 to directory previously specified with a call to specifyOutputDirectory().

This method is deprecated and is provided only for backward compatibility with previous versions of SLBM. Use method saveVelocityModel() instead.

The model is written in format 3 to the directory previously specified with a call to specifyOutputDirectory().

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_saveVelocityModelFormat()

SLBM_LIB int slbm_shell_saveVelocityModelFormat | ( | const char * | modelFileName,
|  | int | format
| ) |  |

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

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 3 single-file format. This is the default+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.

Parameters

  modelFileName | the full or relative path to the file or directory to which the earth model is to be written. For formats 2 and 3, the directory will be created if it does not exist.
  format | the desired format of the output.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_setActiveNodeData()

SLBM_LIB int slbm_shell_setActiveNodeData | ( | int * | nodeId,
|  | double | depth[NLAYERS],
|  | double | pvelocity[NLAYERS],
|  | double | svelocity[NLAYERS],
|  | double | gradient[2]
| ) |  |

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

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

Parameters

  nodeId | the node number of the grid point in the model. (zero based index).
  depth | an array containing the depths of the tops of the layers, in km
  pvelocity | an array containing the P velocities of all the intervals at the specified grid node, in km/sec.
  svelocity | an array containing the S velocities of all the intervals at the specified grid node, in km/sec.
  gradient | a 2-element array containing the P and S velocity gradients in the mantle, in 1/sec.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_setAverageMantleVelocity()

SLBM_LIB int slbm_shell_setAverageMantleVelocity | ( | int * | type,
|  | double * | velocity
| ) |  |

Set the average P or S wave mantle velocity that is recorded in the model input file, in km/sec.

Set the average P or S wave mantle velocity that is specified in the model input file. This value is used in the calculation of the Zhao c parameter.

Parameters

  type | specify either BaseObject::PWAVE or BaseObject::SWAVE.
  velocity | the P or S wave velocity that is to be set, in km/sec. This value will be stored in the model file, if the model file is written to file by a call to saveVelocityModel() subsequent to a call to this method.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_setCHMax()

SLBM_LIB int slbm_shell_setCHMax | ( | double * | chMax | ) |

Set the value of chMax. c is the zhao c parameter and h is the turning depth of the ray below the moho. Zhao method only valid for c*h << 1. When c*h > chMax, then slbm will throw an exception.

Set the value of chMax. c is the zhao c parameter and h is the turning depth of the ray below the moho. Zhao method only valid for c*h << 1. When c*h > chMax, then slbm will throw an exception. This call modifies global parameter BaseObject::ch_max

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_setDelDepth()

SLBM_LIB int slbm_shell_setDelDepth | ( | double | delDepth | ) |

Set the value of del_depth, in km.

Set the value of del_depth, in km. This is the vertical separation between two points used to compute the derivative of travel time with respect to depth.

Parameters

  delDepth | vertical separation in km.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_setDelDistance()

SLBM_LIB int slbm_shell_setDelDistance | ( | double | delDistance | ) |

Set the value of del_distance, radians.

Set the value of del_distance, in radians. This is the horizontal separation between two points used to compute horizontal slowness and the derivative of travel time with respect to lat and lon.

Parameters

  delDistance | horizontal separation in radians.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_setGridData()

SLBM_LIB int slbm_shell_setGridData | ( | int * | nodeId,
|  | double * | depth,
|  | double * | pvelocity,
|  | double * | svelocity,
|  | double * | gradient
| ) |  |

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

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

Parameters

  nodeId | the node number of the grid point in the model. (zero based index).
  depth | an array containing the depths of the tops of all the interfaces.
  pvelocity | an array containing the P velocities of all the intervals at the specified grid node, in km/sec.
  svelocity | an array containing the S velocities of all the intervals at the specified grid node, in km/sec.
  gradient | a 2-element array containing the P and S velocity gradients in the mantle, in 1/sec.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_setInterpolatorType()

SLBM_LIB int slbm_shell_setInterpolatorType | ( | char * | interpolatorType | ) |

Specify the interpolation type to use, either 'linear' or 'natural_neighbor'.

Specify the interpolation type to use, either "LINEAR" or "NATUTAL_NEIGHBOR".. When using the old SLBMGrid objects, LINEAR is the only option allowed.

## ◆ slbm_shell_setMaxDepth()

SLBM_LIB int slbm_shell_setMaxDepth | ( | const double * | maxDepth | ) |

Set the maximum source depth for Pn/Sn phase, in km.

Set the maximum source depth for Pn/Sn phase, in km. Source depths greater than the specified value will result in an exception being thrown in createGreatCircle(). Default value is 9999 km.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_setMaxDistance()

SLBM_LIB int slbm_shell_setMaxDistance | ( | const double * | maxDistance | ) |

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

Set the maximum source-receiver separation for Pn/Sn phase, in radians. Source-receiver separations greater than the specified value will result in an exception being thrown in createGreatCircle(). Default value is PI radians.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_setPathIncrement()

SLBM_LIB int slbm_shell_setPathIncrement | ( | double | pathIncrement | ) |

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

Set the desired spacing of great circle nodes along the head wave interface, in radians. 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.

Parameters

  pathIncrement | the desired spacing of great circle nodes along the head wave interface, in radians.

## ◆ slbm_shell_specifyOutputDirectory()

SLBM_LIB int slbm_shell_specifyOutputDirectory | ( | const char * | directoryName | ) |

Deprecated. Use saveVelocityModel() instead. Specify the directory into which the model that is currently in memory should be written the next time that saveVelocityModelBinary() is called.

This method is deprecated and is provided only for backward compatibility with previous versions of SLBM. Use method saveVelocityModel() instead.

Specify the directory into which the model that is currently in memory should be written the next time that saveVelocityModelBinary() is called. The model will be written in format 3, which is the SLBM version 3 binary directory format (GeoTess).

Parameters

  directoryName | the name of the directory where model files are to be written. The directory will be created if it does not exist.

Returns
  "0" if this call was successful, positive error code if this call generated an error.

## ◆ slbm_shell_toString()

SLBM_LIB int slbm_shell_toString | ( | char * | str,
|  | int | verbosity
| ) |  |

Returns a human-readable string representation of the GreatCircle object.

Returns a human-readable string representation of the GreatCircle object.

Parameters

  str | a char pointer. NOTE: User should allocate memory to accommodate 10000 chars.
  verbosity | specifies the amount of information that is to be included in the return string. Each verbosity level includes all information in preceding verbosity levels. 0 : nothing. An empty string is returned. 1 : total distance and travel time summary 2 : gradient correction information for Pn/Sn. Nothing for Pg/Lg 3 : Source and receiver CrustalProfile information. 4 : Grid node weights. 5 : Head wave interface profiles 6 : Interpolation coefficients for great circle nodes on the head wave interface.

Returns
  "0" if this call was successful, positive error code if this call generated an error.