Package edu.sc.seis.TauP

# Class SeismicPhase

java.lang.Object
edu.sc.seis.TauP.SeismicPhase

All Implemented Interfaces:
  `java.io.Serializable`, `java.lang.Cloneable`

    public class SeismicPhase
    extends java.lang.Object
    implements java.io.Serializable, java.lang.Cloneable

Stores and transforms seismic phase names to and from their corresponding sequence of branches.

See Also:
  Serialized Form

- ## Field Summary

  Fields
  Modifier and Type | Field | Description
  --- | --- | ---
  `protected java.util.List<java.lang.Integer>` | `branchSeq` | Array of branch numbers for the given phase.
  `protected int` | `currBranch` | temporary branch number so we know where to start add to the branch sequence.
  `boolean` | `DEBUG` | Enables debugging output.
  `static int` | `DIFFRACT` | Used by addToBranch when the path transmits down through the end of a segment.
  `protected double[]` | `dist` | Array of distances corresponding to the ray parameters stored in rayParams.
  `protected java.util.ArrayList<java.lang.Boolean>` | `downGoing` | true if the current leg of the phase is down going.
  `static int` | `END` | Used by addToBranch for the last segment of a phase.
  `static int` | `END_DOWN` | Used by addToBranch for the last segment of a phase if downgoing to receiver at depth..
  `static boolean` | `expert` | Enables phases originating in core.
  `protected java.util.List<java.lang.Integer>` | `headOrDiffractSeq` | Array of branchSeq positions where a head or diffracted segment occurs.
  `protected java.util.ArrayList<java.lang.Integer>` | `legAction` | records the end action for the current leg.
  `protected java.util.ArrayList<java.lang.String>` | `legs` | ArrayList containing Strings for each leg.
  `protected static double` | `maxDiffraction` | The maximum degrees that a Pdiff or Sdiff can diffract along the CMB.
  `protected double` | `maxDistance` | The maximum distance that this phase can be theoretically observed.
  `protected double` | `maxRayParam` | Maximum ray parameter that exists for this phase.
  `protected int` | `maxRayParamIndex` | Index within TauModel.rayParams that corresponds to maxRayParam.
  `protected int` | `maxRecursion` |
  `protected static double` | `maxRefraction` | The maximum degrees that a Pn or Sn can refract along the moho.
  `protected double` | `minDistance` | The minimum distance that this phase can be theoretically observed.
  `protected double` | `minRayParam` | Minimum ray parameter that exists for this phase.
  `protected int` | `minRayParamIndex` | Index within TauModel.rayParams that corresponds to minRayParam.
  `protected java.lang.String` | `name` | The phase name, ie PKiKP.
  `protected java.lang.String` | `puristName` | name with depths corrected to be actuall discontinuities in the model.
  `static boolean` | `PWAVE` |
  `protected double[]` | `rayParams` | Array of possible ray parameters for this phase.
  `protected double` | `receiverDepth` | The receiver depth within the TauModel that was used to generate this phase.
  `protected double` | `refineDistToleranceRadian` |
  `static int` | `REFLECT_TOPSIDE` | Used by addToBranch when the path reflects off the bottom of the end of a segment, ie v.
  `static int` | `REFLECT_TOPSIDE_CRITICAL` | Used by addToBranch when the path reflects off the bottom of the end of a segment, ie "V".
  `static int` | `REFLECT_UNDERSIDE` | Used by addToBranch when the path reflects off the top of the end of a segment, ie ^.
  `static int` | `REFLECT_UNDERSIDE_CRITICAL` | Used by addToBranch when the path critically reflects off the top of the end of a segment, ie "^x".
  `protected java.util.List<SeismicPhaseSegment>` | `segmentList` | Description of segments of the phase.
  `protected double` | `sourceDepth` | The source depth within the TauModel that was used to generate this phase.
  `static boolean` | `SWAVE` |
  `protected double[]` | `time` | Array of times corresponding to the ray parameters stored in rayParams.
  `protected TauModel` | `tMod` | TauModel to generate phase for.
  `static int` | `TRANSDOWN` | Used by addToBranch when the path transmits down through the end of a segment.
  `static int` | `TRANSUP` | Used by addToBranch when the path transmits up through the end of a segment.
  `static int` | `TURN` | Used by addToBranch when the path turns within a segment.
  `boolean` | `verbose` | Enables verbose output.
  `protected java.util.ArrayList<java.lang.Boolean>` | `waveType` | ArrayList of wave types corresponding to each leg of the phase.

