gov.sns.tools.beam.em
Class EllipsoidalCharge

java.lang.Object
  |
  +--gov.sns.tools.beam.em.EllipsoidalCharge

public class EllipsoidalCharge

extends java.lang.Object

Encapsulates the properties of a ellipsoidally symmetric distribution of charge in 3D space, in particular, the electromagnetic properties. Provides convenience methods for creating arbitrarily oriented ellipsoids and determining their fields, and their effects on beam particles, specifically, in the form of a linear transfer matrix generator.

Field Summary

static double

FCONST

Constructor Summary

EllipsoidalCharge()
Default Constructor.

EllipsoidalCharge(double K, CorrelationMatrix matChi)
Construct a beam charge density ellipsoid described by the phase space correlation matrix matChi and generalized beam perveance K.

EllipsoidalCharge(double K, double a, double b, double c)
Constructs an ellipsoidal charge from its semi-axes values and the generalized beam pervance.

EllipsoidalCharge(double K, R3x3 matSigma)
Construct an ellipsoidal charge from its covariance matrix and the generalized beam perveance.

EllipsoidalCharge(double K, R3x3 matSigma, R3 vecDispl)
Construct an ellipsoid charge from its covariance matrix, displacement vector and generalized beam perveance.

Method Summary

R3	compDefocusConstants() Computes the normalized defocusing lengths for a space charge kick given the semi-axes of the beam ellipsoid.
R3	compDefocusConstantsAlaTrace3D() This method is provided as a comparison utility for validation against simulation with Trace3D.
PhaseMatrix	compPhaseRotation() Compute the rotation matrix in phase space that corresponds to the current rotation matrix in 3D configuration space.
PhaseMatrix	compTransMatrixGen() Calculates the transfer matrix generator for space charge effects from this EllipsoidalCharge object.
void	configureFromCorrelation(CorrelationMatrix matChi) Configure the ellipsoidal charge from the given CorrelationMatrix.
void	configureFromCovariance(R3x3 matSigma) Configure the ellipsoidal charge from the given covariance matrix.
double	getBeamPerveance() Return the generalized beam perveance of the ellipsoidal charge.
R3	getDisplacement() Return the displacement from the standard cartesian coordinate original.
R3x3	getRotation() Get orthogonal rotation matrix R in SO(3) that converts from ellipsoid coordinates to standard cartesian coordinates.
R3	getSemiAxes() Return all the ellipsoid semi-axes as a vector.
double	getSemiAxisX() Return the value of the first ellispoid semi-axis.
double	getSemiAxisY() Return the value of the second ellispoid semi-axis.
double	getSemiAxisZ() Return the value of the third ellispoid semi-axis.
void	setBeamPerveance(double K) Set the generalized beam perveance of the ellipsoidal charge directly.
void	setDisplacement(R3 vecDispl) Sets the displacement of the ellipsoid centroid from the coordinate origin.
void	setRotation(R3x3 matRot) Set the rotation matrix for the ellipsoid.
void	setSemiAxes(double a, double b, double c) Set the semi-axes of the ellipsoid directly.

Methods inherited from class java.lang.Object

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

Field Detail

FCONST

public static final double FCONST

Constructor Detail

EllipsoidalCharge

public EllipsoidalCharge()

Default Constructor. Creats a new, empty EllipsoidalCharge object

EllipsoidalCharge

public EllipsoidalCharge(double K,
                         double a,
                         double b,
                         double c)

Constructs an ellipsoidal charge from its semi-axes values and the generalized beam pervance. The ellipsoid is assumed to be centered on the coordinate origin and aligned to the coordinate axes. Thus, the reference ellipsoid is described by the equation (x/a)^2 + (y/b)^2 + (z/c)^2 = 1 where a,b,c are the semi-axes values on the x,y,z coordinate directions, respectively.

Parameters:

K - generalized beam perveance

a - ellipsoid semi-axis in x direction

