sim_types

At present three "sim_type"s are defined: Vector, TransferMatrix, and MomentMatrix.

sim_type=Vector

Selects use of VectorState as the state type. Elements derive from LinearElementBase.

The vector VectorState::state defaults to all zeros.

The propagation step LinearElementBase::advance multiples the an Element's transfer matrix (LinearElementBase::transfer) with the vector VectorState::state.

$\begin{eqnarray*} state = Transfer \cdot state \end{eqnarray*}$

sim_type=TransferMatrix

Selects use of MatrixState as the state type. Elements derive from LinearElementBase.

The matrix MatrixState::state defaults to an identity matrix.

The propagation step LinearElementBase::advance multiples the an Element's transfer matrix (LinearElementBase::transfer) with the matrix MatrixState::state.

$\begin{eqnarray*} State = Transfer \cdot State \end{eqnarray*}$

sim_type=MomentMatrix

Selects use of MomentState as the state type. Elements derive from MomentElementBase

MomentState has several components. A single reference Particle MomentState::ref as well has several members which held as arrays over the number of charge states. MomentState::real hold a Particle for each charge state. MomentState::moment0 and MomentState::moment1 hold an array of vectors and matricies.

The members MomentState::moment0_env, MomentState::moment1_env, MomentState::moment0_rms are derived from MomentState::moment0 and MomentState::moment1 in MomentState::calc_rms().

A Particle holds several independent member: Particle::IonQ, Particle::IonZ, Particle::IonEs, Particle::IonEk, and Particle::phis. The remaining members are derived from IonEk and IonEs by Particle::recalc().

Each MomentElementBase holds an array of transfer matrices (MomentElementBase::transfer). One for each charge state.

The propagation step MomentElementBase::advance() multiples the an Element's transfer matrix (MomentElementBase::transfer) with the matrix MomentState::state, and also by the vector MomentState::moment0.

$\begin{eqnarray*} Moment1_n &=& Transfer_n \cdot Moment1_n \cdot Transfer_n^t \\ moment0_n &=& Transfer_n \cdot moment0_n \end{eqnarray*}$

Specializations of advance() exist for the rf cavity and charge stripper elements:

transfer matrix caching

MomentElementBase::transfer can be viewed as a linear approximation around the given reference and real Particle. As long as the approximation remains valid, the previously computed (cached) transfer matrix can be reused.

The method MomentElementBase::check_cache determines if the cached transfer matrices, and output Particles can be reused. It works by comparing MomentElementBase::last_ref_in and MomentElementBase::last_real_in with MomentState::ref and MomentState::real.

If check_cache() returns true, then ref and real are overwritten with MomentElementBase::last_ref_out and MomentElementBase::last_real_out. If not, then MomentElementBase::recompute_matrix() is called, then ref and real are copied into last_ref_out and last_real_out.

Note: As a debugging/troubleshooting aid, setting the Config parameter 'skipcache' to a non-zero value will force check_cache() to return false. This will for recalculation of transfer matricies on each iteration.

MomentState configuration

The members of MomentState are configured from a number of input Config parameters. Several "magic" parameters control initialization of either 0, 1, or many charge states depending on the presense of the parameters "IonChargeStates" and "cstate".

If neither is included, an empty Config will initialize a MomentState with zero charge states. Such a MomentState is only useful in conjunction with the source element type .

If only "IonChargeStates" is given, it must be an array of floating point values. This will initalize a number of charge states equal to the length of "IonChargeStates".

# initialize two charge states with a source element in a lattice file
S: source, IonChargeStates= [33.0/238.0, 34.0/238.0],
           NCharge        = [10111.0, 10531.0],
           IonEs = 931.49432e6,
           IonEk = 0.5e6,
           vector_variable = "vecname",
           matrix_variable = "matname",
           vecname0 = [ ... 7 values ... ],
           vecname1 = [ ... 7 values ... ],
           matname0 = [ ... 49 values ... ],
           matname1 = [ ... 49 values ... ];
