gov.sandia.gnem.slbmjni
Class SlbmInterface

java.lang.Object
  extended by gov.sandia.gnem.slbmjni.SlbmInterface

public class SlbmInterface
extends java.lang.Object

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

SlbmInterface (Java) manages a connection to the C++ SLBM library. To make this work, 5 conditions must be met:
1) The C++ shared objects libslbm.so and libslbmjni.so must both be accessible via the LD_LIBRARY_PATH.
2) The java application must include the jar file slbmjni.jar in its classpath.
3) The java application must import gov.sandia.gnem.slbmjni.*;
4) The java application must execute the command: System.loadLibrary("slbmjni");
5) The java applicaiton can then instantiate a new SlbmInterface object by calling
SlbmInterface slbm = new SlbmInterface();

If all of these conditions are successfully met, then the the Java application can use the slbm attribute to access all the methods described in this document.

A SlbmInterface object maintains a C++ Grid object, which manages interaction with the Earth model. The Earth model is loaded by calling the loadVelocityModelBinary(java.lang.String) method, described below. This Grid object remains in memory until the SlbmInterface object goes out of scope, or a different Earth model is loaded with another call to loadVelocityModelBinary(java.lang.String).

SlbmInterface also maintains a single instance of a C++ GreatCircle object which is instantiated with a call to createGreatCircle(). Once instantiated, many SlbmInterface 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 owned by SlbmInterface stores a vector of map objects which associates the phase and Location of a CrustalProfile object with a pointer to the instance of the CrustalProfile. When createGreatCircle() is called with a latitude, longitude and depth which has been used before, the Grid object will return a pointer to the existing CrustalProfile object, thereby enhancing performance. This vector of maps is cleared when clear() is called. The implications of all this is that applications that loop over many calls to createGreatCircle() will see a performance improvement if clear() is not called within the loop. However, for problems 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 SLBM_Root/doc/geovectors.pdf

Copyright 2009 Sandia Corporation. Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains certain rights in this software.

BSD Open Source License. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Author: Sandy Ballard

Version: 2.7


Field Summary
protected  int vtkId
           
 
Constructor Summary
SlbmInterface()
          This is the constructor that should be used under normal circumstances.
SlbmInterface(double earthRadius)
          Location::EARTH_RADIUS is a variable that controls how the radius of the earth is defined.
 
