Package xal.model.alg

Class EnvTrackerAdapt

java.lang.Object
xal.model.alg.Tracker
xal.model.alg.EnvelopeTrackerBase
xal.model.alg.EnvTrackerAdapt
All Implemented Interfaces:
Remote, IAlgorithm, IArchive, IContextAware
public class EnvTrackerAdapt extends EnvelopeTrackerBase

Tracking algorithm for EnvelopeProbe's. The EnvelopeProbe's state, which is a CovarianceMatrix object, is advanced using the linear dynamics portion of any beamline element (IElement exposing object) transfer map. The linear portion is represented as a matrix, thus, the state advance is accomplished with a transpose conjugation with this matrix.

The effects of space charge are also included in the dynamics calculations. Space charge effects are also represented with a matrix transpose conjugation, however, the matrix is computed using the values of the probe's correlation matrix. The result is a nonlinear effect. The space charge forces are computed using a linear fit to the fields generated by an ellipsoidal charge distribution with the same statistics described in the probe's correlation matrix. The linear fit is weighted by the beam distribution itself, so it is more accurate in regions of higher charged density. For a complete description see the reference below.

This algorithm uses a second-order accurate, adaptive step sizing algorithm where the step size is continually adjusted to maintain an given error tolerance in the residual.

Author:
Christopher K. Allen
See Also:

  • Field Details

    • NORM_LINF

      public static final int NORM_LINF
      l-infinity norm
      See Also:

    • NORM_L1

      public static final int NORM_L1
      l-1 norm
      See Also:

    • NORM_L2

      public static final int NORM_L2
      l-2 norm
      See Also:

    • ACCUR_ERROR

      public static final int ACCUR_ERROR
      Error condition in integration accuracy
      See Also:

    • ACCUR_ORDER1

      public static final int ACCUR_ORDER1
      1st order accurate integration algorithm
      See Also:

    • ACCUR_ORDER2

      public static final int ACCUR_ORDER2
      2nd order accurate integration algorithm
      See Also:

    • ACCUR_RANGE

      public static final int ACCUR_RANGE
      Range of available integration accuracies
      See Also:

    • TYPE_ID

      public static final String TYPE_ID
      string type identifier for algorithm

    • VERSION

      public static final int VERSION
      current algorithm version
      See Also:

    • CLS_PROBE_TYPE

      public static final Class<EnvelopeProbe> CLS_PROBE_TYPE
      probe type recognized by this algorithm

  • Constructor Details

    • EnvTrackerAdapt

      public EnvTrackerAdapt()
      Creates a new, uninitialized instance of EnvTrackerAdapt

    • EnvTrackerAdapt

      public EnvTrackerAdapt(EnvTrackerAdapt sourceTracker)
      Copy constructor for EnvTrackerAdapt
      Parameters:
      sourceTracker - Tracker that is being copied

  • Method Details

    • copy

      public EnvTrackerAdapt copy()
      Creates a deep copy of EnvTrackerAdapt

    • initialize

      public void initialize()
      Initialize the algorithm object for propagation. Internal state of algorithm object is initialized: - Step size is set to initial step size - Start/Stop elements are inspected
      Specified by:
      initialize in interface IAlgorithm
      Overrides:
      initialize in class Tracker
      See Also:

    • setInitStepSize

      public void setInitStepSize(double dblStepSize)
      Set the initial step size for applying space charge corrections. Note that the step size will be modified as the algorithm progresses according to the adaptation rule. The current step size is reset to this value anytime the initialize() method is called.
      Parameters:
      dblStepSize - initial step size in meters
      See Also:

    • setStepSize

      public void setStepSize(double dblStepSize)
      Set the current step size for applying space charge corrections. Note that the step size will be modified as the algorithm progresses according to the adaptation rule.
      Overrides:
      setStepSize in class EnvelopeTrackerBase
      Parameters:
      dblStepSize - initial step size in meters

    • setMaxStepSize

      public void setMaxStepSize(double dblMaxStep)
      Set the maximum allowable step size. If this value is set then the step sizing algorithm will never generate steps larger than the provided value regardless of the residual error. If this value is cleared to zero, then the step size is unbound.
      Parameters:
      dblMaxStep - maximum allowable step size in meters

    • setMaxStepSizeDriftPmq

      public void setMaxStepSizeDriftPmq(double dblMaxStepDriftPmq)
      Set the maximum allowable step size. If this value is set then the step sizing algorithm will never generate steps larger than the provided value regardless of the residual error. If this value is cleared to zero, then the step size is unbound.
      Parameters:
      dblMaxStepDriftPmq - maximum allowable step size in meters

    • setMaxIterations

      public void setMaxIterations(int intMaxIter)
      Sets the maximum allowable number of steps to propagate a probe through an element. If the number of steps increases beyond this number a race condition is assumed and an exception is thrown during the propagation. If the value is zero then no maximum step count is enforced.
      Parameters:
      intMaxIter - maximum allowable single-element step count

    • setErrorTolerance

      public void setErrorTolerance(double dblErr)
      Set the acceptable error in the residual correlation matrix. The residual correlation matrix is determined by going a full step, then two half step and taking the difference in the resulting correlation matrices. The step size is continually adjusted to keep the resulting residual error at or about this given tolerance value. Thus, yield a more accurate solution however they also result in small step sizes.
      Parameters:
      dblErr - acceptable residual error

    • setAccuracyOrder

      public void setAccuracyOrder(int intOrder)
      Set the integration accuracy order for the underlying stepping algorithm. For example, when using a second-order accurate algorithm the residual error is of the order h^2 where h is the step size.
      Parameters:
      intOrder - integration order

    • setSlackTolerance

      public void setSlackTolerance(double dblSlack)
      Set the slack size in the adaptive step size determination. That is, if the suggested new step size differs only by this percentage, then no action is taken. Explicitly, if the new step size lies in the interval [h-dblSlack, h+dblSlack], then nothing is done. This feature prevents excessive micro-management of the step size.
      Parameters:
      dblSlack - size of the slack region in meters

    • setMatrixNorm

      public void setMatrixNorm(int enmNorm)
      Set the type of Lebesque norm used in the matrix calculations.
      Parameters:
      enmNorm - enumeration constant of family EnvTrackerAdapt.NORM_*

    • getInitStepSize

      public double getInitStepSize()
      Return the initial step size for this algorithm. This is the step size when beginning a propagation. Note that the actual step size used afterwards will likely change due to the adaptive nature of the algorithm.
      Returns:
      initial step size in meters

    • getStepSize

      public double getStepSize()
      Return the current step size, that is, the step size currently used in the propagation.
      Overrides:
      getStepSize in class EnvelopeTrackerBase
      Returns:
      the current step size in meters

    • getMaxIterations

      public int getMaxIterations()
      Return the maximum allowable number of steps to propagate a probe through an element. If the number of steps increases beyond this number a race condition is assumed and an exception is thrown during the propagation. If the value is zero then no maximum step count is enforced.
      Returns:
      maximum allowable step count while propagating thru a single element

    • getMaxStepSize

      public double getMaxStepSize()
      Return the maximum allowable step size. The step sizing algorithm is bound by this value, or unbounded if zero.
      Returns:
      maximum allowable step size in meters

    • getMaxStepSizeDriftPmq

      public double getMaxStepSizeDriftPmq()
      Return the maximum allowable step size. The step sizing algorithm is bound by this value, or unbounded if zero.
      Returns:
      maximum allowable step size in meters

    • getAccuracyOrder

      public int getAccuracyOrder()
      Get the current accuracy order of the space charge stepping algorithm.
      Returns:
      order of the integration algorithm accuracy
      See Also:

    • getErrorTolerance

      public double getErrorTolerance()
      Return the acceptable tolerance in the residual error between a full step and two half steps.
      Returns:
      tolerable residual error

    • getSlackTolerance

      public double getSlackTolerance()
      Step size adjustment slack tolerance. If adjustments in the step size are less than this percentage, we do nothing.
      Returns:
      size of the slack region in meters

    • getMatrixNorm

      public int getMatrixNorm()
      Get the type of Lebesque norm used for matrices.
      Returns:
      0 for l-inf norm, 1 for l-1 norm, 2 for l2 norm

    • doPropagation

      public void doPropagation(IProbe ifcProbe, IElement elem) throws ModelException
      Propagates the probe through the element using a second-order accurate adaptive step size algorithm for space charge calculations. The new probe state is first computed by taken a full step with the second- order accurate transfer matrix with includes space charge effect. The algorithm then computes the new probe state by taking two half-steps. The residual error (correlation matrix) between the two states is computed. If the norm of the matrix is below the error tolerance (@see #getErrorTolerance) the step may be lengthened. If the residual error is greater than tolerance the step size must be shortened and the new probe state recomputed.
      Specified by:
      doPropagation in class Tracker
      Parameters:
      ifcProbe - probe to propagate
      elem - element acting on probe
      Throws:
      ModelException - invalid probe type or error in advancing probe
      See Also:

    • load

      public void load(String strPrimKeyVal, EditContext ecTableData) throws DataFormatException
      Load the parameters of this IAlgorithm object from the table data in the given EditContext. Here we load only the parameters specific to the base class. It is expected that Subclasses should override this method to recover the data particular to there own operation.
      Specified by:
      load in interface IContextAware
      Overrides:
      load in class EnvelopeTrackerBase
      Parameters:
      strPrimKeyVal - primary key value specifying the name of the data record
      ecTableData - EditContext containing table data
      Throws:
      DataFormatException - bad data format - error in reading
      See Also:

    • load

      public void load(DataAdaptor daptArchive) throws DataFormatException
      Load the parameters of the algorithm from a data source exposing the IArchive interface. The superclass load method is called first, then the properties particular to EnvTrackerAdapt are loaded.
      Specified by:
      load in interface IArchive
      Overrides:
      load in class EnvelopeTrackerBase
      Parameters:
      daptArchive - data source containing algorithm configuration
      Throws:
      DataFormatException - bad format in algorithm data
      See Also:

    • save

      public void save(DataAdaptor daptArchive)
      Save the settings particular to this subclass of Tracker. The superclass save method is called first, then the properties particular to EnvTrackerAdapt are saved.
      Specified by:
      save in interface IArchive
      Overrides:
      save in class EnvelopeTrackerBase
      Parameters:
      daptArchive - data sink exposing IArchive interface
      See Also:

    • stepThinElement

      protected void stepThinElement(EnvelopeProbe probe, IElement ifcElem) throws ModelException
      new stepThinElement by Sako, taken from EnvelopeTracker Advances the probe state through a subsection of the element with the specified length. Applies a space charge kick at the end of the element subsection for any probe having nonzero beam current.
      Parameters:
      ifcElem - interface to the beam element
      probe - interface to the probe
      Throws:
      ModelException - bad element transfer matrix/corrupt probe state