Package xal.model.probe.traj

Class Trajectory<S extends ProbeState<S>>

java.lang.Object
xal.model.probe.traj.Trajectory<S>
Record Components:
S - the ProbeState-derived type indicating the class of objects to be stored in this container
All Implemented Interfaces:
Iterable<S>, IArchive
public class Trajectory<S extends ProbeState<S>> extends Object implements IArchive, 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. The entire set of states then forms the trajectory of the associated probe through the machine model under simulation.
Version:
$id:
Author:
Craig McChesney, Christopher K. Allen

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    TRAJ_LABEL
    data node tag for trajectory

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addState(S state)
    Save the ProbeState object to this trajectory.
    S
    finalState()
    Returns the probe's final state or null if there is none.
    String
    getDescription()
    Return the user comment associated with this trajectory.
    Class<S>
    getStateClass()
    Gets the class type of the probe states forming the trajectory.
    List<S>
    getStatesViaIndexer()
    Returns a list of all the states in this trajectory managed by the state numeric (position) indexer.
    List<S>
    getStatesViaStateMap()
    Get the list of all states in this trajectory managed by the state map.
    Date
    getTimestamp()
    Return the time stamp of the trajectory object
    int[]
    indicesForElement(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.
    Iterator<S>
    iterator()
    Returns an iterator over all the probe states in the trajectory.
    void
    load(DataAdaptor daptSrc)
    Load the current Trajectory object with the state history information in the DataAdaptor object.
    static <S extends ProbeState<S>>
    Trajectory<S>
    loadFrom(DataAdaptor daptSrc)
    Return a new instance of the appropriately typed Trajectory object initialized with the data contained in the given data source.
    int
    numStates()
    Return the number of states in the trajectory.
    S
    peakLastByPosition()
    Returns, but does not remove, the probe state at the last axial position.
    S
    peakLastByType(String strElemTypeId)
    Return the last state in the trajectory with the given type.
    S
    popLastState()
    Remove the last state from the trajectory and return it.
    void
    save(DataAdaptor container)
    Adds a representation of this Trajectory and its state history to the supplied DataAdaptor.
    void
    saveState(S state)
    Deprecated.
    this method is replaced with addState(ProbeState) which is more appropriately named
    void
    setDescription(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(String strSmfNodeId)
    The old comment read

        "Get the probe state for the specified element ID."
    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
    List<S>
    statesForElement(String strSmfNodeId)
    Revised version of state lookup method for an element ID class, which now corresponds to a hardware node ID lookup.
    List<S>
    statesForElementType(String strTypeId)
    Returns a list of all the states created by modeling elements of the given type.
    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(String strSmfNodeId1, 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(String strSmfNodeId1, 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.
    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 Details

  • Constructor Details

    • Trajectory

      public Trajectory(Class<S> clsStates)
      Creates a new Trajectory given the Class<S> object of the underlying ProbeState type, S.
      Parameters:
      S - the template type of ProbeState object that the new trajectory will manage
      clsStates - the class type the ProbeState derived managed objects
      Since:
      Jul 1, 2014

  • Method Details

    • loadFrom

      public static <S extends ProbeState<S>> Trajectory<S> loadFrom(DataAdaptor daptSrc) throws DataFormatException
      Return a new instance of the appropriately typed Trajectory object initialized with the data contained in the given data source.
      Parameters:
      daptSrc - data source containing trajectory information
      Returns:
      new Trajectory instance initialized from the data source
      Throws:
      DataFormatException - malformed data stare

    • setDescription

      public void setDescription(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 Class<S> getStateClass()
      Gets the class type of the probe states forming the trajectory.
      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

    • addState

      public void addState(S state)
      Save the ProbeState object to this trajectory. It is then indexed by its position, by its hardware node source, and by its modeling element type identifier.
      Parameters:
      state - new state addition to trajectory
      Since:
      Dec 16, 2014 by Christopher K. Allen

    • saveState

      @Deprecated public void saveState(S state)
      Deprecated.
      this method is replaced with addState(ProbeState) which is more appropriately named

      This is the legacy method for adding states to the trajectory. See the method addState(ProbeState), which should be used instead as it follows the standard Java naming convention.

      Parameters:
      state - new state 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

    • peakLastByPosition

      public S peakLastByPosition()
      Returns, but does not remove, the probe state at the last axial position.
      Returns:
      the probe state in this trajectory with the largest axial position
      Since:
      Dec 16, 2014 by Christopher K. Allen

    • peakLastByType

      public S peakLastByType(String strElemTypeId)
      Return the last state in the trajectory with the given type.
      Parameters:
      strElemTypeId - class name of the desired probe state type
      Returns:
      final probe state in the trajectory of the given type
      Since:
      Dec 29, 2015, Christopher K. Allen

    • getDescription

      public String getDescription()
      Return the user comment associated with this trajectory.
      Returns:
      user comment (meta-data)

    • getTimestamp

      public Date getTimestamp()
      Return the time stamp of the trajectory object
      Returns:
      trajectory time stamp

    • numStates

      public int numStates()
      Return the number of states in the trajectory.
      Returns:
      the number of states

    • stateIterator

      public Iterator<S> stateIterator()
      Return an Iterator over the iterator's 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 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 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(String strSmfNodeId1, 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

      public Trajectory<S> subTrajectoryInclusive(String strSmfNodeId1, 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:

    • 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 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(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

      public List<S> statesForElement(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 iterator()).

      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

    • statesForElementType

      public List<S> statesForElementType(String strTypeId)

      Returns a list of all the states created by modeling elements of the given type. Specifically, the method argument is the element type identifier string which is found in the source code of each modeling element. The ordering in the list is determined by the axial position of the state.

      Parameters:
      strTypeId - modeling element type identifier string.
      Returns:
      all states in this trajectory created by elements of the given type
      Since:
      Dec 16, 2014 by Christopher K. Allen

    • indicesForElement

      public int[] indicesForElement(String element)
      Returns an array of the state indices corresponding to the specified element.

      NOTES - CKA

      · I have changed this method so the given argument is assumed to be the hardware node identifier, not the modeling element ID. I believe that is the original intent.

      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 Iterator<S> iterator()
      Returns an iterator over all the probe states in the trajectory. This is the single method in the Iterable<T> interface which facilitates the "for each" statement. States are traversed in their order along the beamline.
      Specified by:
      iterator in interface Iterable<S extends ProbeState<S>>
      Returns:
      iterator for use in a (T X : Container<T>) statement
      Since:
      Oct 28, 2013

    • 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 daptSrc) throws DataFormatException
      Load the current Trajectory object with the state history information in the DataAdaptor object.
      Specified by:
      load in interface IArchive
      Parameters:
      daptSrc - DataAdaptor from which state history is extracted
      Throws:
      DataFormatException - mal-formated data in DataAdaptor

    • toString

      public String toString()
      Store a textual representation of the trajectory to a string
      Overrides:
      toString in class Object
      Returns:
      trajectory contents in string form