Package xal.model.alg

Class Tracker

java.lang.Object
xal.model.alg.Tracker
All Implemented Interfaces:
Remote, IAlgorithm, IArchive, IContextAware
Direct Known Subclasses:
DiagnosticTracker, EnsembleTracker, EnvelopeTrackerBase, ParticleTracker, SynchronousTracker, Trace3dTracker, TrackerAdaptive, TransferMapTracker, TwissTracker
public abstract class Tracker extends Object implements IAlgorithm, IArchive

Abstract Base Class for Tracking Algorithms

Provides boiler plate functionality for probe tracking algorithms from which more sophisticated algorithms may inherit.

Tracking algorithm objects are classes that implement the IAlgorithm interface. This class provides default implementations for all methods of the IAlgorithm interface. Derived classes must implement the doPropagation() abstract method in order to provide the actual dynamics of the algorithm. Note that derived classes may wish to override the propagate(IProbe, IElement) method directly for complete control of the propagation mechanism.

This class provides the methods the methods advanceProbe and retractProbe for forward-propagating and back-propagating the common probe properties upstream and downstream, respectively. (Common properties meaning all properties except the defining state, which is clearly unknowable by this class.) These methods are conveniences meant to be used in the abstract method doPropagation.

NOTES:   CKA
· We might get a significant performance upgrade by eliminating the calls to validElement(IElement) and validProbe(IProbe) within the method propagate(IProbe, IElement).
· Derived classes should call registerProbeType(Class) in order that the the validProbe() method function properly, that is, identify all probes that this class recognizes.
· Perhaps it's better to eliminate validProbe as a safety measure since, in the current implementation, each probe carries it's own algorithm object. So the probe already knows it's valid.