b - ellipsoid semi-axis in y direction

c - ellipsoid semi-axis in z direction

See Also:

setBeamPerveance(double), setSemiAxes(double, double, double)

EllipsoidalCharge

public EllipsoidalCharge(double K,
                         R3x3 matSigma)
                  throws java.lang.IllegalArgumentException

Construct an ellipsoidal charge from its covariance matrix and the generalized beam perveance. The reference elllipsoid is represented by the equation r'*matSigmaInv*r=1 where matSigmaInv is the inverse of the 3x3 matrix argument matSigma, r=(x y z) is the position vector in R3, and the prime indicates transposition. Note that matSigma must be symmetric and positive definite. Thus, it is diagonalizable with the decomposition matSigma = R*D*R' where the prime indicates transposition, R in SO(3) is the orthogonal rotation matrix and D is the diagonal matrix of real eigenvalues. Note from the above that these eigenvalues are the squares of the ellipsoid semi-axes.

Parameters:

K - generalized beam perveance

matSigma - covariance matrix for ellipsoid

Throws:

java.lang.IllegalArgumentException - matrix is not symmetric and/or positive definite

See Also:

setBeamPerveance(double), configureFromCovariance(gov.sns.tools.math.r3.R3x3)

EllipsoidalCharge

public EllipsoidalCharge(double K,
                         R3x3 matSigma,
                         R3 vecDispl)
                  throws java.lang.IllegalArgumentException

Construct an ellipsoid charge from its covariance matrix, displacement vector and generalized beam perveance. The reference elllipsoid is represented by the equation (r-vecDispl)'*matSigmaInv*(r-vecDispl) = 1 where matSigmaInv is the inverse of the 3x3 matrix argument matSigma, r=(x y z) is the position vector in R3, and the prime indicates tansposition. Note that matSigma must be symmetric and positive definite. Thus, it is diagonalizable with the decomposition matSigma = R*D*R' where the prime indicates transposition, R in SO(3) is the orthogonal rotation matrix and D is the diagonal matrix of real eigenvalues. Note from the above that these eigenvalues are the squares of the ellipsoid semi-axes.

Parameters:

K - generalized beam perveance

matSigma - covariance matrix for ellipsoid

vecDispl - displacement vector from the coordinate origin

Throws:

java.lang.IllegalArgumentException - matrix is not symmetric and/or positive definite

See Also:

setBeamPerveance(double), setDisplacement(gov.sns.tools.math.r3.R3), configureFromCovariance(gov.sns.tools.math.r3.R3x3)

EllipsoidalCharge

public EllipsoidalCharge(double K,
                         CorrelationMatrix matChi)

Construct a beam charge density ellipsoid described by the phase space correlation matrix matChi and generalized beam perveance K. Note that the phase space correlation matrix in homogeneous coordinates contains all moments up to and including second order; this includes the first-order moments that describe the displacement of the ellipsoid from the coordinate origin. Thus, from the 7x7 phase space correlation matrix we extract the displacement vector (<x>,<y><z>) and the 3x3 covariance matrix | <x*x> <x*y> <x*z> | | <x>*<x> <x>*<y> <x>*<z> | | <y*x> <y*y> <y*z> | - | <y>*<x> <y>*<y> <y>*<z> | | <z*x> <z*y> <z*z> | | <z>*<x> <z>*<y> <z>*<z> | to construct the ellipsoidal charge object according to the previous constructor parameters.

Parameters:

K - generalized beam perveance

matChi - envelope correlation matrix in homogeneous phase space coordinates

See Also:

setBeamPerveance(double), configureFromCorrelation(gov.sns.tools.beam.CorrelationMatrix)

Method Detail

configureFromCovariance

public void configureFromCovariance(R3x3 matSigma)
                             throws java.lang.IllegalArgumentException