- ## Constructor Summary

  Constructors
  Constructor | Description
  --- | ---
  `SeismicPhase​(java.lang.String name, TauModel tMod)` |
  `SeismicPhase​(java.lang.String name, TauModel tMod, double receiverDepth)` |
  `SeismicPhase​(java.lang.String name, TauModel tMod, double receiverDepth, boolean debug)` |
  `SeismicPhase​(java.lang.String name, java.lang.String modelName, double depth)` |

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `protected void` | `addToBranch​(TauModel tMod, int startBranch, int endBranch, boolean isPWave, int endAction, java.lang.String currLeg)` |
  `protected int[][]` | `calcBranchMultiplier()` | Calculates how many times the phase passes through a branch, up or down, so that we can just multiply instead of doing the ray calc for each time.
  `double` | `calcIncidentAngle​(double arrivalRayParam)` |
  `java.util.List<Arrival>` | `calcPath​(double deg)` | Deprecated. Use the getPath() method on each Arrival from calcTime()
  `Arrival` | `calcPath​(Arrival currArrival)` | Deprecated. use the getPath() method on the arrival.
  `protected java.util.List<TimeDist>` | `calcPathTimeDist​(Arrival currArrival)` |
  `java.util.List<Arrival>` | `calcPierce​(double deg)` | Deprecated. Use the getPierce() method on each Arrival from calcTime()
  `Arrival` | `calcPierce​(Arrival currArrival)` | Deprecated. Use the getPierce() method on each Arrival from calcTime()
  `protected java.util.List<TimeDist>` | `calcPierceTimeDist​(Arrival currArrival)` |
  `double` | `calcRayParamForTakeoffAngle​(double takeoffDegree)` |
  `double` | `calcTakeoffAngle​(double arrivalRayParam)` |
  `java.util.List<Arrival>` | `calcTime​(double deg)` | calculates arrival times for this phase, sorted by time.
  `int` | `closestBranchToDepth​(TauModel tMod, java.lang.String depthString)` | Finds the closest discontinuity to the given depth that can have refletions and phase transformations.
  `protected void` | `createPuristName​(TauModel tMod)` |
  `java.lang.String` | `describe()` |
  `void` | `dump()` |
  `static java.lang.String` | `endActionString​(int endAction)` |
  `double[]` | `getDist()` |
  `double` | `getDist​(int i)` |
  `boolean[]` | `getDownGoing()` | Direction of the leg between pierce point i and i+1, true is downgoing, false if upgoing
  `Arrival` | `getEarliestArrival​(double degrees)` |
  `static Arrival` | `getEarliestArrival​(java.util.List<SeismicPhase> phases, double degrees)` |
  `int[]` | `getLegAction()` | Leg type i layer interaction, one of TURN, REFLECTTOP, REFLECTBOT, TRANSUP, TRANSDOWN
  `java.util.List<java.lang.String>` | `getLegs()` |
  `static double` | `getMaxDiffraction()` |
  `double` | `getMaxDistance()` |
  `double` | `getMaxDistanceDeg()` |
  `double` | `getMaxRayParam()` |
  `int` | `getMaxRayParamIndex()` |
  `static double` | `getMaxRefraction()` |
  `double` | `getMinDistance()` |
  `double` | `getMinDistanceDeg()` |
  `double` | `getMinRayParam()` |
  `int` | `getMinRayParamIndex()` |
  `java.lang.String` | `getName()` |
  `java.util.List<SeismicPhaseSegment>` | `getPhaseSegments()` |
  `java.lang.String` | `getPuristName()` |
  `double[]` | `getRayParams()` |
  `double` | `getRayParams​(int i)` |
  `double[]` | `getTau()` |
  `double` | `getTau​(int i)` |
  `TauModel` | `getTauModel()` |
  `double[]` | `getTime()` |
  `double` | `getTime​(int i)` |
  `java.lang.String` | `getValidationFailMessage()` |
  `boolean[]` | `getWaveType()` | Wave type of the leg between pierce point i and i+1, true is P, false if S
  `boolean` | `hasArrivals()` |
  `protected static java.util.ArrayList<java.lang.String>` | `legPuller​(java.lang.String name)` | Tokenizes a phase name into legs, ie PcS becomes 'P'+'c'+'S' while p^410P would become 'p'+'^410'+'P'.
  `static void` | `main​(java.lang.String[] args)` |
  `protected void` | `parseName​(TauModel tMod)` | Constructs a branch sequence from the given phase name and tau model.
  `protected void` | `phaseConversion​(TauModel tMod, int fromBranch, int endAction, boolean isPtoS)` | changes maxRayParam and minRayParam whenever there is a phase conversion.
  `boolean` | `phasesExistsInModel()` |
  `static java.lang.String` | `phaseValidate​(java.util.ArrayList<java.lang.String> legs)` | Performs consistency checks on the previously tokenized phase name stored in legs.
  `Arrival` | `refineArrival​(int rayNum, double distRadian, double distTolRadian, int maxRecursion)` |
  `Arrival` | `refineArrival​(Arrival leftEstimate, Arrival rightEstimate, double searchDist, double distTolRadian, int maxRecursion)` |
  `static void` | `setMaxDiffraction​(double max)` |
  `static void` | `setMaxRefraction​(double max)` |
  `Arrival` | `shootRay​(double rayParam)` |
  `protected void` | `sumBranches​(TauModel tMod)` | Sums the appropriate branches for this phase.
  `java.lang.String` | `toString()` |

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### DEBUG

    public transient boolean DEBUG
    Enables debugging output.

  - ### verbose

    public transient boolean verbose
    Enables verbose output.

  - ### expert

    public static transient boolean expert
    Enables phases originating in core.

  - ### tMod

    protected TauModel tMod
    TauModel to generate phase for.

  - ### TURN

    public static final int TURN
    Used by addToBranch when the path turns within a segment. We assume that no ray will turn downward so turning implies turning from downward to upward, ie U.
    See Also:
      Constant Field Values

  - ### REFLECT_UNDERSIDE

    public static final int REFLECT_UNDERSIDE
    Used by addToBranch when the path reflects off the top of the end of a segment, ie ^.
    See Also:
      Constant Field Values

  - ### REFLECT_TOPSIDE

    public static final int REFLECT_TOPSIDE
    Used by addToBranch when the path reflects off the bottom of the end of a segment, ie v.
    See Also:
      Constant Field Values

  - ### TRANSUP

    public static final int TRANSUP
    Used by addToBranch when the path transmits up through the end of a segment.
    See Also:
      Constant Field Values

  - ### TRANSDOWN

    public static final int TRANSDOWN
    Used by addToBranch when the path transmits down through the end of a segment.
    See Also:
      Constant Field Values

  - ### DIFFRACT

    public static final int DIFFRACT
    Used by addToBranch when the path transmits down through the end of a segment.
    See Also:
      Constant Field Values

  - ### END

    public static final int END
    Used by addToBranch for the last segment of a phase.
    See Also:
      Constant Field Values

  - ### END_DOWN

    public static final int END_DOWN
    Used by addToBranch for the last segment of a phase if downgoing to receiver at depth..
    See Also:
      Constant Field Values

  - ### REFLECT_UNDERSIDE_CRITICAL

    public static final int REFLECT_UNDERSIDE_CRITICAL
    Used by addToBranch when the path critically reflects off the top of the end of a segment, ie "^x". Note this is disabled as it is hard to create a model where this phase interaction is physically possible, delay implement this feature for now.
    See Also:
      Constant Field Values

  - ### REFLECT_TOPSIDE_CRITICAL

    public static final int REFLECT_TOPSIDE_CRITICAL
    Used by addToBranch when the path reflects off the bottom of the end of a segment, ie "V".
    See Also:
      Constant Field Values

  - ### maxRefraction

    protected static double maxRefraction
    The maximum degrees that a Pn or Sn can refract along the moho. Note this is not the total distance, only the segment along the moho. The default is 20 degrees.

  - ### maxDiffraction

    protected static double maxDiffraction
    The maximum degrees that a Pdiff or Sdiff can diffract along the CMB. Note this is not the total distance, only the segment along the CMB. The default is 60 degrees.

  - ### sourceDepth

    protected double sourceDepth
    The source depth within the TauModel that was used to generate this phase.

  - ### receiverDepth

    protected double receiverDepth
    The receiver depth within the TauModel that was used to generate this phase. Normally this is 0.0 for a surface stations, but can be different for borehole or scattering calculations.

  - ### dist

    protected double[] dist
    Array of distances corresponding to the ray parameters stored in rayParams.

  - ### time

    protected double[] time
    Array of times corresponding to the ray parameters stored in rayParams.

  - ### rayParams

    protected double[] rayParams
    Array of possible ray parameters for this phase.

  - ### minRayParam

    protected double minRayParam
    Minimum ray parameter that exists for this phase.

  - ### maxRayParam

    protected double maxRayParam
    Maximum ray parameter that exists for this phase.

  - ### maxRayParamIndex

    protected int maxRayParamIndex
    Index within TauModel.rayParams that corresponds to maxRayParam. Note that maxRayParamIndex < minRayParamIndex as ray parameter decreases with increasing index.

  - ### minRayParamIndex

    protected int minRayParamIndex
    Index within TauModel.rayParams that corresponds to minRayParam. Note that maxRayParamIndex < minRayParamIndex as ray parameter decreases with increasing index.

  - ### minDistance

    protected double minDistance
    The minimum distance that this phase can be theoretically observed.

  - ### maxDistance

    protected double maxDistance
    The maximum distance that this phase can be theoretically observed.

  - ### branchSeq

    protected java.util.List<java.lang.Integer> branchSeq
    Array of branch numbers for the given phase. Note that this depends upon both the earth model and the source depth.

  - ### headOrDiffractSeq

    protected java.util.List<java.lang.Integer> headOrDiffractSeq
    Array of branchSeq positions where a head or diffracted segment occurs.

  - ### name

    protected java.lang.String name
    The phase name, ie PKiKP.

  - ### puristName

    protected java.lang.String puristName
    name with depths corrected to be actuall discontinuities in the model.

  - ### legs

    protected java.util.ArrayList<java.lang.String> legs
    ArrayList containing Strings for each leg.

  - ### segmentList

    protected java.util.List<SeismicPhaseSegment> segmentList
    Description of segments of the phase.

  - ### currBranch

    protected transient int currBranch
    temporary branch number so we know where to start add to the branch sequence. Used in addToBranch() and parseName().

  - ### legAction

    protected java.util.ArrayList<java.lang.Integer> legAction
    records the end action for the current leg. Will be one of SeismicPhase.TURN, SeismicPhase.TRANSDOWN, SeismicPhase.TRANSUP, SeismicPhase.REFLECTBOT, or SeismicPhase.REFLECTTOP. This allows a check to make sure the path is correct. Used in addToBranch() and parseName().

  - ### downGoing

    protected java.util.ArrayList<java.lang.Boolean> downGoing
    true if the current leg of the phase is down going. This allows a check to make sure the path is correct. Used in addToBranch() and parseName().

  - ### waveType

    protected java.util.ArrayList<java.lang.Boolean> waveType
    ArrayList of wave types corresponding to each leg of the phase.

  - ### refineDistToleranceRadian

    protected double refineDistToleranceRadian

  - ### maxRecursion

    protected int maxRecursion

  - ### PWAVE

    public static final boolean PWAVE
    See Also:
      Constant Field Values

  - ### SWAVE

    public static final boolean SWAVE
    See Also:
      Constant Field Values

