Package xal.tools.beam.ens

Class Ensemble

java.lang.Object
xal.tools.beam.ens.Ensemble
All Implemented Interfaces:
Serializable
public class Ensemble extends Object implements Serializable
Represents an ensemble of charged particles and the collective properties associated with such physical object.
Author:
CKAllen
See Also:

  • Constructor Details

    • Ensemble

      public Ensemble()
      Creates a new instance of Ensemble

    • Ensemble

      public Ensemble(Ensemble ens)
      Create a deep copy clone of an ensemble object
      Parameters:
      ens - ensemble object to be deep copied

  • Method Details

    • restoreUrl

      public static Ensemble restoreUrl(String strUrl) throws IOException
      Creates an Ensemble from a file store.
      Parameters:
      strUrl - the URL of the file store
      Returns:
      new Ensemble instance corresponding to file store
      Throws:
      IOException - unable to read file at URL

    • deepCopy

      public Ensemble deepCopy()
      Create a deep copy object of this ensemble

    • add

      public void add(Particle p)
      Add a particle to ensemble

    • iterator

      public Iterator<Particle> iterator()
      Iterate through ensemble

    • getCount

      public int getCount()
      Get size of ensemble

    • phaseMean

      public PhaseVector phaseMean()
      Compute the centroid of the ensemble
      Returns:
      homogeneous phase space coordinates of ensemble centroid

    • phaseCovariance

      public CovarianceMatrix phaseCovariance()
      Get the correlation matrix of the ensemble in homogeneous coordinates
      Returns:
      the 7x7 correlation matrix of the ensemble distribution

    • rmsEmittances

      public double[] rmsEmittances()
      Compute the rms emittances in each phase plane
      Returns:
      three-element array containing (ex,ey,ez)

    • totalCurrent

      public R3 totalCurrent()
      Get the total current of the ensemble.

      NOTE: If the momentum components of the particle phases are not the velocities, the return value must be scaled. For example, if the trace space values are used then the returned value must be multiplied by beta*c.

    • totalCharge

      public double totalCharge()
      Get the total charge of the ensemble

    • potentialSummation

      public double potentialSummation(R3 ptFld)
      Computes the Coulomb potential of the ensemble at the given field point.

      The potentials from every ensemble particle are summed at the field point and no averaging is performed. Thus, vary large potential values may occur if the field point is sufficiently near an ensemble particle.

      Parameters:
      ptFld - field point to evaluate the potential
      Returns:
      the coulomb potential in MKS units

    • potentialQuadExpansion

      public double potentialQuadExpansion(R3 pt, double q, PhaseMatrix matSigma)
      Computes the electric potential from a quadrupole multipole expansion. This approximation is accurate at points outside the distribution, becoming more accurate as the distance increases. Therefore, note that returned potential is inaccurate for field points inside the particle expanse, with a singularity located at the ensemble centroid.

      Use this method when the ensemble particles all have the same charge, since the covariance matrix is used to compute the moments of the multipole expansion. The covariance matrix is with respect to the phase coordinates and, thus, all particles receive equal weighting.

      This method uses the multipoles up to the quadrupole moment, as taken from the covariance matrix. The expansion is taken from the centroid of the distribution, as such the dipole moments are zero at that point. Thus, the result potential field appears to be generated from the centroid as a point particle along with the quadrupole fields due to the cross moments.

      This method is intended for determining the potential at many fields points for the same ensemble configuration. To avoid repeated calculations of the covariance matrix (using getSigma()) this matrix should be called once and passed to this method on each invocation with the same ensemble configuration.

      Parameters:
      pt - field point to evaluate the potential
      Returns:
      potential from quadrupole expansion of the ensemble

    • load

      public boolean load(String strFile)
      Populate the ensemble from a data file. Particle objects are loaded from persistent phase space data in file.
      Parameters:
      strFile - descriptor of file containing persistent data
      Returns:
      true if successfully recovered ensemble from file

    • load

      public boolean load(File file)
      Populate the ensemble from a data file. Particle objects are loaded from persistent phase space data in file.
      Parameters:
      file - descriptor of file containing persistent data
      Returns:
      true if successfully recovered ensemble from file

    • save

      public boolean save(File file)
      Save ensemble state to persistent disk file. All ensemble particles have phase space coordinates saved.
      Parameters:
      file - file containing persistent data
      Returns:
      true if successfully saved ensemble to file

    • print

      public void print(PrintWriter os)
      Print out contents of the ensemble. WARING - since typical ensembles contain >10^3 particles this method could absorb a large amount of system resources

    • main

      public static void main(String[] arg)
      Test driver for testing Ensemble class.

    • testPersistence

      public static void testPersistence(PrintWriter osLog)
      Test the file persistence mechanism.
      Parameters:
      osLog - output stream to send logging information

    • deepCopyParticles

      protected TreeSet<Particle> deepCopyParticles(Ensemble ens)
      Make a deep copy of the ensemble's particle container.
      Parameters:
      ens - ensemble whose particles are to be cloned
      Returns:
      TreeSet container of cloned particles