xal.model.probe.traj

Class Trajectory<S extends ProbeState<S>>

java.lang.Object

xal.model.probe.traj.Trajectory<S>

All Implemented Interfaces:

java.lang.Iterable<S>, IArchive

public class Trajectory<S extends ProbeState<S>>
extends java.lang.Object
implements IArchive, java.lang.Iterable<S>

Manages the history for a probe. Saves ProbeState objects, each of which reflects the state of the Probe at a particular point in time.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	TRAJ_LABEL XML element tag for trajectory

Constructor Summary

Constructors

Constructor and Description
Trajectory(java.lang.Class<S> clsStates) Creates a new Trajectory given the Class<S> object of the underlying ProbeState type, S.

Method Summary

Modifier and Type	Method and Description
protected void	addPropertiesTo(DataAdaptor container) Override this method in subclasses to add subclass-specific properties to the output.
S	finalState() Returns the probe's final state or null if there is none.
java.lang.String	getDescription() Return the user comment associated with this trajectory.
java.lang.Class<S>	getStateClass() Gets the Class<S> object of the generic type S.
java.util.List<S>	getStatesViaIndexer() Returns a list of all the states in this trajectory managed by the state numeric (position) indexer.
java.util.List<S>	getStatesViaStateMap() Get the list of all states in this trajectory managed by the state map.
java.util.Date	getTimestamp() Return the time stamp of the trajectory object
int[]	indicesForElement(java.lang.String element) Returns an array of the state indices corresponding to the specified element.
S	initialState() Returns the probe's initial state or null if there is none.
java.util.Iterator<S>	iterator() Returns an iterator over all the probe states in the trajectory.
void	load(DataAdaptor container) Load the current Trajectory object with the state history information in the DataAdaptor object.
int	numStates() Return the number of states in the trajectory.
S	popLastState() Remove the last state from the trajectory and return it.
static Trajectory<? extends ProbeState<?>>	readFrom(DataAdaptor container) Read the contents of the supplied DataAdaptor and return an instance of the appropriate Trajectory species.
protected void	readPropertiesFrom(DataAdaptor container) Allow subclasses to read subclass-specific properties from the DataAdaptor.
void	save(DataAdaptor container) Adds a representation of this Trajectory and its state history to the supplied DataAdaptor.
void	saveState(S state) Save the ProbeState object directly to the trajectory at the tail.
void	setDescription(java.lang.String strDescr) Set the user comment string
void	setTimestamp(long lngTimeStamp) Set the time stamp of the trajectory.
S	stateAtPosition(double pos) Returns the probe state at the specified position.
S	stateForElement(java.lang.String strSmfNodeId) The old comment read "Get the probe state for the specified element ID." which is now inaccurate.
java.util.Iterator<S>	stateIterator() Return an Iterator over the iterator's states.
S	stateNearestPosition(double position) Get the state that is closest to the specified position
ProbeState[]	statesForElement_OLD(java.lang.String strElemId) Deprecated.
java.util.List<S>	statesForElement(java.lang.String strSmfNodeId) Revised version of state lookup method for an element ID class, which now corresponds to a hardware node ID lookup.
java.util.List<S>	statesInPositionRange(double low, double high) Returns the states that fall within the specified position range, inclusive.
S	stateWithIndex(int i) Returns the state corresponding to the specified index, or null if there is none.
Trajectory<S>	subTrajectory(java.lang.String strSmfNodeId1, java.lang.String strSmfNodeId2) Creates and returns a "sub-trajectory" object built from the contiguous state objects of this trajectory between the start node strSmfNodeId1 and the stop node strSmfNodeId2.
Trajectory<S>	subTrajectoryInclusive(java.lang.String strSmfNodeId1, java.lang.String strSmfNodeId2) Creates and returns a "sub-trajectory" object built from the contiguous state objects of this trajectory between the start node strSmfNodeId1 and the stop node strSmfNodeId2.
java.lang.String	toString() Store a textual representation of the trajectory to a string
void	update(Probe<S> probe) Captures the specified probe's current state to a ProbeState object then saves it to the trajectory.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

TRAJ_LABEL

public static final java.lang.String TRAJ_LABEL

XML element tag for trajectory

See Also:

Constant Field Values

Constructor Detail

Trajectory

public Trajectory(java.lang.Class<S> clsStates)

Creates a new Trajectory given the Class<S> object of the underlying ProbeState type, S.