# in python
M = Machine(...)
S = M.allocState({
    'IonChargeStates':[33.0/238.0, 34.0/238.0],
    'NCharge': [10111.0, 10531.0],
    'IonEs': 931.49432e6,
    'IonEk': 0.5e6,
    'vector_variable': "vecname",
    'matrix_variable': "matname",
    'vecname0': [ ... 7 values ... ],
    'vecname1': [ ... 7 values ... ],
    'matname0': [ ... 49 values ... ],
    'matname1': [ ... 49 values ... ],
})

As a debugging/development aid, if the parameter 'cstate' is set to a value in the range [0, # of change states), the the simulation will only be initialized for a single selected change state.

Element Types

This section lists all element types, and lists which "sim_type"s each is defined for.

source

The purpose of the "source" element is to overwrite the State.

Each instance holds an internal State. The advance() method simply assigns this internal State to the state being propagate()d.

The parameters accepted are the same as the associated State type.

sim_type = "Vector";
elemname: source, initial = [0, 0, 0, 0, 0, 0, 0];
sim_type = "TransferMatrix";
elemname: source, initial = [1, 0, 0, 0, 0, 0, 0,
                             0, 1, 0, 0, 0, 0, 0,
                             0, 0, 1, 0, 0, 0, 0,
                             0, 0, 0, 1, 0, 0, 0,
                             0, 0, 0, 0, 1, 0, 0,
                             0, 0, 0, 0, 0, 1, 0,
                             0, 0, 0, 0, 0, 0, 1];

drift

A drift section.

Name	Default	Desc.
L	None	Length

Supported by all "sim_type"s.

elemname: drift, L = 0.1;

marker

Equivalent to a zero length drift section. No parameters.

Supported by all "sim_type"s.

elemname: marker;

sbend

Sector bend magnet.

Name	Default	Desc.
L	None	Length
phi	None	Bend angle
phi1	None	??? angle
phi2	None	??? angle
K	0.0	Strength
bg	None	Reference energy (beta*gamma)

Supported by all "sim_type"s. Only MomentMatrix uses phi1, phi2, and bg.

# general
elem1: sbend, L = 0.1, phi = pi/16, K = 10;
# MomentMatrix
elem2: sbend, L = 0.060000, phi = -1.000000, phi1 = 0.000000, phi2 =  0.000000, bg = 0.190370;

quadrupole

Magnetic quadrupole.

Name	Default	Desc.
L	None	Length
K	0.0	Strength. K>0 focusing in horizontal. K<0 focusing in vertical.
B2	None	Field. B2>0 focusing in horizontal. B2<0 focusing in vertical.

Supported by all "sim_type"s. MomentMatrix uses B2, others use K.

# general
elem1: quadrupole, L = 0.1, K = 10;
# MomentMatrix
elem2: quadrupole, L = 0.250000, B2 = 3.459800, aper = 0.025000;

solenoid

Solenoid magnet.

Name	Default	Desc.
L	None	Length
K	0.0	Strength.
B	None	Field

Supported by all "sim_type"s. MomentMatrix uses B, others use K.

elemname: solenoid, L = 0.1, K = 10;

rfcavity

Name	Default	Desc.
L	None	Length
cavtype	None	Cavity type ID string
Eng_Data_Dir	None	Directory containing data files
f	None	Cavity frequency (Hz)
phi	None	Synchrotron phase (rad)
scl_fac	None	Electric field scale factor
MpoleLevel	"2"	"0", "1", or "2"

stripper

Placeholder. Equivalent to marker.

edipole

Placeholder. Equivalent to marker.

generic

Element for which transfer matrix is directly specified.

Name	Default	Desc.
transfer	None	Flattened transfer matrix

Supported by all "sim_type"s.

elemname: generic, transfer = [1, 0, 0, 0, 0, 0, 0,
                               0, 1, 0, 0, 0, 0, 0,
                               0, 0, 1, 0, 0, 0, 0,
                               0, 0, 0, 1, 0, 0, 0,
                               0, 0, 0, 0, 1, 0, 0,
                               0, 0, 0, 0, 0, 1, 0,
                               0, 0, 0, 0, 0, 0, 1];