Method Summary
 void clear()
          Delete the current GreatCircle object from memory and clear the pool of stored CrustalProfile objects.
 void close()
          Delete the C++ SlbmInterface object from memory.
 void createGreatCircle(java.lang.String phase, double sourceLat, double sourceLon, double sourceDepth, double receiverLat, double receiverLon, double receiverDepth)
          Instantiate a new GreatCircle object between two locations.
 void finalize()
          Delete the C++ SlbmInterface object from memory.
 double get_dtt_ddepth()
          Retrieve the derivative of travel time wrt to source depth, in seconds/km.
 double get_dtt_dlat()
          Retrieve the derivative of travel time wrt to source latitude, in seconds/radian.
 double get_dtt_dlon()
          Retrieve the derivative of travel time wrt to source longitude, in seconds/radian.
 GridProfile getActiveNodeData(int nodeId)
          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.
 int getActiveNodeId(int gridNodeId)
          Retrieve the active node ID that corresponds to a specified grid node ID.
 QueryNeighborInfo getActiveNodeNeighborInfo(int actnid)
          Retrieve NeighborInfo
 int[] getActiveNodeNeighbors(int nodeId)
          Retrieve the active node IDs of the nodes that surround the specified active node.
 GridWeight getActiveNodeWeights()
          Retrieve the weight assigned to each active node that was touched by the GreatCircle that is currently in memory.
 GridWeight getActiveNodeWeightsReceiver()
           
 GridWeight getActiveNodeWeightsSource()
           
 double getAverageMantleVelocity(int type)
          Retrieve the average P or S wave mantle velocity that is specified in the model input file.
 double getCHMax()
          Retrieve the current value of chMax.
 double getDelDepth()
          Retrieve del_depth, the vertical separation of two points used to compute derivative of travel time with respect to depth (in km).
 double getDelDistance()
          Retrieve the horizontal separation of two points used to compute horizontal slowness and derivatives of travel time with respect to latitude and longitude (in radians).
 double getDistance()
          Retrieve the source-receiver separation, in radians.
 double[] getDistAz(double latA, double lonA, double latB, double lonB, double naValue)
          Retrieve distance and azimuth between two points, A and B (all quantities are in radians).
 double getFractionActive()
          Retrieve the fraction of the path length of the current GreatCircle object that is within the currently defined active region.
 GreatCircleData getGreatCircleData()
          Retrieve the information required for input to the travel time calculation, for the GreatCircle object currently in memory.
 double[][] getGreatCircleLocations()
          Retrieve the latitudes, longitudes and depths of all the profile positions along the moho.
 double[][] getGreatCirclePoints(double aLat, double aLon, double bLat, double bLon, int npoints)
          Retrieve an array of lat, lon points along a great circle path between two points, a and b.
 double[][] getGreatCirclePointsOnCenters(double aLat, double aLon, double bLat, double bLon, int npoints)
          Retrieve an array of lat, lon points along a great circle path between two specified points.
 GridProfile getGridData(int nodeId)
          Retrieve data from a single grid node in the earth model.
 int getGridNodeId(int activeNodeId)
          Retrieve the grid node ID that corresponds to a specified active node ID.
 double getHeadwaveDistance()
          Retrieve the angular distance traveled by the ray below the headwave interface, in radians.
 double getHeadwaveDistanceKm()
          Retrieve horizontal distance traveled by the ray below the headwave interface, in km.
 QueryProfile getInterpolatedPoint(double lat, double lon)
          Retrieve interpolated data from the earth model at a single specified latitude, longitude.
 java.util.ArrayList<QueryProfile> getInterpolatedTransect(java.util.ArrayList<java.lang.Double> lat, java.util.ArrayList<java.lang.Double> lon)
          Retrieve interpolated data from the earth model along a 1 dimensional transect across the model.
 double getMaxDepth()
          Retrieve the current value for the maximum source depth, in km.
 double getMaxDistance()
          Retrieve the current value for the maximum source-receiver separation, in radians.
 int getNActiveNodes()
          Retrieve the number of active nodes in the Grid.
 int getNGridNodes()
          Retrieve the number of Grid nodes in the Earth model.
 int getNHeadWavePoints()
          Retrieve the number of Head Wave Points.
 double getNodeAzimuth(int node1, int node2)
          Retrieve the azimuth from grid node1 to grid node2, radians.
 int getNodeHitCount(int nodeId)
          Retrieve the number of times that the specified node has been 'touched' by a GreatCircle object.
 QueryNeighborInfo getNodeNeighborInfo(int nid)
          Retrieve NeighborInfo
 int[] getNodeNeighbors(int nodeId)
          Retrieve the node IDs of the nodes that surround the specified node.
 double getNodeSeparation(int node1, int node2)
          Retrieve the angular separation of two grid nodes, in radians.
 double getPathIncrement()
          Retrieve the current value of the spacing of great circle nodes along the head wave interface, in radians.
 double[] getPgLgComponents()
          Retrieve information about Pg/Lg travel time calculations.
 java.lang.String getPhase()
          Retrieve phase specified in last call to createGreatCircle()
 double[] getPiercePointReceiver()
          Retrieve the geographic latitude, longitude and depth of the moho pierce point below the receiver, in radians, km.
 double[] getPiercePointSource()
          Retrieve the geographic latitude, longitude and depth of the moho pierce point below the receiver, in radians, km.
 double[] getReceiverCoefficients()
          Retrieve the interpolation coefficients for grid nodes that contributed to the interpolation of values at the receiver location.
 double getReceiverDistance()
          Retrieve horizontal offset below the receiver, in radians.
 int[] getReceiverNodeIds()
          Retrieve the node IDs for grid nodes that contributed to the interpolation of values at the receiver location.
 double getSlowness()
          Retrieve horizontal slowness, in seconds/radian.
 double getSlownessUncertainty()
          Get the slowness uncertainty (seconds/radian) resulting from last call to createGreatCircle()
 double getSlownessUncertainty(java.lang.String phase, double distance)
          Retrieve uncertainty of horizontal slowness, in seconds/radian-km.
 double[] getSourceCoefficients()
          Retrieve the interpolation coefficients for grid nodes that contributed to the interpolation of values at the source location.
 double getSourceDistance()
          Retrieve horizontal offset below the source, in radians.
 int[] getSourceNodeIds()
          Retrieve the node IDs for grid nodes that contributed to the interpolation of values at the source location.
 java.lang.String getTessId()
          Retrieve the tessellation ID of the model currently in memory.
 double getTravelTime()
          Retrieve the total travel time for the GreatCircle, in seconds.
 double[] getTravelTimeComponents()
          Retrieve the total travel time and all the components that contributed to the total.
 double getTravelTimeUncertainty()
          Calculate an uncertainty value (seconds) resulting from last call to createGreatCircle()
 double getTravelTimeUncertainty(java.lang.String phase, double distance)
          Calculate an uncertainty value (seconds) as a function of distance in radians for a supported seismic phase (Pn, Sn, Pg, & Lg).
 java.lang.String getVersion()
          Retrieve the SLBM version number.
 GridWeight getWeights()
          Retrieve the weight assigned to each grid node that was touched by the GreatCircle that is currently in memory.
 GridWeight getWeightsReceiver()
           
 GridWeight getWeightsSource()
           
 ZhaoParameters getZhaoParameters()
          Retrieve some of the parameters that contribute to the calculation of of total travel time using the Zhao algorithm.
 void initializeActiveNodes(double latmin, double lonmin, double latmax, double lonmax)
          Initialize the list of active nodes in the model grid.
 void loadVelocityModel(java.lang.String modelFileName)
          Load the velocity model into memory from the specified file.
 void loadVelocityModelBinary(java.lang.String modelDirectory)
          Load the velocity model into memory from files located in the specified directory.
 double[] movePoint(double latA, double lonA, double distance, double azimuth)
          Find geographic latitude and longitude of the point that is the specified distance and azimuth from point A.
 void saveVelocityModel(java.lang.String modelFileName)
          Save the velocity model currently in memory to the specified file.
 void saveVelocityModelBinary()
          Write the model currently in memory out to files.
 void setActiveNodeData(GridProfile gridProfile)
          Modify the velocity and gradient information associated with a specified active node in the Grid.
 void setAverageMantleVelocity(int type, double velocity)
          Set the average P or S wave mantle velocity that is specified in the model input file.
 void setCHMax(double chMax)
          Set the value of chMax.
 void setDelDepth(double del_depth)
          Modify the value of del_depth, the vertical separation of two points used to compute derivative of travel time with respect to depth (in km).
 void setDelDistance(double del_distance)
          Modify the horizontal separation of two points used to compute horizontal slowness and derivatives of travel time with respect to latitude and longitude.
 void setGridData(GridProfile gridProfile)
          Modify the velocity and gradient information for a single grid node in the earth model currently in memory.
 void setMaxDepth(double maxDepth)
          Set the maximum source depth for Pn/Sn phase, in km.
 void setMaxDistance(double maxDistance)
          Set the maximum source-receiver separation for Pn/Sn phase, in radians.
 void setPathIncrement(double pathIncrement)
          Set the desired spacing of great circle nodes along the head wave interface, in radians.
 void specifyOutputDirectory(java.lang.String directoryName)
          Specify the directory where the model that is currently in memory should be written to the next time that saveVelocityModelBinary() is called.
 java.lang.String toString(int verbosity)
          Retrieve a formatted String representation of the results computed by a GreatCircle object.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

