RSTT: taup::TauPSite Class Reference

RSTT 3.1.0 Regional Seismic Travel Time

Public Member Functions | Static Public Member Functions | List of all members
taup::TauPSite Class Reference

`#include <TauPSite.h>`

## Public Member Functions
| TauPSite ()
| Default Constructor. More...
| TauPSite (const string &staname, const string &phase)
| Standard Constructor. Sets the station name and phase represented by this TauPSite. More...
| TauPSite (const TauPSite &tps)
| Copy Constructor. More...
virtual | ~TauPSite ()
| Destructor. More...
TauPSite & | operator= (const TauPSite &tps)
| Assignment operator. More...
void | setSiteDepth (double depth)
| Sets 'this' sites depth. More...
void | setVelocityModels (const vector< TPVelocityLayer * > &vm)
| Sets the velocity models for 'this' TauPSite ... model ownership is set to NOT OWNED (tpsIsVelModlOwned = false). More...
void | appendVelocityModel (TPVelocityLayer *vm)
| Appends another velocity model to the profile for 'this' TauPSite. If this is the first then model pointer is saved and ownership is set to NOT OWNED (tpsIsVelModlOwned = false). If this is the second or greater velocity layer added then if tpsIsVelModlOwned is false the pointer is added else a copy of the object is made and added. More...
void | appendConstVelocityModel (double c, double rt, double rb, const string &layrnam="")
| Appends a new OWNED constant velocity model to the profile stack. If this is the first entry a new model is created and tpsIsVelModlOwned is set to true. If this is the second or greater model and tpsIsVelModlOwned is false an error is thrown. Otherwise, the new model is added to the stack. Note the top radius must equal the bottom radius of the previous layer else an error is thrown. More...
void | appendLinearVelocityModel (double a0, double a1, double rt, double rb, const string &layrnam="", double normradius=1.0)
| Appends a new OWNED linear velocity model to the profile stack. If this is the first entry a new model is created and tpsIsVelModlOwned is set to true. If this is the second or greater model and tpsIsVelModlOwned is false an error is thrown. Otherwise, the new model is added to the stack. Note the top radius must equal the bottom radius of the previous layer else an error is thrown. More...
void | appendQuadraticVelocityModel (double a0, double a1, double a2, double rt, double rb, const string &layrnam="", double normradius=1.0)
| Appends a new OWNED quadratic velocity model to the profile stack. If this is the first entry a new model is created and tpsIsVelModlOwned is set to true. If this is the second or greater model and tpsIsVelModlOwned is false an error is thrown. Otherwise, the new model is added to the stack. Note the top radius must equal the bottom radius of the previous layer else an error is thrown. More...
void | appendCubicVelocityModel (double a0, double a1, double a2, double a3, double rt, double rb, const string &layrnam="", double normradius=1.0)
| Appends a new OWNED cubic velocity model to the profile stack. If this is the first entry a new model is created and tpsIsVelModlOwned is set to true. If this is the second or greater model and tpsIsVelModlOwned is false an error is thrown. Otherwise, the new model is added to the stack. Note the top radius must equal the bottom radius of the previous layer else an error is thrown. More...
void | clearVelocityModels ()
| Clears all velocity models from the current profile. If the models are OWNED they are deleted. More...
void | calculateTravelTimes (double srcdist, double srcdepth, bool evalderivs=true)
| Calculates travel times for all valid phases at the input distance and depth. This is the primary work function of the TauPSite object. More...
TravelTimeResult * | getFirstTravelTimeResult ()
| Returns the first travel time result. If no travel time exists a NULL pointer is returned. More...
double | getFirstTravelTime () const
| Returns the first travel time (smallest) for the last call to calculateTravelTimes(dist, depth). More...
double | getFirstNonDiffractedTravelTime () const
| Returns the first travel time (smallest) for the last call to calculateTravelTimes(dist, depth) that is not a diffracted ray (e.g. not Pdiff). If only a diffracted results exists this first is returned. If no travel time exists a -1.0 is returned. More...
TravelTimeResult * | getTravelTimeResult (const string &phase, bool matchPhase)
double | getTravelTime (const string &phase, bool matchPhase) const
const map< double, TravelTimeResult * > & | getAllTravelTimes () const
| Returns the map of all discovered travel time results sorted from fastest to slowest. More...
bool | integrateDistance (double p, double &d, bool bottom_pass=false)
| Returns the total integrated distance of a ray with ray parameter p in the input parameter d. The function returns true if successful and false if the result is invalid. The result is integrated from the surface of the planet to the turning depth, wherever that may be. More...
bool | integrateDistance (double p, double r, double &d)
| Returns the total integrated distance of a ray with ray parameter p in the input parameter d. The function returns true if successful and false if the result is invalid. The result is integrated from the surface of the planet to the input depth r. More...
bool | integrateDistance (double p, double r1, double r2, double &d)
| Returns the total integrated distance of a ray with ray parameter p in the input parameter d. The function returns true if successful and false if the result is invalid. The result is integrated from the r1 to depth r2. More...
bool | integrateTime (double p, double &d, bool bottom_pass=false)
| Returns the total integrated travel time of a ray with ray parameter p in the input parameter t. The function returns true if successful and false if the result is invalid. The result is integrated from the surface of the planet to the turning depth, wherever that may be. More...
bool | integrateTime (double p, double r, double &d)
| Returns the total integrated travel time of a ray with ray parameter p in the input parameter t. The function returns true if successful and false if the result is invalid. The result is integrated from the surface of the planet to the input depth r. More...
bool | integrateTime (double p, double r1, double r2, double &t)
| Returns the total integrated travel time of a ray with ray parameter p in the input parameter d. The function returns true if successful and false if the result is invalid. The result is integrated from the r1 to depth r2. An invalid ray is returned if p is greater than the larger ray parameter evaluated at r1 and r2 or if the ray turns before reaching r2 (r1 must be > r2). More...
virtual void | writeData (const string &filename) const
| Writes the TauPSite as a standard ASCII file in CLR format (see TauPModel function readData for a description of the format). More...
void | writeLayerData (int i, ostream &os, int n, double f0=0.0, double f1=1.0)
| This function writes out the surface to surface distance for waves turning in layer i of the input wave velocity layer vector vellyr. More...
void | dumpLocalSrcRcvrLayers (ostream &os)
| Debug function to output source receiver local conditions. More...
void | dumpLayerInfo (ostream &os)
| Debug function to output layer information. More...
string | toString () const
| Print object data to string. More...
virtual void | toStream (ostream &os, string indent) const
| Print object data to input stream os. More...
virtual string | get_class_name () const
| Virtual function that returns the class name. More...
virtual int | class_size () const
| Static function that returns the class size. More...
virtual string | getCommonName () const
| virtual function that returns the class common name. More...
const string & | getName () const
| Returns the assigned site name. More...
const string & | getPhase () const
| Returns the assigned site phase. More...
void | setModelName (const string &modname)
| Sets the assigned model name string. More...
const string & | getModelName () const
| Returns the assigned model name string. More...
void | setEarthRadius (double r)
| Set the Earth radius for this site. Overrides the default. More...
double | getEarthRadius () const
| Return the Earth radius. More...
void | setBrentsTolerance (double tol)
| Sets the Brents zero-in tolerance. More...
double | getBrentsTolerance () const
| Returns the Brents zero-in tolerance. More...
const vector< TPVelocityLayer * > & | getVelocityModels () const
| Returns the vector of layered velocity models assigned to this site. More...
virtual int64 | get_memory () const
| Returns the total memory resource for this TauPSite. More...
virtual int64 | get_alloc_memory () const
| Returns the total heap allocated memory resource for this TauPSite. More...

