xal.model.probe

Class EnvelopeProbe

java.lang.Object

xal.model.probe.Probe<S>

xal.model.probe.BunchProbe<EnvelopeProbeState>

xal.model.probe.EnvelopeProbe

All Implemented Interfaces:

IProbe, IArchive

public class EnvelopeProbe
extends BunchProbe<EnvelopeProbeState>

EnvelopeProbe represents the RMS beam envelopes of a beam. Specifically, its primary state object is the 7×7 matrix of homogeneous phase space moments up to, and including second order. This is the covariance matrix for the beam and is represented as

τ ≡ <z*z^T>

where z=(x,x',y,y',z,z',1) is the vector of homogeneous phase space coordinates, and < · > is the moment operator with respect to the beam distribution. We reserve the symbol σ for the central covariance matrix, which is defined

σ ≡ τ - <z><z>^T

Note that the centroid position = <z> is carried in the last row and column of τ

Since:

August, 2002

See Also:

EnvelopeTrackerBase, EnvelopeProbeState

Field Summary

Fields inherited from class xal.model.probe.Probe

COMMENT_LABEL, PROBE_LABEL, stateCurrent, TEXT_LABEL, TIME_LABEL, trajHist, TYPE_LABEL

Fields inherited from interface xal.model.IProbe

LightSpeed, Permittivity, UnitCharge

Constructor Summary

Constructors

Constructor and Description
EnvelopeProbe() Default Constructor.
EnvelopeProbe(EnvelopeProbe probe) Copy constructor - clones the argument

Method Summary

Modifier and Type	Method and Description
EnvelopeProbe	copy() Create a deep copy of this probe with all state information.
EnvelopeProbeState	createEmptyProbeState() Creates a new, empty EnvelopeProbeState.
EnvelopeProbeState	createProbeState() Creates a snapshot of the current state and returns it as a ProbeState object of the proper type.
Trajectory<EnvelopeProbeState>	createTrajectory() Creates a Trajectory<EnvelopeProbeState> object of the proper type for saving the probe's history.
CovarianceMatrix	getCovariance() Returns the correlation matrix for the beam in homogeneous phase space coordinates.
PhaseMatrix	getCurrentResponseMatrix() Return the last element in the semigroup of response matrices, that is, the last matrix to be post-multiplied onto the response matrix proper.
PhaseMatrix	getResponseMatrix() Get the first-order response matrix accumulated by the Envelope since its initial state.
PhaseMatrix	getResponseMatrixNoSpaceCharge() Get the first-order response matrix accumulated by the Envelope since its initial state.
boolean	getSaveTwissFlag() Deprecated.
void	initFromTwiss(Twiss[] twiss) Set the twiss parameters for each phase plane.
protected void	initializeFrom(Probe<EnvelopeProbeState> probe) Deprecated. Never used
static EnvelopeProbe	newInstance(EnvelopeProbe probe) Probe factory convenient method - clone given probe.
CovarianceMatrix	phaseCovariance() Return the covariance matrix of the distribution.
PhaseVector	phaseMean() Return the phase space coordinates of the centroid in homogeneous coordinates
protected EnvelopeProbeState	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 Trajectory.
void	setCovariance(CovarianceMatrix matTau) Set the correlation matrix for this probe (7x7 matrix in homogeneous coordinates).
void	setCurrentResponseMatrix(PhaseMatrix matRespCurr) Set the current factor of the overall response matrix.
void	setResponseMatrix(PhaseMatrix matResp) Set the first-order response matrix accumulated by the Envelope since its initial state.
void	setResponseMatrixNoSpaceCharge(PhaseMatrix matResp) Set the first-order response matrix accumulated by the Envelope since its initial state.
void	setSaveTwissFlag(boolean bolSaveTwiss) Deprecated. If you want Twiss parameters, either take them from the covariance matrix or use the TwissProbe
PhaseMatrix	stateResponse(java.lang.String elemFrom, java.lang.String elemTo) Deprecated. This calculation should be done using the utility class xal.tools.beam.calc.CalculationsOnMachines

Methods inherited from class xal.model.probe.BunchProbe

beamPerveance, bunchCharge, getBeamCurrent, getBunchFrequency, setBeamCurrent, setBunchFrequency

Methods inherited from class xal.model.probe.Probe

applyState, cloneCurrentProbeState, deepCopy, getAlgorithm, getArchive, getBeta, getComment, getCurrentElement, getCurrentHardwareId, getGamma, getKineticEnergy, getMomentum, getPosition, getSpeciesCharge, getSpeciesName, getSpeciesRestEnergy, getTime, getTimestamp, getTrajectory, initialize, load, newProbeInitializedFrom, performPostProcessing, readFrom, save, setAlgorithm, setComment, setCurrentElement, setCurrentHardwareId, setKineticEnergy, setPosition, setSpeciesCharge, setSpeciesName, setSpeciesRestEnergy, setTime, setTimestamp, setTracking, update

Methods inherited from class java.lang.Object

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

Constructor Detail

EnvelopeProbe

public EnvelopeProbe()

Default Constructor. Creates a new, empty instance of EnvelopeProbe

EnvelopeProbe

public EnvelopeProbe(EnvelopeProbe probe)

Copy constructor - clones the argument

Parameters:

probe - EnvelopeProbe object to be cloned

Method Detail

newInstance

public static EnvelopeProbe newInstance(EnvelopeProbe probe)

Probe factory convenient method - clone given probe. The real work here is being done in the base class Probe by the static factory method of the same name. The current method just ensure type safety.

Parameters:

probe - probe object to be cloned.

Returns:

a clone of the given probe argument

copy

public EnvelopeProbe copy()

Create a deep copy of this probe with all state information.

Specified by:

copy in class Probe<EnvelopeProbeState>

Since:

Oct 23, 2013

See Also:

Probe.copy()

initFromTwiss

public void initFromTwiss(Twiss[] twiss)

Set the twiss parameters for each phase plane. CKA NOTES: - The current method signature is misleading. If there is an beam axis offset before this method is called, then that offset is preserved, but the previous correlation matrix is wiped out. Thus, even though the method signature suggests there will be no offset, there can be.

Parameters:

twiss - array of Twiss objects for H, V , long. directions

initializeFrom

@Deprecated
protected void initializeFrom(Probe<EnvelopeProbeState> probe)

Deprecated. Never used

Initialize this probe from the one specified.

Overrides:

initializeFrom in class Probe<EnvelopeProbeState>

Parameters:

probe - the probe from which to initialize this one

setSaveTwissFlag

@Deprecated
public void setSaveTwissFlag(boolean bolSaveTwiss)

Deprecated. If you want Twiss parameters, either take them from the covariance matrix or use the TwissProbe

Set the Twiss parameters storage flag.

Changes the behavior of the save state methods. By setting this flag to true the Twiss parameter attributes will be saved instead of the correlation matrix. The default behavior for this class is to save the correlation matrix.

CKA Notes:

- This is clearly a kluge; use this method with caution. It is provided to maintain backward compatibility.
- There is another version of code (this version) where the correlation matrix is saved as three sets of Twiss parameters.
o This can be dangerous as we have the potential to loose a lot of information. In particular, if the probe has pasted through a bend or a steering magnet, the Twiss parameters do not contain enough information to restart the probe.

Because of all of these dangers, the method is here, but deprecated.

Parameters:

bolSaveTwiss - Twiss parameter save flag

See Also:

Probe.save(DataAdaptor), Probe.applyState(ProbeState)

setCovariance

public void setCovariance(CovarianceMatrix matTau)

Set the correlation matrix for this probe (7x7 matrix in homogeneous coordinates).

Parameters:

matSigam - new phase space covariance matrix of this probe

See Also:

CovarianceMatrix

setResponseMatrix

public void setResponseMatrix(PhaseMatrix matResp)

Set the first-order response matrix accumulated by the Envelope since its initial state. Note that this response includes the effects of space charge.

Parameters:

matResp - first-order response matrix in homogeneous coordinates

setResponseMatrixNoSpaceCharge

public void setResponseMatrixNoSpaceCharge(PhaseMatrix matResp)

Set the first-order response matrix accumulated by the Envelope since its initial state. Note that this response includes the effects of space charge.

Parameters:

matResp - first-order response matrix in homogeneous coordinates

setCurrentResponseMatrix

public void setCurrentResponseMatrix(PhaseMatrix matRespCurr)

Set the current factor of the overall response matrix. This is the last factor post multiplied onto the response matrix.

Parameters:

matRespCurr - current response matrix factor

getCovariance

public CovarianceMatrix getCovariance()

Returns the correlation matrix for the beam in homogeneous phase space coordinates. This is the primary state object for an EnvelopeProbe object.

Returns:

the 7x7 matrix in homogeneous coordinates

getResponseMatrix

public PhaseMatrix getResponseMatrix()

Get the first-order response matrix accumulated by the Envelope since its initial state. Note that this response includes the effects of space charge.

Returns:

first-order response matrix in homogeneous coordinates

getResponseMatrixNoSpaceCharge

public PhaseMatrix getResponseMatrixNoSpaceCharge()

Get the first-order response matrix accumulated by the Envelope since its initial state. Note that this response does not include the effects of space charge.

Returns:

first-order response matrix in homogeneous coordinates

getCurrentResponseMatrix

public PhaseMatrix getCurrentResponseMatrix()

Return the last element in the semigroup of response matrices, that is, the last matrix to be post-multiplied onto the response matrix proper.

Returns:

last factor of the response matrix

getSaveTwissFlag

@Deprecated
public boolean getSaveTwissFlag()

Deprecated.

Return the save Twiss parameters flag. If this flag is set then only the Twiss parameters are saved to a DataAdaptor object. NOTES: This can be dangerous as we have the potential to loss a lot of information. In particular, if the probe has pasted through a bend or a steering magnet, the Twiss parameters do not contain enough information to restart the probe.

Returns:

Twiss parameter save flag

See Also:

Probe.save(DataAdaptor), Probe.applyState(ProbeState)

phaseCovariance

public CovarianceMatrix phaseCovariance()

Return the covariance matrix of the distribution. Note that this can be computed from the correlation matrix in homogeneous coordinates since the mean values are included in that case.

Returns:

<(z-)*(z-)^T> = - *^T

phaseMean

public PhaseVector phaseMean()

Return the phase space coordinates of the centroid in homogeneous coordinates

Returns:

= (, , , , , , 1)^T

stateResponse

@Deprecated
public PhaseMatrix stateResponse(java.lang.String elemFrom,
                                             java.lang.String elemTo)

Deprecated. This calculation should be done using the utility class xal.tools.beam.calc.CalculationsOnMachines

Returns the state response matrix calculated from the front face of elemFrom to the back face of elemTo. This is a convenience wrapper to the real method in the trajectory class

Parameters:

elemFrom - String identifying starting lattice element

elemTo - String identifying ending lattice element

Returns:

response matrix from elemFrom to elemTo

See Also:

EnvelopeTrajectory#computeTransferMatrix(String, String)

createProbeState

public EnvelopeProbeState createProbeState()

Creates a snapshot of the current state and returns it as a ProbeState object of the proper type.

Specified by:

createProbeState in class BunchProbe<EnvelopeProbeState>

Returns:

a new EnvelopeProbeState encapsulating the probe's current state

See Also:

Probe.createProbeState()

createEmptyProbeState

public EnvelopeProbeState createEmptyProbeState()

Creates a new, empty EnvelopeProbeState.

Specified by:

createEmptyProbeState in class BunchProbe<EnvelopeProbeState>

Returns:

a new, empty EnvelopeProbeState

Since:

Jul 1, 2014

createTrajectory

public Trajectory<EnvelopeProbeState> createTrajectory()

Creates a Trajectory<EnvelopeProbeState> object of the proper type for saving the probe's history.

Specified by:

createTrajectory in class Probe<EnvelopeProbeState>

Returns:

a new, empty Trajectory<EnvelopeProbeState> for saving the probe's history

reset

public void reset()

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

Overrides:

reset in class Probe<EnvelopeProbeState>

readStateFrom

protected EnvelopeProbeState readStateFrom(DataAdaptor container)
                                    throws ParsingException

Description copied from class: Probe

Read the contents of the supplied DataAdaptor and return an instance of the appropriate Trajectory species.

Specified by:

readStateFrom in class Probe<EnvelopeProbeState>

Parameters:

container - DataAdaptor to read a Trajectory from

Returns:

a ProbeState for the contents of the DataAdaptor

Throws:

ParsingException - error encountered reading the DataAdaptor

See Also:

Probe.readStateFrom(xal.tools.data.DataAdaptor)