Class SlownessModel

  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    SphericalSModel

    public abstract class SlownessModel
    extends java.lang.Object
    implements java.io.Serializable
    This class provides storage and methods for generating slowness-depth pairs.
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected boolean allowInnerCoreS
      Should we allow J phases, S waves in the inner core? If true, then the slowness sampling for S will use the S velocity structure for the inner core.
      protected java.util.List<CriticalDepth> criticalDepths
      Stores the layer number for layers in the velocity model with a critical point at their top.
      static boolean DEBUG
      True to enable debugging output.
      static double DEFAULT_SLOWNESS_TOLERANCE  
      protected java.util.List<DepthRange> fluidLayerDepths
      Stores depth ranges that are fluid, ie S velocity is zero.
      protected java.util.List<DepthRange> highSlownessLayerDepthsP
      Stores depth ranges that contains a high slowness zone for P.
      protected java.util.List<DepthRange> highSlownessLayerDepthsS
      Stores depth ranges that contains a high slowness zone for S.
      protected double maxDeltaP
      Maximum difference between successive slowness samples.
      protected double maxDepthInterval
      Maximum difference between successive depth samples, default is 115 km.
      protected double maxInterpError  
      protected double maxRangeInterval
      Maximum difference between successive ranges, in radians.
      protected double minDeltaP
      Minimum difference between successive slowness samples.
      protected java.util.List<SlownessLayer> PLayers
      Stores the final slowness-depth layers for P waves.
      static boolean PWAVE
      Just useful for calling methods that need to know whether to use P or S waves.
      protected double radiusOfEarth
      Radius of the Earth in km, usually input from the velocity model.
      protected java.util.List<SlownessLayer> SLayers
      Stores the final slowness-depth layers for S waves.
      protected double slownessTolerance
      Tolerance for slownesses.
      static boolean SWAVE
      Just useful for calling methods that need to know whether to use P or S waves.
      protected static int vectorLength
      Initial length of the slowness vectors.
      static boolean verbose
      True to enable verbose output.
      protected VelocityModel vMod
      Velocity Model used to get slowness model.
    • Constructor Summary

      Constructors 
      Constructor Description
      SlownessModel​(double radiusOfEarth, VelocityModel vMod, java.util.List<CriticalDepth> criticalDepth, java.util.List<DepthRange> highSlownessLayerDepthsP, java.util.List<DepthRange> highSlownessLayerDepthsS, java.util.List<DepthRange> fluidLayerDepths, java.util.List<SlownessLayer> pLayers, java.util.List<SlownessLayer> sLayers, double minDeltaP, double maxDeltaP, double maxDepthInterval, double maxRangeInterval, double maxInterpError, boolean allowInnerCoreS, double slownessTolerance)  
      SlownessModel​(VelocityModel vMod, double minDeltaP, double maxDeltaP, double maxDepthInterval, double maxRangeInterval, double maxInterpError, boolean allowInnerCoreS, double slownessTolerance)  
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected void addSlowness​(double p, boolean isPWave)
      Adds the given ray parameter, p, to the slowness sampling for the given waveType.
      TimeDist approxDistance​(int slownessTurnLayer, double p, boolean isPWave)
      generate approximate distance, in radians, for a ray from a surface source that turns at the bottom of the given slowness layer.
      org.json.JSONObject asJSON()  
      protected void coarseSample()
      Creates a coarse slowness sampling of the velocity model (vMod).
      protected void depthIncCheck()
      Checks to make sure no slowness layer spans more than maxDepthInterval.
      boolean depthInFluid​(double depth)
      Determines if the given depth is contained within a fluid zone.
      boolean depthInFluid​(double depth, DepthRange fluidZoneDepth)
      Determines if the given depth is contained within a fluid zone.
      boolean depthInHighSlowness​(double depth, double rayParam, boolean isPWave)
      Determines if the given depth and corresponding slowness is contained within a high slowness zone.
      boolean depthInHighSlowness​(double depth, double rayParam, DepthRange highSZoneDepth, boolean isPWave)
      Determines if the given depth and corresponding slowness is contained within a high slowness zone.
      protected void distanceCheck()
      Checks to make sure no slowness layer spans more than maxRangeInterval and that the (estimated) error due to linear interpolation is less than maxInterpError.
      protected void findCriticalPoints()
      Finds all critical points within a velocity model.
      double findDepth​(double rayParam, boolean isPWave)
      Finds a depth corresponding to a slowness over the whole VelocityModel.
      double findDepth​(double rayParam, double topDepth, double botDepth, boolean isPWave)
      Finds a depth corresponding to a slowness between two given depths in the Velocity Model.
      double findDepth​(double p, int topCriticalLayer, int botCriticalLayer, boolean isPWave)
      Finds a depth corresponding to a slowness between two given velocity layers, including the top and the bottom.
      protected void fixCriticalPoints()
      Resets the slowness layers that correspond to critical points.
      protected java.util.List<SlownessLayer> getAllSlownessLayers​(boolean isPWave)  
      CriticalDepth getCriticalDepth​(int i)  
      DepthRange[] getHighSlowness​(boolean isPWave)  
      double getMaxDeltaP()  
      double getMaxDepthInterval()  
      double getMaxInterpError()
      gets the maximum value of the estimated error due to linear interpolation.
      double getMaxRangeInterval()  
      double getMinDeltaP()  
      double getMinRayParam​(double depth, boolean isPWave)  
      double getMinTurnRayParam​(double depth, boolean isPWave)  
      int getNumCriticalDepths()  
      int getNumLayers​(boolean isPWave)  
      double getRadiusOfEarth()  
      protected SlownessLayer getSlownessLayer​(int layerNum, boolean isPWave)
      Returns the SlownessLayer of the requested waveType.
      double getSlownessTolerance()  
      VelocityModel getVelocityModel()  
      abstract double interpolate​(double p, double topVelocity, double topDepth, double slope)  
      boolean isAllowInnerCoreS()  
      SlownessLayer layerAbove​(double depth, boolean isPWave)
      Finds the slowness layer that contains the given depth Note that if the depth is a layer boundary, it returns the shallower of the two or possibly more (since total reflections are zero thickness layers) layers.
      SlownessLayer layerBelow​(double depth, boolean isPWave)
      Finds the slowness layer that contains the given depth Note that if the depth is a layer boundary, it returns the deeper of the two or possibly more (since total reflections are zero thickness layers) layers.
      int layerNumberAbove​(double depth, boolean isPWave)
      Finds the index of the slowness layer that contains the given depth Note that if the depth is a layer boundary, it returns the shallower of the two or possibly more (since total reflections are zero thickness layers) layers.
      int layerNumberBelow​(double depth, boolean isPWave)
      Finds the index of the slowness layer that contains the given depth Note that if the depth is a layer boundary, it returns the deeper of the two or possibly more (since total reflections are zero thickness layers) layers.
      int layerNumForDepth​(double depth, boolean isPWave)
      finds a layer that contains the depth.
      TimeDist layerTimeDist​(double rayParam, int layerNum, boolean isPWave)  
      abstract TimeDist layerTimeDist​(double rayParam, int layerNum, boolean isPWave, boolean downgoing)  
      abstract TimeDist layerTimeDistAllowTurn​(double rayParam, int layerNum, boolean isPWave, boolean downgoing)  
      void printGMT​(java.io.PrintWriter dos)
      prints out the slowness model into a file in a for suitable for plotting with GMT.
      void printGMT​(java.lang.String filename)
      prints out the velocity model into a file in a form suitable for plotting with GMT.
      protected void rayParamIncCheck()
      Checks to make sure that no slowness layer spans more than maxDeltaP.
      void setAllowInnerCoreS​(boolean allowInnerCoreS)  
      void setMaxDeltaP​(double maxDeltaP)  
      void setMaxDepthInterval​(double maxDepthInterval)  
      void setMaxInterpError​(double maxInterpError)
      sets the maximum value of the estimated error due to linear interpolation.
      void setMaxRangeInterval​(double maxRangeInterval)
      sets the maximum range interval for surface focus turning waves between slowness samples, input in degrees.
      void setMinDeltaP​(double minDeltaP)  
      void setRadiusOfEarth​(double radiusOfEarth)  
      void setSlownessTolerance​(double slownessTolerance)  
      SplitLayerInfo splitLayer​(double depth, boolean isPWave)  
      protected SlownessLayer[] splitLayerForNewRayParam​(double p, boolean isPWave, SlownessLayer sLayer)  
      abstract double toSlowness​(double velocity, double depth)  
      abstract SlownessLayer toSlownessLayer​(VelocityLayer vLayer, boolean isPWave)  
      java.lang.String toString()  
      abstract double toVelocity​(double slowness, double depth)  
      boolean validate()
      Performs consistency check on the slowness model.
      boolean validateRPCompatibility()  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • DEBUG

        public static boolean DEBUG
        True to enable debugging output.
      • verbose

        public static boolean verbose
        True to enable verbose output.
      • radiusOfEarth

        protected double radiusOfEarth
        Radius of the Earth in km, usually input from the velocity model.
      • vMod

        protected VelocityModel vMod
        Velocity Model used to get slowness model. Usually set in createSlowness().
      • criticalDepths

        protected java.util.List<CriticalDepth> criticalDepths
        Stores the layer number for layers in the velocity model with a critical point at their top. These form the "branches" of slowness sampling.
        See Also:
        CriticalDepth
      • highSlownessLayerDepthsP

        protected java.util.List<DepthRange> highSlownessLayerDepthsP
        Stores depth ranges that contains a high slowness zone for P. Stored as DepthRange objects, containing the top depth and bottom depth.
        See Also:
        DepthRange
      • highSlownessLayerDepthsS

        protected java.util.List<DepthRange> highSlownessLayerDepthsS
        Stores depth ranges that contains a high slowness zone for S. Stored as DepthRange objects, containing the top depth and bottom depth.
        See Also:
        DepthRange
      • fluidLayerDepths

        protected java.util.List<DepthRange> fluidLayerDepths
        Stores depth ranges that are fluid, ie S velocity is zero. Stored as DepthRange objects, containing the top depth and bottom depth.
        See Also:
        DepthRange
      • vectorLength

        protected static int vectorLength
        Initial length of the slowness vectors.
      • PLayers

        protected java.util.List<SlownessLayer> PLayers
        Stores the final slowness-depth layers for P waves. Stored as SlownessLayer objects.
        See Also:
        SlownessLayer
      • SLayers

        protected java.util.List<SlownessLayer> SLayers
        Stores the final slowness-depth layers for S waves. Stored as SlownessLayer objects. Note that SLayers and PLayers share the same SlownessLayer object within fluid layers, so changes made to one will affect the other.
        See Also:
        SlownessLayer
      • minDeltaP

        protected double minDeltaP
        Minimum difference between successive slowness samples. The default is 0.1 (km-sec/km or sec/rad for spherical, sec/km for flat models). This keeps the sampling from becoming too fine. For example, a strong negative S velocity gradient just above the CMB will cause the totally reflected ScS too have an extremely large range of distances, over a very small range of ray parameters. The distance check would otherwise force a very fine sampling of this region. However since in this case time and distance are likely to be very close to being linearly related, this sort of sampling is overkill. So we ignore the distance check if the ray parameter becomes smaller than minDeltaP.
      • maxDeltaP

        protected double maxDeltaP
        Maximum difference between successive slowness samples. The default is 11.0 (km-sec/km or sec/rad for spherical, sec/km for flat models). See Buland and Chapman p1292
      • maxDepthInterval

        protected double maxDepthInterval
        Maximum difference between successive depth samples, default is 115 km. See Buland and Chapman p1292
      • maxRangeInterval

        protected double maxRangeInterval
        Maximum difference between successive ranges, in radians. The default is 200 km / radiusOfEarth. See Buland and Chapman p1292.
      • maxInterpError

        protected double maxInterpError
      • allowInnerCoreS

        protected boolean allowInnerCoreS
        Should we allow J phases, S waves in the inner core? If true, then the slowness sampling for S will use the S velocity structure for the inner core. If false, then we will use the P velocity structure for both the inner and outer core for S waves as well as P waves. Disallowing inner core S phases reduces the number of slowness samples significantly due to the large geometrical spreading of S waves in the inner core. The default is false.
      • DEFAULT_SLOWNESS_TOLERANCE

        public static final double DEFAULT_SLOWNESS_TOLERANCE
        See Also:
        Constant Field Values
      • slownessTolerance

        protected double slownessTolerance
        Tolerance for slownesses. If two slownesses are closer that this value, then we consider them to be identical. Basically this just provides some protection against numerical "chatter".
      • PWAVE

        public static final boolean PWAVE
        Just useful for calling methods that need to know whether to use P or S waves.
        See Also:
        Constant Field Values
      • SWAVE

        public static final boolean SWAVE
        Just useful for calling methods that need to know whether to use P or S waves.
        See Also:
        Constant Field Values
    • Method Detail

      • setRadiusOfEarth

        public void setRadiusOfEarth​(double radiusOfEarth)
      • setMinDeltaP

        public void setMinDeltaP​(double minDeltaP)
      • setMaxDeltaP

        public void setMaxDeltaP​(double maxDeltaP)
      • setMaxDepthInterval

        public void setMaxDepthInterval​(double maxDepthInterval)
      • setMaxRangeInterval

        public void setMaxRangeInterval​(double maxRangeInterval)
        sets the maximum range interval for surface focus turning waves between slowness samples, input in degrees.
      • setMaxInterpError

        public void setMaxInterpError​(double maxInterpError)
        sets the maximum value of the estimated error due to linear interpolation. Care should be taken not to set this too small as a very large number of samples may be required. Note also that this is only an estimate of the error, and thus the bound is by no means assured.
      • setAllowInnerCoreS

        public void setAllowInnerCoreS​(boolean allowInnerCoreS)
      • setSlownessTolerance

        public void setSlownessTolerance​(double slownessTolerance)
      • getRadiusOfEarth

        public final double getRadiusOfEarth()
      • getMinDeltaP

        public final double getMinDeltaP()
      • getMaxDeltaP

        public final double getMaxDeltaP()
      • getMaxDepthInterval

        public final double getMaxDepthInterval()
      • getMaxRangeInterval

        public final double getMaxRangeInterval()
        Returns:
        the maximum range interval for surface focus turning waves between slowness samples output in degrees.
      • getMaxInterpError

        public final double getMaxInterpError()
        gets the maximum value of the estimated error due to linear interpolation. Care should be taken not to set this too small as a very large number of samples may be required. Note also that this is only an estimate of the error, and thus the bound is by no means assured.
      • isAllowInnerCoreS

        public final boolean isAllowInnerCoreS()
      • getSlownessTolerance

        public final double getSlownessTolerance()
      • getNumCriticalDepths

        public final int getNumCriticalDepths()
      • getCriticalDepth

        public final CriticalDepth getCriticalDepth​(int i)
      • getNumLayers

        public final int getNumLayers​(boolean isPWave)
      • getMinTurnRayParam

        public double getMinTurnRayParam​(double depth,
                                         boolean isPWave)
                                  throws NoSuchLayerException,
                                         SlownessModelException
        Returns:
        the minimum ray parameter that turns, but is not reflected, at or above the given depth. Normally this is the slowness sample at the given depth, but if the depth is within a high slowness zone, then it may be smaller.
        Throws:
        NoSuchLayerException
        SlownessModelException
      • getMinRayParam

        public double getMinRayParam​(double depth,
                                     boolean isPWave)
                              throws NoSuchLayerException,
                                     SlownessModelException
        Returns:
        the minimum ray parameter that turns or is critically reflected at or above the given depth. Normally this is the slowness sample at the given depth, but if the depth is within a high slowness zone, then it may be smaller. Also, at first order discontinuities, there may be many slowness samples at the same depth.
        Throws:
        NoSuchLayerException
        SlownessModelException
      • getHighSlowness

        public DepthRange[] getHighSlowness​(boolean isPWave)
        Returns:
        the DepthRange objects for all high slowness zones within the slowness model.
      • getSlownessLayer

        protected SlownessLayer getSlownessLayer​(int layerNum,
                                                 boolean isPWave)
        Returns the SlownessLayer of the requested waveType. This is NOT a clone and any changes will possibly corrupt the SlownessModel.
      • getAllSlownessLayers

        protected java.util.List<SlownessLayer> getAllSlownessLayers​(boolean isPWave)
      • approxDistance

        public TimeDist approxDistance​(int slownessTurnLayer,
                                       double p,
                                       boolean isPWave)
                                throws SlownessModelException
        generate approximate distance, in radians, for a ray from a surface source that turns at the bottom of the given slowness layer.
        Throws:
        SlownessModelException - occurs if getNumLayers() == 0 as we cannot compute a distance without a layer.
      • depthInHighSlowness

        public boolean depthInHighSlowness​(double depth,
                                           double rayParam,
                                           boolean isPWave)
        Determines if the given depth and corresponding slowness is contained within a high slowness zone. Whether the high slowness zone includes its upper boundary and its lower boundaries depends upon the ray parameter. The slowness at the depth is needed because if depth happens to correspond to a discontinuity that marks the bottom of the high slowness zone but the ray is actually a total reflection then it is not part of the high slowness zone. Calls depthInHighSlowness(double, double, DepthRange).
        See Also:
        depthInHighSlowness(double, double, DepthRange, boolean)
      • depthInHighSlowness

        public boolean depthInHighSlowness​(double depth,
                                           double rayParam,
                                           DepthRange highSZoneDepth,
                                           boolean isPWave)
        Determines if the given depth and corresponding slowness is contained within a high slowness zone. Whether the high slowness zone includes its upper boundary and its lower boundaries depends upon the ray parameter. The slowness at the depth is needed because if depth happens to correspond to a discontinuity that marks the bottom of the high slowness zone but the ray is actually a total reflection then it is not part of the high slowness zone. The ray parameter that delimits the zone, ie it can turn at the top and the bottom, is in the zone at the top, but out of the zone at the bottom.
      • depthInFluid

        public boolean depthInFluid​(double depth)
        Determines if the given depth is contained within a fluid zone. The fluid zone includes its upper boundary but not its lower boundary. Calls depthInFluid(double, DepthRange).
        See Also:
        depthInFluid(double, DepthRange)
      • depthInFluid

        public boolean depthInFluid​(double depth,
                                    DepthRange fluidZoneDepth)
        Determines if the given depth is contained within a fluid zone. The fluid zone includes its upper boundary but not its lower boundary. The top and bottom of the fluid zone are returned in DepthRange.
      • findCriticalPoints

        protected void findCriticalPoints()
                                   throws SlownessModelException
        Finds all critical points within a velocity model. Critical points are first order discontinuities in velocity/slowness, local extrema in slowness. A high slowness zone is a low velocity zone, but it is possible to have a slight low velocity zone within a spherical earth that is not a high slowness zone and thus does not exhibit any of the pathological behavior of a low velocity zone.
        Throws:
        SlownessModelException - occurs if validate() returns false, this indicates a bug in the code.
      • findDepth

        public double findDepth​(double rayParam,
                                boolean isPWave)
                         throws SlownessModelException
        Finds a depth corresponding to a slowness over the whole VelocityModel. Calls findDepth(double, int, int, char).
        Throws:
        SlownessModelException
      • findDepth

        public double findDepth​(double rayParam,
                                double topDepth,
                                double botDepth,
                                boolean isPWave)
                         throws SlownessModelException
        Finds a depth corresponding to a slowness between two given depths in the Velocity Model. Calls findDepth(double, int, int, char).
        Throws:
        SlownessModelException
      • findDepth

        public double findDepth​(double p,
                                int topCriticalLayer,
                                int botCriticalLayer,
                                boolean isPWave)
                         throws SlownessModelException
        Finds a depth corresponding to a slowness between two given velocity layers, including the top and the bottom. We also check to see if the slowness is less than the bottom slowness of these layers but greater than the top slowness of the next deeper layer. This corresponds to a total reflection. In this case a check needs to be made to see if this is an S wave reflecting off of a fluid layer, use P velocity below in this case. We assume that slowness is monotonic within these layers and therefore there is only one depth with the given slowness. This means we return the first depth that we find.
        Throws:
        SlownessModelException - occurs if topCriticalLayer > botCriticalLayer because there are no layers to search, or if there is an increase in slowness, ie a negative velocity gradient, that just balances the decrease in slowness due to the spherical earth, or if the ray parameter p is not contained within the specified layer range.
      • addSlowness

        protected void addSlowness​(double p,
                                   boolean isPWave)
                            throws SlownessModelException,
                                   NoSuchLayerException
        Adds the given ray parameter, p, to the slowness sampling for the given waveType. It splits slowness layers as needed and keeps P and S sampling consistant within fluid layers. Note, this makes use of the velocity model, so all interpolation is linear in velocity, not in slowness!
        Throws:
        SlownessModelException
        NoSuchLayerException
      • layerNumForDepth

        public int layerNumForDepth​(double depth,
                                    boolean isPWave)
                             throws NoSuchLayerException
        finds a layer that contains the depth. This may not be unique in the case of a depth on a boundary in the velocity model due to zero thickness layers. If the uppermost or lowermost layer containing the depth is needed, use layerNumberAbove() or layerNumberBelow().
        Throws:
        NoSuchLayerException
      • layerNumberAbove

        public int layerNumberAbove​(double depth,
                                    boolean isPWave)
                             throws NoSuchLayerException
        Finds the index of the slowness layer that contains the given depth Note that if the depth is a layer boundary, it returns the shallower of the two or possibly more (since total reflections are zero thickness layers) layers.
        Returns:
        the layer number.
        Throws:
        NoSuchLayerException - occurs if no layer in the slowness model contains the given depth.
      • layerAbove

        public SlownessLayer layerAbove​(double depth,
                                        boolean isPWave)
                                 throws NoSuchLayerException
        Finds the slowness layer that contains the given depth Note that if the depth is a layer boundary, it returns the shallower of the two or possibly more (since total reflections are zero thickness layers) layers.
        Returns:
        the layer
        Throws:
        NoSuchLayerException - occurs if no layer in the slowness model contains the given depth.
      • layerNumberBelow

        public int layerNumberBelow​(double depth,
                                    boolean isPWave)
                             throws NoSuchLayerException
        Finds the index of the slowness layer that contains the given depth Note that if the depth is a layer boundary, it returns the deeper of the two or possibly more (since total reflections are zero thickness layers) layers.
        Returns:
        the layer number.
        Throws:
        NoSuchLayerException - occurs if no layer in the slowness model contains the given depth.
      • layerBelow

        public SlownessLayer layerBelow​(double depth,
                                        boolean isPWave)
                                 throws NoSuchLayerException
        Finds the slowness layer that contains the given depth Note that if the depth is a layer boundary, it returns the deeper of the two or possibly more (since total reflections are zero thickness layers) layers.
        Returns:
        the layer
        Throws:
        NoSuchLayerException - occurs if no layer in the slowness model contains the given depth.
      • printGMT

        public void printGMT​(java.lang.String filename)
                      throws java.io.IOException
        prints out the velocity model into a file in a form suitable for plotting with GMT.
        Throws:
        java.io.IOException
      • printGMT

        public void printGMT​(java.io.PrintWriter dos)
                      throws java.io.IOException
        prints out the slowness model into a file in a for suitable for plotting with GMT.
        Throws:
        java.io.IOException
      • asJSON

        public org.json.JSONObject asJSON()
      • validate

        public boolean validate()
                         throws SlownessModelException
        Performs consistency check on the slowness model.
        Returns:
        true if successful, throws SlownessModelException otherwise.
        Throws:
        SlownessModelException - if any check fails
      • toString

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

        public boolean validateRPCompatibility()