An Individualized Linear Matrix for each particle for fast symplectic tracking with chromatic and
amplitudedependent effects
Parallel capable? : yes
GPU capable? : no
Backtracking capable? : no
Parameter Name  Units  Type  Default  Description 
L  M  double  0.0  Length (used for position and timeofflight computation) 
NUX  double  0.0  Horizontal tune  
NUY  double  0.0  Vertical tune 

NUX1M  double  0.0  First chromatic derivative of the horizontal tune 

NUY1M  double  0.0  First chromatic derivative of the vertical tune 

NUX2M  double  0.0  Second chromatic derivative of the horizontal tune 

NUY2M  double  0.0  Second chromatic derivative of the vertical tune 

NUX3M  double  0.0  Third chromatic derivative of the horizontal tune 

NUY3M  double  0.0  Third chromatic derivative of the vertical tune 

NUX1AX  1∕M  double  0.0  First amplitude derivative of the horizontal tune wrt Ax 
NUY1AX  1∕M  double  0.0  First amplitude derivative of the vertical tune wrt Ax 
NUX1AY  1∕M  double  0.0  First amplitude derivative of the horizontal tune wrt Ay 
NUY1AY  1∕M  double  0.0  First amplitude derivative of the vertical tune wrt Ay 
NUX2AX  1∕M^{2}  double  0.0  Second amplitude derivative of the horizontal tune wrt Ax 
NUY2AX  1∕M^{2}  double  0.0  Second amplitude derivative of the vertical tune wrt Ax 
NUX2AY  1∕M^{2}  double  0.0  Second amplitude derivative of the horizontal tune wrt Ay 
NUY2AY  1∕M^{2}  double  0.0  Second amplitude derivative of the vertical tune wrt Ay 
ILMATRIX continued
An Individualized Linear Matrix for each particle for fast symplectic tracking with chromatic and
amplitudedependent effects
Parameter Name  Units  Type  Default  Description 
NUX1AX1AY  1∕M^{2}  double  0.0  Amplitude derivative of the horizontal tune wrt Ax and Ay 
NUY1AX1AY  1∕M^{2}  double  0.0  Amplitude derivative of the vertical tune wrt Ax and Ay 
BETAX  M  double  0.0  Onmomentum horizontal beta function 
BETAY  M  double  0.0  Onmomentum vertical beta function 
BETAX1M  M  double  0.0  First chromatic derivative of horizontal beta function 
BETAY1M  M  double  0.0  First chromatic derivative of vertical beta function 
ALPHAX  double  0.0  Onmomentum horizontal alpha function 

ALPHAY  double  0.0  Onmomentum vertical alpha function 

ALPHAX1M  double  0.0  First chromatic derivative of horizontal alpha function 

ALPHAY1M  double  0.0  First chromatic derivative of vertical alpha function 

ETAX  M  double  0.0  Onmomentum horizontal eta function 
ETAPX  double  0.0  Onmomentum horizontal eta’ function 

ETAY  M  double  0.0  Onmomentum vertical eta function 
ETAPY  double  0.0  Onmomentum vertical eta’ function 

ETAX1  M  double  0.0  First chromatic derivative of horizontal eta function 
ETAPX1  double  0.0  First chromatic derivative of horizontal eta’ function 

ETAY1  M  double  0.0  First chromatic derivative of vertical eta function 
ETAPY1  double  0.0  First chromatic derivative of vertical eta’ function 

ILMATRIX continued
An Individualized Linear Matrix for each particle for fast symplectic tracking with chromatic and
amplitudedependent effects
Parameter Name  Units  Type  Default  Description 
ALPHAC  double  0.0  Firstorder momentum compaction factor 

ALPHAC2  double  0.0  Secondorder momentum compaction factor 

ALPHAC3  double  0.0  Thirdorder momentum compaction factor 

DS1AX  double  0.0  First amplitude derivative of the path length wrt Ax 

DS1AY  double  0.0  First amplitude derivative of the path length wrt Ay 

DS2AX  1∕M  double  0.0  Second amplitude derivative of the path length wrt Ax 
DS2AY  1∕M  double  0.0  Second amplitude derivative of the path length wrt Ay 
DS1AX1AY  1∕M  double  0.0  Amplitude derivative of the path length wrt Ax and Ay 
TILT  RAD  double  0.0  Rotation angle about the longitudinal axis. 
CROSS_RESONANCE  short  0  If zero, then particles that cross an integer or halfinteger resonance are considered lost. 

VERBOSITY  short  0  If nonzero, then information about particle losses is printed out. 

GROUP  string  NULL  Optionally used to assign an element to a group, with a userdefined name. Group names will appear in the parameter output file in the column ElementGroup 

This element allows fast, symplectic tracking of transport through a periodic cell with chromatic and amplitudedependent tunes, beta functions, and dispersion. This is done by computing a linear matrix for every particle using Twiss parameters, tunes, dispersion, etc., supplied by the user. The user can also supply selected chromatic and amplitude derivatives of these quantities, which are used to compute the individual particle’s beta functions, tune, dispersion, etc., which in turn allows computing the individual particle’s linear matrix.
The starting point is the wellknown expression for the oneturn linear matrix in terms of the lattice functions
 (54) 
where ν_{q} is the tune in the q plane. We can expand the quantities in the matrix using
 (55) 
where δ = (pp_{0})∕p_{0} is the fractional momentum offset, A_{q} = (q_{β}^{2} + (α_{q}q_{β} + β_{q}q_{β}^{′})^{2})∕β_{q} is the betatron amplitude, and the betatron coordinates are computed using
 (56) 
and
 (57) 
At each turn, δ, A_{x}, and A_{y} are computed for each particle. The usersupplied values of the various derivatives are then used to compute the tunes for each particle. Similar expansions are used to compute the other lattice functions. This allows computing the 2x2 transfer matrices for the betatron coordinates in the x and planes, then advancing the betatron coordinates one turn, after which the full coordinates are recomputed by adding back the momentumdependent closed orbit.
The pathlength is computed using the expansion
 (58) 
where α_{c,1} is the linear momentum compaction factor. Note that in keeping with convention the higherorder momentum compaction is expressed by polynomial coefficients, not derivatives. The terms dependent on betatron amplitude are expressed in terms of the more typical derivatives. Note the difference between the R_{5n} terms (added in version 2019.4) and those dependent on A_{x,y}: the former are oscillatory while the latter will accumulate. The frequency_map command can be used to compute pathlength dependence on betatron amplitude.
Using this element is very similar to using the setup_linear_chromatic_tracking command. The advantage is that using LMATRIX, one can split a ring into segments and place, for example, impedance elements between the segments.
This element was inspired by requests from Y. Chae (APS).
N.B.: There is a bug related to using ILMATRIX that will result in a crash if one does not request computation of the twiss parameters. If you encounter this problem, just add the following statement after the run_setup command:
IONEFFECTS