Parameters:

clsStates - - the Class<S> object of the underlying ProbeState type

Since:

Jul 1, 2014

Method Detail

readFrom

public static Trajectory<? extends ProbeState<?>> readFrom(DataAdaptor container)
                                                    throws ParsingException

Read the contents of the supplied DataAdaptor and return an instance of the appropriate Trajectory species.

Parameters:

container - DataAdaptor to read a Trajectory from

Returns:

a Trajectory for the contents of the DataAdaptor

Throws:

ParsingException - error encountered reading the DataAdaptor

addPropertiesTo

protected void addPropertiesTo(DataAdaptor container)

Override this method in subclasses to add subclass-specific properties to the output. Subclass implementations should call super.addPropertiesTo so that superclass implementations are executed.

Parameters:

container - the DataAdaptor to add properties to

readPropertiesFrom

protected void readPropertiesFrom(DataAdaptor container)
                           throws ParsingException

Allow subclasses to read subclass-specific properties from the DataAdaptor. Implementations should call super.readPropertiesFrom to ensure that superclass implementations are executed.

Parameters:

container - DataAdaptor to read properties from

Throws:

ParsingException

setDescription

public void setDescription(java.lang.String strDescr)

Set the user comment string

Parameters:

strDescr - user comment string

setTimestamp

public void setTimestamp(long lngTimeStamp)

Set the time stamp of the trajectory.

Parameters:

lngTimeStamp - number of milliseconds since January 1, 1970 GMT

getStateClass

public java.lang.Class<S> getStateClass()

Gets the Class<S> object of the generic type S.

Returns:

a Class<S> object for the class S

update

public void update(Probe<S> probe)

Captures the specified probe's current state to a ProbeState object then saves it to the trajectory. State goes at the tail of the trajectory list.

Parameters:

probe - target probe object

saveState

public void saveState(S state)

Save the ProbeState object directly to the trajectory at the tail.

Parameters:

state - new addition to trajectory

popLastState

public S popLastState()

Remove the last state from the trajectory and return it.

Returns:

the most recent ProbeState in the history

getDescription

public java.lang.String getDescription()

Return the user comment associated with this trajectory.

Returns:

user comment (meta-data)

getTimestamp

public java.util.Date getTimestamp()

Return the time stamp of the trajectory object

Returns:

trajectory time stamp

stateIterator

public java.util.Iterator<S> stateIterator()

Return an Iterator over the iterator's states.

numStates

public int numStates()

Return the number of states in the trajectory.

Returns:

the number of states

initialState

public S initialState()

Returns the probe's initial state or null if there is none.

Returns:

the probe's initial state or null

finalState

public S finalState()

Returns the probe's final state or null if there is none.

Returns:

the probe's final state or null

getStatesViaStateMap

public java.util.List<S> getStatesViaStateMap()

Get the list of all states in this trajectory managed by the state map.

Returns:

a new list of this trajectory's states

getStatesViaIndexer

public java.util.List<S> getStatesViaIndexer()

Returns a list of all the states in this trajectory managed by the state numeric (position) indexer.

Returns:

Since:

Aug 26, 2014

subTrajectory

public Trajectory<S> subTrajectory(java.lang.String strSmfNodeId1,
                                   java.lang.String strSmfNodeId2)

Creates and returns a "sub-trajectory" object built from the contiguous state objects of this trajectory between the start node strSmfNodeId1 and the stop node strSmfNodeId2. The returned trajectory contains references to the same states contained in this trajectory, they are not duplicates. So any modifications made on the returned object will be reflected here. Also, it is important to note that the returned sub-trajectory excludes all states belonging to the stop hardware node strSmfNodeId2. That is, the returned value contains states from, and including, node 1 up to, but not including, state 2. If you wish to include the states of both hardware nodes see subTrajectoryInclusive(String, String).

Parameters:

strSmfNodeId1 - hardware node ID defining the first state object in sub-trajectory

strSmfNodeId2 - hardware node ID defining the last state object in sub-trajectory

Returns:

sub-trajectory of this trajectory defined by the above hardware nodes

Since:

Nov 14, 2014

See Also:

subTrajectoryInclusive(String, String)

subTrajectoryInclusive

public Trajectory<S> subTrajectoryInclusive(java.lang.String strSmfNodeId1,
                                            java.lang.String strSmfNodeId2)