## Static Public Member Functions
static string | class_name ()
| Static function that returns the class name. More...
static string | commonName ()
| Static function that returns the class common name. More...

## Detailed Description

The TauPSite object is used to represent a specific receiver location for the TauP 1D spherical travel time calculation. The objects primary function is calculateTravelTimes(double srcdist, double srcdepth) which determines all viable ray path solutions at the input source distance / depth position to the 1D spherical travel time equations as defined in:

Lay, Thorne; Wallace, T. C.; "Modern Global Seismology", Volume 58, International Geophysics Series, Academic Press, 1995, pp 91-93. The object contains functionality to assign or create a series of layered velocity models that define the planetary velocity structure to be modeled. Functionality is also provided to set the receiver depth. Both the receiver and source depths can be negative (elevated) which uses the top layer velocity structure as an infinite propagation medium using an inverted radius definition.

All valid branches are evaluated for a single input distance / depth. These are stored in a map that associates the travel time for the branch with an internal descriptive object (a TravelTimeResult) that describes the path in specific detail. The entries in the map are stored in ascending order (fastest to slowest). The Model also solves for all requested diffracted phases (e.g. Pdiff) if a particular velocity layers upper or lower diffracted phase interface flag is set.

Individual layers can be modeled as one of the following variations:

Constant Power Law Linear Quadratic Cubic