vtkId

protected int vtkId
Constructor Detail

SlbmInterface

public SlbmInterface()
This is the constructor that should be used under normal circumstances.


SlbmInterface

public SlbmInterface(double earthRadius)
Location::EARTH_RADIUS is a variable that controls how the radius of the earth is defined. It is initialized to -1 in SLBM::Location.cc, outside the class definition. If Location::EARTH_RADIUS is less than zero, then Location::getEarthRadius() will return the radius of the earth that is a function of geocentric latitude (larger at the equator, smaller at the poles). If Location::EARTH_RADIUS is > 0, then getEarthRadius() returns Location::EARTH_RADIUS. Applications can modify Location::EARTH_RADIUS by calling this routine.

In it's default state, SLBM will return travel times that do not require application of ellipticity corrections, since the radius of the elliptical earth is computed at every latitude. However, when comparing SLBM results to results obtained with radially symmetric, 1D models, or any model which assumes a spherical earth, it is important to fix the Earth radius to the correct value for the comparison (usually 6371 km).

Parameters:
earthRadius - double earth radius in km.
Method Detail

finalize

public void finalize()
Delete the C++ SlbmInterface object from memory.

Overrides:
finalize in class java.lang.Object

close

public void close()
Delete the C++ SlbmInterface object from memory.


