public abstract class Tracker extends java.lang.Object implements IAlgorithm, IArchive
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 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.
doPropagation(IProbe, IElement)
,
IAlgorithm
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
ATTRTAG_DEBUG
attribute tag for debugging flag
|
static java.lang.String |
ATTRTAG_RFGAP_PHASE
flag to update the beam phase in RF gaps ( a la parmila) rather than use default values
|
static java.lang.String |
ATTRTAG_TYPE
attribute label for type string identifier
|
static java.lang.String |
ATTRTAG_UPDATE
attribute tag for trajectory state update policy
|
static java.lang.String |
ATTRTAG_VER
attribute tag for the algorithm version number
|
static java.lang.String |
NODETAG_ALG
data node label for algorithm data
|
static java.lang.String |
NODETAG_TRACKER
data node tag for common data
|
static java.lang.String |
TBL_PRIM_KEY_NAME
Table record primary key name
|
static int |
UPDATE_ALWAYS
save every state whenever probe is moved
|
static int |
UPDATE_CUSTOM
never update - this is done custom somewhere else
|
static int |
UPDATE_ENTRANCE
save state at element entrance
|
static int |
UPDATE_ENTRANCEANDEXIT
save state at element exit and entrance
|
static int |
UPDATE_EXIT
save state at element exit only
|
Modifier | Constructor and Description |
---|---|
protected |
Tracker(java.lang.String strType,
int intVersion,
java.lang.Class<? extends IProbe> clsProbeType)
Creates a new, empty, instance of Tracker.
|
protected |
Tracker(Tracker sourceTracker)
Copy constructor for Tracker
|
Modifier and Type | Method and 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
|
java.lang.Class<? extends IProbe> |
getProbeType()
TODO CKA - Remove, never used.
|
int |
getProbeUpdatePolicy()
Return the probe trajectory updating policy.
|
java.lang.String |
getStartElementId()
Get the modeling element string identifier where propagation is to start.
|
java.lang.String |
getStopElementId()
Get the modeling element string identifier where propagation is to stop.
|
java.lang.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(DataAdaptor daSource)
Load the state and settings of this algorithm from a data source
exposing the
DataAdaptor interface. |
void |
load(java.lang.String strPrimKeyVal,
EditContext ecTableData)
Load the parameters of this
IAlgorithm object from the
table data in the given EditContext . |
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
. |
static IAlgorithm |
newFromEditContext(java.lang.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
. |
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(java.lang.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 gov.sns.xal.model.alg.Tracker#advanceProbe(gov.sns.xal.model.IProbe, gov.sns.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(java.lang.String id)
Sets the element from which to start propagation.
|
void |
setStopElementId(java.lang.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
|
boolean |
useRfGapPhaseCalculation()
Indicates whether to calculate the beam phase in multi gap Rf cavities,
(a la Parmila) rather than use default values (a la Trace 3D)
|
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.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
copy
public static final int UPDATE_CUSTOM
public static final int UPDATE_ALWAYS
public static final int UPDATE_EXIT
public static final int UPDATE_ENTRANCE
public static final int UPDATE_ENTRANCEANDEXIT
public static final java.lang.String NODETAG_ALG
public static final java.lang.String ATTRTAG_TYPE
public static final java.lang.String ATTRTAG_VER
public static final java.lang.String NODETAG_TRACKER
public static final java.lang.String ATTRTAG_UPDATE
public static final java.lang.String ATTRTAG_DEBUG
public static final java.lang.String ATTRTAG_RFGAP_PHASE
public static final java.lang.String TBL_PRIM_KEY_NAME
protected Tracker(java.lang.String strType, int intVersion, java.lang.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.
strType
- string type identifier of algorithmintVersion
- version of algorithmclsProbeType
- class object for probe handled by this algorithm.protected Tracker(Tracker sourceTracker)
sourceTracker
- Tracker that is being copiedpublic 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.
probe
- probe to propagateelem
- element acting on probeModelException
- invalid probe type or error in advancing probevalidProbe(IProbe)
public static IAlgorithm newInstance(DataAdaptor daSource) throws DataFormatException
DataAdaptor
and return
a new instance of the appropriate IAlgorithm
object
initialized with the data source behind the DataAdaptor
interface.daSource
- DataAdaptor
to read a Probe fromDataFormatException
- bad data format, error reading data@Deprecated public static IAlgorithm newFromEditContext(AcceleratorSeq sequence)
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.
<Algorithm>
table contained in the
model.params
file. The developer must ensure that the Probe
and the Algorithm objects are of the correct type.
sequence
- sequence from which to retrieve the algorithms' parameters.DataFormatException
- bad data format, error reading data@Deprecated public static IAlgorithm newFromEditContext(java.lang.String strLocationId, AcceleratorSeq sequence)
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
.
<Algorithm>
table contained in the
model.params
file. The developer must ensure that the Probe
and the Algorithm objects are of the correct type.
strLocationId
- The location ID of the entrance parameters to usesequence
- The sequence for which to get the adaptive tracker parameters.DataFormatException
- bad data format, error reading datapublic void setProbeUpdatePolicy(int enmPolicy)
enmPolicy
- probe update policy enumeration codepublic void setDebugMode(boolean bolDebug)
bolDebug
- public int getProbeUpdatePolicy()
public boolean getDebugMode()
true
if in debug modepublic boolean isStopElementIncluded()
true
indicates propagation stops after the stop element,
false
indicates propagation stops before the stop element (entrance)public java.lang.Class<? extends IProbe> getProbeType()
public boolean useRfGapPhaseCalculation()
useRfGapPhaseCalculation
in interface IAlgorithm
true
if phase calculations are made, false
otherwisepublic java.lang.String getType()
getType
in interface IAlgorithm
public int getVersion()
getVersion
in interface IAlgorithm
public boolean validProbe(IProbe ifcProbe)
validProbe
in interface IAlgorithm
ifcProbe
- probe interface to be validatedpublic java.lang.String getStartElementId()
getStartElementId
in interface IAlgorithm
public java.lang.String getStopElementId()
getStopElementId
in interface IAlgorithm
public void setRfGapPhaseCalculation(boolean tf)
setRfGapPhaseCalculation
in interface IAlgorithm
tf
- flag for turning on/off the phase calculationspublic void setStartElementId(java.lang.String id)
setStartElementId
in interface IAlgorithm
id
- String
id of the element from which to start propagationpublic void setStopElementId(java.lang.String id)
setStopElementId
in interface IAlgorithm
id
- String
id of the element at which to stop propagationpublic void setIncludeStopElement(boolean bolInclStopElem)
setIncludeStopElement
in interface IAlgorithm
bolInclStopElem
- propagation stops after stop element if true
,
before the stop element if false
public void unsetStartElementId()
unsetStartElementId
in interface IAlgorithm
public void unsetStopElementId()
unsetStopElementId
in interface IAlgorithm
public void initialize()
initialize
in interface IAlgorithm
IAlgorithm.initialize()
public void propagate(IProbe probe, IElement elem) throws ModelException
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?
propagate
in interface IAlgorithm
probe
- probe to propagateelem
- element acting on probeModelException
- invalid probe type or error in advancing probepublic void load(java.lang.String strPrimKeyVal, EditContext ecTableData) throws DataFormatException
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.load
in interface IContextAware
strPrimKeyVal
- primary key value specifying the name of the data recordecTableData
- EditContext containing table dataDataFormatException
- bad data format - error in readingIContextAware.load(String, EditContext)
public void load(DataAdaptor daSource) throws DataFormatException
DataAdaptor
interface. Subclasses should
override this method to recover the data particular to there own
operation.load
in interface IArchive
daSource
- data source containing algorithm configurationDataFormatException
- bad format in algorithm dataIArchive.load(xal.tools.data.DataAdaptor)
public void save(DataAdaptor daptArchive)
DataAdaptor
interface. Subclasses should
override this method to store the data particular to there own
operation.save
in interface IArchive
daptArchive
- data source to receive algorithm configurationIArchive.save(xal.tools.data.DataAdaptor)
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.
probe
- target probe whose position and energy will be modified.elem
- element acting on probedblLen
- length of element subsection to advance throughModelException
- unable to advance probe through elementprotected void retractProbe(IProbe probe, IElement elem, double dblLen) throws ModelException
Override of gov.sns.xal.model.alg.Tracker#advanceProbe(gov.sns.xal.model.IProbe, gov.sns.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.
probe
- beam probe to propagate backwardselem
- element through which beam is backwards propagateddblLen
- distance to backward propagate the beamModelException
- error occured while trying to update the probe values (unlikely)advanceProbe(IProbe, IElement, double)
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.
elem
- element interface to validate propagationprotected void registerProbeType(java.lang.Class<? extends IProbe> clsProbeType)
clsProbeType
- class object of probe which this algorithm can propagateprotected double getElemPosition()
public void setElemPosition(double dblPosElem)
dblPosElem
- current element position in meters