Each layer can be given a standard phase name or can default to the internal evaluated phase name of the form Tn[b,i][+,-] where T can be "P" or "S"; n is the turning layer index between 0 and N-1 where N is the number of layers; either b or i is appended for a body wave or diffracted interface; and either + or - can be appended whose meaning depends on if b or i was used in the naming. If b (a body wave) is defined and the turning layer is a retro-grade layer (i.e. contains a minimum in path distance wrt. the ray parameter such as the outer core for example) then a "+" will be appended if the ray turned in the upper half of the retro-grade layer above the minimum, or a "-" will be appended if the ray turned in the lower half of the layer below the minimum. If "i" (a diffracted ray) is defined and the ray uses the upper layer velocity to propagate then a "+" will be appended, else if the ray uses the lower layer velocity to propagate a "-" will be appended.

Definition at line 120 of file TauPSite.h.

## Constructor & Destructor Documentation

## ◆ TauPSite() [1/3]

taup::TauPSite::TauPSite | ( |  | ) |

Default Constructor.

## ◆ TauPSite() [2/3]

taup::TauPSite::TauPSite | ( | const string & | staname,
|  | const string & | phase
| ) |  |

Standard Constructor. Sets the station name and phase represented by this TauPSite.

## ◆ TauPSite() [3/3]

taup::TauPSite::TauPSite | ( | const TauPSite & | tps | ) |

Copy Constructor.

## ◆ ~TauPSite()

virtual taup::TauPSite::~TauPSite | ( |  | ) |
| virtual

Destructor.

## Member Function Documentation

## ◆ appendConstVelocityModel()

void taup::TauPSite::appendConstVelocityModel | ( | double | c,
|  | double | rt,
|  | double | rb,
|  | const string & | layrnam = `""`
| ) |  |

Appends a new OWNED constant velocity model to the profile stack. If this is the first entry a new model is created and tpsIsVelModlOwned is set to true. If this is the second or greater model and tpsIsVelModlOwned is false an error is thrown. Otherwise, the new model is added to the stack. Note the top radius must equal the bottom radius of the previous layer else an error is thrown.

## ◆ appendCubicVelocityModel()

void taup::TauPSite::appendCubicVelocityModel | ( | double | a0,
|  | double | a1,
|  | double | a2,
|  | double | a3,
|  | double | rt,
|  | double | rb,
|  | const string & | layrnam = `""`,
|  | double | normradius = `1.0`
| ) |  |

Appends a new OWNED cubic velocity model to the profile stack. If this is the first entry a new model is created and tpsIsVelModlOwned is set to true. If this is the second or greater model and tpsIsVelModlOwned is false an error is thrown. Otherwise, the new model is added to the stack. Note the top radius must equal the bottom radius of the previous layer else an error is thrown.

## ◆ appendLinearVelocityModel()