getVersion

public java.lang.String getVersion()
Retrieve the SLBM version number.

Returns:
String

loadVelocityModel

public void loadVelocityModel(java.lang.String modelFileName)
                       throws SLBMException
Load the velocity model into memory from the specified file.

Parameters:
modelFileName - String
Throws:
SLBMException

saveVelocityModel

public void saveVelocityModel(java.lang.String modelFileName)
                       throws SLBMException
Save the velocity model currently in memory to the specified file.

Parameters:
modelFileName - String
Throws:
SLBMException

createGreatCircle

public void createGreatCircle(java.lang.String phase,
                              double sourceLat,
                              double sourceLon,
                              double sourceDepth,
                              double receiverLat,
                              double receiverLon,
                              double receiverDepth)
                       throws SLBMException
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 geographic longitude of source in radians.
sourceDepth - the depth of the source in km.
receiverLat - the geographic latitude of the receiver in radians.
receiverLon - the geographic longitude of the receiver in radians.
receiverDepth - the depth of the receiver in km. along the head wave interface, in radians.
Throws:
SLBMException

clear

public void 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. 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(java.lang.String, double, double, double, double, double, double) 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(java.lang.String, double, double, double, double, double, double) 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.


toString

public java.lang.String toString(int verbosity)
                          throws SLBMException
Retrieve a formatted String representation of the results computed by a GreatCircle object.

Parameters:
verbosity - specifies the amount of information that is to be included in the return string. Each verbosity level includes all information in preceeding 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 profiles
- 4 : Grid node weights.
- 5 : Head wave interface profiles
- 6 : Interpolation coefficients for great circle nodes on the head wave interface.
Returns:
String a formatted String representation of the results computed by a GreatCircle object.
Throws:
SLBMException

getTravelTime

public double getTravelTime()
                     throws SLBMException
Retrieve the total travel time for the GreatCircle, in seconds.

Returns:
double the total travel time for the GreatCircle, in seconds.
Throws:
SLBMException

getPhase

public java.lang.String getPhase()
                          throws SLBMException
Retrieve phase specified in last call to createGreatCircle()

Returns:
String phase
Throws:
SLBMException

getDistance

public double getDistance()
                   throws SLBMException
Retrieve the source-receiver separation, in radians.

Returns:
double the source-receiver separation, in radians.
Throws:
SLBMException

getSourceDistance

public double getSourceDistance()
                         throws SLBMException
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.

Returns:
the horizontal offset below the source, in radians.
Throws:
SLBMException

getReceiverDistance

public double getReceiverDistance()
                           throws SLBMException
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.

Returns:
the horizontal offset below the receiver, in radians.
Throws:
SLBMException

getHeadwaveDistance

public double getHeadwaveDistance()
                           throws SLBMException
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().

Returns:
the angular distance traveled by the ray below the headwave interface, in radians.
Throws:
SLBMException

getHeadwaveDistanceKm

public double getHeadwaveDistanceKm()
                             throws SLBMException
Retrieve horizontal distance traveled by the ray below the headwave interface, in km. This is the sum of actual_path_increment(i) * R(i) where actual_path_increment(i) is the angular distance traveled by the ray in each angular distance increment along the head wave interface, and R(i) is the radius of the head wave interface in that same horizontal increment.

Returns:
the horizontal distance traveled by the ray below the headwave interface, in km.
Throws:
SLBMException

getTravelTimeComponents

public double[] getTravelTimeComponents()
                                 throws SLBMException
Retrieve the total travel time and all the components that contributed to the total. All values are in seconds.

Returns:
double[]
t[0] : total travel time
t[1] : crustal travel time below the source
t[2] : crustal travel time below the receiver
t[3] : travel time along the head wave interface
t[4] : gradient correction term. Zero for Pg/Lg
Throws:
SLBMException