Configure the ellipsoidal charge from the given covariance matrix. The reference ellipsoid is then described by the equation r'*matSigInv*r = 1 where r=(x y z) is the position vector in R3, matSigInv is the inverse of covariance matrix argument, and the prime indicates transposition. Consider ellipsoidally symmetric distributions described by the current reference ellipsoid, that is distributions F of the form F(x,y,z) = F(r'*matSigmaInv*r). Then the second-order central moments, or covariances, of the ellipsoid are exactly the elements of the covariance matrix. That is <(ri-<ri&gr;)*(rj-<rj>)> = C*matSigma_ij where C is some constant that depends upon the distribution profile. The covariance matrix is decomposed into its eigensystem of eigenvalues and orthogonal rotation. Note that matSigma must be symmetric and positive definite. Thus, it is diagonalizable with the decomposition matSigma = R*D*R' where R in SO(3) is the orthogonal rotation matrix and D is the diagonal matrix of real eigenvalues. Note from the above that these eigenvalues are the squares of the ellipsoid semi-axes. This identifies the ellipsoid uniquely (and clearly). Note that the eigenvalues in this case are the squares of the semi-axes.

Parameters:

matSigma - the covariance matrix of the ellipsoid

Throws:

java.lang.IllegalArgumentException - the covariance matrix is not symmetric and/or positive definite

See Also:

setRotation(gov.sns.tools.math.r3.R3x3), setSemiAxes(double, double, double)

configureFromCorrelation

public void configureFromCorrelation(CorrelationMatrix matChi)

Configure the ellipsoidal charge from the given CorrelationMatrix. Note that the phase space correlation matrix in homogeneous coordinates contains all moments up to and including second order; this includes the first-order moments that describe the displacement of the ellipsoid from the coordinate origin. Thus, from the 7x7 phase space correlation matrix we extract the displacement vector (<x>,<y><z>) and the 3x3 covariance matrix | <x*x> <x*y> <x*z> | | <x>*<x> <x>*<y> <x>*<z> | | <y*x> <y*y> <y*z> | - | <y>*<x> <y>*<y> <y>*<z> | | <z*x> <z*y> <z*z> | | <z>*<x> <z>*<y> <z>*<z> | to construct the ellipsoidal charge object according to the previous constructor parameters.

Parameters:

matChi - phase space correlation matrix (in homogeneous coordinates) for the ellipsoidal charge

setBeamPerveance

public void setBeamPerveance(double K)

Set the generalized beam perveance of the ellipsoidal charge directly.

Parameters:

K - generalized beam perveance unitless

setSemiAxes

public void setSemiAxes(double a,
                        double b,
                        double c)

Set the semi-axes of the ellipsoid directly.

Parameters:

a - ellipsoid semi-axis in x direction

b - ellipsoid semi-axis in y direction

c - ellipsoid semi-axis in z direction

setDisplacement

public void setDisplacement(R3 vecDispl)

Sets the displacement of the ellipsoid centroid from the coordinate origin.

setRotation

public void setRotation(R3x3 matRot)

Set the rotation matrix for the ellipsoid. The argument must be an element of the special orthogonal group SO(3) that converts from the natural coordinates of the ellipsoid to the standard cartesian coordinates. That is, to convert a point r in the ellipsoid coordinate frame to standard cartesian coordinates apply the transform rs = matRot*r where rs represents the point in standard cartesian coordinates. That is, matRot is the eigenvector matrix of the covariance matrix for the ellipsoid.

Parameters:

matRot - rotation matrix in SO(3)

See Also:

#setCovariance

getBeamPerveance

public double getBeamPerveance()

Return the generalized beam perveance of the ellipsoidal charge.

getSemiAxisX

public double getSemiAxisX()

Return the value of the first ellispoid semi-axis.

getSemiAxisY

public double getSemiAxisY()

Return the value of the second ellispoid semi-axis.

getSemiAxisZ

public double getSemiAxisZ()