void taup::TauPSite::appendLinearVelocityModel | ( | double | a0,
|  | double | a1,
|  | double | rt,
|  | double | rb,
|  | const string & | layrnam = `""`,
|  | double | normradius = `1.0`
| ) |  |

Appends a new OWNED linear velocity model to the profile stack. If this is the first entry a new model is created and tpsIsVelModlOwned is set to true. If this is the second or greater model and tpsIsVelModlOwned is false an error is thrown. Otherwise, the new model is added to the stack. Note the top radius must equal the bottom radius of the previous layer else an error is thrown.

## ◆ appendQuadraticVelocityModel()

void taup::TauPSite::appendQuadraticVelocityModel | ( | double | a0,
|  | double | a1,
|  | double | a2,
|  | double | rt,
|  | double | rb,
|  | const string & | layrnam = `""`,
|  | double | normradius = `1.0`
| ) |  |

Appends a new OWNED quadratic velocity model to the profile stack. If this is the first entry a new model is created and tpsIsVelModlOwned is set to true. If this is the second or greater model and tpsIsVelModlOwned is false an error is thrown. Otherwise, the new model is added to the stack. Note the top radius must equal the bottom radius of the previous layer else an error is thrown.

## ◆ appendVelocityModel()

void taup::TauPSite::appendVelocityModel | ( | TPVelocityLayer * | vm | ) |

Appends another velocity model to the profile for 'this' TauPSite. If this is the first then model pointer is saved and ownership is set to NOT OWNED (tpsIsVelModlOwned = false). If this is the second or greater velocity layer added then if tpsIsVelModlOwned is false the pointer is added else a copy of the object is made and added.

## ◆ calculateTravelTimes()

void taup::TauPSite::calculateTravelTimes | ( | double | srcdist,
|  | double | srcdepth,
|  | bool | evalderivs = `true`
| ) |  |

Calculates travel times for all valid phases at the input distance and depth. This is the primary work function of the TauPSite object.

## ◆ class_name()

string taup::TauPSite::class_name | ( |  | ) |
| inlinestatic

Static function that returns the class name.

Definition at line 948 of file TauPSite.h.

## ◆ class_size()

int taup::TauPSite::class_size | ( |  | ) | const
| inlinevirtual

Static function that returns the class size.

Returns the class size (in bytes).

Definition at line 968 of file TauPSite.h.

## ◆ clearVelocityModels()

void taup::TauPSite::clearVelocityModels | ( |  | ) |

Clears all velocity models from the current profile. If the models are OWNED they are deleted.

## ◆ commonName()

string taup::TauPSite::commonName | ( |  | ) |
| inlinestatic

Static function that returns the class common name.

Static function that returns the common name of the object.

Definition at line 978 of file TauPSite.h.

## ◆ dumpLayerInfo()

void taup::TauPSite::dumpLayerInfo | ( | ostream & | os | ) |

Debug function to output layer information.

## ◆ dumpLocalSrcRcvrLayers()

void taup::TauPSite::dumpLocalSrcRcvrLayers | ( | ostream & | os | ) |

Debug function to output source receiver local conditions.

## ◆ get_alloc_memory()

virtual int64 taup::TauPSite::get_alloc_memory | ( |  | ) | const
| virtual

Returns the total heap allocated memory resource for this TauPSite.

## ◆ get_class_name()

string taup::TauPSite::get_class_name | ( |  | ) | const
| inlinevirtual

Virtual function that returns the class name.

Returns the class name.

Definition at line 958 of file TauPSite.h.

## ◆ get_memory()

int64 taup::TauPSite::get_memory | ( |  | ) | const
| inlinevirtual

Returns the total memory resource for this TauPSite.

Returns the total memory allocated by 'this' TTBMTauP object.

Definition at line 998 of file TauPSite.h.

## ◆ getAllTravelTimes()

const map< double, TravelTimeResult * > & taup::TauPSite::getAllTravelTimes | ( |  | ) | const
| inline

Returns the map of all discovered travel time results sorted from fastest to slowest.