getWeights

public GridWeight getWeights()
                      throws SLBMException
Retrieve the weight assigned to each grid node that was touched by the GreatCircle that is currently in memory.

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 retreived. 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 node, 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.

Returns:
GridWeight a storage container for the results.
Throws:
SLBMException

getWeightsSource

public GridWeight getWeightsSource()
                            throws SLBMException
Throws:
SLBMException

getActiveNodeWeightsSource

public GridWeight getActiveNodeWeightsSource()
                                      throws SLBMException
Throws:
SLBMException

getWeightsReceiver

public GridWeight getWeightsReceiver()
                              throws SLBMException
Throws:
SLBMException

getActiveNodeWeightsReceiver

public GridWeight getActiveNodeWeightsReceiver()
                                        throws SLBMException
Throws:
SLBMException

getSourceNodeIds

public int[] getSourceNodeIds()
Retrieve the node IDs for grid nodes that contributed to the interpolation of values at the source location. There should be 4 of these.

Returns:
int[] source node ids.

getSourceCoefficients

public double[] getSourceCoefficients()
Retrieve the interpolation coefficients for grid nodes that contributed to the interpolation of values at the source location. There should be 4 of these and they should sum to one.

Returns:
int[] source interpolation coefficients

getReceiverNodeIds

public int[] getReceiverNodeIds()
Retrieve the node IDs for grid nodes that contributed to the interpolation of values at the receiver location. There should be 4 of these.

Returns:
int[] receiver node ids.

getReceiverCoefficients

public double[] getReceiverCoefficients()
Retrieve the interpolation coefficients for grid nodes that contributed to the interpolation of values at the receiver location. There should be 4 of these and they should sum to one.

Returns:
int[] receiver interpolation coefficients

getGridData

public GridProfile getGridData(int nodeId)
                        throws SLBMException
Retrieve data from a single grid node in the earth model.

Parameters:
nodeId - the grid node ID number.
Returns:
GridProfile
Throws:
SLBMException

setGridData

public void setGridData(GridProfile gridProfile)
                 throws SLBMException
Modify the velocity and gradient information for a single grid node in the earth model currently in memory. The Earth model in the input file is not modified. To save the Earth model that is currently in memory to the file system call method saveVelocityModel(String)

Parameters:
gridProfile - GridProfile containing the nodeId, velocity and gradient information that is to replace the information currently stored in the Earth model in memory.
Throws:
SLBMException

setActiveNodeData

public void setActiveNodeData(GridProfile gridProfile)
                       throws SLBMException
Modify the velocity and gradient information associated with a specified active node in the Grid.

Parameters:
gridProfile - the node number of the grid point in the model. (zero based index).
Throws:
SLBMException

getInterpolatedPoint

public QueryProfile getInterpolatedPoint(double lat,
                                         double lon)
                                  throws SLBMException
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.
Returns:
QueryProfile
Throws:
SLBMException

getInterpolatedTransect

public java.util.ArrayList<QueryProfile> getInterpolatedTransect(java.util.ArrayList<java.lang.Double> lat,
                                                                 java.util.ArrayList<java.lang.Double> lon)
                                                          throws SLBMException
Retrieve interpolated data from the earth model along a 1 dimensional transect across the model.

Parameters:
lat - the latitudes where information is to be interpolated, in radians.
lon - the longitudes where information is to be interpolated, in radians.
Returns:
QueryProfile
Throws:
SLBMException

getGreatCircleData

public GreatCircleData getGreatCircleData()
                                   throws SLBMException
Retrieve the information required for input to the travel time calculation, for the GreatCircle object currently in memory.

Returns:
GreatCircleData a storage container for the results.
Throws:
SLBMException

getGreatCircleLocations

public double[][] getGreatCircleLocations()
                                   throws SLBMException
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 actualPathIncrement/2 radians from the source, the last profile position is located actualPathIncrement/2 radians from the receiver, and the others are spaced actualPathIncrement radians apart.

Returns:
double[][] a 3 x npoints array containing the latitudes, longitudes and depths of the points along the great circle. Latitudes and longitudes are in radians. Depths are in km.
Throws:
SLBMException

getGreatCirclePoints