Author:
Christopher K. Allen, Craig McChesney
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    ATTRTAG_DEBUG
    attribute tag for debugging flag
    static final String
    ATTRTAG_RFGAP_PHASE
    flag to update the beam phase in RF gaps ( a la parmila) rather than use default values
    static final String
    ATTRTAG_TYPE
    attribute label for type string identifier
    static final String
    ATTRTAG_UPDATE
    attribute tag for trajectory state update policy
    static final String
    ATTRTAG_VER
    attribute tag for the algorithm version number
    static final String
    NODETAG_ALG
    data node label for algorithm data
    static final String
    NODETAG_TRACKER
    data node tag for common data
    static final String
    TBL_LBL_ALGORITHM
    EditContext table name for Tracker Data
    static final String
    TBL_PRIM_KEY_NAME
    Table record primary key name
    static final int
    UPDATE_ALWAYS
    save every state whenever probe is moved
    static final int
    UPDATE_CUSTOM
    never update - this is done custom somewhere else
    static final int
    UPDATE_ENTRANCE
    save state at element entrance
    static final int
    UPDATE_ENTRANCEANDEXIT
    save state at element exit and entrance
    static final int
    UPDATE_EXIT
    save state at element exit only

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Tracker(String strType, int intVersion, Class<? extends IProbe> clsProbeType)
    Creates a new, empty, instance of Tracker.
    protected
    Tracker(Tracker sourceTracker)
    Copy constructor for Tracker

  • Method Summary

    Modifier and Type
    Method
    Description
    protected void
    advanceProbe(IProbe probe, IElement elem, double dblLen)
    Convenience method for common propagation dynamics for all probes.
    abstract void
    doPropagation(IProbe probe, IElement elem)
    The implementation must propagate the probe through the element according to the dynamics of the specific algorithm.
    boolean
    getDebugMode()
    Indicate whether or not algorithm is in debug mode.
    protected double
    getElemPosition()
    Return the current position within the element through which the probe is being propagated
    Class<? extends IProbe>
    getProbeType()
    The implementation must propagate the probe through the element according to the dynamics of the specific algorithm.
    int
    getProbeUpdatePolicy()
    Return the probe trajectory updating policy.
    boolean
    getRfGapPhaseCalculation()
    Indicates whether to calculate the beam phase in multi gap Rf cavities, (a la Parmila) rather than use default values (a la Trace 3D)
    String
    getStartElementId()
    Get the modeling element string identifier where propagation is to start.
    String
    getStopElementId()
    Get the modeling element string identifier where propagation is to stop.
    String
    getType()
    Return the algorithm type.
    int
    getVersion()
    Returns the version number of this algorithm
    void
    initialize()
    Initializes the algorithm to begin a new propagation cycle.
    boolean
    isStopElementIncluded()
    Returns the flag that indicates whether or not the stop element is propagated through.
    void
    load(String strPrimKeyVal, EditContext ecTableData)
    Load the parameters of this IAlgorithm object from the table data in the given EditContext.
    void
    load(DataAdaptor daSource)
    Load the state and settings of this algorithm from a data source exposing the DataAdaptor interface.
    static IAlgorithm
    newFromEditContext(String strLocationId, AcceleratorSeq sequence)
    Deprecated.
    I want to discourage use of this method since it return the same "default" algorithm regardless the type of probe being used.
    static IAlgorithm
    newFromEditContext(AcceleratorSeq sequence)
    Deprecated.
    I want to discourage use of this method since it return the same "default" algorithm regardless the type of probe being used.
    static IAlgorithm
    newInstance(DataAdaptor daSource)
    Read the contents of the supplied DataAdaptor and return a new instance of the appropriate IAlgorithm object initialized with the data source behind the DataAdaptor interface.
    void
    propagate(IProbe probe, IElement elem)
    Propagates the probe through the element
    protected void
    registerProbeType(Class<? extends IProbe> clsProbeType)
    Register the class of a probe recognized by this algorithm.
    protected void
    retractProbe(IProbe probe, IElement elem, double dblLen)
    Override of xal.model.alg.Tracker#advanceProbe(xal.model.IProbe, xal.model.IElement, double)
    void
    save(DataAdaptor daptArchive)
    Save the state and settings of this algorithm to a data source exposing the DataAdaptor interface.
    void
    setDebugMode(boolean bolDebug)
    Set or clear the debugging mode flag.
    void
    setElemPosition(double dblPosElem)
    Set the current position within the element though which the probe is being propagated.
    void
    setIncludeStopElement(boolean bolInclStopElem)
    Sets the flag that determines whether or not the propagation stops at the entrance of the stop element (if set), or at the exit of the stop node.
    void
    setProbeUpdatePolicy(int enmPolicy)
    Set the frequency of probe trajectory updates.
    void
    setRfGapPhaseCalculation(boolean tf)
    Toggle the RF phase calculation on or off.
    void
    setStartElementId(String id)
    Sets the element from which to start propagation.
    void
    setStopElementId(String id)
    Sets the element at which to stop propagation.
    void
    unsetStartElementId()
    reset the Start Element Id to null
    void
    unsetStopElementId()
    reset the Stop Element Id to null
    protected boolean
    validElement(IElement elem)
    Check if the specified element is requires probe propagating.
    boolean
    validProbe(IProbe ifcProbe)
    Check if probe can be handled by this algorithm.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface xal.model.IAlgorithm

    copy

  • Field Details

    • UPDATE_CUSTOM

      public static final int UPDATE_CUSTOM
      never update - this is done custom somewhere else
      See Also:

    • UPDATE_ALWAYS

      public static final int UPDATE_ALWAYS
      save every state whenever probe is moved
      See Also:

    • UPDATE_EXIT

      public static final int UPDATE_EXIT
      save state at element exit only
      See Also:

    • UPDATE_ENTRANCE

      public static final int UPDATE_ENTRANCE
      save state at element entrance
      See Also:

    • UPDATE_ENTRANCEANDEXIT

      public static final int UPDATE_ENTRANCEANDEXIT
      save state at element exit and entrance
      See Also:

    • NODETAG_ALG

      public static final String NODETAG_ALG
      data node label for algorithm data
      See Also:

    • ATTRTAG_TYPE

      public static final String ATTRTAG_TYPE
      attribute label for type string identifier
      See Also:

    • ATTRTAG_VER

      public static final String ATTRTAG_VER
      attribute tag for the algorithm version number
      See Also:

    • NODETAG_TRACKER

      public static final String NODETAG_TRACKER
      data node tag for common data
      See Also:

    • ATTRTAG_UPDATE

      public static final String ATTRTAG_UPDATE
      attribute tag for trajectory state update policy
      See Also:

    • ATTRTAG_DEBUG

      public static final String ATTRTAG_DEBUG
      attribute tag for debugging flag
      See Also:

    • ATTRTAG_RFGAP_PHASE

      public static final String ATTRTAG_RFGAP_PHASE
      flag to update the beam phase in RF gaps ( a la parmila) rather than use default values
      See Also:

    • TBL_LBL_ALGORITHM

      public static final String TBL_LBL_ALGORITHM
      EditContext table name for Tracker Data
      See Also:

    • TBL_PRIM_KEY_NAME

      public static final String TBL_PRIM_KEY_NAME
      Table record primary key name
      See Also:

  • Constructor Details

    • Tracker

      protected Tracker(String strType, int intVersion, Class<? extends IProbe> clsProbeType)

      Creates a new, empty, instance of Tracker.

      Note that if the child algorithm may handle more than one probe type the additional types should be registered using the method registerProbeType() in the constructor.

      Parameters:
      strType - string type identifier of algorithm
      intVersion - version of algorithm
      clsProbeType - class object for probe handled by this algorithm.

    • Tracker

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

  • Method Details

    • doPropagation

      public abstract void doPropagation(IProbe probe, IElement elem) throws ModelException

      The implementation must propagate the probe through the element according to the dynamics of the specific algorithm. Derived classes must implement this method but the Tracker base provided convenient methods for this implementation.

      NOTE:
      The protected method advanceProbe(IProbe, IElement, double) is available for derived classes. It is a convenience method for performing many of the common tasks in the forward propagation of any probe. Thus, its use is not required.

      Parameters:
      probe - probe to propagate
      elem - element acting on probe
      Throws:
      ModelException - invalid probe type or error in advancing probe
      See Also:

    • newInstance

      public static IAlgorithm newInstance(DataAdaptor daSource) throws DataFormatException
      Read the contents of the supplied DataAdaptor and return a new instance of the appropriate IAlgorithm object initialized with the data source behind the DataAdaptor interface.
      Parameters:
      daSource - DataAdaptor to read a Probe from
      Returns:
      new IAlgorithm object initialized to the given data source
      Throws:
      DataFormatException - bad data format, error reading data

    • newFromEditContext

      @Deprecated public static IAlgorithm newFromEditContext(AcceleratorSeq sequence)
      Deprecated.
      I want to discourage use of this method since it return the same "default" algorithm regardless the type of probe being used. Please refer to AlgorithmFactory.

      Load the sequence's model parameters for the adaptive tracker from the global XAL edit context, which is retrievable through the given AcceleratorSeq argument.

      The actual record used for the initializing data is taken as the that with the primary key having the name of the given AcceleratorSeq name.

      NOTE

      · The returned algorithm type is that specified by the "type" attribute of the <Algorithm> table contained in the model.params file. The developer must ensure that the Probe and the Algorithm objects are of the correct type.

      Parameters:
      sequence - sequence from which to retrieve the algorithms' parameters.
      Returns:
      new IAlgorithm object initialized to the given table data
      Throws:
      DataFormatException - bad data format, error reading data
      Since:
      > Oct 17, 2012

    • newFromEditContext

      @Deprecated public static IAlgorithm newFromEditContext(String strLocationId, AcceleratorSeq sequence)
      Deprecated.
      I want to discourage use of this method since it return the same "default" algorithm regardless the type of probe being used. Please refer to AlgorithmFactory.

      Load the sequence's model parameters for the adaptive tracker from the global XAL edit context, which is retrievable through the given AcceleratorSeq argument.

      The record used to initialize the data is that with the primary key have the given value of the argument strLocationId.

      NOTE

      · The returned algorithm type is that specified by the "type" attribute of the <Algorithm> table contained in the model.params file. The developer must ensure that the Probe and the Algorithm objects are of the correct type.

      Parameters:
      strLocationId - The location ID of the entrance parameters to use
      sequence - The sequence for which to get the adaptive tracker parameters.
      Returns:
      new IAlgorithm object initialized to the given table data
      Throws:
      DataFormatException - bad data format, error reading data
      Since:
      > Oct 17, 2012

    • setProbeUpdatePolicy

      public void setProbeUpdatePolicy(int enmPolicy)
      Set the frequency of probe trajectory updates.
      Parameters:
      enmPolicy - probe update policy enumeration code

    • setDebugMode

      public void setDebugMode(boolean bolDebug)
      Set or clear the debugging mode flag.
      Parameters:
      bolDebug -

    • getProbeUpdatePolicy

      public int getProbeUpdatePolicy()
      Return the probe trajectory updating policy.
      Returns:
      enumeration code for the update policy

    • getDebugMode

      public boolean getDebugMode()
      Indicate whether or not algorithm is in debug mode.
      Returns:
      true if in debug mode

    • isStopElementIncluded

      public boolean isStopElementIncluded()
      Returns the flag that indicates whether or not the stop element is propagated through.
      Returns:
      true indicates propagation stops after the stop element, false indicates propagation stops before the stop element (entrance)
      Since:
      Oct 20, 2014

    • getProbeType

      public Class<? extends IProbe> getProbeType()

      The implementation must propagate the probe through the element according to the dynamics of the specific algorithm. Derived classes must implement this method but the Tracker base provided convenient methods for this implementation.

      NOTE:
      The protected method advanceProbe(IProbe, IElement, double) is available for derived classes. It is a convenience method for performing many of the common tasks in the forward propagation of any probe. Thus, its use is not required.

      Parameters:
      probe - probe to propagate
      elem - element acting on probe
      Throws:
      ModelException - invalid probe type or error in advancing probe
      Since:
      Oct 20, 2014

    • getRfGapPhaseCalculation

      public boolean getRfGapPhaseCalculation()
      Indicates whether to calculate the beam phase in multi gap Rf cavities, (a la Parmila) rather than use default values (a la Trace 3D)
      Specified by:
      getRfGapPhaseCalculation in interface IAlgorithm
      Returns:
      true if phase calculations are made, false otherwise

    • getType

      public String getType()
      Return the algorithm type.
      Specified by:
      getType in interface IAlgorithm
      Returns:
      name of the integration algorithm

    • getVersion

      public int getVersion()
      Returns the version number of this algorithm
      Specified by:
      getVersion in interface IAlgorithm
      Returns:
      version number of the integration algorithm

    • validProbe

      public boolean validProbe(IProbe ifcProbe)
      Check if probe can be handled by this algorithm.
      Specified by:
      validProbe in interface IAlgorithm
      Parameters:
      ifcProbe - probe interface to be validated
      Returns:
      true if algorithm supports the probe type

    • getStartElementId

      public String getStartElementId()
      Get the modeling element string identifier where propagation is to start.
      Specified by:
      getStartElementId in interface IAlgorithm
      Returns:
      string id if element is defined, null otherwise

    • getStopElementId

      public String getStopElementId()
      Get the modeling element string identifier where propagation is to stop.
      Specified by:
      getStopElementId in interface IAlgorithm
      Returns:
      string id if element is defined, null otherwise

    • setRfGapPhaseCalculation

      public void setRfGapPhaseCalculation(boolean tf)
      Toggle the RF phase calculation on or off.
      Specified by:
      setRfGapPhaseCalculation in interface IAlgorithm
      Parameters:
      tf - flag for turning on/off the phase calculations

    • setStartElementId

      public void setStartElementId(String id)
      Sets the element from which to start propagation.
      Specified by:
      setStartElementId in interface IAlgorithm
      Parameters:
      id - String id of the element from which to start propagation

    • setStopElementId

      public void setStopElementId(String id)
      Sets the element at which to stop propagation.
      Specified by:
      setStopElementId in interface IAlgorithm
      Parameters:
      id - String id of the element at which to stop propagation

    • setIncludeStopElement

      public void setIncludeStopElement(boolean bolInclStopElem)
      Sets the flag that determines whether or not the propagation stops at the entrance of the stop element (if set), or at the exit of the stop node. The later case is the default.
      Specified by:
      setIncludeStopElement in interface IAlgorithm
      Parameters:
      bolInclStopElem - propagation stops after stop element if true, before the stop element if false
      Since:
      Oct 20, 2014

    • unsetStartElementId

      public void unsetStartElementId()
      reset the Start Element Id to null
      Specified by:
      unsetStartElementId in interface IAlgorithm

    • unsetStopElementId

      public void unsetStopElementId()
      reset the Stop Element Id to null
      Specified by:
      unsetStopElementId in interface IAlgorithm

    • initialize

      public void initialize()
      Initializes the algorithm to begin a new propagation cycle.
      Specified by:
      initialize in interface IAlgorithm
      See Also:

    • propagate

      public void propagate(IProbe probe, IElement elem) throws ModelException

      Propagates the probe through the element

      NOTE:   CKA
      · We might get a significant performance upgrade by eliminating the internal call to validProbe(IProbe).
      · The method validElement(IElement)} needs to be called here in the current implementation. It is called for every element - Is there a better (faster) way?

      Specified by:
      propagate in interface IAlgorithm
      Parameters:
      probe - probe to propagate
      elem - element acting on probe
      Throws:
      ModelException - invalid probe type or error in advancing probe

    • 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
      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 daSource) throws DataFormatException
      Load the state and settings of this algorithm from a data source exposing the DataAdaptor interface. Subclasses should override this method to recover the data particular to there own operation.
      Specified by:
      load in interface IArchive
      Parameters:
      daSource - data source containing algorithm configuration
      Throws:
      DataFormatException - bad format in algorithm data
      See Also:

    • save

      public void save(DataAdaptor daptArchive)
      Save the state and settings of this algorithm to a data source exposing the DataAdaptor interface. Subclasses should override this method to store the data particular to there own operation.
      Specified by:
      save in interface IArchive
      Parameters:
      daptArchive - data source to receive algorithm configuration
      See Also:

    • advanceProbe

      protected void advanceProbe(IProbe probe, IElement elem, double dblLen) throws ModelException

      Convenience method for common propagation dynamics for all probes. This method performs propagation tasks that are common to all probes.

      Advances the position, time, and the kinetic energy of the probe through a subsection of the specified element of the specified length.

      Parameters:
      probe - target probe whose position and energy will be modified.
      elem - element acting on probe
      dblLen - length of element subsection to advance through
      Throws:
      ModelException - unable to advance probe through element

    • retractProbe

      protected void retractProbe(IProbe probe, IElement elem, double dblLen) throws ModelException

      Override of xal.model.alg.Tracker#advanceProbe(xal.model.IProbe, xal.model.IElement, double)

      This method is the converse of advanceProbe(IProbe, IElement, double). Rather than forward propagating the probe through an IElement object, the method back-propagates the probe object. These effects include the loss of kinetic energy, the decrement of lattice position, etc.

      NOTES: CKA
      · In order to use this method the derived class must override the propagate method, since it default implementation forward propagates the probe.

      Parameters:
      probe - beam probe to propagate backwards
      elem - element through which beam is backwards propagated
      dblLen - distance to backward propagate the beam
      Throws:
      ModelException - error occured while trying to update the probe values (unlikely)
      Since:
      Feb 3, 2009
      See Also:

    • validElement

      protected boolean validElement(IElement elem)

      Check if the specified element is requires probe propagating. That is, is the element within the specified start and stop boundaries defined with this algorithm object.

      NOTE: CKA
      · Maybe there is a better way of using start and stop elements.

      Parameters:
      elem - element interface to validate propagation
      Returns:
      true if we propagate, false if not

    • registerProbeType

      protected void registerProbeType(Class<? extends IProbe> clsProbeType)
      Register the class of a probe recognized by this algorithm. This method should be called in the constructor of all derived classes for each additional probe that the algorithm may propagate.
      Parameters:
      clsProbeType - class object of probe which this algorithm can propagate

    • getElemPosition

      protected double getElemPosition()
      Return the current position within the element through which the probe is being propagated
      Returns:
      the current element position in meters

    • setElemPosition

      public void setElemPosition(double dblPosElem)
      Set the current position within the element though which the probe is being propagated.
      Parameters:
      dblPosElem - current element position in meters