Returns the first travel time result. If no travel time exists a NULL pointer is returned.

Definition at line 1098 of file TauPSite.h.

## ◆ getBrentsTolerance()

double taup::TauPSite::getBrentsTolerance | ( |  | ) | const
| inline

Returns the Brents zero-in tolerance.

Definition at line 1088 of file TauPSite.h.

## ◆ getCommonName()

string taup::TauPSite::getCommonName | ( |  | ) | const
| inlinevirtual

virtual function that returns the class common name.

Returns the common name.

Definition at line 988 of file TauPSite.h.

## ◆ getEarthRadius()

double taup::TauPSite::getEarthRadius | ( |  | ) | const
| inline

Return the Earth radius.

Definition at line 1068 of file TauPSite.h.

## ◆ getFirstNonDiffractedTravelTime()

double taup::TauPSite::getFirstNonDiffractedTravelTime | ( |  | ) | const

Returns the first travel time (smallest) for the last call to calculateTravelTimes(dist, depth) that is not a diffracted ray (e.g. not Pdiff). If only a diffracted results exists this first is returned. If no travel time exists a -1.0 is returned.

## ◆ getFirstTravelTime()

double taup::TauPSite::getFirstTravelTime | ( |  | ) | const

Returns the first travel time (smallest) for the last call to calculateTravelTimes(dist, depth).

## ◆ getFirstTravelTimeResult()

TravelTimeResult* taup::TauPSite::getFirstTravelTimeResult | ( |  | ) |

Returns the first travel time result. If no travel time exists a NULL pointer is returned.

## ◆ getModelName()

const string & taup::TauPSite::getModelName | ( |  | ) | const
| inline

Returns the assigned model name string.

Returns the model name.

Definition at line 1038 of file TauPSite.h.

## ◆ getName()

const string & taup::TauPSite::getName | ( |  | ) | const
| inline

Returns the assigned site name.

Returns the site name.

Definition at line 1008 of file TauPSite.h.

## ◆ getPhase()

const string & taup::TauPSite::getPhase | ( |  | ) | const
| inline

Returns the assigned site phase.

Returns the site phase.

Definition at line 1018 of file TauPSite.h.

## ◆ getTravelTime()

double taup::TauPSite::getTravelTime | ( | const string & | phase,
|  | bool | matchPhase
| ) |  | const

## ◆ getTravelTimeResult()

TravelTimeResult* taup::TauPSite::getTravelTimeResult | ( | const string & | phase,
|  | bool | matchPhase
| ) |  |

## ◆ getVelocityModels()

const vector< TPVelocityLayer * > & taup::TauPSite::getVelocityModels | ( |  | ) | const
| inline

Returns the vector of layered velocity models assigned to this site.

Returns the vector of layered velocity models.

Definition at line 1048 of file TauPSite.h.

## ◆ integrateDistance() [1/3]

bool taup::TauPSite::integrateDistance | ( | double | p,
|  | double & | d,
|  | bool | bottom_pass = `false`
| ) |  |

Returns the total integrated distance of a ray with ray parameter p in the input parameter d. The function returns true if successful and false if the result is invalid. The result is integrated from the surface of the planet to the turning depth, wherever that may be.

If the ray parameter is equal to the top of a layers ray parameter in a shadow then the boolean flag bottom_pass should be set to true to ensure that the integration does not terminate before accumulating the run-up to the top of the next layer.

## ◆ integrateDistance() [2/3]

bool taup::TauPSite::integrateDistance | ( | double | p,
|  | double | r,
|  | double & | d
| ) |  |

Returns the total integrated distance of a ray with ray parameter p in the input parameter d. The function returns true if successful and false if the result is invalid. The result is integrated from the surface of the planet to the input depth r.

## ◆ integrateDistance() [3/3]

bool taup::TauPSite::integrateDistance | ( | double | p,
|  | double | r1,
|  | double | r2,
|  | double & | d
| ) |  |