public double[][] getGreatCirclePoints(double aLat,
                                       double aLon,
                                       double bLat,
                                       double bLon,
                                       int npoints)
                                throws SLBMException
Retrieve an array of lat, lon points along a great circle path between two points, a and b. 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 - double the latitude of the first point in radians.
aLon - double the longitude of the first point in radians.
bLat - double the latitude of the second point in radians.
bLon - double the longitude of the second point in radians.
npoints - int the number of points desired.
Returns:
double[][] a 2 x npoints array containing the latitudes and longitudes of the points along the great circle, in radians.
Throws:
SLBMException

getGreatCirclePointsOnCenters

public double[][] getGreatCirclePointsOnCenters(double aLat,
                                                double aLon,
                                                double bLat,
                                                double bLon,
                                                int npoints)
                                         throws SLBMException
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 - double the latitude of the first point in radians.
aLon - double the longitude of the first point in radians.
bLat - double the latitude of the second point in radians.
bLon - double the longitude of the second point in radians.
npoints - int the number of points desired.
Returns:
double[][] a 2 x npoints array containing the latitudes and longitudes of the points along the great circle, in radians.
Throws:
SLBMException

getTravelTimeUncertainty

public double getTravelTimeUncertainty()
                                throws SLBMException
Calculate an uncertainty value (seconds) resulting from last call to createGreatCircle()

Returns:
the uncertainty in seconds
Throws:
SLBMException

getTravelTimeUncertainty

public double getTravelTimeUncertainty(java.lang.String phase,
                                       double distance)
                                throws SLBMException
Calculate an uncertainty value (seconds) as a function of distance in radians for a supported seismic phase (Pn, Sn, Pg, & Lg).

Parameters:
phase - String one of Pn, Sn, Pg, Lg
distance - the angular distance in radians
Returns:
the uncertainty in seconds
Throws:
SLBMException

getZhaoParameters

public ZhaoParameters getZhaoParameters()
                                 throws SLBMException
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.

Returns:
ZhaoParameters
Throws:
SLBMException

getPgLgComponents

public double[] getPgLgComponents()
                           throws SLBMException
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.

This method returns a 7 element array of doubles. The values have the following interpretation:

0: total travel time, sec
1: TauP travel time, sec
2: Headwave travel time, sec
3: TauP ray parameter, seconds/radian
4: Headwave ray parameter, seconds/km
5: TauP Turning radius, km
6: Headwave turning radius, km

Returns:
double[]
Throws:
SLBMException

getNodeNeighbors

public int[] getNodeNeighbors(int nodeId)
Retrieve the node IDs of the nodes that surround the specified node.

Parameters:
nodeId - int
Returns:
int[]

getActiveNodeNeighbors

public int[] getActiveNodeNeighbors(int nodeId)
Retrieve the active node IDs of the nodes that surround the specified active node.

Parameters:
nodeId - int
Returns:
int[]

getNodeSeparation

public double getNodeSeparation(int node1,
                                int node2)
Retrieve the angular separation of two grid nodes, in radians.

Parameters:
node1 - int
node2 - int
Returns:
double

getNodeAzimuth

public double getNodeAzimuth(int node1,
                             int node2)
Retrieve the azimuth from grid node1 to grid node2, radians.

Parameters:
node1 - int
node2 - int
Returns:
double

initializeActiveNodes

public void initializeActiveNodes(double latmin,
                                  double lonmin,
                                  double latmax,
                                  double lonmax)
Initialize the list of active nodes in the model grid. After a call to this method, active nodes can be accessed by looping over the active nodes. See getNActiveNodes() and getActiveNodeData().

Active nodes includes all grid nodes that fall within the specified range of latitude and longitude. Lats and lons must be specified in radians. Lonmin and lonmax should -PI <= lon <= PI.

Parameters:
latmin - double
lonmin - double
latmax - double
lonmax - double

getNodeHitCount

public int getNodeHitCount(int nodeId)
Retrieve the number of times that the specified node has been 'touched' by a GreatCircle object. The hit count of each node is initialized in the loadVelocityModel() method. Every time the getWeights() method is called for a particular GreatCircle object, all the nodeIds that contribute any weight to that GreatCircle object have their hit count incremented by one.

Parameters:
nodeId - int
Returns:
int

getNActiveNodes

public int getNActiveNodes()
Retrieve the number of active nodes in the Grid.