Creates and returns a "sub-trajectory" object built from the contiguous state objects of this trajectory between the start node strSmfNodeId1 and the stop node strSmfNodeId2. The returned trajectory contains references to the same states contained in this trajectory, they are not duplicates. So any modifications made on the returned object will be reflected here. Also, it is important to note that the returned sub-trajectory includes all states belonging to the stop hardware node strSmfNodeId2. That is, the returned value contains states from, and including, node 1 up to and including state 2. If you wish to exclude the states of both hardware nodes see subTrajectory(String, String).

Parameters:

strSmfNodeId1 - hardware node ID defining the first state object in sub-trajectory

strSmfNodeId2 - hardware node ID defining the last state object in sub-trajectory

Returns:

sub-trajectory of this trajectory defined by the above hardware nodes

Since:

Nov 14, 2014

See Also:

subTrajectory(String, String)

stateAtPosition

public S stateAtPosition(double pos)

Returns the probe state at the specified position. Returns null if there is no state for the specified position.

stateNearestPosition

public S stateNearestPosition(double position)

Get the state that is closest to the specified position

Parameters:

position - the position for which to find a state

Returns:

the state nearest the specified position

statesInPositionRange

public java.util.List<S> statesInPositionRange(double low,
                                               double high)

Returns the states that fall within the specified position range, inclusive.

Parameters:

low - lower bound on position range

high - upper bound on position range

Returns:

an array of ProbeState objects whose position falls within the specified range

stateForElement

public S stateForElement(java.lang.String strSmfNodeId)

The old comment read

"Get the probe state for the specified element ID."

which is now inaccurate. The returned state is actual the first state for the given identifier which is treated as that for an SMF hardware node. The "first state" is the state with the smallest upstream position, that which the probe encounters first in an forward propagation.

Parameters:

strSmfNodeId - hardware node ID of the desired state

Returns:

The first probe state for the given hardware node.

statesForElement_OLD

@Deprecated
public ProbeState[] statesForElement_OLD(java.lang.String strElemId)

Deprecated.

Returns the states associated with the specified element.

Parameters:

strElemId - the name of the element to search for

Returns:

an array of ProbeState objects for that element

statesForElement

public java.util.List<S> statesForElement(java.lang.String strSmfNodeId)

Revised version of state lookup method for an element ID class, which now corresponds to a hardware node ID lookup. Since the lattice generator creates element IDs by prefixing and suffixing hardware node IDs, the actual hardware node ID must be used to get all the states corresponding to a given hardware node.

The revised part comes from the fact that the states are now stored and retrieved by hashing or a tree lookup, rather that by a linear search. Specifically, a map of probe states for every hardware node ID is maintained, along with an ordered list of states arranged according to their position along the beamline (for iterations, e.g., see ).

Parameters:

strSmfNodeId - identifier for the SMF hardware node

Returns:

all the probe states associated with the element ID class containing the given element ID

Since:

Jun 5, 2013

indicesForElement

public int[] indicesForElement(java.lang.String element)

Returns an array of the state indices corresponding to the specified element.

Parameters:

element - name of element to search for

Returns:

an array of integer indices corresponding to that element

stateWithIndex

public S stateWithIndex(int i)

Returns the state corresponding to the specified index, or null if there is none.

Parameters:

i - index of state to return

Returns:

state corresponding to specified index

iterator

public java.util.Iterator<S> iterator()

Returns an iterator over all the probe states in the trajectory. This is the single method in the Iterable interface which facilitates the "for each" statement. States are traversed in their order along the beamline.

Specified by:

iterator in interface java.lang.Iterable<S extends ProbeState<S>>

Returns:

iterator for use in a (T X : Container<T>) statement

Since:

Oct 28, 2013

toString

public java.lang.String toString()

Store a textual representation of the trajectory to a string

Overrides:

toString in class java.lang.Object

Returns:

trajectory contents in string form

save

public void save(DataAdaptor container)

Adds a representation of this Trajectory and its state history to the supplied DataAdaptor.

Specified by:

save in interface IArchive

Parameters:

container - DataAdaptor in which to add Trajectory data

load

public void load(DataAdaptor container)
          throws DataFormatException

Load the current Trajectory object with the state history information in the DataAdaptor object.

Specified by:

load in interface IArchive

Parameters:

container - DataAdaptor from which state history is extracted

Throws:

DataFormatException - malformated data in DataAdaptor