gov.sns.tools.beam
Class TraceXalUnitConverter

java.lang.Object
  |
  +--gov.sns.tools.beam.TraceXalUnitConverter

public class TraceXalUnitConverter

extends java.lang.Object

Converts between Trace3D and XAL unit for envelope simulations.

Field Summary

double

LightSpeed Speed of light in a vaccuum (meters/second)

Method Summary

PhaseVector	centroidFromXal(CorrelationMatrix matCorrel) Compute and return the beam centroid coordinates from the correlation matrix in homogeneous coordinates.
CorrelationMatrix	correlationMatrixFromT3d(Twiss t3dX, Twiss t3dY, Twiss t3dZ) Builds a correlation matrix from Twiss parameters in the three phase planes.
CorrelationMatrix	correlationMatrixFromT3d(Twiss t3dX, Twiss t3dY, Twiss t3dZ, PhaseVector centroid) Builds a correlation matrix from Twiss parameters in the three phase planes.
static TraceXalUnitConverter	newConverter(double f, double ER, double W) Creates a new TraceXalUnitConverter object configured to the specified machine and beam species parameters.
PhaseVector	traceToXalCoordinates(PhaseVector vecCoords) Converts phase vector values in Trace3D units to values in units used by XAL (MKS).
Twiss	traceToXalLongitudinal(Twiss t3dTwiss) Converts Twiss parameters in Trace3D units to XAL (MKS) units for the longitudinal phase planes.
Twiss	traceToXalTransverse(Twiss t3dTwiss) Converts Twiss parameter in Trace3D units to XAL (MKS) units for the transverse phase planes.
Twiss[]	twissParametersFromXal(CorrelationMatrix mat) Computes and return the Twiss parameters for each plane that correspond to the given correlation matrix.
PhaseVector	xalToTraceCoordinates(PhaseVector vecCoords) Converts phase vector values in XAL (MKS) units to values in units used by Trace3D.
Twiss	xalToTraceLongitudinal(Twiss twissXal) Converts Twiss parameters in XAL (MKS) units to Trace3D units for the longitudinal phase planes.
Twiss	xalToTraceTransverse(Twiss twissXal) Converts Twiss parameter in XAL (MKS) units to Trace3D units for the transverse phase planes.

Methods inherited from class java.lang.Object

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

Field Detail

LightSpeed

public final double LightSpeed

Speed of light in a vaccuum (meters/second)

See Also:

Constant Field Values

Method Detail

newConverter

public static TraceXalUnitConverter newConverter(double f,
                                                 double ER,
                                                 double W)

Creates a new TraceXalUnitConverter object configured to the specified machine and beam species parameters. All conversions done by the returned object will assume the values provided in the initial configuration.

Parameters:

f - machine electromagnetic frequency in Hz

ER - the rest energy of the beam particle species in eV

W - the kinetic energy of the beam in eV

Returns:

new unit conversion object configured to above parameters

traceToXalCoordinates

public PhaseVector traceToXalCoordinates(PhaseVector vecCoords)

