xal.extension.twissobserver

Class TransferMatrixGenerator

java.lang.Object

xal.extension.twissobserver.TransferMatrixGenerator

public class TransferMatrixGenerator
extends java.lang.Object

Class for generating transfer matrices for the XAL accelerator beamlines. For economic reasons the simulation is first run using methods generateWithoutSpaceCharge() for the zero-current case or generateWithSpaceCharge(double, double, CovarianceMatrix) for the finite beam current case. Once the simulation is completed transfer matrices between any two beamline elements may be retrieved with the method retrieveTransferMatrix(String, String). Note that when space charge is present an initial covariance matrix for the beam must be supplied. The matrix describes the beam sizes at the entrance to the beamline.

Since:

June 8, 2012

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TransferMatrixGenerator.SYNC Enumeration set representing the possible synchronization modes of the Scenario class.

Constructor Summary

Constructors

Constructor and Description
TransferMatrixGenerator(AcceleratorSeq smfSeq) Creates a new TransferMatrixGenerator object using the given sequence, and synchronizes to the design parameters.
TransferMatrixGenerator(AcceleratorSeq smfSeq, long lngPvLogId) Creates a new TransferMatrixGenerator object using the given sequence, initializes the model to the historical machine state identified by the given PV Logger ID.
TransferMatrixGenerator(AcceleratorSeq smfSeq, TransferMatrixGenerator.SYNC enmSyn) Creates a new TransferMatrixGenerator object using the given accelerator (XML definition file) accelerator, the given sequence, and the given synchronization mode.

Method Summary

Modifier and Type	Method and Description
void	generateWithoutSpaceCharge() Generates all the transfer matrices for the zero-current case.
void	generateWithSpaceCharge(double dblBnchFreq, double dblBeamCurr, CovarianceMatrix matInitState) Generates all the transfer matrices including space charge effects.
void	generateWithSpaceCharge(java.lang.String strDevIdStart, double dblBnchFreq, double dblBeamCurr, CovarianceMatrix matInitState) Generates all the transfer matrices when there are significant space charge effects.
PhaseMatrix	retrieveTransferMatrix(java.lang.String strElemStop) Compute and return the transfer matrix from the beginning of the current accelerator sequence to the entrance of the given element.
PhaseMatrix	retrieveTransferMatrix(java.lang.String strElemStart, java.lang.String strElemStop) Compute and return the transfer matrix from the entrance of the given starting element to the entrance of the given stop element (within the current accelerator sequence).
void	setSynchronizationMode(TransferMatrixGenerator.SYNC enmSync) Sets the source of hardware parameters for the simulations.
void	setSyncToMachineHistory(long lngPvLogId) Synchronizes to the machine parameters at the time of the given PV logger snapshot ID.

Methods inherited from class java.lang.Object

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

Constructor Detail

TransferMatrixGenerator

public TransferMatrixGenerator(AcceleratorSeq smfSeq)
                        throws ModelException

Creates a new TransferMatrixGenerator object using the given sequence, and synchronizes to the design parameters.

Parameters:

smfSeq - the desired sequence for transfer matrix computation

Throws:

ModelException - and error occurred when instantiating the machine model

TransferMatrixGenerator

public TransferMatrixGenerator(AcceleratorSeq smfSeq,
                               long lngPvLogId)
                        throws ModelException

Creates a new TransferMatrixGenerator object using the given sequence, initializes the model to the historical machine state identified by the given PV Logger ID.

Parameters:

smfSeq - the desired sequence for transfer matrix computation

lngPvLogId - PV Logger ID of the historical machine snapshot where model parameters are taken

Throws:

ModelException - and error occurred when instantiating the machine model

TransferMatrixGenerator

public TransferMatrixGenerator(AcceleratorSeq smfSeq,
                               TransferMatrixGenerator.SYNC enmSyn)
                        throws ModelException

Creates a new TransferMatrixGenerator object using the given accelerator (XML definition file) accelerator, the given sequence, and the given synchronization mode.

Parameters:

smfSeq - the desired sequence for transfer matrix computation

enmSyn - source of machine parameters

Throws:

ModelException - and error occurred when instantiating the machine model or a component

Method Detail

setSynchronizationMode

public void setSynchronizationMode(TransferMatrixGenerator.SYNC enmSync)
                            throws SynchronizationException

Sets the source of hardware parameters for the simulations. The given synchronization mode determines where this parameters are taken from (e.g., the live machine, the design parameters, etc.). It is also possible to synchronize the hardware parameters to a historical machine state with a know PV Logger ID (see setSyncToMachineHistory(long)).