Return the value of the third ellispoid semi-axis.

getSemiAxes

public R3 getSemiAxes()

Return all the ellipsoid semi-axes as a vector.

Returns:

vector (a,b,c) of ellipsoid semi-axes

getDisplacement

public R3 getDisplacement()

Return the displacement from the standard cartesian coordinate original. That is, if d is this displacement, then the centroid of the ellipsoid lies at the point d in standard cartesian coordinates.

Returns:

location point (dx,dy,dz) of ellipsoid centroid

getRotation

public R3x3 getRotation()

Get orthogonal rotation matrix R in SO(3) that converts from ellipsoid coordinates to standard cartesian coordinates. From an alternate perspective, if we align the ellipsoid to the standard coordinate axes, a rotaton by R' will put the ellipsoid into its current position, or a rotation by R will move it from its current position back into standard position.

Returns:

rotation matrix in SO(3) moving the ellipsoid into standard position

compPhaseRotation

public PhaseMatrix compPhaseRotation()

Compute the rotation matrix in phase space that corresponds to the current rotation matrix in 3D configuration space. Since the tangent bundles of 3D configuration space at a point (x,y,z) are represented by the cartesian planes (x',y',z'), they must be rotated in the same manner as the point (x,y,z). This is a convenience method to build that corresponding phase matrix in SO(7).

Returns:

phase rotation matrix in S0(7) corresponding to the current rotation in S0(3)

compDefocusConstants

public R3 compDefocusConstants()

Computes the normalized defocusing lengths for a space charge kick given the semi-axes of the beam ellipsoid. The true defocusing lengths are obtained by multiplying the result by the factor 1/f = (1/fnorm)*K*ds where f is the defocusing length, fnorm is the normalized defocusing length (returned by this method), K is the generalized beam perveance, and ds is the pathlength over which the kick is being applied. The defocusing lengths (1/fx,1/fy,1/fz) are given for the cartesian coordinate system x',y',z' which is aligned to the ellipsoid semi-axes. If the ellipsoid is rotated with respect to the coordinate system in which the ellipsoid was defined (constructed), then any transfer matrix built from these focusing constants must be rotated into the original coordinate system. The defocusing lengths are computed from a weighted linear regression of the true fields generated by an ellipsoidally symmetric charge distribution. By the equivalent uniform beam principle the space charge effects (to second order) are only loosely coupled to the actual profile of the distribution (assuming that it is ellipsoidally symmetric). The effect from the distribution profile manifests itself as a factor, we take this factor to be that for a uniform ellipsoid for computational purposes.

Returns:

vector (fxnorm,fynorm,fznorm) of defocusing constants

See Also:

getRotation(), compPhaseRotation(), Theory and Technique of Beam Envelope Simulation

compDefocusConstantsAlaTrace3D

public R3 compDefocusConstantsAlaTrace3D()

This method is provided as a comparison utility for validation against simulation with Trace3D. Trace3D uses an approximation to the elliptic integrals encountered in the space charge field expressions. These approximations break down to first order as the beam ellipsoid becomes increasingly eccentric in the transverse direction.

Returns:

vector (fxnorm,fynorm,fznorm) of defocusing constants

See Also:

compDefocusConstants()

compTransMatrixGen

public PhaseMatrix compTransMatrixGen()

Calculates the transfer matrix generator for space charge effects from this EllipsoidalCharge object. Denoting the returned transfer matrix generator as B then the actual transfer matrix M(s) for the space charge effect is given as M(s) = exp(sB) where s is the path length of the dynamics. Note that to obtain this matrix a linear fit to the true fields was performed where the regression is weighted by the distribution itself. According the "Equivalent Beam" principle by Sacherar this regression then only loosely couples to the actual distribution profile of the the ellipsoidal charge. For computational purposes we have assumed a uniform density ellipsoid, but that is of no real consequence practically.

Returns:

transfer matrix generator representing linear space charge effects