gov.sns.tools.beam.ens
Class Ensemble

java.lang.Object
  |
  +--gov.sns.tools.beam.ens.Ensemble

All Implemented Interfaces:

java.io.Serializable

public class Ensemble

extends java.lang.Object

implements java.io.Serializable

Represents an ensemble of charged particles and the collective properties associated with such physical object.

See Also:

Serialized Form

Constructor Summary

Ensemble()
Creates a new instance of Ensemble

Ensemble(Ensemble ens)
Create a deep copy clone of an ensemble object

Method Summary

void	add(Particle p) Add a particle to ensemble
Ensemble	deepCopy() Create a deep copy object of this ensemble
protected java.util.TreeSet	deepCopyParticles(Ensemble ens) Make a deep copy of the ensemble's particle container.
int	getCount() Get size of ensemble
java.util.Iterator	iterator() Iterate through ensemble
boolean	load(java.io.File file) Populate the ensemble from a data file.
boolean	load(java.lang.String strFile) Populate the ensemble from a data file.
static void	main(java.lang.String[] arg) Test driver for testing Ensemble class.
CorrelationMatrix	phaseCorrelation() Get the correlatiom matrix of the ensemble in homogeneous coordinates
PhaseVector	phaseMean() Compute the centroid of the ensemble
double	potentialQuadExpansion(R3 pt, double Q, PhaseMatrix matSigma) Computes the electric potential from a quadrupole multipole expansion.
double	potentialSummation(R3 ptFld) Computes the Coulomb potential of the ensemble at the given field point.
void	print(java.io.PrintWriter os) Print out contents of the ensemble.
static Ensemble	restoreUrl(java.lang.String strUrl) Creates an Ensemble from a file store.
double[]	rmsEmittances() Compute the rms emittances in each phase plane
boolean	save(java.io.File file) Save ensemble state to persisten disk file.
static void	testPersistence(java.io.PrintWriter osLog) Test the file persistence mechanism.
double	totalCharge() Get the total charge of the ensemble
R3	totalCurrent() Get the total current of the ensemble.

Methods inherited from class java.lang.Object

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

Constructor Detail

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 Detail

restoreUrl

public static Ensemble restoreUrl(java.lang.String strUrl)
                           throws java.io.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:

java.io.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 java.util.Iterator 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

phaseCorrelation

public CorrelationMatrix phaseCorrelation()

Get the correlatiom 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 componets 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 determing 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

See Also:

#getSigma()

load

public boolean load(java.lang.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(java.io.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(java.io.File file)

Save ensemble state to persisten 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(java.io.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(java.lang.String[] arg)

Test driver for testing Ensemble class.

testPersistence

public static void testPersistence(java.io.PrintWriter osLog)

Test the file persistence mechanism.

Parameters:

osLog - output stream to send logging information

deepCopyParticles

protected java.util.TreeSet 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