Returns the total integrated distance of a ray with ray parameter p in the input parameter d. The function returns true if successful and false if the result is invalid. The result is integrated from the r1 to depth r2.

## ◆ integrateTime() [1/3]

bool taup::TauPSite::integrateTime | ( | double | p,
|  | double & | d,
|  | bool | bottom_pass = `false`
| ) |  |

Returns the total integrated travel time of a ray with ray parameter p in the input parameter t. The function returns true if successful and false if the result is invalid. The result is integrated from the surface of the planet to the turning depth, wherever that may be.

If the ray parameter is equal to the top of a layers ray parameter in a shadow then the boolean flag bottom_pass should be set to true to ensure that the integration does not terminate before accumulating the run-up to the top of the next layer.

## ◆ integrateTime() [2/3]

bool taup::TauPSite::integrateTime | ( | double | p,
|  | double | r,
|  | double & | d
| ) |  |

Returns the total integrated travel time of a ray with ray parameter p in the input parameter t. The function returns true if successful and false if the result is invalid. The result is integrated from the surface of the planet to the input depth r.

## ◆ integrateTime() [3/3]

bool taup::TauPSite::integrateTime | ( | double | p,
|  | double | r1,
|  | double | r2,
|  | double & | t
| ) |  |

Returns the total integrated travel time of a ray with ray parameter p in the input parameter d. The function returns true if successful and false if the result is invalid. The result is integrated from the r1 to depth r2. An invalid ray is returned if p is greater than the larger ray parameter evaluated at r1 and r2 or if the ray turns before reaching r2 (r1 must be > r2).

## ◆ operator=()

TauPSite& taup::TauPSite::operator= | ( | const TauPSite & | tps | ) |

Assignment operator.

## ◆ setBrentsTolerance()

void taup::TauPSite::setBrentsTolerance | ( | double | tol | ) |
| inline

Sets the Brents zero-in tolerance.

Definition at line 1078 of file TauPSite.h.

## ◆ setEarthRadius()

void taup::TauPSite::setEarthRadius | ( | double | r | ) |
| inline

Set the Earth radius for this site. Overrides the default.

Set the Earth radius.

Definition at line 1058 of file TauPSite.h.

## ◆ setModelName()

void taup::TauPSite::setModelName | ( | const string & | modname | ) |
| inline

Sets the assigned model name string.

Returns the model name.

Definition at line 1028 of file TauPSite.h.

## ◆ setSiteDepth()

void taup::TauPSite::setSiteDepth | ( | double | depth | ) |

Sets 'this' sites depth.

## ◆ setVelocityModels()

void taup::TauPSite::setVelocityModels | ( | const vector< TPVelocityLayer * > & | vm | ) |

Sets the velocity models for 'this' TauPSite ... model ownership is set to NOT OWNED (tpsIsVelModlOwned = false).

## ◆ toStream()

virtual void taup::TauPSite::toStream | ( | ostream & | os,
|  | string | indent
| ) |  | const
| virtual

Print object data to input stream os.

## ◆ toString()

string taup::TauPSite::toString | ( |  | ) | const

Print object data to string.

## ◆ writeData()

virtual void taup::TauPSite::writeData | ( | const string & | filename | ) | const
| virtual

Writes the TauPSite as a standard ASCII file in CLR format (see TauPModel function readData for a description of the format).

## ◆ writeLayerData()

void taup::TauPSite::writeLayerData | ( | int | i,
|  | ostream & | os,
|  | int | n,
|  | double | f0 = `0.0`,
|  | double | f1 = `1.0`
| ) |  |

This function writes out the surface to surface distance for waves turning in layer i of the input wave velocity layer vector vellyr.

The ray parameter (s/deg) is written along with the travel distance (deg) into the input stream os. At least n points will be written but more may be required if the maximum traversed distance divided by n is exceeded in any step. The function automatically decrements the ray-parameter step size for areas where the corresponding distance step size exceeds the aforementioned limit.

The documentation for this class was generated from the following file:

- rstt/SLBM/include/TauPSite.h