Returns:
int

getGridNodeId

public int getGridNodeId(int activeNodeId)
Retrieve the grid node ID that corresponds to a specified active node ID.

Parameters:
activeNodeId - int
Returns:
int

getActiveNodeId

public int getActiveNodeId(int gridNodeId)
Retrieve the active node ID that corresponds to a specified grid node ID.

Parameters:
gridNodeId - int
Returns:
int

getActiveNodeWeights

public GridWeight getActiveNodeWeights()
                                throws SLBMException
Retrieve the weight assigned to each active node that was touched by the GreatCircle that is currently in memory.

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 retreived. 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 node, and the weight extracted into double array weight.

Note: Only active nodes touched by this GreatCircle are included in the output. Each active 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.

Returns:
GridWeight a storage container for the results.
Throws:
SLBMException

getActiveNodeData

public GridProfile getActiveNodeData(int nodeId)
                              throws SLBMException
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).
Returns:
GridProfile
Throws:
SLBMException

getNGridNodes

public int getNGridNodes()
Retrieve the number of Grid nodes in the Earth model.

Returns:
int

getNHeadWavePoints

public int getNHeadWavePoints()
Retrieve the number of Head Wave Points.

Returns:
int

getNodeNeighborInfo

public QueryNeighborInfo getNodeNeighborInfo(int nid)
Retrieve NeighborInfo

Parameters:
nid - int
Returns:
QueryNeighborInfo

getActiveNodeNeighborInfo

public QueryNeighborInfo getActiveNodeNeighborInfo(int actnid)
Retrieve NeighborInfo

Parameters:
actnid - int
Returns:
QueryNeighborInfo

setCHMax

public void 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. This call modifies global parameter BaseObject::ch_max

Parameters:
chMax - double

getCHMax

public double getCHMax()
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:
double

getAverageMantleVelocity

public double getAverageMantleVelocity(int type)
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.
Returns:
double

setAverageMantleVelocity

public void setAverageMantleVelocity(int type,
                                     double velocity)
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.

loadVelocityModelBinary

public void loadVelocityModelBinary(java.lang.String modelDirectory)
Load the velocity model into memory from files located in the specified directory. Slbm expects the specified modelDirectory to exist and to contain two binary files: geostacks and connectivity. It also expects there to exist a directory called tess at the same diretory level as the specified directory and for that directory to contain the binary file that specifies the tessellation with which the model data is to be associated. For example, assume the following directory structure:

/SLBM_Root
/models
/tess
450fe54afbf70f1a2f62c30d249c5643
/unified_crust20
connectivity
geostacks
/unified_iasp
connectivity
geostacks

To access model unified_crust20, you would specify modelDirectory = SLBM_Root/models/unified_crust20. Note that the name of the tessellation file is embedded in the unified_crust20/connectivity file and slbm will expect to find that file by appending "/../tess/{filename)" onto the end of the specified modelDirectory parameter.

Parameters:
modelDirectory - String

specifyOutputDirectory

public void specifyOutputDirectory(java.lang.String directoryName)
Specify the directory where the model that is currently in memory should be written to the next time that saveVelocityModelBinary() is called. A call to specifyOutputDirectory() will check to make sure that the specified directory exists. If it does not exist, slbm will attempt to create it. Then slbm will write a very small file called deleteme.buf to the specified directory and then delete that file. All of this is done to ensure that when the model is actually written to the specified directory, the probability of error is minimized. Call method saveVelocityModelBinary() to actually write the model to the specified directory.

Note that specified directory name is associated with the Grid object currently in memory. If the current Grid object is deleted and a different Grid object loaded, the directoryName will be reset to "".

Parameters:
directoryName - String

saveVelocityModelBinary

public void saveVelocityModelBinary()
Write the model currently in memory out to files. The model is written to a directory which was previously specified with a call to specifyOutputDirectory().


getTessId

public java.lang.String getTessId()
Retrieve the tessellation ID of the model currently in memory.

Returns:
String

getFractionActive

public double getFractionActive()
Retrieve the fraction of the path length of the current GreatCircle object that is within the currently defined active region.

Returns:
double

setMaxDistance

public void setMaxDistance(double maxDistance)
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.

Parameters:
maxDistance - double

