Package xal.model.probe

Class Probe<S extends ProbeState<S>>

java.lang.Object
xal.model.probe.Probe<S>
All Implemented Interfaces:
IProbe, IArchive
Direct Known Subclasses:
BunchProbe, DiagnosticProbe, ParticleProbe, TransferMapProbe
public abstract class Probe<S extends ProbeState<S>> extends Object implements IProbe, IArchive

Provides a base class implementation of the IProbe interface that is useful for most standard probe types. This class provides most of the functionality necessary for the implementation of the IProbe interface, except a definition and implementation of a probe "state". Thus, it is up to base classes to provide and implement the particular aspect of a beam the probe represents.

Author:
Christopher K. Allen

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final String
    COMMENT_LABEL
    element tag for comment data
    static final String
    PROBE_LABEL
    element tag for probe data
    protected S
    stateCurrent
    current state of the probe - defines the probe
    protected static final String
    TEXT_LABEL
    attribute tag for comment text
    protected static final String
    TIME_LABEL
    attribute tag for the time stamp
    protected Trajectory<S>
    trajHist
    Current probe trajHist
    protected static final String
    TYPE_LABEL
    attribute tag for probe type name

    Fields inherited from interface xal.model.IProbe

    LIGHT_SPEED, PERMITTIVITY, UNIT_CHARGE

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Probe()
    Creates a new instance of Probe.
    protected
    Probe(IAlgorithm ifcAlg)
    Creates a new instance of Probe.
    protected
    Probe(Probe<S> probe)
    Copy constructor for Probe.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    applyState(S state)
    Apply the contents of ProbeState to update my current state.
    S
    cloneCurrentProbeState()
    This method returns a clone of the current state of this probe.
    abstract Probe<S>
    copy()
    Creates a deep copy of the probe
    abstract S
    createEmptyProbeState()
    Creates a new, blank ProbeState of the appropriate species.
    abstract S
    createProbeState()
    Captures the probe's state in a ProbeState of the appropriate species.
    abstract Trajectory<S>
    createTrajectory()
    Require concrete implementations to override this method to create a Trajectory object of the appropriate species.
    protected void
    deepCopy(Probe<S> probe)
    This is a convenience function for derived classes when implementing their deepCopy() method.
    IAlgorithm
    getAlgorithm()
    Return the algorithm defining the probes dynamics.
    IArchive
    getArchive()
    Return the archiving interface for this object.
    double
    getBeta()
    Returns the probe velocity normalized to the speed of light.
    String
    getComment()
    Returns the comment string associated with the probe
    String
    getCurrentElement()
    Returns the id of the current lattice element that the probe is visiting.
    String
    getCurrentElementTypeId()
    Get the type identifier string of the modeling element where this probe currently exists.
    String
    getCurrentHardwareId()
    Returns the identifier of the hardware modeled by the element associated with this state.
    S
    getCurrentState()
    Returns the current state object maintained by this probe.
    double
    getGamma()
    Returns the relativistic parameter corresponding to the probe velocity.
    S
    getInitialState()
    Returns the initial state of this probe.
    double
    getKineticEnergy()
    Return the kinetic energy of the probe.
    double
    getLongitinalPhase()
    Returns the longitudinal phase of this probe with respect to the RF phase.
    double
    getMomentum()
    Returns the momentum
    double
    getPosition()
    Returns the current beam-line position of the probe
    double
    getSpeciesCharge()
    Returns the charge of probe's particle species
    String
    getSpeciesName()
    returns the species name
    double
    getSpeciesRestEnergy()
    Returns the rest energy of particle species
    double
    getTime()
    Return the time elapsed since the probe began propagation.
    Date
    getTimestamp()
    Returns the time stamp of the probe.
    Trajectory<S>
    getTrajectory()
    Get the state history of the probe.
    void
    initialize()
    Initializes the probe, resetting state as necessary.
    protected void
    initializeFrom(Probe<S> probe)
    Deprecated.
    This method is only called from child class overrides which are never called themselves.
    void
    load(DataAdaptor daptSource)
    Load the contents of a probe from an data archive represented by a DataAdaptor interface.
    ProbeState<?>
    lookupLastStateFor(String strElemTypeId)
    Looks up the last probe state created by a modeling element of the given identifier.
    static Probe<?>
    newProbeInitializedFrom(Probe<?> probeInit)
    Clone factory method.
    void
    performPostProcessing()
    Deprecated.
    This method is called in several places I don't think it ever is implemented to do anything.
    static Probe<?>
    readFrom(DataAdaptor container)
    Read the contents of the supplied DataAdaptor and return an instance of the appropriate Probe species.
    protected abstract S
    readStateFrom(DataAdaptor container)
    Read the contents of the supplied DataAdaptor and return an instance of the appropriate Trajectory species.
    void
    reset()
    Resets the probe to the saved initial state, if there is one and clears the trajHist.
    void
    save(DataAdaptor daSink)
    Save the contents of a probe to a data archive represented by a DataAdaptor interface.
    boolean
    setAlgorithm(IAlgorithm ifcAlg)
    Set the algorithm defining the probes dynamics through elements
    void
    setComment(String strComment)
    Provide a user comment associated with the probe
    void
    setCurrentElement(String id)
    Set the current lattice element id.
    void
    setCurrentElementTypeId(String strTypeId)
    Sets the type identifier string of the modeling element where this probe currently exists.
    void
    setCurrentHardwareId(String strSmfId)
    Sets the identifier of the hardware modeled by the current element.
    void
    setKineticEnergy(double w)
    Set the current kinetic energy of the probe.
    void
    setLongitudinalPhase(double dblPhsLng)
    Set the longitudinal phase of this probe with respect to the RF phase.
    void
    setPosition(double s)
    Set the current position of the probe along the beamline.
    void
    setSpeciesCharge(double q)
    Set the charge of the particle species in the beam
    void
    setSpeciesName(String name)
    Set the species name
    void
    setSpeciesRestEnergy(double eR)
    Set the rest energy of a single particle in the beam
    void
    setTime(double dblTime)
    Set the current time since the probe began propagating
    void
    setTimestamp(Date dateStamp)
    Sets a time stamp for the probe.
    void
    setTracking(boolean bolTrack)
    Set particle trajHist tracking for probes.
    void
    update()
    Save the probe state into trajHist.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

    • Probe

      protected Probe()
      Creates a new instance of Probe. Since Probe is an abstract base only derived classes may call constructor.

    • Probe

      protected Probe(IAlgorithm ifcAlg)
      Creates a new instance of Probe. Since Probe is an abstract base only derived classes may call constructor.
      Parameters:
      ifcAlg - default dynamics algorithm for probe

    • Probe

      protected Probe(Probe<S> probe)
      Copy constructor for Probe. This constructor does a deep copy of the Probe base attributes by calling member support method deepCopyProbeBase().
      Parameters:
      probe - Probe object to be cloned

  • Method Details

    • readFrom

      public static Probe<?> readFrom(DataAdaptor container) throws DataFormatException
      Read the contents of the supplied DataAdaptor and return an instance of the appropriate Probe species.
      Parameters:
      container - DataAdaptor to read a Probe from
      Returns:
      a Probe for the contents of the DataAdaptor
      Throws:
      DataFormatException - error encountered reading the DataAdaptor

    • newProbeInitializedFrom

      public static Probe<?> newProbeInitializedFrom(Probe<?> probeInit)

      Clone factory method. Creates a new Probe object, of the appropriate type, initialized to the argument Probe.

      NOTE:

      There is now a reset() method that is preferable to this one. It clears the probe trajHist and restores the initial state saved in the initialize() method, without creating a new probe instance.

      Parameters:
      probeInit - Probe object containing initial data
      Returns:
      new Probe object initialized to argument

    • createTrajectory

      public abstract Trajectory<S> createTrajectory()
      Require concrete implementations to override this method to create a Trajectory object of the appropriate species.
      Returns:
      a Trajectory of the appropriate species for this probe type

    • createProbeState

      public abstract S createProbeState()
      Captures the probe's state in a ProbeState of the appropriate species.

    • createEmptyProbeState

      public abstract S createEmptyProbeState()
      Creates a new, blank ProbeState of the appropriate species.
      Returns:
      a new, blank ProbeState
      Since:
      Jul 1, 2014

    • readStateFrom

      protected abstract S readStateFrom(DataAdaptor container) throws DataFormatException
      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 ProbeState for the contents of the DataAdaptor
      Throws:
      DataFormatException - error encountered reading the DataAdaptor

    • copy

      public abstract Probe<S> copy()
      Creates a deep copy of the probe

    • setComment

      public void setComment(String strComment)
      Provide a user comment associated with the probe
      Parameters:
      strComment - user comment string

    • setTimestamp

      public void setTimestamp(Date dateStamp)
      Sets a time stamp for the probe.
      Parameters:
      dateStamp - time stamp for probe

    • setSpeciesName

      public void setSpeciesName(String name)
      Set the species name
      Parameters:
      name - the species name

    • setAlgorithm

      public boolean setAlgorithm(IAlgorithm ifcAlg)
      Set the algorithm defining the probes dynamics through elements
      Parameters:
      ifcAlg - object exposing the IAlgorithm interface

    • setTracking

      public void setTracking(boolean bolTrack)
      Set particle trajHist tracking for probes.
      Parameters:
      bolTrack - turn tracking on or off

    • initializeFrom

      @Deprecated protected void initializeFrom(Probe<S> probe)
      Deprecated.
      This method is only called from child class overrides which are never called themselves.
      Initialize this probe from the one specified.
      Parameters:
      probe - the probe from which to initialize this one

    • cloneCurrentProbeState

      public S cloneCurrentProbeState()
      This method returns a clone of the current state of this probe. That is, the ProbeState object is a representation of this probe at the moment this method was called.
      Returns:
      a deep copy of the current state of this probe
      Since:
      Jun 26, 2014

    • applyState

      public void applyState(S state)
      Apply the contents of ProbeState to update my current state. Subclass implementations should call super.applyState to ensure superclass state is applied.
      Parameters:
      state - ProbeState object containing new probe state data

    • reset

      public void reset()

      Resets the probe to the saved initial state, if there is one and clears the trajHist.

      CKA NOTES:

      These notes concern the refactoring of the probe component in order to tighten the typing.

      · The new behavior should be the same as before, only the implementation differs. The current state is set to a clone of the (previously saved) initial state. · The trajectory is cleared.

    • getComment

      public String getComment()
      Returns the comment string associated with the probe
      Returns:
      comment string

    • getTimestamp

      public Date getTimestamp()
      Returns the time stamp of the probe.
      Returns:
      time stamp

    • getMomentum

      public double getMomentum()
      Returns the momentum
      Returns:
      particle momentum

    • getCurrentState

      public S getCurrentState()
      Returns the current state object maintained by this probe. The state object contains all the defining state information at the current simulation trajectory location.
      Returns:
      the current state of this probe
      Since:
      Nov 18, 2014

    • getInitialState

      public S getInitialState()
      Returns the initial state of this probe. This is the state with which the probe begins the simulation. Whenever the reset() command is called the current state of the simulation is set to this state.
      Returns:
      the current starting state for this probe
      Since:
      Dec 29, 2015, Christopher K. Allen

    • getTrajectory

      public Trajectory<S> getTrajectory()
      Get the state history of the probe.
      Specified by:
      getTrajectory in interface IProbe
      Returns:
      Trajectory object of the proper sub-type for the probe type

    • getLongitinalPhase

      public double getLongitinalPhase()

      Returns the longitudinal phase of this probe with respect to the RF phase. Typically used to account for phase delay/advance in cavities incurred due to finite propagation time. For example

          φ ≜ φ0 - Δφ

      where Δφ = 2πfΔt is the phase delay due to elapsed time Δt, f is the cavity resonant frequency, and φ0 is the operating phase of the cavity (w.r.t. the synchronous particle).

      Specified by:
      getLongitinalPhase in interface IProbe
      Returns:
      the probe phase φ with respect to the machine RF frequency
      Since:
      Nov 17, 2014

    • getSpeciesName

      public String getSpeciesName()
      returns the species name
      Specified by:
      getSpeciesName in interface IProbe
      Returns:
      species name

    • getSpeciesCharge

      public double getSpeciesCharge()
      Returns the charge of probe's particle species
      Specified by:
      getSpeciesCharge in interface IProbe
      Returns:
      particle species charge (Coulombs)

    • getSpeciesRestEnergy

      public double getSpeciesRestEnergy()
      Returns the rest energy of particle species
      Specified by:
      getSpeciesRestEnergy in interface IProbe
      Returns:
      particle species rest energy (electron-volts)

    • getCurrentElement

      public String getCurrentElement()
      Returns the id of the current lattice element that the probe is visiting.
      Specified by:
      getCurrentElement in interface IProbe
      Returns:
      id of current lattice element

    • getCurrentElementTypeId

      public String getCurrentElementTypeId()
      Description copied from interface: IProbe
      Get the type identifier string of the modeling element where this probe currently exists. Note that all modeling elements have a static string identifier defined in their class definition.
      Specified by:
      getCurrentElementTypeId in interface IProbe
      Since:
      Dec 16, 2014 by Christopher K. Allen
      See Also:

    • getCurrentHardwareId

      public String getCurrentHardwareId()
      Returns the identifier of the hardware modeled by the element associated with this state.
      Specified by:
      getCurrentHardwareId in interface IProbe
      Returns:
      hardware ID of the associated modeling element
      Since:
      Sep 3, 2014
      See Also:

    • getPosition

      public double getPosition()
      Returns the current beam-line position of the probe
      Specified by:
      getPosition in interface IProbe
      Returns:
      probe position (meters)

    • getTime

      public double getTime()
      Return the time elapsed since the probe began propagation.
      Specified by:
      getTime in interface IProbe
      Returns:
      elapsed time in seconds

    • getKineticEnergy

      public double getKineticEnergy()
      Return the kinetic energy of the probe. Depending upon the probe type, this could be the actual kinetic energy of a single constituent particle, the average kinetic energy of an ensemble, the design energy, etc.
      Specified by:
      getKineticEnergy in interface IProbe
      Returns:
      probe kinetic energy (electron-volts)

    • getBeta

      public double getBeta()
      Returns the probe velocity normalized to the speed of light.
      Specified by:
      getBeta in interface IProbe
      Returns:
      normalized probe velocity v/c (unitless

    • getGamma

      public double getGamma()
      Returns the relativistic parameter corresponding to the probe velocity. The relativistic factor is given by the formulae

          γ = (W/mc2) + 1 = [1/(1-β2)]1/2
      Specified by:
      getGamma in interface IProbe
      Returns:
      probe relativistic factor (unitless)

    • lookupLastStateFor

      public ProbeState<?> lookupLastStateFor(String strElemTypeId)
      Description copied from interface: IProbe
      Looks up the last probe state created by a modeling element of the given identifier. The history of the probe (i.e., a Trajectory object is searched for the last state with the modeling type ID equal to the given value.
      Specified by:
      lookupLastStateFor in interface IProbe
      Parameters:
      strElemTypeId - modeling element type identification string
      Returns:
      the last state created by such a modeling element
      Since:
      Dec 17, 2014 by Christopher K. Allen
      See Also:

    • setCurrentElement

      public void setCurrentElement(String id)
      Set the current lattice element id.
      Specified by:
      setCurrentElement in interface IProbe
      Parameters:
      id - element id of current lattice element

    • setCurrentElementTypeId

      public void setCurrentElementTypeId(String strTypeId)
      Description copied from interface: IProbe
      Sets the type identifier string of the modeling element where this probe currently exists. Note that all modeling elements have a static string identifier defined in their class definition.
      Specified by:
      setCurrentElementTypeId in interface IProbe
      Parameters:
      strTypeId - static identifier string of the modeling element class
      Since:
      Dec 16, 2014 by Christopher K. Allen
      See Also:

    • setCurrentHardwareId

      public void setCurrentHardwareId(String strSmfId)
      Sets the identifier of the hardware modeled by the current element.
      Specified by:
      setCurrentHardwareId in interface IProbe
      Parameters:
      strSmfId - hardware ID of the current modeling element
      Since:
      Sep 3, 2014
      See Also:

    • setPosition

      public void setPosition(double s)
      Set the current position of the probe along the beamline.
      Specified by:
      setPosition in interface IProbe
      Parameters:
      s - new probe position (meters)
      See Also:

    • setTime

      public void setTime(double dblTime)
      Set the current time since the probe began propagating
      Specified by:
      setTime in interface IProbe
      Parameters:
      dblTime - new probe current time in seconds

    • setLongitudinalPhase

      public void setLongitudinalPhase(double dblPhsLng)

      Set the longitudinal phase of this probe with respect to the RF phase. Typically used to account for phase delay/advance in cavities incurred due to finite propagation time. For example

          φ ≜ φ0 - Δφ

      where Δφ = 2πfΔt is the phase delay due to elapsed time Δt, f is the cavity resonant frequency, and φ0 is the operating phase of the cavity (w.r.t. the synchronous particle).

      Specified by:
      setLongitudinalPhase in interface IProbe
      Parameters:
      dblPhsLng - the phase delay Δφ incurred from probe propagate between RF cavities
      Since:
      Nov 17, 2014

    • setKineticEnergy

      public void setKineticEnergy(double w)
      Set the current kinetic energy of the probe.
      Specified by:
      setKineticEnergy in interface IProbe
      Parameters:
      w - new probe kinetic energy (electron-volts)
      See Also:

    • setSpeciesCharge

      public void setSpeciesCharge(double q)
      Set the charge of the particle species in the beam
      Specified by:
      setSpeciesCharge in interface IProbe
      Parameters:
      q - species particle charge in units of positive electron charge
      See Also:

    • setSpeciesRestEnergy

      public void setSpeciesRestEnergy(double eR)
      Set the rest energy of a single particle in the beam
      Specified by:
      setSpeciesRestEnergy in interface IProbe
      Parameters:
      eR - particle rest energy (electron-volts)
      See Also:

    • initialize

      public void initialize()

      Initializes the probe, resetting state as necessary.

      CKA NOTES:

      These notes concern the refactoring of the probe component in order to tighten the typing.

      · In order to make this method compatible with the previous behavior it must set the saved "initial state" to the current probe state. The previous incarnation assigned the new initial state by calling the createProbeState() method to which created a new probe state representing the current state of the probe.
      · The trajectory is cleared, that is, there is no longer any history in the probe
      · Thus, initialize() is really a poor choice, since all that is done is

          - The initial state is reset to the current state
          - The trajectory is cleared

      Specified by:
      initialize in interface IProbe

    • update

      public void update() throws ModelException
      Save the probe state into trajHist.
      Specified by:
      update in interface IProbe
      Throws:
      ModelException - an error occurred while trying to update the probe

    • performPostProcessing

      @Deprecated public void performPostProcessing()
      Deprecated.
      This method is called in several places I don't think it ever is implemented to do anything.
      Subclasses should override this method to perform any required post processing upon completion of algorithm processing. This method implementation does nothing.
      Specified by:
      performPostProcessing in interface IProbe

    • getAlgorithm

      public IAlgorithm getAlgorithm()
      Return the algorithm defining the probes dynamics.
      Specified by:
      getAlgorithm in interface IProbe
      Returns:
      interface to probe dynamics

    • getArchive

      public IArchive getArchive()
      Return the archiving interface for this object.
      Specified by:
      getArchive in interface IProbe
      See Also:

    • load

      public void load(DataAdaptor daptSource) throws DataFormatException
      Load the contents of a probe from an data archive represented by a DataAdaptor interface.
      Specified by:
      load in interface IArchive
      Parameters:
      daptSource - data archive containing probe info
      Throws:
      DataFormatException - bad probe type, missing child data node, or bad number format

    • save

      public void save(DataAdaptor daSink)
      Save the contents of a probe to a data archive represented by a DataAdaptor interface.
      Specified by:
      save in interface IArchive
      Parameters:
      daSink - data archive to receive probe information

    • deepCopy

      protected void deepCopy(Probe<S> probe)
      This is a convenience function for derived classes when implementing their deepCopy() method. This functions deep copies all attributes in the Probe base class. The derived classes need only then deep copy all attributes particular to their type (e.g., state, etc.).
      Parameters:
      probe - probe object whose Probe base is to be deep copied into this