Converts phase vector values in Trace3D units to values in units used by XAL (MKS). Specifically, the argument vecCoord is assumed to be in the form vecPhase=(x,x',y,y',dPhi,dW,1) x in mm x' in mrad y in mm y' in mrad dPhi in degrees dW in keV The output vector in in the following form along with the units: returned=(x,x',y,y',z,z',1) x in meters x' in radians y in meters y' in radians z in meters z' in radians

Returns:

coordinate phase vector in XAL (MKS) units

xalToTraceCoordinates

public PhaseVector xalToTraceCoordinates(PhaseVector vecCoords)

Converts phase vector values in XAL (MKS) units to values in units used by Trace3D. Specifically, the argument vecCoords is assumed to be in the form vecCoords=(x,x',y,y',z,z',1) x in meters x' in radians y in meters y' in radians z in meters z' in radians The output vector in in the following form along with the units: returned=(x,x',y,y',dPhi,dW,1) x in mm x' in mrad y in mm y' in mrad dPhi in degrees dW in keV

Returns:

coordinate phase vector in Trace3D units

traceToXalTransverse

public Twiss traceToXalTransverse(Twiss t3dTwiss)

Converts Twiss parameter in Trace3D units to XAL (MKS) units for the transverse phase planes. Method takes the set of Twiss parameters as a Twiss object argument and returns a new object containing the same Twiss in the different units. The method is none destructive.

alpha Trace3D XAL unitless unitless (no conversion)

beta Trace3D XAL m/rad m/rad

emittance Trace3D XAL eff. (5xRMS) mm-mrad RMS m-rad

Parameters:

t3dTwiss - Twiss parameters in Trace3D units

Returns:

Twiss parameters in XAL units

traceToXalLongitudinal

public Twiss traceToXalLongitudinal(Twiss t3dTwiss)

Converts Twiss parameters in Trace3D units to XAL (MKS) units for the longitudinal phase planes. Method takes the set of Twiss parameters as a Twiss object argument and returns a new object containing the same Twiss in the different units. The method is non destructive.

alpha Trace3D XAL unitless (-1)unitless (phase lag is positive)

beta Trace3D XAL deg/keV m/rad

emittance Trace3D XAL eff. (5xRMS) deg-keV RMS m-rad

Parameters:

t3dTwiss - Trace3D twiss parameters

Returns:

Twiss parameters in XAL units

xalToTraceTransverse

public Twiss xalToTraceTransverse(Twiss twissXal)

Converts Twiss parameter in XAL (MKS) units to Trace3D units for the transverse phase planes. Method takes the set of Twiss parameters as a Twiss object argument and returns a new object containing the same Twiss in the different units. The method is none destructive.

alpha Trace3D XAL unitless unitless (no conversion)

beta Trace3D XAL m/rad m/rad

emittance Trace3D XAL eff. (5xRMS) mm-mrad RMS m-rad

Parameters:

twissXal - Twiss parameters in XAL (MKS) units

Returns:

Twiss parameters in Trace3D units

xalToTraceLongitudinal

public Twiss xalToTraceLongitudinal(Twiss twissXal)

Converts Twiss parameters in XAL (MKS) units to Trace3D units for the longitudinal phase planes. Method takes the set of Twiss parameters as a Twiss object argument and returns a new object containing the same Twiss in the different units. The method is none destructive.

alpha Trace3D XAL unitless (-1)unitless (phase lag is positive)

beta Trace3D XAL deg/keV m/rad

emittance Trace3D XAL eff. (5xRMS) deg-keV RMS m-rad

Returns:

Twiss parameters in XAL units

correlationMatrixFromT3d

public CorrelationMatrix correlationMatrixFromT3d(Twiss t3dX,
                                                  Twiss t3dY,
                                                  Twiss t3dZ)

Builds a correlation matrix from Twiss parameters in the three phase planes. The Twiss parameters are assumed to be in the units used by Trace3D. The beam is also assumed to be centered (on axis), thus the correlation matrix equals the covariance matrix (usually denoted sigma).

NOTE: The returned matrix is in homogeneous coordinates of the block diagonal form | Rxx 0 0 0 | | 0 Ryy 0 0 | | 0 0 Rzz 0 | | 0 0 0 1 | where Rii are 2x2 symmetric blocks corresponding to each phase plane. Clearly the phase planes are uncoupled.

The covariance matrix is the second central moment of the beam distribution defined by sigma=<(z-)^2> =-^T = since since the centroid =0.

Parameters:

t3dX - Twiss parameters describing the beam ellipse in the x plane

t3dY - Twiss parameters describing the beam ellipse in the y plane

t3dZ - Twiss parameters describing the beam ellipse in the z plane

Returns:

correlation matrix corresponding to the above Twiss parameters

See Also:

traceToXalLongitudinal(gov.sns.tools.beam.Twiss), traceToXalTransverse(gov.sns.tools.beam.Twiss)

correlationMatrixFromT3d

public CorrelationMatrix correlationMatrixFromT3d(Twiss t3dX,
                                                  Twiss t3dY,
                                                  Twiss t3dZ,
                                                  PhaseVector centroid)

Builds a correlation matrix from Twiss parameters in the three phase planes. The Twiss parameters are assumed to be in the units used by Trace3D. The correlation matrix also has the mean values corresponding to the mean value vector provided in the argument. The mean value vector centroid is also assumed to be in the units used by Trace3D. It is also assumed to have the form centroid==(,,,,,,1)

The correlation matrix is computed by first computing the covariance matrix (usually denoted sigma in the literature) from the Twiss parameters then adjusting the value according to the effects of being "off center". This is done by adding the tensor product of the mean value vector .

To see this not that the correlation matrix is the second moment of the beam distribution defined by Thus, denoting sigma the covariance matrix we have sigma=<(z-)^2> =-^T or = sigma + ^T

NOTE: The returned matrix is in homogeneous coordinates of the block diagonal form | Rxx 0 0 0 | | 0 Ryy 0 0 | + ^T | 0 0 Rzz 0 | | 0 0 0 1 | where Rii are 2x2 symmetric blocks corresponding to each phase plane and is the vector of mean values in the phase plane, e.g., =(, , , , , ).

Parameters:

t3dX - Twiss parameters describing the beam ellipse in the x plane

t3dY - Twiss parameters describing the beam ellipse in the y plane

t3dZ - Twiss parameters describing the beam ellipse in the z plane

centroid - phase position of the beam centroid

Returns:

correlation matrix corresponding to the above Twiss parameters and centroid

See Also:

traceToXalLongitudinal(gov.sns.tools.beam.Twiss), traceToXalTransverse(gov.sns.tools.beam.Twiss)

centroidFromXal

public PhaseVector centroidFromXal(CorrelationMatrix matCorrel)

Compute and return the beam centroid coordinates from the correlation matrix in homogeneous coordinates. The correlation matrix is assumed to be in MKS units used by XAL and the returned centroid coordinate vector is in phase coordinates units used by Trace3D.

Parameters:

matCorrel - correlation matrix in MKS units

Returns:

coordinates of the centroid in Trace3D units

See Also:

xalToTraceCoordinates(gov.sns.tools.beam.PhaseVector)

twissParametersFromXal

public Twiss[] twissParametersFromXal(CorrelationMatrix mat)

Computes and return the Twiss parameters for each plane that correspond to the given correlation matrix. The Twiss parameters are returned in the units used by Trace3D. The correlation matrix is assumed to be in MKS units used by XAL. NOTE: This method ignores any coupling between phase planes and any offsets of the beam centroid from the beam axis. TODO - Make the method consider the general case of coupling between phase planes and return the Twiss parameters as projections that one would observe in experiments.

Returns:

array of Twiss with length 3 where array[0] = Twiss parameters in x plane array[1] = Twiss parameters in y plane array[2] = Twiss parameters in z plane