getMaxDistance

public double getMaxDistance()
Retrieve the current value for the maximum source-receiver separation, in radians.

Returns:
double

setMaxDepth

public void setMaxDepth(double maxDepth)
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.

Parameters:
maxDepth - double

getMaxDepth

public double getMaxDepth()
Retrieve the current value for the maximum source depth, in km.

Returns:
double

get_dtt_dlat

public double get_dtt_dlat()
                    throws SLBMException
Retrieve the derivative of travel time wrt to source latitude, in seconds/radian.

Returns:
double the derivative of travel time wrt to source latitude, in seconds/radian.
Throws:
SLBMException

get_dtt_dlon

public double get_dtt_dlon()
                    throws SLBMException
Retrieve the derivative of travel time wrt to source longitude, in seconds/radian.

Returns:
double the derivative of travel time wrt to source longitude, in seconds/radian.
Throws:
SLBMException

get_dtt_ddepth

public double get_dtt_ddepth()
                      throws SLBMException
Retrieve the derivative of travel time wrt to source depth, in seconds/km.

Returns:
double the derivative of travel time wrt to source depth, in seconds/km.
Throws:
SLBMException

getSlowness

public double getSlowness()
                   throws SLBMException
Retrieve horizontal slowness, in seconds/radian.

Returns:
double the horizontal slowness, in seconds/radian.
Throws:
SLBMException

getSlownessUncertainty

public double getSlownessUncertainty()
                              throws SLBMException
Get the slowness uncertainty (seconds/radian) resulting from last call to createGreatCircle()

Returns:
the uncertainty in seconds/radian
Throws:
SLBMException

getSlownessUncertainty

public double getSlownessUncertainty(java.lang.String phase,
                                     double distance)
                              throws SLBMException
Retrieve uncertainty of horizontal slowness, in seconds/radian-km.

Parameters:
phase - String
distance - double
Returns:
double the uncertainty of horizontal slowness, in seconds/radian-km.
Throws:
SLBMException

movePoint

public double[] movePoint(double latA,
                          double lonA,
                          double distance,
                          double azimuth)
Find geographic latitude and longitude of the point that is the specified distance and azimuth from point A.

Parameters:
latA - radians
lonA - radians
distance - radians
azimuth - radians
Returns:
[latB, lonB] in radians

getDistAz

public double[] getDistAz(double latA,
                          double lonA,
                          double latB,
                          double lonB,
                          double naValue)
Retrieve 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:
latA - geographic latitude of point A, in radians.
lonA - geographic longitude of point A, in radians.
latB - geographic latitude of point B, in radians.
lonB - geographic longitude of point B, in radians.
naValue - if distance is zero or if A is coincident with north or south pole, then azimuth is invalid and this value will be returned as the azimuth.
Returns:
[distance, azimuth] in radians.

getPiercePointSource

public double[] getPiercePointSource()
Retrieve the geographic latitude, longitude and depth of the moho pierce point below the receiver, in radians, km. For Pg, Lg an exception is thrown.


getPiercePointReceiver

public double[] getPiercePointReceiver()
Retrieve the geographic latitude, longitude and depth of the moho pierce point below the receiver, in radians, km. For Pg, Lg an exception is thrown.


getDelDistance

public double getDelDistance()
                      throws SLBMException
Retrieve the horizontal separation of two points used to compute horizontal slowness and derivatives of travel time with respect to latitude and longitude (in radians).

Returns:
double del_distance, in radians
Throws:
SLBMException

setDelDistance

public void setDelDistance(double del_distance)
Modify the horizontal separation of two points used to compute horizontal slowness and derivatives of travel time with respect to latitude and longitude.

Parameters:
del_distance - in radians

getDelDepth

public double getDelDepth()
                   throws SLBMException
Retrieve del_depth, the vertical separation of two points used to compute derivative of travel time with respect to depth (in km).

Returns:
del_depth, in km.
Throws:
SLBMException

setDelDepth

public void setDelDepth(double del_depth)
Modify the value of del_depth, the vertical separation of two points used to compute derivative of travel time with respect to depth (in km).

Parameters:
del_depth - in km.

setPathIncrement

public void setPathIncrement(double pathIncrement)
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.

getPathIncrement

public double getPathIncrement()
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.

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