- ## Constructor Details

  - ### SeismicPhase

    public SeismicPhase​(java.lang.String name, java.lang.String modelName, double depth) throws TauModelException
    Throws:
      `TauModelException`

  - ### SeismicPhase

    public SeismicPhase​(java.lang.String name, TauModel tMod) throws TauModelException
    Parameters:
      `name` - String containing a name of the phase.
      `tMod` - Tau model to be used to construct the phase. This should be corrected for the source depth.
    Throws:
      `TauModelException`

  - ### SeismicPhase

    public SeismicPhase​(java.lang.String name, TauModel tMod, double receiverDepth) throws TauModelException
    Throws:
      `TauModelException`

  - ### SeismicPhase

    public SeismicPhase​(java.lang.String name, TauModel tMod, double receiverDepth, boolean debug) throws TauModelException
    Throws:
      `TauModelException`

- ## Method Details

  - ### phasesExistsInModel

    public boolean phasesExistsInModel()

  - ### getEarliestArrival

    public Arrival getEarliestArrival​(double degrees)

  - ### getTauModel

    public TauModel getTauModel()

  - ### getMinDistanceDeg

    public double getMinDistanceDeg()

  - ### getMinDistance

    public double getMinDistance()

  - ### getMaxDistanceDeg

    public double getMaxDistanceDeg()

  - ### getMaxDistance

    public double getMaxDistance()

  - ### getMaxRayParam

    public double getMaxRayParam()

  - ### getMinRayParam

    public double getMinRayParam()

  - ### getMaxRayParamIndex

    public int getMaxRayParamIndex()

  - ### getMinRayParamIndex

    public int getMinRayParamIndex()

  - ### getMaxRefraction

    public static double getMaxRefraction()

  - ### setMaxRefraction

    public static void setMaxRefraction​(double max)

  - ### getMaxDiffraction

    public static double getMaxDiffraction()

  - ### setMaxDiffraction

    public static void setMaxDiffraction​(double max)

  - ### getName

    public java.lang.String getName()

  - ### getPuristName

    public java.lang.String getPuristName()

  - ### getLegs

    public java.util.List<java.lang.String> getLegs()

  - ### getPhaseSegments

    public java.util.List<SeismicPhaseSegment> getPhaseSegments()

  - ### getRayParams

    public double getRayParams​(int i)

  - ### getRayParams

    public double[] getRayParams()

  - ### getDist

    public double getDist​(int i)

  - ### getDist

    public double[] getDist()

  - ### getTime

    public double getTime​(int i)

  - ### getTime

    public double[] getTime()

  - ### getTau

    public double getTau​(int i)

  - ### getTau

    public double[] getTau()

  - ### getDownGoing

    public boolean[] getDownGoing()
    Direction of the leg between pierce point i and i+1, true is downgoing, false if upgoing

  - ### getWaveType

    public boolean[] getWaveType()
    Wave type of the leg between pierce point i and i+1, true is P, false if S

  - ### getLegAction

    public int[] getLegAction()
    Leg type i layer interaction, one of TURN, REFLECTTOP, REFLECTBOT, TRANSUP, TRANSDOWN

  - ### hasArrivals

    public boolean hasArrivals()

  - ### calcTime

    public java.util.List<Arrival> calcTime​(double deg)
    calculates arrival times for this phase, sorted by time.

  - ### refineArrival

    public Arrival refineArrival​(int rayNum, double distRadian, double distTolRadian, int maxRecursion)

  - ### refineArrival

    public Arrival refineArrival​(Arrival leftEstimate, Arrival rightEstimate, double searchDist, double distTolRadian, int maxRecursion)

  - ### shootRay

    public Arrival shootRay​(double rayParam) throws SlownessModelException, NoSuchLayerException
    Throws:
      `SlownessModelException`
      `NoSuchLayerException`

  - ### calcRayParamForTakeoffAngle

    public double calcRayParamForTakeoffAngle​(double takeoffDegree)

  - ### calcTakeoffAngle

    public double calcTakeoffAngle​(double arrivalRayParam)

  - ### calcIncidentAngle

    public double calcIncidentAngle​(double arrivalRayParam)

  - ### phaseConversion

    protected void phaseConversion​(TauModel tMod, int fromBranch, int endAction, boolean isPtoS) throws TauModelException
    changes maxRayParam and minRayParam whenever there is a phase conversion. For instance, SKP needs to change the maxRayParam because there are SKS ray parameters that cannot propagate from the cmb into the mantle as a p wave.
    Throws:
      `TauModelException`

  - ### endActionString

    public static final java.lang.String endActionString​(int endAction)

  - ### addToBranch

    protected void addToBranch​(TauModel tMod, int startBranch, int endBranch, boolean isPWave, int endAction, java.lang.String currLeg) throws TauModelException
    Throws:
      `TauModelException`

  - ### closestBranchToDepth

    public int closestBranchToDepth​(TauModel tMod, java.lang.String depthString)
    Finds the closest discontinuity to the given depth that can have refletions and phase transformations.
    Returns:
      the branch number with the closest top depth.

  - ### parseName

    protected void parseName​(TauModel tMod) throws TauModelException
    Constructs a branch sequence from the given phase name and tau model.
    Throws:
      `TauModelException`

  - ### legPuller

    protected static java.util.ArrayList<java.lang.String> legPuller​(java.lang.String name) throws TauModelException
    Tokenizes a phase name into legs, ie PcS becomes 'P'+'c'+'S' while p^410P would become 'p'+'^410'+'P'. Once a phase name has been broken into tokens we can begin to construct the sequence of branches to which it corresponds. Only minor error checking is done at this point, for instance pIP generates an exception but ^410 doesn't. It also appends "END" as the last leg.
    Throws:
      `TauModelException` - if the phase name cannot be tokenized.

  - ### createPuristName

    protected void createPuristName​(TauModel tMod)

  - ### calcBranchMultiplier

    protected int[][] calcBranchMultiplier()
    Calculates how many times the phase passes through a branch, up or down, so that we can just multiply instead of doing the ray calc for each time.
    Returns:

  - ### sumBranches

    protected void sumBranches​(TauModel tMod) throws TauModelException
    Sums the appropriate branches for this phase.
    Throws:
      `TauModelException` - if the topDepth of the high slowness zone is not contained within the TauModel. This should never happen and would indicate an invalid TauModel.

  - ### calcPierce

    @Deprecated public java.util.List<Arrival> calcPierce​(double deg) throws TauModelException
    Deprecated.
    Use the getPierce() method on each Arrival from calcTime()
    Calculates the "pierce points" for the arrivals stored in arrivals. The pierce points are stored within each arrival object.
    Throws:
      `TauModelException`

  - ### calcPierce

    @Deprecated public Arrival calcPierce​(Arrival currArrival)
    Deprecated.
    Use the getPierce() method on each Arrival from calcTime()
    Calculates the pierce points for a particular arrival. The returned arrival is the same as the input arguement but now has the pierce points filled in.
    Parameters:
      `currArrival` -
    Returns:
      same arrival with pierce points

  - ### calcPierceTimeDist

    protected java.util.List<TimeDist> calcPierceTimeDist​(Arrival currArrival)

  - ### calcPath

    @Deprecated public java.util.List<Arrival> calcPath​(double deg)
    Deprecated.
    Use the getPath() method on each Arrival from calcTime()
    calculates the paths this phase takes through the earth model.

  - ### calcPath

    @Deprecated public Arrival calcPath​(Arrival currArrival)
    Deprecated.
    use the getPath() method on the arrival.
    Parameters:
      `currArrival` -
    Returns:

  - ### calcPathTimeDist

    protected java.util.List<TimeDist> calcPathTimeDist​(Arrival currArrival)

  - ### getValidationFailMessage

    public java.lang.String getValidationFailMessage()

  - ### phaseValidate

    public static java.lang.String phaseValidate​(java.util.ArrayList<java.lang.String> legs)
    Performs consistency checks on the previously tokenized phase name stored in legs. Returns null if all is ok, a message if there is a problem.

  - ### getEarliestArrival

    public static Arrival getEarliestArrival​(java.util.List<SeismicPhase> phases, double degrees)

  - ### describe

    public java.lang.String describe()

  - ### toString

    public java.lang.String toString()
    Overrides:
      `toString` in class `java.lang.Object`

  - ### dump

    public void dump()

  - ### main

    public static void main​(java.lang.String[] args)