Parameters:

enmSync - synchronization mode determining parameter source

Throws:

SynchronizationException - general error during model synchronization

Since:

Jul 19, 2012

setSyncToMachineHistory

public void setSyncToMachineHistory(long lngPvLogId)
                             throws SynchronizationException

Synchronizes to the machine parameters at the time of the given PV logger snapshot ID. The transfer matrices provided will be from this machine state.

Parameters:

lngPvLogId - PV Logger ID for the historical machine state

Throws:

SynchronizationException - general error during model synchronization

Since:

Jul 19, 2012

generateWithoutSpaceCharge

public void generateWithoutSpaceCharge()
                                throws ModelException

Generates all the transfer matrices for the zero-current case. The model is run using a transfer map probe which only collects machine data.

NOTE:

· This simulation always starts with the first element in the sequence since the transfer matrices are not dependent upon beam state.

Throws:

ModelException - general error during model synchronization or simulation

Since:

Jul 26, 2012

generateWithSpaceCharge

public void generateWithSpaceCharge(double dblBnchFreq,
                                    double dblBeamCurr,
                                    CovarianceMatrix matInitState)
                             throws ModelException

Generates all the transfer matrices including space charge effects. The simulation is performed with the given bunch charge and the initial beam state at the entrance to the associated accelerator sequence.

This methods is a direct proxy to #generateWithSpaceCharge(String, double, CovarianceMatrix) using null as the first argument.

NOTE

· Bunch charge (the target parameter) is given by beam current divided by bunch frequency.

Parameters:

dblBnchFreq - bunch arrival frequency (in Hz)

dblBeamCurr - beam current (in Amperes)

matInitState - initial state of the beam, initial covariance matrix

Throws:

ModelException - general error during model synchronization or simulation

Since:

Mar 28, 2013

See Also:

#generateWithSpaceCharge(String, double, CovarianceMatrix)

generateWithSpaceCharge

public void generateWithSpaceCharge(java.lang.String strDevIdStart,
                                    double dblBnchFreq,
                                    double dblBeamCurr,
                                    CovarianceMatrix matInitState)
                             throws ModelException

Generates all the transfer matrices when there are significant space charge effects. The simulation is performed with the given bunch charge and the initial beam state at the given element location. Thus, the given probe state corresponds to the given element.

There is a self-consistency issue between the space charge effects and the beam size. Thus, the transfer matrices will typically be different for different starting configurations of the beam.

NOTE:

· Bunch charge Q is given by beam current I divided by bunch frequency f. Specifically, Q = I/f.

Parameters:

strDevIdStart - ID of device with which to start the simulation, or null for the beginning of the sequence

dblBnchChg - beam bunch charge in Coulombs

matInitState - initial state of the beam, initial covariance matrix

Throws:

ModelException - general error during model synchronization or simulation

Since:

Jul 26, 2012

retrieveTransferMatrix

public PhaseMatrix retrieveTransferMatrix(java.lang.String strElemStop)
                                   throws java.lang.IllegalStateException

Compute and return the transfer matrix from the beginning of the current accelerator sequence to the entrance of the given element. This method is viable only after a call to methods generateWithoutSpaceCharge() or #generateWithSpaceCharge(String, double, CovarianceMatrix).

Parameters:

strElemStop - string identifier of the terminal element

Returns:

beam optics transfer matrix for the beam line up to the given element

Throws:

java.lang.IllegalStateException - The transfer matrices have not been generated yet

Since:

Jul 27, 2012

See Also:

generateWithoutSpaceCharge(), #generateWithSpaceCharge(String, double, CovarianceMatrix)

retrieveTransferMatrix

public PhaseMatrix retrieveTransferMatrix(java.lang.String strElemStart,
                                          java.lang.String strElemStop)
                                   throws java.lang.IllegalStateException

Compute and return the transfer matrix from the entrance of the given starting element to the entrance of the given stop element (within the current accelerator sequence). This method is viable only after a call to methods generateWithoutSpaceCharge() or #generateWithSpaceCharge(String, double, CovarianceMatrix).

Parameters:

strElemStart - string identifier of the starting element

strElemStop - string identifier of the terminal element

Returns:

beam optics transfer matrix for the beam line up to the given element

Throws:

java.lang.IllegalStateException - The transfer matrices have not been generated yet

Since:

Jul 18, 2012

See Also:

generateWithoutSpaceCharge(), #generateWithSpaceCharge(String, double, CovarianceMatrix)