Welcome to SAD/FFS & SADScript
The FFS commands are shown in uppercases. The minimum abbreviated form
of each command is enclosed in (). Down to that form each command can be
shorten. The optional arguments for the commands are usually enclosed in
[].
ABORT
APPEND(APP)
ATTRIBUTE(ATTR)
BYE
commandsyntax
components
CALCULATE(CAL)
CHROMATICITY(CHRO)
CLOSE(CLO)
COUPLE(COUP)
DISPLAY(DISP)
ACCELERATION(A)
ALL
BEAM(B)
DUMPOPTICS(D)
GEOMETRY(G)
OGEOMETRY(OG)
ORBIT(O)
patternstring
PHYSICAL(P)
region
RMATRIX(R)
DRAW
DUMP
elements
APERT
BEND
AE1
AE2
ANGLE
DISFRIN
DISRAD
DROTATE
DX
DY
E1
E2
F1
FB1
FB2
FRINGE
K0
K1
L
ROTATE
transformation
CAVI
DISFRIN
DPHI
DX
DY
FREQ
HARM
L
PHI
ROTATE
V02
V1
V11
V20
VOLT
COORD
defaultkeyword
DECA
DISFRIN
DISRAD
DX
DY
K4
L
ROTATE
transformation
DODECA
DISFRIN
DISRAD
DX
DY
K5
L
ROTATE
transformation
DRIFT
L
RADIUS
transformation
keywords
MARK
OFFSET
MULT
AE1
AE2
ANGLE
DISFRIN
DISRAD
DPHI
E1
E2
F1
F2
FB1
FB2
FREQ
FRINGE
HARM
K0
K1
K10
K11
K12
K13
K14
K15
K16
K17
K18
K19
K2
K20
K21
K3
K4
K5
K6
K7
K8
K9
L
misalignments
multipole_with_nonzero_ANGLE
PHI
RADIUS
SK0
SK1
SK10
SK11
SK12
SK13
SK14
SK15
SK16
SK17
SK18
SK19
SK2
SK20
SK21
SK3
SK4
SK5
SK6
SK7
SK8
SK9
VOLT
OCT
DISFRIN
DISRAD
DX
DY
K3
L
ROTATE
transformation
QUAD
DISFRIN
DISRAD
DX
DY
F1
F2
FRINGE
K1
L
ROTATE
transformation
SEXT
DISFRIN
DISRAD
DX
DY
K2
L
ROTATE
transformation
SOL
BOUND
BZ
DISFRIN
DPX
DPY
DX
DY
F1
GEO
expressions
()
(/)
AddTo(+=)
Alternatives()
And(&&)
Apply(@@)
CompoundExpression(;)
Decrement()
DivideBy(/=)
Dot(.)
Equal(==)
Function(&)
Greater(>)
GreaterEqual(>= or =>)
Increment(++)
Less(<)
LessEqual(<= or =<)
List({})
Map(/@)
MapAll(//@)
Member(@)
MessageName(::)
Not(~)
Or()
Part([[]])
PatternTest(?)
Plus(+)
Power(^)
Repeated(..)
RepeatedNull(...)
ReplaceAll(/.)
ReplaceRepeated(//.)
Rule(>)
RuleDelayed(:>)
SameQ(===)
Sequence([])
Set(=)
SetDelayed(:=)
StringJoin(//)
SubtractFrom(=)
TagSet(/:)
Times(*)
TimesBy(*=)
Unequal(<>)
UnsameQ(<=>)
Unset(=.)
extendedTwissparameters
definitions
ELSE
ELSEIF
EMITTANCE(EMIT)
END
ENDIF
EXECUTE(EXEC)
flags
ABSW
BIPOL
CELL
CMPLOT
COD
CODPLOT
CONV
CONVCASE
DAMPONLY
DAPERT
EMIOUT
FFSPRMPT
FIXSEED
FLUC
GAUSS
GEOCAL
GEOFIX
IDEAL
INS
INTRA
JITTER
LWAKE
MOVESEED
PHOTONS
PRSVCASE
PSPAC
QUIET
RAD
RADCOD
RADLIGHT
REAL
RELW
RFSW
RING
SELFCOD
SPAC
STABLE
TRPT
TWAKE
UNIFORM
UNIPOL
UNSTABLE
WSPAC
functions
Beamlinefunctions
BeamLine
BeamLineName
ExtractBeamLine
PrintBeamLine
WriteBeamLine
DataManipulation
Fit
PolynomialFit
Spline
NIntegrate
DownhillSimplex
FFSdedicatedfunctions
AccelerateParticles
BeamMatrix
DynamicApertureSurvey
Element
keystrings
Emittance
ExternalMap
FFS
FitValue
FitWeight
GeoBase
LINE
keystrings
OptimizeOptics
OrbitGeo
RadiationField
RadiationSpectrum
SetElement
SurvivedParticles
SymplecticJ
SynchroBetaEmittance
TouschekLifetime
TrackParticles
Twiss
VariableRange
VariableWeight
WakeFunction
Functionaloperations
Difference
FixedPoint
FixedPointList
SelectCases
SwitchCases
Graphics
ListPlot
ColumnPlot
HistoPlot
ListContourPlot
ListDensityPlot
GeometryPlot
BeamPlot
OpticsPlot
FitPlot
Plot
Multiprocessing
Fork
OpenShared
Shared
SharedSize
Objectorientedprograming
Class
Randomnumberfunctions
Random
GaussRandom
ParabolaRandom
SeedRandom
ListRandom
Systeminterface
System
TemporaryName
Utilities
DateString
FIT
FITPOINTS(FITP)
FIX
FREE
defaultkeyword
geometricalfunctions
GEO
GO
IF
INPUT(IN)
machineerrorcommands
matchingfunctioncommands
multiturntracking
MATRIX(MAT)
MEASURE(MEA)
offmomentummatching
opticalfunctions
OUTPUT(OUT)
PRINT(PRI)
QUIT
RADINT
READ
RECOVER(REC)
REJECT(REJ)
REPEAT(REP)
RESET
REVERSE(REV)
setvalueofelement
keywords
defaultkeyword
specialsymbols
specialvariables
$FORM
CASE
CHARGE
CONVERGENCE
DAPWIDTH
DP
DP0
DTSYNCH
EFFVCRATIO
ElementValues
EMITX
EMITXE
EMITY
EMITYE
EMITZ
EMITZE
FFS$NumericalDerivative
FitFunction
FSHIFT
GCUT
InitialOrbits
LOSSAMPL
LOSSDZ
MatchingAmplitude
MatchingResidual
MASS
MINCOUP
MOMENTUM
NBUNCH
NetResidual
NP
OffMomentumWeight
OMEGA0
OpticsEpilog
OpticsProlog
PageWidth
PBUNCH
PhotonList
PHICAV
SpeedOfLight
StabilityLevel
STACKSIZ
TITLE
SAVE
SEED
SHOW
SPLIT
STATUS(STAT)
STOP
TDR
TERMINATE(TERM)
TYPE(T)
UNTIL
USE
VARIABLES(VAR)
VARY
VISIT
wildcards
xycoupling
Stops SAD immediately.
APP {filename  filenumber} switches the output stream to the specified
file or the file number. The output is appended to the existing file.
Usage: ATTR elementpattern
prints out the current value, minimum and maximum values, COUPLEd element
and its coefficient for elements which match the elementpattern.
Exits from the current beam line and returns to the original beam line
where VISIT command was issued. All information specific to the beam line,
such as matching conditions are restored.
Note that BYE does neither SAVE the values of elements of the leaving
beam line, nor RESET the values of elements of the returning beam line.
The command syntax in FFS is
expression1 [param1..] [;] expression2..
(1) The input is first evaluated as an expression. If the expression
returns a Symbol with the same name as the expression itself, it is
interpreted as an FFS command, otherwise the returned value is printed
out unless it is Null.
(2) Each command takes succeeding its parameters if necessary. A command with
indefinite number of parameters can be terminated by semicolon.
Most commands terminate itself at the end of line.
(3) A line can be continued to the next line if a backslash is placed at the
end of the line.
(4) An expression continues to the next line if it is not closed in the line.
(5) An exclamation mark comments out the rest of the line.
Example: A command line
QF* .1
means the setvalueofelement command as unless the symbol QF has been defined otherwise.
If QF has been defines as a number, such as QF=2.5, the above command line
is interpreted as Times[QF,.1] then returns .25 .
Components are the objects which consist the beam line. A component simulates
an individual magnet, drift space, or rfcavity. The parameters of a
component is specified the values in the corresponding element with the
same name as the component, which simulates a power supply. Many
components can be attached to the same element. Parameters of each
component may deviate from the corresponding element if machine errors are
given.
A component is specified with the form name[.order][{+}offset], where
name is the name of the component. The number order means the orderth
component which belongs to name element, counted from the beginning of the
line starting from 1. Offset is a positive or negative number to specify
the downstream or upstream components from the given component. If order
is omitted, the first element is assumed, and if offset is omitted, zero is
assumed.
The end of line is specified by $$$. The first component can be
specified by ^^^.
Usage: (1) CALC [[NO]EXPAND]]
(2) CALC matchingfunction1[] [matchingfunction2[]..]
(1) With no argument or with an option [NO]EXPAND, calculates the optics
and the matchingfunctions using the current values of the components.
It prints out the values of the matchingfunctions specified either by the
matchingfunctioncommands or the second usage of CALC, as described below.
If an option EXPAND is given(default), it expands the beam line before the
calculation. If NOEXPAND is given, it calculates without any expansion.
FFS["CAL"] and FFS["GO"] returns the result as a list, whose format
is
{dp, kind, reslist, functionvalues},
where
dp: a list contains dp/p0 .
kind: a list of kind of the orbit (ususally 0, but 1 to 6 for the
finite amplitude matching, see specialvariables:MatchingAmplitude).
reslist: a list of {residual, xstab, ystab}, where
residual: matching residual,
xstab: True when the matrix is stable in X,
ystab: True when the matrix is stable in Y, for each orbit.
Above are lists with length nf (== number of orbits).
functionvalues: a list of length nc (== number of calculated items). Each
element has the form:
{component1, component2, function, listofvalues},
where
component1, component2: fit locations (see FIT).
function: name of the function (see matchingfunctioncommands).
listofvalues: list of the value of the function for each orbit.
Length nf.
The central orbit comes at the Floor[(n+1)/2]th element.
(2) With matchingfuction names, sets the matchingfunctions at the current
fit point to be printed out after calculation. If the matchingfunction is
followed by a minus sign, it suppresses the printout.
Example: CALC BX BY CALC
CHRO prints out the chromaticity of QUAD and SEXT in the entire beam
line using the simplest formula:
xi_{x,y}=Integrate[(K1/L) beta_{x,y}(s) ds] for QUAD,
xi_{x,y}=Integrate[(K2/L) eta_x (s) beta_{x,y}(s) ds] for SEXT.
These formula are not valid when there is xy coupling or vertical
dispersion.
CLOSE [INPUT(IN)] closes the current input stream and switches it to
the previous input stream.
CLOSE OUTPUT(OUT) suspends the current output and switches it to the
previous output stream.
Usage: COUP slaveelement masterelement coefficient
sets the value of the defaultkeyword of slaveelement to be equal to
coefficient times the value of the defaultkeyword of masterelement.
COUPLE(COUP) cannot be cascaded. The masterelement cannot be COUPLEd to
any other element. To reset COUPLE, say COUP slaveelement slaveelement 1.
Usage: DISP_LAY [keywords] [patternstring] [region]
Displays values of various optical/geometricfunctions at the components
given by the patternstring in the region (see region) in the current beam
line.
It has several display modes specified by the keywords. As the default,
it displays AX, BX, NX, EX, EPX, AY, BY, NY, EY, EPY, LENG, the length and
the value of the defaultkeyword of the component.
Each line refers to the entrance of each component of the line.
The end of the beam line has the name "$$$". The first component can be
specified by "^^^".
DISP does not calculate the functions to be displayed, so CALCULATE(CALC)
is necessary whenever values of components are updated.

DISP A displays the nominal energy, energy deviation(DDP), longitudinal
position(z), and emittances for a transport line with accelerating cavities.
The flag TRPT must be on.

ALL is a word to choose the entire beam line for the region to be displayed.

DISP B displays the beam sizes and the projected Twiss parameters,
calculated either by the BEAMSIZE(BEAM) command or the EMIT command with
the CODPLOT flag.
Example: EMITX=...; EMITY=...;DP=...;
BEAMSIZE(BEAM)
DISP B

DISP D displays all matchingfunctions in one line
suitable to be read by a spreadsheet program.

DISP G displays geometric information of the beam line.
It shows the geometry at the coordinate, except for a SOL region,
where the geometry at the orbit is shown.

DISP OG displays geometric information at the orbit.

DISP O displays the orbits DX, DPX, DY, DPY together with the other
opticalfunctions.

The components in the current region can be selectively displayed
by the DISP command using the patternstring. The patternstring is a
character string involving the wildcards to match the name of the components.
Note that the components are chosen in the current region, and the keyword
ALL is necessary to extend it to the entire beam line.

DISP P displays the physical dispersions PEX, PEPX, PEY, PEPY,
together with the 1D optical parameters.

Region for DISPLAY(DISP) is specified as
DISP .... begin [end]
with begin and end having the form name[.order][{+}offset] (see components).
Example: DISP ... QF.210 QD+5
displays functions starting at 10 elements upstream from the entrance of the
second QF through 5 elements downstream from the entrance of the first QD.
The region for DISP is kept after once set It is shown in the second part
of the prompt when FFSPRMPT is ON, and also seen by the STATUS(STAT)
command.
The components which match the patternstring in DISP are only chosen in
the current region.

DISP R displays the components of the xy coupling matrix R
together with the 1D optical parameters. See xycoupling.
Usage: DRAW [begin end] fun1 [fun2..] [& fun11 [fun12..]] [elementpattern]
prints out the TopDrawer commands of the plots of functions fun1...
Available functions are all matchingfunctions (except LENG, TRX, TRY, GX,
GY, GZ, CHI1, CHI2, CHI3) and additional functions. If functions are
separated by ampersand (&), these are plotted in a separated window.
If begin and endcomponents are specified, the plot region is limited
between them. If the endcomponent comes earlier than the
begincomponents, it wraps the plot around the beam line.
If the optional elementpattern is given, it draws the beamline lattice
with the labels for elements which match elementpattern. If LAT is
specified for elementpattern, the lattice is drawn without label.
Usage: DUMP componentpattern [compnentpattern1..]
prints out the current machine errors of components which match component
pattern.
An element in FFS represents an object which has a unique name and
several keywords with values. This simulates a power supply of a magnet.
An element has one or more components, which correspond to individual
magnets in a beam line. Each component may have different values from
the values of the corresponding element. This simulates the machine error
which varies magnet to magnet.
The value of an element can be saved to or recovered from the
elementsavebuffer by SAVE or RESET commnads. Different beam lines can
share the same element, and their values can be different to each other,
but they have the common elementsavebuffer. Therefore the value of an
element can be transferred between beam lines by SAVE and RESET command
through the elementsavebuffer.
An element is created only in SAD MAIN level. In the definition, if a
keyword is omitted, the previous definition is unchanged. All keywords have
the default value zero. In FFS, it is only possible to change their values.

An aperture. Only valid in tracking. A particle with
(x  DX)^2/AX^2 + (y  DY)^2/AY^2 < 1 &&
Min[DX1, DX2] < x < Max[DX1, DX2] &&
Min[DY1, DY2] < y < Max[DY2, DY2]
can pass through the aperture, otherwise it is lost and a message
is printed out. If AX or AY is zero (default), they are interpreted as
infinity. If AX <=> 0 && AY <=> 0 and (DX1 == DX2 or DY1 == DY2) then
the aperture is only determined by AX and AY.

A bending magnet.

The absolute face angle at the entrance.
The effective face angle is E1 * ANGLE + AE1, and a positive
angle at the entrance corresponds to a surface with dx/ds > 0.

The absolute faceangle at the exit to the bending angle.
The effective face angle is E2 * ANGLE + AE2, and a positive
angle at the exit corresponds to a surface with dx/ds < 0.

The bending angle. If positive, it bends the orbit in xs plane toward
negativexdirection. ANGLE determines the geometry of the beam line,
while K0 represents a dipole kick on top of the bending angle given by
ANGLE, i.e., the total deflection of the beam is given of ANGLE + K0.

If nonzero, the nonlinear Maxwellian fringe is suppressed.

If nonzero, the synchrotron radiation in the particletracking is inhibited.

Additional rotation in xy plane to simulate a rotation error.
DROTATE does not afgfect the geometry of the ring.

Horizontal displacement of magnet. This applied before the rotation by
ROTATE.

Vertical displacement of magnet. This applied before the rotation by
ROTATE.

The ratio of the faceangle at the entrance to the bending angle.
The effective face angle is E1 * ANGLE + AE1, and a positive
angle at the entrance corresponds to a surface with dx/ds > 0.
For example, a symmetricallyplaced rectangular magnet has
E1 = 0.5 and E2 = 0.5.

The ratio of the faceangle at the exit to the bending angle.
The effective face angle is E2 * ANGLE + AE2, and a positive
angle at the exit corresponds to a surface with dx/ds < 0.
For example, a symmetricallyplaced rectangular magnet has
E1 = 0.5 and E2 = 0.5.

Length of the slope of the field at the edge as:
By(s)  *******
 *
 *
*
*
*
* 
* 
*******+ s
 
<>
 F1 
Only the effects up to y^4 in Hamiltonian are taken into account.
More rigorous definition is
F1 = 6 Integrate[By(s)/B0  (By(s)/B0)^2, {s, Inf, Inf}] ,
where integration is done over one fringe.
The transformation of the linear fringe of the entrance of a bend is
exp(:V:), V = f^2/rhob px/p/24  f/rhob^2 y^2/p/12
+ 1/rhob^2/f y^4/p/6 ,
where f is the length of fringe given by F1, and rhob bending radius
at the design momentum. At the exit, the sign of rhob is changed.
This linear fringe also changes the path length in the body of the bend as
l'=l(phi0 f)^2/l/24 Sin[(phi0(1E1E2)AE1AE2)/2]/Sin[phi0/2]
to maintain the geometric position of the design orbit, i.e., you have to
increase the bend field a little bit to keep the orbit unchanged. Unlike a
quadrupole, the effect of linear fringe is always applied at both the
entrance and the exit, otherwise you cannot obtain a circular design orbit.
Use FB1 and FB2 to specify the values of entrance and exit separately.

F1 at the entrance. Actually F1 + FB1 is used at the entrance.

F1 at the exit. Actually F1 + FB2 is used at the exit.

When FRINGE is nonzero, the effect of the linear fringe F1 is taken into
account both at the entrance and the exit.
The transformation of the linear fringe of the entrance of a bend is
exp(:V:), V = f^2/rhob px/p/24  f/rhob^2 y^2/p/12
+ 1/rhob^2/f y^4/p/6 ,
where f is the length of fringe given by F1, and rhob bending radius
at the design momentum. At the exit, the sign of rhob is changed.
This linear fringe also changes the path length in the body of the bend as
l'=l(phi0 f)^2/l/24 Sin[(phi0(1E1E2)AE1AE2)/2]/Sin[phi0/2]
to maintain the geometric position of the design orbit, i.e., you have to
increase the bend field a little bit to keep the orbit unchanged. Unlike a
quadrupole, the effect of linear fringe is always applied at both the
entrance and the exit, otherwise you cannot obtain a circular design orbit.
Use FB1 and FB2 to specify the values of entrance and exit separately.

The normal 2pole magnetic field component (times the length L).
K0 = B^(0)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 4pole magnetic field component (times the length L).
K1 = B^(1)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

Length along the arc of the orbit.

Rotation in xy plane. After displacing the magnet by DX and DY,
rotate the magnet around the local saxis by (amount given by ROTATE),
then place the component. At the exit rotate back the magnet around
the local saxis at the exit, then take out displacement.

The transformation of a bend depends on the value of K1. If K1 is zero,
it is a series of transformations:
(kick due to rotation error)
px2 = px1 + dphix
py2 = py1 + dphiy
(drift to the entrance face)
x2 = x1/(cos(psi1)  sin(psi1) (px1/pz1))
px2 = px1 cos(psi1) + pz1 sin(psi1)
y2 = y1 + (py1/pz1) x2 sin(psi1)
z2 = z1  (p1 /pz1) x2 sin(psi1) ,
where psi1 = ANGLE * E1 + AE1;
(linear fringe at entrance face)
x2 = x1 + dxfr (p1  p0)/p1
py2 = py1 + (dyfr  dyfra y1^2) y1/p1^2
z2 = z1 + (dxfr px1 + (dyfr  dyfra y1^2/2) y1^2/(2 p1))/p1
where dxfr = F1^2/(24 rhob) ,
dyfr = F1/(6 rhob^2) ,
dyfra= 2/3 1/(F1 rhob^2) ,
rhob = L'/(ANGLE + K0) ,
L' = L  (ANGLE F1)^2 /(24 L)
* sin((ANGLE (1  E1  E2)  AE1  AE2)/2)/sin(ANGLE/2)
(nonlinear fringe at entrance)
x2 = x1 + y1^2 (1y1^2/rhob^2/12) p1^2/(2 rhob (p1^2  px1^2)^(3/2))
py2 = py1  px1 (1y1^2/rhob^2/6) y1/(p1 rhob sqrt(p1^2  px1^2))
z2 = z1  px1 y1^2 (1y1^2/rhob^2/12) p1/(2 rhob (p1^2  px1^2)^(3/2))
(body of bend)
px2 = rho0/rhob (sin(psi2) + sin(omega + psi1))
+ sin(omega) pz1 + cos(omega) px1  x1/rhob sin(omega)
x2 = x1 cos(omega) + rhob (pz2  cos(omega) pz1 + sin(omega) px1)
+ rho0 (cos(omega+psi1)  cos(psi2))
y2 = y1 + py1/sqrt(p1^2  py1^2) s
z2 = z1  s p1/sqrt(p1^2  py1^2) + v1/v0 L'
where rho0 = L'/ANGLE
omega = ANGLE  psi1  psi2
s = rhob ANGLE (arcsin(px1/sqrt(p1^2  py1^2))
 arcsin(px2/sqrt(p2^2  py2^2)) + omega)
(nonlinear fringe at exit)
x2 = x1  y1^2 (1y1^2/rhob^2/12) p1^2/(2 rhob (p1^2  px1^2)^(3/2))
py2 = py1 + px1 y1 (1y1^2/rhob^2/6)/(p1 rhob sqrt(p1^2  px1^2))
z2 = z1 + px1 y1^2 (1y1^2/rhob^2/12) p1/(2 rhob (p1^2  px1^2)^(3/2))
(linear fringe at exit face)
x2 = x1  dxfr (p1  p0)/p1
py2 = py1 + (dyfr  dyfra y1^2) y1/p1^2
z2 = z1 + (dxfr px1 + (dyfr  dyfra y1^2/2) y1^2/(2 p1))/p1  dzfr
where dzfr = dxfr * ( sin(ANGLE E1 + AE1) + sin(ANGLE E2 + AE2) )
(drift from the exit face)
px2 = cos(psi2) px1 + sin(psi2) pz1
x2 = x1 (cos(psi2) + px2/pz2 sin(psi2))
y2 = y1 + py2/pz2 x1 sin(psi2)
z2 = z1  x1 sin(psi2) p2/pz2
where psi2 = ANGLE * E2;
(kick due to rotation error)
px2 = px1 + dphix
py2 = py1 + dphiy .
If K1 is nonzero, the effects from E1 and E2 are approximated by thin
quadrupoles. Then the body is subdivided into
1 + floor(sqrt(abs(K1 L')/(12 10^5 EPS)))
pieces (EPS = 1 is used when EPS = 0), and the bendbody transformation
above is done for each piece and the kick from K1 is applied alternatively.
In FFS optics and Emittance calculations, or when the synchrotron radiation
is turned on, the same algorithm as K1 <> 0 is applied.

Accelerating structure.

If nonzero, the Maxwellian fringe is suppressed. The
effects of DISFRIN and FRINGE are summarized as
DISFRIN=0 DISFRIN<>0
FRINGE=0 entr & exit none
FRINGE=1 entr none
FRINGE=2 exit none
FRINGE=3 entr & exit none

Relative phase offset. The stable synchrotron phase above the
transition is near PHI = 0.
The acceleration is given as
dE =  e*(VOLT+V1 x+V20 x^2/2+V11 x y+V02 y^2/2)
*Sin[2 Pi FREQ (tts) + PHI + DPHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.
DPHI is not taken into account to determine the design mementum p0(s).

Horizontal displacement of magnet. This applied before the rotation by
ROTATE.

Vertical displacement of magnet. This applied before the rotation by
ROTATE.

Rf frequency. If this keyword is nonzero, the keyword HARM is ignored.
The acceleration is given by
dE =  e*(VOLT+V1 x+V20 x^2/2+V11 x y+V02 y^2/2)
*Sin[2 Pi FREQ (tts) + PHI +DPHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.
(CAVI only) The nonrelativistic corrections
VOLT*(2 Pi FREQ/c)^2/(gamma beta)^2/4 are
automatically added to V20 and V02, respectively. The Lorentz factor
is evaluated as inverse of average of 1/(beta gamma) at the entrance
and the exit.
CAVI includes the edge effect at the lowest order, given by a Hamiltonian
at the entrance edge at s0:
Hf =  (e VOLT/L)(Sin(omega t  dphi) + Sin(dphi)  offset) (x^2+y^2)/4 delta(ss0)
where dphi and offset are determined by the cavity phase and the radiation loss,
which is nonzero only in the case of NORAD. The sign flips at the exit.
This Hamiltonian should be consistent with what Kiyoshi Kubo derived.

A harmonic number. This is valid only when FREQ is zero.

Effective length.

Relative phase offset. The stable synchrotron phase above the
transition is near PHI = 0.
The acceleration is given as
dE =  e*(VOLT+V1 x+V20 x^2/2+V11 x y+V02 y^2/2)
*Sin[2 Pi FREQ (tts) + PHI + DPHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.

Rotation in xy plane. After displacing the magnet by DX and DY,
rotate the magnet around the local saxis by (amount given by ROTATE),
then place the component. At the exit rotate back the magnet around
the local saxis at the exit, then take out displacement.

The y^2dependence of the acceleration. Tracking only.
The acceleration is given by
dE =  e*(VOLT+V1 x+V20 x^2/2+V11 x y+V02 y^2/2)
*Sin[2 Pi FREQ (tts) + PHI +DPHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.
(CAVI only) The nonrelativistic corrections
VOLT*(2 Pi FREQ/c)^2/(gamma beta)^2/4 are
automatically added to V20 and V02, respectively. The Lorentz factor
is evaluated as inverse of average of 1/(beta gamma) at the entrance
and the exit.
CAVI includes the edge effect at the lowest order, given by a Hamiltonian
at the entrance edge at s0:
Hf =  (e VOLT/L)(Sin(omega t  dphi) + Sin(dphi)  offset) (x^2+y^2)/4 delta(ss0)
where dphi and offset are determined by the cavity phase and the radiation loss,
which is nonzero only in the case of NORAD. The sign flips at the exit.
This Hamiltonian should be consistent with what Kiyoshi Kubo derived.

The linear xdependence of the acceleration. Tracking only.
The acceleration is given by
dE =  e*(VOLT+V1 x+V20 x^2/2+V11 x y+V02 y^2/2)
*Sin[2 Pi FREQ (tts) + PHI +DPHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.
(CAVI only) The nonrelativistic corrections
VOLT*(2 Pi FREQ/c)^2/(gamma beta)^2/4 are
automatically added to V20 and V02, respectively. The Lorentz factor
is evaluated as inverse of average of 1/(beta gamma) at the entrance
and the exit.
CAVI includes the edge effect at the lowest order, given by a Hamiltonian
at the entrance edge at s0:
Hf =  (e VOLT/L)(Sin(omega t  dphi) + Sin(dphi)  offset) (x^2+y^2)/4 delta(ss0)
where dphi and offset are determined by the cavity phase and the radiation loss,
which is nonzero only in the case of NORAD. The sign flips at the exit.
This Hamiltonian should be consistent with what Kiyoshi Kubo derived.

The xydependence of the acceleration. Tracking only.
The acceleration is given by
dE =  e*(VOLT+V1 x+V20 x^2/2+V11 x y+V02 y^2/2)
*Sin[2 Pi FREQ (tts) + PHI +DPHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.
(CAVI only) The nonrelativistic corrections
VOLT*(2 Pi FREQ/c)^2/(gamma beta)^2/4 are
automatically added to V20 and V02, respectively. The Lorentz factor
is evaluated as inverse of average of 1/(beta gamma) at the entrance
and the exit.
CAVI includes the edge effect at the lowest order, given by a Hamiltonian
at the entrance edge at s0:
Hf =  (e VOLT/L)(Sin(omega t  dphi) + Sin(dphi)  offset) (x^2+y^2)/4 delta(ss0)
where dphi and offset are determined by the cavity phase and the radiation loss,
which is nonzero only in the case of NORAD. The sign flips at the exit.
This Hamiltonian should be consistent with what Kiyoshi Kubo derived.

The x^2dependence of the acceleration. Tracking only.
The acceleration is given by
dE =  e*(VOLT+V1 x+V20 x^2/2+V11 x y+V02 y^2/2)
*Sin[2 Pi FREQ (tts) + PHI +DPHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.
(CAVI only) The nonrelativistic corrections
VOLT*(2 Pi FREQ/c)^2/(gamma beta)^2/4 are
automatically added to V20 and V02, respectively. The Lorentz factor
is evaluated as inverse of average of 1/(beta gamma) at the entrance
and the exit.
CAVI includes the edge effect at the lowest order, given by a Hamiltonian
at the entrance edge at s0:
Hf =  (e VOLT/L)(Sin(omega t  dphi) + Sin(dphi)  offset) (x^2+y^2)/4 delta(ss0)
where dphi and offset are determined by the cavity phase and the radiation loss,
which is nonzero only in the case of NORAD. The sign flips at the exit.
This Hamiltonian should be consistent with what Kiyoshi Kubo derived.

Accelerating peak voltage in Volt.
The acceleration is given by
dE =  e*(VOLT+V1 x+V20 x^2/2+V11 x y+V02 y^2/2)
*Sin[2 Pi FREQ (tts) + PHI +DPHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.
(CAVI only) The nonrelativistic corrections
VOLT*(2 Pi FREQ/c)^2/(gamma beta)^2/4 are
automatically added to V20 and V02, respectively. The Lorentz factor
is evaluated as inverse of average of 1/(beta gamma) at the entrance
and the exit.
CAVI includes the edge effect at the lowest order, given by a Hamiltonian
at the entrance edge at s0:
Hf =  (e VOLT/L)(Sin(omega t  dphi) + Sin(dphi)  offset) (x^2+y^2)/4 delta(ss0)
where dphi and offset are determined by the cavity phase and the radiation loss,
which is nonzero only in the case of NORAD. The sign flips at the exit.
This Hamiltonian should be consistent with what Kiyoshi Kubo derived.

An element for an arbitrary coordinate transformation. This element can be
used to express an offaxis element.
Usage: COORD name=(DX=dx DY=dy CHI1=chi1 CHI2=chi2 CHI3=chi3 DIR=dir); .
If dir is zero (default), the transformation of the coordinate by COORD is
{x1 {c3 s3 0 {1 0 0 {c1 0 s1 {xdx
y1 = s3 c3 0 0 c2 s2 0 1 0 ydy
z1} 0 0 1}. 0 s2 c2}. s1 0 c1}. z } ,
and if dir is nonzero,
{x1 { dx {c3 s3 0 {1 0 0 {c1 0 s1 {x
y1 = dy + s3 c3 0 0 c2 s2 0 1 0 y
z1} 0 } 0 0 1}. 0 s2 c2}. s1 0 c1}. z} ,
where {x1, y1, z1} is the new coordinate and
c1=cos(chi1), s1=sin(chi1), etc.
Note that these are NOT the inverse to each other.
To use this element, you have to calculate the values of those parameters
carefully. DISP G may help you but there is no automatic way to get them.
You may also have to be careful when you use a line with this element in the
reverse direction.
A better way to do an equivalent thing in most cases is to use SOL.
Unlike COORD, SOL automatically determines the parameters for the coordinate
transformation.

The default and available nondefault variable keywords are:
type defaultkeyword nondefault variable keyword
DRIFT L 
BEND ANGLE K1,K0,E1,E2
QUAD K1 ROTATE
SEXT K2 ROTATE
OCT K3 ROTATE
DECA K4 ROTATE
DODECA K5 ROTATE
MULT K1 K0,K2..K21,SK0,SK1,SK2..SK21,ROTATE,ANGLE
MARK  AX,BX,EX,EPX,AY,BY,EY,EPY,R1,R2,R3,R4,DX,DPX,DY,DPY
DZ,DDP

A decapole magnet.

If nonzero, the nonlinear Maxwellian fringe is suppressed.

If nonzero, the synchrotron radiation in the particletracking is inhibited.

Horizontal displacement of magnet. This applied before the rotation by
ROTATE.

Vertical displacement of magnet. This applied before the rotation by
ROTATE.

The normal 10pole magnetic field component (times the length L).
K4 = B^(4)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

Effective length.

Rotation in xy plane. After displacing the magnet by DX and DY,
rotate the magnet around the local saxis by (amount given by ROTATE),
then place the component. At the exit rotate back the magnet around
the local saxis at the exit, then take out displacement.

The transformation in a DECA is given as
exp(:Fin:)exp(:a L:)exp(:H4/2:)exp(:b L:)
*exp(:V4:)exp(:a L:)exp(:H4/2:)exp(:b L:)exp(:Fout:) ,
where L and H4 are Hamiltonians of a drift of length L and a thin
decapole kick of integrated strength K4:
H4 = K4/5! Re((x  I y)^5) ,
respectively. The coeffients are a = 1/2  1/sqrt(12) and
b = 1/2  a. Terms exp(:Fin:) and exp(:Fout:) are transformations for
entrance and exit nonlinear fringes. The term exp(:V4:) is a
correction to adjust the thirdorder terms in L:
V4 = (SUM over j=(x,y), k=(x,y)) [
 beta/2 (H4,k)^2
+ gamma (H4,j H4,k H4,j,k)] ,
where ,i represents the derivative by x or y. We have also introduced two
coefficients beta = 1/6  1/sqrt(48) and gamma = 1/40  1/24/sqrt(3).

A dodecapole magnet.

If nonzero, the nonlinear Maxwellian fringe is suppressed.

If nonzero, the synchrotron radiation in the particletracking is inhibited.

Horizontal displacement of magnet. This applied before the rotation by
ROTATE.

Vertical displacement of magnet. This applied before the rotation by
ROTATE.

The normal 12pole magnetic field component (times the length L).
K5 = B^(5)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

Effective length.

Rotation in xy plane. After displacing the magnet by DX and DY,
rotate the magnet around the local saxis by (amount given by ROTATE),
then place the component. At the exit rotate back the magnet around
the local saxis at the exit, then take out displacement.

The transformation in a DODECA is given as
exp(:Fin:)exp(:a L:)exp(:H5/2:)exp(:b L:)
*exp(:V5:)exp(:a L:)exp(:H5/2:)exp(:b L:)exp(:Fout:) ,
where L and H5 are Hamiltonians of a drift of length L and a thin
dodecapole kick of integrated strength K5:
H5 = K5/6! Re((x  I y)^6) ,
respectively. The coeffients are a = 1/2  1/sqrt(12) and
b = 1/2  a. Terms exp(:Fin:) and exp(:Fout:) are transformations for
entrance and exit nonlinear fringes. The term exp(:V5:) is a
correction to adjust the thirdorder terms in L:
V5 = (SUM over j=(x,y), k=(x,y)) [
 beta/2 (H5,k)^2
+ gamma (H5,j H5,k H5,j,k)] ,
where ,i represents the derivative by x or y. We have also introduced two
coefficients beta = 1/6  1/sqrt(48) and gamma = 1/40  1/24/sqrt(3).

A drift space.

Length.

Radius of the vacuum chamber. Effective when SPAC is ON.

The transformation of a drift is
exp(:H:),
with
H(x, px, y, py, z, p) = ((p^2  px^2  py^2) + 1  E/v0) L .

Available keywords are:
type keywords
DRIFT L RADIUS
BEND L ROTATE DROTATE DX DY ANGLE K0 K1 E1 E2 AE1 AE2
F1 FB1 FB2 FRINGE DISFRIN
DISRAD EPS RANKICK
QUAD L ROTATE DX DY K1 F1 F2 FRINGE DISFRIN DISRAD EPS
SEXT L ROTATE DX DY K2 DISFRIN DISRAD
OCT L ROTATE DX DY K3 DISFRIN DISRAD
DECA L ROTATE DX DY K4 DISFRIN DISRAD
DODECA L ROTATE DX DY K5 DISFRIN DISRAD
MULT L DX DY DZ CHI1 CHI2 ROTATE(=CHI3) K0..K21 SK0..SK21
DISFRIN F1 F2 FRINGE DISRAD EPS VOLT HARM PHI DPHI FREQ
RADIUS ANGLE E1 E2 AE1 AE2 DROTATE
SOL BZ DX DY DZ DPX DPY BOUND GEO CHI1 CHI2 CHI3 DBZ DISFRIN
CAVI L ROTATE DX DY VOLT V1 V20 V11 V02 FREQ PHI HARM RANVOLT RANPHASE
DISFRIN FRINGE
TCAVI L ROTATE DX DY K0 V1 FREQ PHI HARM RANKICK RANPHASE
COORD DX DY CHI1 CHI2 CHI3 DIR
MARK AX BX AY BY EX EPX EY EPY R1 R2 R3 R4 DX DPX DY DPY DZ DDP
EMITX EMITY DP AZ SIGZ GEO OFFSET
APERT DX1 DX2 DY1 DY2 DP AX AY DX DY

MARK elements play special rolls in FFS:
(1) The first element of the beam line must be a MARK element to be used by
FFS. In this case the MARK element contains the parameters of the
incoming beam (see opticalfunctions, specialvariables EMITX, EMITY,
DP).
(2) The calculated optical parameters at a MARK command is saved by
SAVE or STOP commands, then it can be used as the incoming condition
of other beam lines which have the same MARK element.
Example: MARK P1 = (EMITX = .. EMITY = .. DP = ..);
LINE A = ( .. P1 ..)
B = (P1 .. );
FFS USE = A;
... do matching on LINE A
SAVE P1 save the parameters at P1
USE B; switch to LINE B
... do matching of LINE B whose entrance is to be
matched P1.
(3) If a MARK element has keyword GEO nonzero, this MARK element becomes the
origin of the geometric rotation after the last SOL element.
(4) The values of opticalfunctions of the MARK element at the beginning of
the beam line can be specified as matching variables by the FREE command.
A MARK elements have all opticalfunctions as its keywords except NX, NY,
TRX, TRY, and LENG. Also it has keywords EMITX, EMITY, and DP which give
the values of the corresponding specialvariables.

OFFSET is a relative position from the current position. A fraction is
allowed to specify a location within an element.
If the MARK at the beginning of a beam line has OFFSET nonzero, the optics
calculation starts from the shifted location. If the last component of a
beam line is a MARK with nonzero OFFSET, the optics calculation stops at the
shifted location. The periodic condition is applied between those shifted
locations.
The geometric origin and the origin of LENG shift to the first MARK.
Examples:
(1) LINE A = ( ... QF PQFC ... );
QUAD QF = (L=0.3 K1=0.2);
MARK PQFC = (OFFSET = 0.5);
Here PQFC represents the center of QF.
(2) LINE A = ( ... PQFC QF ... );
QUAD QF = (L=0.3 K1=0.2);
MARK PQFC = (OFFSET = 1.5);
Here PQFC represents the center of QF, too (consider why). The value
of OFFSET is interpreted taking the direction of the LINE into account,
i.e., a MARK in a line A represents the same location in a line A.
Restrictions:
(1) Function TrackParticles does not take OFFSET into account if the start
or stop location is in the midst of a beam line and a Mark with nonzero
OFFSET, in the current version. Tracking for entire beam line or
MEASURE(MEA) command supports OFFSET.
(2) The outputs by DISPLAY(DISP) outside of the narrowed region by OFFSET are
meaningless.

A magnet with multipoles. Note that the reference plane is
defined so that the skew quadrupole component becomes zero.
It can have a nonzero ANGLE to express a combined function
bending magnet with multipoles. Note that the definition of
the multipoles with nonzero ANGLE is very special
The current version does not allow nonzero ANGLE inside a solenoid
or with acceleration. Also the fringe field and emittance
calculation are not installed properly for nonzero ANGLE.

The absolute face angle at the entrance.
The effective face angle is E1 * ANGLE + AE1, and a positive
angle at the entrance corresponds to a surface with dx/ds > 0.

The absolute faceangle at the exit to the bending angle.
The effective face angle is E2 * ANGLE + AE2, and a positive
angle at the exit corresponds to a surface with dx/ds < 0.

The bending angle. If positive, it bends the orbit in xs plane toward
negativexdirection. ANGLE determines the geometry of the beam line,
while K0 represents a dipole kick on top of the bending angle given by
ANGLE, i.e., the total deflection of the beam is given of ANGLE + K0.

If nonzero, the nonlinear maxwellian fringe is suppressed. The
effects of DISFRIN and FRINGE are summarized as
DISFRIN=0 DISFRIN<>0
Nonlinear Linear Nonlinear Linear
FRINGE=0 entr & exit none none none
FRINGE=1 entr entr none entr
FRINGE=2 exit exit none exit
FRINGE=3 entr & exit entr & exit none entr & exit

If nonzero, the synchrotron radiation in the particletracking is inhibited.

Relative phase offset. The stable synchrotron phase above the
transition is near PHI = 0.
The acceleration is given as
dE =  e*(VOLT+V1 x+V20 x^2/2+V11 x y+V02 y^2/2)
*Sin[2 Pi FREQ (tts) + PHI + DPHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.
DPHI is not taken into account to determine the design mementum p0(s).

The ratio of the faceangle at the entrance to the bending angle.
The effective face angle is E1 * ANGLE + AE1, and a positive
angle at the entrance corresponds to a surface with dx/ds > 0.
For example, a symmetricallyplaced rectangular magnet has
E1 = 0.5 and E2 = 0.5.

The ratio of the faceangle at the exit to the bending angle.
The effective face angle is E2 * ANGLE + AE2, and a positive
angle at the exit corresponds to a surface with dx/ds < 0.
For example, a symmetricallyplaced rectangular magnet has
E1 = 0.5 and E2 = 0.5.

F1 and F2 are parameters to characterize the slope of the field at the edges
defined as:
F1 = SIGN(Sqrt[a],a), a = 24(I_0^2/2  I_1),
F2 = I_2  I_0^3/3
with
I_n = Integrate[(ss0)^n K1[s]/K1_0,{s,Infinity,Infinity}],
where s0 is the location of the edge where the effective length is defined,
and K1_0 is the nominal value of K1, given by the keyword K1.
The effects only in the first order of K1 is taken into account.

F1 and F2 are parameters to characterize the slope of the field at the edges
defined as:
F1 = SIGN(Sqrt[a],a), a = 24(I_0^2/2  I_1),
F2 = I_2  I_0^3/3
with
I_n = Integrate[(ss0)^n K1[s]/K1_0,{s,Infinity,Infinity}],
where s0 is the location of the edge where the effective length is defined,
and K1_0 is the nominal value of K1, given by the keyword K1.
The effects only in the first order of K1 is taken into account.

Linear Fringe length F1 for the K0 component at the entrance.

Linear Fringe length F1 for the K0 component at the exit.

Rf frequency. If this keyword is nonzero, the keyword HARM is ignored.
The acceleration is given by
dE =  e*(VOLT+V1 x+V20 x^2/2+V11 x y+V02 y^2/2)
*Sin[2 Pi FREQ (tts) + PHI +DPHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.
(CAVI only) The nonrelativistic corrections
VOLT*(2 Pi FREQ/c)^2/(gamma beta)^2/4 are
automatically added to V20 and V02, respectively. The Lorentz factor
is evaluated as inverse of average of 1/(beta gamma) at the entrance
and the exit.
CAVI includes the edge effect at the lowest order, given by a Hamiltonian
at the entrance edge at s0:
Hf =  (e VOLT/L)(Sin(omega t  dphi) + Sin(dphi)  offset) (x^2+y^2)/4 delta(ss0)
where dphi and offset are determined by the cavity phase and the radiation loss,
which is nonzero only in the case of NORAD. The sign flips at the exit.
This Hamiltonian should be consistent with what Kiyoshi Kubo derived.

The effects of the linear fringe (characterized by F1 and F2), and the
nonlinear Mexwellian fringe are controled as:
DISFRIN=0 DISFRIN<>0
Nonlinear Linear Nonlinear Linear
FRINGE=0 entr & exit none none none
FRINGE=1 entr entr none entr
FRINGE=2 exit exit none exit
FRINGE=3 entr & exit entr & exit none entr & exit

A harmonic number. This is valid only when FREQ is zero.

The normal 2pole magnetic field component (times the length L).
K0 = B^(0)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 4pole magnetic field component (times the length L).
K1 = B^(1)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 22pole magnetic field component (times the length L).
K10 = B^(10)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 24pole magnetic field component (times the length L).
K11 = B^(11)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 26pole magnetic field component (times the length L).
K12 = B^(12)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 28pole magnetic field component (times the length L).
K13 = B^(13)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 30pole magnetic field component (times the length L).
K14 = B^(14)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 32pole magnetic field component (times the length L).
K15 = B^(15)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 34pole magnetic field component (times the length L).
K16 = B^(16)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 36pole magnetic field component (times the length L).
K17 = B^(17)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 38pole magnetic field component (times the length L).
K18 = B^(18)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 40pole magnetic field component (times the length L).
K19 = B^(19)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 6pole magnetic field component (times the length L).
K2 = B^(2)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 42pole magnetic field component (times the length L).
K20 = B^(20)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 44pole magnetic field component (times the length L).
K21 = B^(21)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 8pole magnetic field component (times the length L).
K3 = B^(3)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 10pole magnetic field component (times the length L).
K4 = B^(4)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 12pole magnetic field component (times the length L).
K5 = B^(5)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 14pole magnetic field component (times the length L).
K6 = B^(6)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 16pole magnetic field component (times the length L).
K7 = B^(7)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 18pole magnetic field component (times the length L).
K8 = B^(8)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

The normal 20pole magnetic field component (times the length L).
K9 = B^(9)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

Effective length.

Misalignments of a MULT element are expressed by the keywords DX, DY, DZ,
CHI1, CHI2, and ROTATE(=CHI3). They specify all misalignments of a rigid
body, At the entrance of MULT, the coordinates of a particle are
transformed as
{ x } { c3 s3 0 } { 1 0 0 } { c1 0 s1 } { x  DX }
{ y } = { s3 c3 0 } { 0 c2 s2 } { 0 1 0 } { y  DY }
{ ds }1 { 0 0 1 }.{ 0 s2 c2 }.{ s1 0 c1 }.{  DZ } ,
where c1 and s1 are Cos[CHI1] and Sin[CHI1], etc. The inverse is applied
at the exit.
Those misalignments are also valid within a solenoid.
Other straight elements such as QUAD or THIN do not and will not have
these full misalignment specifications, because they can be substituted by
MULT.
The geometry of the design orbit is determined by the saved values of
CHI1, CHI2, and DZ, while the current values are used for DX, DY, and ROTATE.

The multipoles in MULT with nonzero ANGLE are defined as
H = ... + As(x, y) ,
As(x, y) = Sum[ g_kn (Kn + I SKn)/(n + 1)! (rho + x)^(1/2  k)
* (x + I y)^(n + k) / rho^(1/2),
{k, 0, Infinity}, {n, 0, nmax}]
with
g_kn =  (2k  1)!! (2k  3)!! (n + 1)! / (8^k (n + k + 1)! k!) ,
where rho = L/ANGLE . Actually the summation is truncated at n + k <= 21
in the current version. While this definition converges to the regular
one for multipoles when ANGLE > 0, K0 and K1 of MUILT are
different from those of BEND.

Relative phase offset. The stable synchrotron phase above the
transition is near PHI = 0.
The acceleration is given as
dE =  e * VOLT * Sin[2 Pi FREQ (tts) + PHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.

Radius of the vacuum chamber. Effective when SPAC is ON.

The skew 2pole magnetic field component (times the length L).
SK0 = B^(0)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 4pole magnetic field component (times the length L).
SK1 = B^(1)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 22pole magnetic field component (times the length L).
SK10 = B^(10)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 24pole magnetic field component (times the length L).
SK11 = B^(11)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 26pole magnetic field component (times the length L).
SK12 = B^(12)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 28pole magnetic field component (times the length L).
SK13 = B^(13)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 30pole magnetic field component (times the length L).
SK14 = B^(14)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 32pole magnetic field component (times the length L).
SK15 = B^(15)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 34pole magnetic field component (times the length L).
SK16 = B^(16)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 36pole magnetic field component (times the length L).
SK17 = B^(17)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 38pole magnetic field component (times the length L).
SK18 = B^(18)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 40pole magnetic field component (times the length L).
SK19 = B^(19)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 6pole magnetic field component (times the length L).
SK2 = B^(2)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 42pole magnetic field component (times the length L).
SK20 = B^(20)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 44pole magnetic field component (times the length L).
SK21 = B^(21)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 8pole magnetic field component (times the length L).
SK3 = B^(3)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 10pole magnetic field component (times the length L).
SK4 = B^(4)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 12pole magnetic field component (times the length L).
SK5 = B^(5)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 14pole magnetic field component (times the length L).
SK6 = B^(6)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 16pole magnetic field component (times the length L).
SK7 = B^(7)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 18pole magnetic field component (times the length L).
SK8 = B^(8)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

The skew 20pole magnetic field component (times the length L).
SK9 = B^(9)L/(Brho),
where L is the length of the component. Positive sign means a horizontally
focusing magnet rotated around zaxis by 90/(n+1) degree, i.e.,
ROTATE = (90/(n+1)) DEG .

Accelerating peak voltage in Volt.
The acceleration is given by
dE =  e * VOLT * Sin[2 Pi FREQ (tts) + PHI + DPHI],
where ts is the equilibrium time determined by the valance between
the acceleration and the radiation loss around the ring.

A octapole magnet.

If nonzero, the nonlinear Maxwellian fringe is suppressed.

If nonzero, the synchrotron radiation in the particletracking is inhibited.

Horizontal displacement of magnet. This applied before the rotation by
ROTATE.

Vertical displacement of magnet. This applied before the rotation by
ROTATE.

The normal 8pole magnetic field component (times the length L).
K3 = B^(3)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

Effective length.

Rotation in xy plane. After displacing the magnet by DX and DY,
rotate the magnet around the local saxis by (amount given by ROTATE),
then place the component. At the exit rotate back the magnet around
the local saxis at the exit, then take out displacement.

The transformation in a OCT is given as
exp(:Fin:)exp(:a L:)exp(:H3/2:)exp(:b L:)
*exp(:V3:)exp(:a L:)exp(:H3/2:)exp(:b L:)exp(:Fout:) ,
where L and H3 are Hamiltonians of a drift of length L and a thin
octapole kick of integrated strength K3:
H3 = K3/4! Re((x  I y)^4) ,
respectively. The coeffients are a = 1/2  1/sqrt(12) and
b = 1/2  a. Terms exp(:Fin:) and exp(:Fout:) are transformations for
entrance and exit nonlinear fringes. The term exp(:V3:) is a
correction to adjust the thirdorder terms in L:
V3 = (SUM over j=(x,y), k=(x,y)) [
 beta/2 (H3,k)^2
+ gamma (H3,j H3,k H3,j,k)] ,
where ,i represents the derivative by x or y. We have also introduced two
coefficients beta = 1/6  1/sqrt(48) and gamma = 1/40  1/24/sqrt(3).

A quadrupole magnet.

If nonzero, the nonlinear maxwellian fringe is suppressed. The
effects of DISFRIN and FRINGE are summarized as
DISFRIN=0 DISFRIN<>0
Nonlinear Linear Nonlinear Linear
FRINGE=0 entr & exit none none none
FRINGE=1 entr entr none entr
FRINGE=2 exit exit none exit
FRINGE=3 entr & exit entr & exit none entr & exit

If nonzero, the synchrotron radiation in the particletracking is inhibited.

Horizontal displacement of magnet. This applied before the rotation by
ROTATE.

Vertical displacement of magnet. This applied before the rotation by
ROTATE.

F1 and F2 are parameters to characterize the slope of the field at the edges
defined as:
F1 = SIGN(Sqrt[a],a), a = 24(I_0^2/2  I_1),
F2 = I_2  I_0^3/3
with
I_n = Integrate[(ss0)^n K1[s]/K1_0,{s,Infinity,Infinity}],
where s0 is the location of the edge where the effective length is defined,
and K1_0 is the nominal value of K1, given by the keyword K1.
The effects only in the first order of K1 is taken into account.

F1 and F2 are parameters to characterize the slope of the field at the edges
defined as:
F1 = SIGN(Sqrt[a],a), a = 24(I_0^2/2  I_1),
F2 = I_2  I_0^3/3
with
I_n = Integrate[(ss0)^n K1[s]/K1_0,{s,Infinity,Infinity}],
where s0 is the location of the edge where the effective length is defined,
and K1_0 is the nominal value of K1, given by the keyword K1.
The effects only in the first order of K1 is taken into account.

The effects of the linear fringe (characterized by F1 and F2), and the
nonlinear Mexwellian fringe are controled as:
DISFRIN=0 DISFRIN<>0
Nonlinear Linear Nonlinear Linear
FRINGE=0 entr & exit none none none
FRINGE=1 entr entr none entr
FRINGE=2 exit exit none exit
FRINGE=3 entr & exit entr & exit none entr & exit

The normal 4pole magnetic field component (times the length L).
K1 = B^(1)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

Effective length.

Rotation in xy plane. After displacing the magnet by DX and DY,
rotate the magnet around the local saxis by (amount given by ROTATE),
then place the component. At the exit rotate back the magnet around
the local saxis at the exit, then take out displacement.

The transformation in a QUAD is a sequence of:
(nonlinear fringe at entrance)
canonical transformation by a generating function
G(x1, px2, y1, py2, p1) = H0(x1, px2, y1, py2, p1)
+ (D[H0, x1] D[H0, px2] + D[H0, y1] D[H0, py2])/2
where H0 = px2 dx1 + py2 dy1
dx1 = x1 (a/3 + b)
dy1 = y1 (a + b/3)
a = K1 x1^2/p1/4
b = K1 y1^2/p1/4 .
(linear fringe at entrance)
px2 = exp(a) px1
py2 = exp(a) py1
x2 = exp(a) x1 + b px1
y2 = exp(a) y1  b py1
z2 = z1  (a x1 + b (1 + a/2) px2) px1
+ (a y1 + b (1  a/2) py2) py1
where a = K1 F1 abs(F1)/(24 p1 L)
b = K1 F2/L .
(body of quad)
The body is subdivided in n = 1 + floor(10 abs(K1 L)/EPS) (EPS = 1
is used when EPS = 0), then a transversely linear transformation
exp(:H:) is done in each slice with
H = ((p + (px^2 + py^2)/(2 p) + E/v0) L + K1 (x^2  y^2)/2)/n .
Between slices applied is the correction exp(:dH:) for the kinematical
term with
dH = (sqrt(p^2  px^2 py^2) + p  (px^2 + py^2)/(2 p)) L/n .
In a solenoid, the forms of H and dH are modified.
(linear fringe at exit)
px2 = exp( a) px1
py2 = exp(a) py1
x2 = exp(a) x1 + b px1
y2 = exp( a) y1  b py1
z2 = z1 + (a x1  b (1  a/2) px2) px1
 (a y1  b (1 + a/2) py2) py1
where a = K1 F1 abs(F1)/(24 p1 L)
b = K1 F2/L .
(nonlinear fringe at exit)
canonical transformation by a generating function
G(x1, px2, y1, py2, p1) = H0(x1, px2, y1, py2, p1)
+ (D[H0, x1] D[H0, px2] + D[H0, y1] D[H0, py2])/2
where H0 = px2 dx1 + py2 dy1
dx1 = x1 (a/3 + b)
dy1 = y1 (a + b/3)
a = K1 x1^2/p1/4
b = K1 y1^2/p1/4 .

A sextupole magnet.

If nonzero, the nonlinear Maxwellian fringe is suppressed.

If nonzero, the synchrotron radiation in the particletracking is inhibited.

Horizontal displacement of magnet. This applied before the rotation by
ROTATE.

Vertical displacement of magnet. This applied before the rotation by
ROTATE.

The normal 6pole magnetic field component (times the length L).
K2 = B^(2)L/(Brho),
where L is the length of the component. Positive sign means horizontal
focusing.

Effective length.

Rotation in xy plane. After displacing the magnet by DX and DY,
rotate the magnet around the local saxis by (amount given by ROTATE),
then place the component. At the exit rotate back the magnet around
the local saxis at the exit, then take out displacement.

The transformation in a SEXT is given as
exp(:Fin:)exp(:a L:)exp(:H2/2:)exp(:b L:)
*exp(:V2:)exp(:a L:)exp(:H2/2:)exp(:b L:)exp(:Fout:) ,
where L and H2 are Hamiltonians of a drift of length L and a thin
sextupole kick of integrated strength K2:
H2 = K2/3! Re((x  I y)^3) ,
respectively. The coeffients are a = 1/2  1/sqrt(12) and
b = 1/2  a. Terms exp(:Fin:) and exp(:Fout:) are transformations for
entrance and exit nonlinear fringes. The term exp(:V2:) is a
correction to adjust the thirdorder terms in L:
V2 = (SUM over j=(x,y), k=(x,y)) [
 beta/2 (H2,k)^2
+ gamma (H2,j H2,k H2,j,k)] ,
where ,i represents the derivative by x or y. We have also introduced two
coefficients beta = 1/6  1/sqrt(48) and gamma = 1/40  1/24/sqrt(3).

A solenoid. Unlike other elements, SOL elements inserted at boundaries or
of a solenoid or at where the field changes. Between SOL elements DRIFT,
BEND(straight bend only), QUAD, and MULT elements can be inserted. The
longitudinal field of the solenoid overlaps on those elements.
In a SOL region, the coordinate is shifted on the axis of the solenoid,
no matter how the design orbit bends there. The xdirection of the
coordinate in a solenoid is so chosen as to CHI3 = 0. At the exit of a
solenoid, the coordinate is shifted back to the design orbit, but the value
of CHI3 is so determined as to set CHI3 zero at the nearest MARK element
which has GEO = 1 after the exit. The offset and orientation of the design
orbit can be given by keywords DX, DY, DPX, DPY at a SOL element with
GEO = 1.
SOL can be used to shift the coordinate to the actual orbit even without BZ.
It is useful to define the coordinate with magnets with DX and DY.

BOUND = 1 must be given at both sides of the boundaries of a solenoid,
otherwise SOL only specifies the change of BZ

The longitudinal field of a solenoid. If a SOL is used with BOUND = 0
(default), only BZ is used to change the field, and no coordinate
transformation is applied.

Disables the nonlinear fringe of solenoid if nonzero. The default is 0. The
transformation for the nonlinear fringe is expressed by
exp(:H:) ,
H = Bz/(8 Brho p^2) p_phi p_r,
where
p_phi = x py  y px ,
p_r = x px + y py ,
whose canonical partners are
phi = ArcTan[y/x] ,
r = Log[x^2 + y^2]/2 ,
respectively.

An offset of the design ORBIT angle CHI1 relative to the solenoid axis at
SOL with GEO = 1.

An offset of the design ORBIT angle CHI2 relative to the solenoid axis at
SOL with GEO = 1.

An xoffset of the design ORBIT relative to the solenoid center at SOL
with GEO = 1.

A yoffset of the design ORBIT relative to the solenoid center at SOL
with GEO = 1.

The length of fringe of the solenoide field. It affects only the EMITTANCE
calculation. If F1 = 0 (default), no radiation arises at the fringe.

One of boundaries (with GEO = 1) of a solenoid must have GEO = 1 to specify
the alignment of the design orbit. At a SOL element with GEO = 1, the
design orbit is determined by DX, DY, DPX, DPY parameters
An expression in FFS consists of a symbol, constants, and operators.
>>> A symbol is a characters of any length starting with an alphabet or $.
>>> There are two kinds of constants, real number and characterstring.
real number is a number in fortranline format.
characterstring is a set of characters surrounded by "" or ''.
specialcharacters can be specified with backslash.
>>> Available operators are (in the order of the priority):
#,##,
?,
::,
@,
[],
++, ,
/@, //@, @@,
.,
^,
*, /,
+, ,
==, <>, >, <, >=, =>, <=, =<,
===, <=>,
~,
&&,
,
.., ...,
,
:,
>, :>,
/., //.,
+=, =, *=, /=,
&,
//,
/:,
=, :=, ^=, ^:=, =.
;,
{}
An operator with higher priority is operated first. An expression
enclosed in () is evaluated first. Most mathematical operations are
threaded into a list, i.e., {a,b} + {c,d} gives {a + b,c + d}, etc.
Each operators can be used as a function using its name. For example,
Plus[x,y] gives the same result as x + y.

operator for subtraction or unary minus.

operator for division.

a+=b is equivalent to a=a+b .

a  b  ... represents a pattern which matches one of patterns a, b, ...

a && b returns True(==1) when both a and b are nonzero real,
False(==0) otherwise. b is not evaluated when a is zero.

f@@a applies function f to subexpressions of a. f@@[a,level] specifies
a levelspec to apply by level.

a ; b evaluates a, then evaluates b and returns its result.

a decrements a by 1, returning the old value of a.
a decrements a by 1, returning the new value of a.

a/=b is equivalent to a=a/b.

a . b returns the inner product of a and b.

a == b returns True(==1) if a and b have the same type and the same
value. It returns False(==0) if a and b have the same type but the
different values. Otherwise returns the expression a == b.

a & is a purefunction whose argument is specified #, #n, ##, ##n.

If both a and b are real, a > b returns True if a is greater than b,
False otherwise. It causes an error when a or b is not real.

If both a and b are real, a => b returns True if a is greater than
or equal to b, False otherwise. It causes an error when a or b is not real.

a++ increments a by 1, returning the old value of a.
++a increments a by 1, returning the new value of a.

If both a and b are real, a < b returns True if a is less than b,
False otherwise. It causes an error when a or b is not real.

If both a and b are real, a <= b returns True if a is less than
or equal to b, False otherwise. It causes an error when a or b is not real.

{a,b,c...} is a list structure.

f/@a maps function f to subexpressions of a. f/@[a,level] specifies
a levelspec of map by level.

f//@a maps function f to all subexpressions of a. f//@[a,Heads>True]
maps including the heads of a and its subexpressions.

f@a refers the member a of an instance or a class f. Otherwise it is same
as f[a]. f@g@h means (f@g)@h, and f@g[h] (f@g)[h].

symbol::tag returns a message associated with symbol and tag
symbol::tag = message sets a message identified by symbol

~a returns True(==1) when a is zero, False(==0) when a is a nonzero
real.

a  b returns True(==1) when a is nonzero real or b is nonzero real,
False(==0) otherwise. b is not evaluated when a is nonzero.

a[[b,..]] is a subexpression of an expression a.
If an index is omitted or Null as a[[,b]], Part returns a list of elements
whose corresponding index takes the entire range. For instance,
{{1, 2}, {3, 4}, {5, 6}}[[,2]] gives {2, 4, 6}.

pattern?test matches to an object which matches pattern
then test[object] gives True.

a + b returns the sum of a and b.

a ^ b returns the power of a to b.

p.. matches sequence of one ore more expressions, each matching p.

p... matches sequence of zero ore more expressions, each matching p.

expr/.rule replaces all subexpressions of expr using rule.

expr//.rule replaces all subexpressionso of expr using rule,
while a replacement is performed.

pattern>expr represents a rule for ReplaceAll.

pattern:>expr represents a rule for ReplaceAll, where expr is kept
unevaluated until the replacement.

a === b returns True(==1) if a and b have the same type and same
value, False(==0) otherwise.

a[b,c,..] means a list of b, c,.. with the head a. It is
evaluated as a functionreference when a is a function or a
definedfunction. When a is a list with head List, it is interpreted
as a part specification of a list. When a is a characterstring, it is
interpreted as a substring specification. When a is an operator, it is
an expression b (a) c (a) .. . When a is Null, it means a sequence.

a = value sets the value b to the symbol a.
{a,b,..}={v1,v2,..} sets a,b,c simultaneously.
a[b,c,..]=v1 sets the part of a[b,c,..] if a is a list.
a[b,c,..] = expression defines the value a[b,c,..] if a is not a list.

same as Set but the right hand side is not evaluated when it is set.

a // b converts a and b to characterstrings, then join them.

a=b is equivalent to a=ab .

symb/:lhs = rhs sets rhs to lhs, associated with symbol symb.
symb/:lhs := rhs sets rhs to lhs unevaluated, associated with symbol symb.
symb/:lhs =. unsets lhs, associated with symbol symb.

a * b returns the product of a and b.

a*=b is equivalent to a=a*b .

a <> b returns True(==1) if a and b have the same type but the different
values. It returns False(==0) if a and b have the same type but the same
value. Otherwise returns the expression a <> b.

a <=> b returns True(==1) if a and b have the different types or different
values. False(==0) otherwise.

a=. clears the definition assigned to a.
A symplectic matrix such as the normal mode matrix can be expressed in terms
of the extended Twiss parameters. In 6 by 6 case, those are
AX BX ZX EX
PSIX ZPX EPX
R1 R2 AY BY ZY EY
R3 R4 PSIY ZPY EPY
AZ BZ
PSIZ .
A(X,Y,Z), B(X,Y,Z) are alphas and betas in the usual sense, after a diagonalization to 2 by 2 submatrices. PSI(X,Y,Z) are the rota
tion angle to set one
the coordinate to parallel to the (X,Y,Z) axes. R(1,2,3,4) are the
components of the xy coupling matrix (see xycoupling). E(X,PX,Y,PY) are
"dispersions" which decouples synchrobeta coupling terms together with
Z(X,PX,Y,PY). Those parameters should agree with what FFS calculates in
the case of no synchrobeta couplings.

Let V denote the matrix to define the normal mode, i.e.,
U = V . u
where U = {X, PX, Y, PY, Z, PZ} and u = {x, px, y, py, z, delta} are normal
physical coordinates, respectively. The matrix V can be expressed as
V = P . B . R . H ,
where
H = {{(1  Det[Hx]/(1 + a))I, Hx.J2.Transpose[Hy].J2/(1+a), Hx},
{Hy.J2.Transpose[Hx].J2/(1+a), (1  Det[Hy]/(1 + a))I, Hy},
{J2.Transpose[Hx].J2, J2.Transpose[Hy].J2, a I}} ,
R = {{b I, J2.Transpose[r].J2, 0},
{r, b I, 0},
{0, 0, I}} ,
P . B = {{Px.Bx, 0, 0 },
{0, Py.By, 0 },
{0, 0, Pz.Bz}} ,
with
a^2 + Det[Hx] + Det[Hy] = 1 ,
b^2 + Det[R] = 1 .
Symbols I, J2, Hx,y, r, Bx,y,z, Px,y,z above are 2 by 2 matrices:
I = {{1, 0},
{0, 1}} ,
J2 = {{0, 1},
{1, 0}} ,
r = {{R1, R2},
{R3, R4}} ,
Bk = {{ 1/Sqrt[betak], 0 },
{ alphak/Sqrt[betak], Sqrt[betak]}} ,
Pk = {{ Cos[psik], Sin[psik]},
{Sin[psik], Cos[psik]}} .
Matrices Hx,y defines dispersions as
{{zetax, etax},
{zetapx, etapx},
{zetay, etay},
{zetapy, etapy}} = R . Join[Hx, Hy] .
Usage: IF expr1 body1 [ELSEIF expr2 body2 [ELSEIF ..]] [ELSE body3] ENDIF
This is a FORTRAN77 like IFstructure. If the expression expr1 is
True(==1) or nonzero, executes commands in body1. If it is False(==0), skip
commands until ELSE, ELSEIF or ENDIF appears at the same level of the
IFstructure, and executes commands after ELSE or ENDIF, or executes the
ELSEIF command. If expr1 is not a real number, an error message is printed
and ignores the command line.
Usage: IF expr1 body1 [ELSEIF expr2 body2 [ELSEIF ..]] [ELSE body3] ENDIF
This is a FORTRAN77 like IFstructure. If the expression expr1 is
True(==1) or nonzero, executes commands in body1. If it is False(==0), skip
commands until ELSE, ELSEIF or ENDIF appears at the same level of the
IFstructure, and executes commands after ELSE or ENDIF, or executes the
ELSEIF command. If expr1 is not a real number, an error message is printed
and ignores the command line.
Usage: (1) EMIT
(2) EMIT dp
(1) EMIT calculates the closed orbit, the normal coordinate, and the
equilibrium emittance assuming the current beam line is a positron ring.
One of EMITTANCE(EMIT), the Emittance[] function, or the EMIT command
in the MAIN level are necessary to be done in prior to multiturn tracking.
See multiturntracking.
(2) EMIT dp, where dp is df_rf/f_rf/(alpha_p == momentum compaction),
does EMIT for five rf frequencies:
df_rf/f_rf/alpha_p = dp, dp/2, 0, dp/2, dp,
then prints out a table of the dependences of various quantities on the
frequency shift.
The results of EMITTANCE(EMIT) are affected by flags COD, RADCOD, RFSW,
INTRA, WSPAC, EMIOUT, CODPLOT and specialvariables MOMENTUM, CHARGE, FSHIFT, MINCOUP,
PBUNCH. The flag TRPT or RING affects only Emittance[], as EMITTANCE(EMIT)
automatically set RING.
EMITTANCE(EMIT) returns the equilibrium emittaces in variables EMITX,
EMITY, EMITZ, and the equilibrium bunch length in SIGZ, the relative
momentum spread in SIGE.
The map used in EMIT is slightly different from that used in the tracking.
For instance, the edge angle of a bend is approximated by a thin quad.
If the edge angle is large and the curvature is small, EMIT may give a wrong
answer. This will be corrected in near future.
Closes the current outputstream and set the output stream to the
standard output(6). It also suspends all the input streams and switches
to the standard input(5). Since this command affects all input and output
streams, you may consider to use TERMINATE(TERM) or CLOSE(CLO) to suspend
or close them selectively.
Usage: IF expr1 body1 [ELSEIF expr2 body2 [ELSEIF ..]] [ELSE body3] ENDIF
This is a FORTRAN77 like IFstructure. If the expression expr1 is
True(==1) or nonzero, executes commands in body1. If it is False(==0), skip
commands until ELSE, ELSEIF or ENDIF appears at the same level of the
IFstructure, and executes commands after ELSE or ENDIF, or executes the
ELSEIF command. If expr1 is not a real number, an error message is printed
and ignores the command line.
Usage: EXEC characterstringexpression
executes the characterstringexpression as FFS commands.
Usage: [NO]flag
turns the flag on. If NO is prepended to flag, the flag is turned off.
Some flags have antonym which works in the opposite way. Flags can be
accessed in the functionsyntax with the form ?flag, which returns True (=1)
when the flag is on, or False (=0) otherwise. Some flags can be
accessed by the ON/OFF commands at the MAIN level.

ABSW or NORELW sets the weights of variable elements independent from
their values in the matching. Otherwise they are weighted relatively.

BIPOL or NOUNIPOL allows the change of sign of the value of the
element during the matching. It affects the default keywords of all
elements. This is overridden by MIN, MAX specification or VariableRange of
each element.

CELL or NOINS sets the periodic condition in calculating the
opticalfunctions.

CMPLOT enables the shift of the center of mass at the beginning of
the tracking. This is almost obsolete.

COD turns on finding the closedorbit in the emittance calculation.
Accessible in MAIN level.

CODPLOT lets the emittance calculation return the information on
the closedorbit and the beam size around the beam line into the FFS optics
buffer, which can be shown by DISPLAY(DISP) or DRAW commands.

CONV is a flag set by the CALCULATE(CAL) or GO commands. It becomes
True when MatchingResidual is less than CONVERGENCE.

When CONVCASE is on, FFS command line parser converts the input characters
to the upper case.(Default on) CONVCASE actions for the element names
and patterns CAN be overridden by PRSVCASE flag.

DAMPONLY is the antonym of FLUC.

DAPERT enables the DAPERT procedure in the multiturn tracking
to obtain the dynamic aperture diagram. Accessible in the MAIN level.

EMIOUT turns on the extented output of emittance calculation.
Accessible in the MAIN level.

When FFSPRMPT is off(default)� the input prompt is In[n]:= , where n
is $Line+1. Otherwise the prompt is the traditional FFS prompt, showing
the FIT location and the DISP range.

FIXSEED or NOMOVESEED disables the change of the seed of the random
number generator after the particle tracking.

FLUC or NODAMPONLY enables the diffusion due to synchrotron radiation
in the particle tracking. Otherwise only the damping is enabled when RAD
is ON.

GAUSS or NOUNIFORM sets the momentum distribution of the incoming
beam to be Gaussian, otherwise uniform(square) distribution is assumed.
It affects the beam size calculated by the BEAM command.

When GEOCAL is on(default), the geometry of the beam line is always
updated by CALCULATE(CAL) or GO commands using the current values
of components. The coordinate transformation by SOL is also updated.
When GEOCAL is off, the geometry is never updated. It is useful to
simulate misalignments within a solenoid, etc.

GEOFIX is the antonym of GEOCAL.

IDEAL or NOREAL inhibits to use the componentspecific deviations
(i.e., machineerrors) in the optics calculation.

INS is the antonym of CELL.

INTRA turns on the calculation of intrabeam scattering in the
emittance calculation. Accessible in MAIN level.

JITTER or NOQUIET allows jitter of the centerofmass of the incoming beam
in the case of TRPT. Otherwise the centerofmass statistically fluctuates
depending on the number of particles.

LWAKE turns on optics calculation with Longitudinal WakeFunction

MOVESEED is the antonym of FIXSEED.

When PHOTONS is ON (default is OFF), TrackParticles generates a list of all
photons radiated through the tracking. The list is assigned to a symbol PhotonList.

When PRSVCASE is on, FFS command line parser preserves the input characters
for the element names and patterns.(Default off)

When on, performs spacecharge simulation in a "ParticleInCell"
method. PSPAC is effective in tracking only.
Do not confuse PSPAC with SPAC/WSPAC.

QUIET is the antonym of JITEER.

RAD turns on the synchrotron radiation in the particletracking.
Accessible in the MAIN level.

RADCOD turns on the energy loss due to synchrotron radiation at the
closedorbit in the emittance calculation. Also turns off the implicit
acceleration in the tracking to compensate the energy loss automatically,
in the case that TRPT is ON. Accessible in MAIN level.

When RADLIGHT is on, the function TrackParticles returns a list of
trajectories which are used to calculate the synchrotron radiation field.

REAL is the antonym of IDEAL.

RELW is the antonym of ABSW.

RFSW turns on the acceleration by CAVI and TCAVI element in the
particletracking and the emittance calculation. Accessible in MAIN level,
but FFS always turns RFSW on at the beginning of the session.

RING is the antonym of TRPT.

When on with WSPAC, in tracking, the space charge force is calculated
relative to the center of mass of the current set of particles each time.
Otherwise(default) it is calculated relative to the closed orbit given by EMIT.
SELFCOD is useful when the closed orbits given by EMIT and TRACK are different.

When SPAC is on, tracking is done with space charge effect.
The actual number of particles in the beam and the number of macro particles
are given by PBUNCH and NP, respectively. This calculation assumes a cylindrical symmetry
of the chamber whose radius is given by RADIUS of DRIFT and MULT elements.
If RADIUS is positive, an aperture is also set at RADIUS to make particle
loss. If RADIUS is zero, no space charge calculation is done. If RADIUS is
negative, no space charge effect is taken, but the aperture is set at
RADIUS.
Do not confuse SPAC with WSPAC.

STABLE is a flag set by the CALCULATE(CAL) or GO commands in the case
of CELL. It becomes True when the closed orbit is found and the optics is
stable in both x and y.

TRPT or NORING decalres that the beam line is a transport line, not
a part of a storage ring. The nominal momentum be changed in the
bem line due to acceleration. The default momentum distribution becomes
uniform distribution. The default is RING or NOTRPT. TRPT affects
Emittance[] to ignore equilibrium calculation for a transport line.

TWAKE turns on optics calculation with Transverse WakeFunction

UNIFORM is the antonym of GAUSS. It assumes the momentum
distribution to be a uniform(square) within +DP.

UNIPOL is the antonym of BIPOL.

UNSTABLE is the antonym of STABLE.

When on, performs spacecharge simulation in a "strongweak"
mode. The beam size through the beam line is to be calculated by
EMIT with CODPLOT. The spacecharge force is calculated assuming Gaussian
distribution in all dimensions, and particles/bunch given by PBUNCH.
WSPAC is effective in optics and emittance calculations and tracking.
Do not confuse WSPAC with SPAC.
FFS functions:
Constants:
Degree GoldenRatio I INF* Infinity NaN* Pi SpeedOfLight
Elementaryfunctions:
ArcCos ArcCosh ArcSin ArcSinh ArcTan ArcTanh Cos Cosh Exp Log Sin Sinh
Sqrt Tan Tanh
Specialfunctions:
BesselI BesselJ BesselK BesselY BesselJZero Erf Erfc Factorial
Gamma LogGamma LogGamma1 GammaRegularized GammaRegularizedQ*
GammaRegularizedP* GaussianCoulomb* GaussianCoulombU*
GaussianCoulombFitted* LegendreP*
Numericalfunctions:
Abs Ceiling Floor Max Min MinMax* Mod Negative NonNegative Positive
Round Sign
Matrixoperations:
Det Eigensystem IdentityMatrix Inner LinearSolve Outer SingularValues*
Transpose
Randomnumber:
GaussRandom* Random* SeedRandom
Complex:
Arg Complex ComplexQ Conjugate Im Re
FourierTransformation:
Fourier InverseFourier
DataManupilation:
FindRoot Fit* NIntegrate* PolynomialFit* Spline*
Calculus:
D
Minimization:
DownhillSimplex*
Listmanipulations:
Append Complement Delete Depth Difference* Dimensions Drop Extract Flatten
FlattenAt HeldPart Insert Intersection Join Length Part Partition Prepend
Product Range ReplacePart Rest Reverse RotateLeft RotateRight Select
Sort Sum Take Table Union
Characterstrings:
FromCharacterCode CharacterPosition Characters DigitQ LetterQ StringDrop
StringFill* StringInsert StringLength StringPosition StringTrim*
Symbol SymbolName ToCharacteCode ToLowerCase ToUpperCase ToExpression
FunctionalOperations:
Apply Cases Count DeleteCases Identity FixedPoint* FixedPointList*
Fold Function Level Map MapAll MapAt MapIndexed MapThread Nest Position
Replace Scan SelectCases* SwitchCases* Thread
Objectoriented programing and context:
Begin BeginPackage Class* End EndPackage
FlowControl:
Break Catch Check Continue Do For Goto If Label Return Switch Throw Which
While
Tests:
AtomQ ComplexQ DirectoryQ* EvenQ FileQ* MatchQ MatrixQ MemberQ NearlySameQ*
Negative NonNegative NumberQ OddQ Order Positive RealQ StringQ* VectorQ
BoundQ* FBoundQ*
Input/Output:
Close Flush* Get OpenRead OpenWrite OpenAppend Print Read SeekFile*
Short* StringToStream Write WriteString
File System:
CopyDirectory CopyFile CreateDirectory DeleteDirectory DeleteFile
DirectoryName FileByteCount FileDate FileNames FileType
RenameDirectory RenameFile SetFileDate ToFileName
Scoping:
Block Module With*
Attributes:
Attributes* Clear Evaluate Head Hold Literal Protect ReleaseHold
SetAttributes* Unevaluated Unprotect
GUI Widget:
Window* PanedWindow* Frame* LabelFrame* Canvas* TextLabel* TextMessage*
Button* CheckButton* RadioButton* Menu* OptionMenu* MenuButton*
Entry* SpinBox* ListBox* ScrollBar* Scale* TextEditor*
Graphics:
BeamPlot* ColumnPlot* HistoPlot* ListContourPlot ListDensityPlot
ListPlot Plot Show FitPlot* GeometryPlot* OpticsPlot* TkPhotoPutBlock*
System Interface:
Directory Evironment GetEnv* GetGID* GetPID* GetUID* ProcessStatus*
SetDirectory SetEnv* System* TemporaryName* MkSecureTemp* RealPath*
Multiprocessing:
BiPipe* Fork* OpenShared* Shared* Wait*
Utilities:
Date DateString* Definition* FromDate* ToDate ToDateString* Pause
MemoryCheck* Message Off On Sleep TimeUsed Timing TracePrint
Functions listed above work basically in the same way as Mathematica's
except those marked by *.
FFSdedicatedfunctions:
BeamMatrix CalculateOptics DynamicApertureSurvey Element Emittance FFS
FitValue FitWeight GeoBase LINE OptimizeOptics OrbitGeo RadiationField
RadiationSpectrum SymplecticJ SetElement TrackParticles Twiss VariableRange
TouschekLifetime WakeFunction
Beamlinefunctions:
BeamLine BeamLineName ExtractBeamLine PrintBeamLine WriteBeamLine

Functions/objects to construct/edit beam lines and elements in FFS.

Usage: BeamLine[e1, e2, ...];
where e1, e2 has a form of
[  ][ n* ] x ,
with x being one of
1) a name (either a symbol or a character string) of an element defined in MAIN.
2) a name (either a symbol or a character string) of a LINE defined in MAIN.
3) a BeamLine object.
An optional negative sign specifies the direction and a number n the repetition
number in the same way as MAIN. A BeamLine object is automatically expanded
to the lowest level whenever it is evaluated. Editing of BeamLine can be
done using any Listhandling functions such as Join, Insert, Delete, etc. of
FFS.
A BeamLine object can be used for FFS calculation when it is used as the
argument of USE or VISIT commands:
Examples:
1) USE BeamLine[IP,QF,QD]
2) aaa=ExtractBeamLine[];
USE Join[aaa,aaa]
In these cases the new beam line becomes a new LINE in the MAIN level, with
a name which is created automatically.

BeamLineName[] returns the name of the current beam line.
If a BeamLine object is used by USE or VISIT, the new beam line becomes a
new LINE in the MAIN level, with a name which is created automatically.

Usage: ExtractBeamLine[line]
returns a BeamLine object which represents the expanded form of line which has
been defined in MAIN. If line is omitted, the current line is assumed.

Usage: PrintBeamLine[b1,.. ,option]
writes the BeamLine b1,.. to stdout. If b1.. is omitteed the current beam line
is assumed. If Format>"MAIN" is given, it writes in
the MAINinput format. If Name>{name1,..} is given, names of BeamLines are
also written. The number of Name must be not smaller than number of BeamLines.

Usage: WriteBeamLine[f, b1,.. ,option]
writes the BeamLine b1,.. to file f. If b1.. is omitteed the current beam line
is assumed. If Format>"MAIN" is given, it writes in
the MAINinput format. If Name>{name1,..} is given, names of BeamLines are
also written. The number of Name must be not smaller than number of BeamLines.


Usage: Fit[data, expr, var,
{par1, ini1, [{min1, max1}] }, .. ,{parn, inin, [{minn, maxn}]},
[options..] ]
performs a nonlinear fitting of data with an expression expr.
data: list of {xi,yi}, {xi,yi,dyi}, or {xi,yi,dxi,dyi}, where dxi and dyi
are the standard deviation of the ith point.
expr: an expression containing var as the xvariable, and
parameters par1,..,parn explicitly. Use Evaluate[fun] if an implicit
expression is necessary.
var: a symbol to express the xaxis variable.
par: parameter symbol to be varied in the fitting.
ini: initial value of the parameter. It must be specified.
(min, max}: optional range of parameter.
Fit returns the result as a list:
{par1 > v1, .., parn>vn, ChiSquare > chisq, GoodnessOfFit > good,
ConfidenceInterval > {c1, .., cn}, ConvarianceMatrix > cov},
where v1,..,vn are the values of the parameters which minimizes chisquare,
chisq is the resulting minimum value of the total chisquare (when no
error is given for yi, variance is returned), good is a number
given by GammaRegularized[(ndatanpara)/2,chisq/2] to represent the goodness
of the fit, c1, .., cn are the estimated errors in parameters, and cov is
the covariance matrix. A typical criterion of the goodness is (good > 0.1).
Options are
MaxIterations Maximum number of iterations.
D If True (default), tries to use analytical derivative.
Cutoff If nonzero, set teh saturation point for each data as:
chisuare = Sum_i ( Min[Cutoff, Max[Cutoff, (d_i  f_ i) / sigma_i]]^2 ) ,
which is a sort of robust MEstimates. By Cutoff, the fit
tends to ignore tail data which are beyond Cutoff.
If Cutoff is zero (default), it is ignored.

Usage: PolynomialFit[data, n]
performs a 1D linear regression of data.
data: list of {xi,yi}
n: the order of the polynomial
Fit returns the result as a list:
{{c0, .., cn}, {Residual > res}} ,
where c0 .. cn are the coefficients of the fitted polynomial,
y = c0 + c1 x + .. + cn x^n . Res is the rms residual of the fit.

Spline returns data for cubicspline interpolation.
Usage: sp = Spline[list, [Derivative>{dy1,dy2}] ]
where list contains data in the form as
{{x1,y1}, ..} or {{x1,{y11, y12, ..}}, ..}.
Complex number can be allowed for y, but not for x.
This spline assumes y''=0 at the boundary, unless
Derivative>{dy1,dy2} is specified to constrain the derivative
at each end to dy1 or dy2. They can be Null to unspecify
the constraint at one of the boundary.
The resulting data of the spline is assigned sp as a SplineData
object. Then one can calculate the interpolated data by
sp[x] value of y at x.
Derivative[1][sp][x] value of y' at x.
Derivative[2][sp][x] value of y'' at x.
Integrate[sp[x],{x, x0, x1}] integral of sp[x] from x0 to x1.

NIntegrate returns numerical integration of a Real or Complex
function
Usage: NIntegrate[f, {x, x0, x1}, options]
where f is a function containing Symbol x as the independent variable.
The integral range is from x0 and x1. The function f must contain the
symbol x explicitly.
Options Default Description

AccuracyGoal 1e13 Relative accuracy
InitialPoints 20 Number of initial points where
the function is evaluated.

Usage: DownhillSimplex[initial, f, options]
minimizes a function f by the downhill simplex method, starting from an
initial simplex initial. Suppose f is a function of n variables. Then
initial is a list of n+1 elements, each of which is a list of the form
{f[vi], vi} ,
where vi is a list of n values correspoinding to each variable.
The initial must be sorted in ascending order of f, i.e.,
initial=Sort[Map[{f[#],#}&,vlist]]
generates initial from a list of variables vlist.
DownhillSimplex returns the final simplex in the same form as initial.
Options:
VariableRange > {{min1 .. minn}, {max1 .. maxn}} gives the range of n
variables. The default is Infinity to Infinity for all variables.
MaxIteration > maxi gives the limit of number of iterations. The
default is Max[100, 10*(n+1)].
Output > lfn sets the output file number for the intermediate results.
the default is 6 (stdout).
Tolerance > tol sets the tolerance to judge the local minimum.
If (fmaxfmin)/(abs(fmax)+abs(fmin)) becomes less than tol, the
iteration loop terminates. The default is 10^6.
Examples:
f:=Apply[Function[{x,y},((x^2+y^2)1)*(x^2+y^2)(x.5)/3.],#]&;
v={{1.,1.},{0.,1.},{0.,1.}};
limit={{0.5,1.5},{0.65,1.5}};
p=Sort[Map[{f[#],#}&,v]]
DownhillSimplex[p,f,MaxIteration>100,
Tolerance>1e4,VariableRange>limit]

Functions dedicated to the optics calculations and simulations in FFS.

AccelerateParticles does TrackParticles with acceleration in a ring for a given
number of turns. The adiabatic damping is automatically taken cared.
Usage: AccelerateParticles[beam_,mom_,{n_Symbol,nturn_},opt___]
where beam is a list of beam coordinates in the same format for TrackParticles.
mom is an expression to determine MOMENTUM in each turn as a function of
turn number n. nturn is the total number of turns. An option Synchronize
specifies a routine to be executed at every turn of the tracking (e.g.
changing voltages and magnet settings, or storing the results.)
Example:
AccelerateParticles[
beam,
Which[
n < 100, 1e9,
n <= 200, 1e9 + (n  100) * 1e7,
True, 2e9],
{n, 300},
Synchronize :> ((
d = {d, MOMENTUM/1e9 * (1 + #2[[2,6,1]])})&)];

BeamMatrix[i] returns a 6 by 6 beammatrix (i.e., ) at location i.
The index i can have a fraction to specify intermediate numbers (see LINE
or Twiss). The calculation is based on linear 4 by 5 calculation in the
present version, so the zdirection is meaningless. Flag GAUSS affects the
result.

Usage: DynamicApertureSurvey[range,nturn,options]
where
range: a list of {xrange,yrange,zrange}, with
xrange: {xmin, xmax},
yrange: {ymin, ymax},
zrange: {z1, z2, .., zn},
These values are the initial amplitude divided by the equilibrium
values, i.e., Sqrt[2Jx,y/(EMITX+EMITY)], Sqrt[2Jz/EMITZ].
See EMITTANCE(EMIT) command or Emittance function.
nturn: number of turns to track.
options: Output>lfn : output to the unit lfn (see OpenWrite).
ReferenceOrbit>{x0, px0, y0, py0, z0, dp0} : Survey is done around
this orbit.
PhaseX>phix : The initial amplitude is rotated in (X, PX) phase space
by phix. Default is zero.
PhaseY>phiy : The initial amplitude is rotated in (Y, PY) phase space
by phiy. Default is zero.
ExpandElementValues>True(default) : set the values of the components
according to the values of elements. Machine errors may be reset.
See machineerrorcommands, CALCULATE(CALC).
DynamicApertureSurvey returns the result as a list:
{score,{{{xmin, xmax},{ymin, ymax},{z1, z2, .., zn}},
{{z1,score1,{turn1_1,..,turn1_50}},..,
{zn,scoren,{turnn_1,..,turnn_50}}}}} ,
where score = Sum[scorei,{i,n}], scorei is the "score" of ith momentum,
and turni_j is the lossed turn of the particle with ith momentum and
jth intial amplitude.
DynamicApertureSurvey tracks number of particles with different initial
conditions in the range given by range. It outputs a zx diagram of the
dynamic aperture of the ring. Fifty one initial conditions are chosen
in the range xrange for each point of zrange. The initial yamplitude is
linearly dependent on the xamplitude. It tracks from xmax to downward for
each zamplitude zn, until the particles turns nturn with successive
DAPWIDTH xamplitudes. The default DAPWIDTH is 7.

Element[keystring, {elementpatternstring  elementposition}] returns
values for keystring of elements which match elementpatternstring or
located at elementposition. It returns a list if more than one elements
match. The keystring and elementpatternstring can be symbols, unless
values are not assigned to them.
If the second argument is omitted, it means all elements.
The elementposition can be known by Element["POSITION"].
Keystrings "VALUE" and elementkeywords allows to be set (i.e.,
Element[a,b] = v) when elementpatternstring chooses only one element.
If a value is set to Element, it is automatically distributed to all
components those belong to the element. If the keyword is the default
variable, the error given by machineerrorcommand DK is applied.
The arguments of Element can be lists. It automatically maps as
Element[{a,b,c..},y] means {Element[a,y],Element[b,y],Element[c,y]..}
Element[x,{a,b,c..}] means {Element[x,a],Element[x,b],Element[x,c]..},
where both x and y can be also a list.
If an option Saved>True is given, Element refers the savebuffer which
can be transferred to other beam lines. Otherwise values set by Element
are not saved when FFS is stopped, unless they are the defaultkeyword or
keywords once used in matching.

The keystring is not casesensitive. Available keystrings are:
"LENGTH" Number of elements in the beam line. No second argument.
"POSITION" Position of the element in the elementlist.
"NAME" Name of the element.
"VALUE" Current value of the default keyword of the element.
"KEYWORDS" List of available keywords of the element.
"DEFAULT" The default keyword of the element
"TYPE" The internal codenumber of the type of the element.
"TYPENAME" The name of the type of the element.
keyword If keyword is the default keyword, it means the current
value. If not, it means the saved value. Changing the
nondefault keyword by Element does not affects the current
setting of the components.
"EXPAND" Distribute the value of the defaultkeywords and the
keywords used in the matching to all components in the
beam line. No second argument.
Setting by Element["VALUE",..] or Element[keyword,..] to the DEFAULT
keyword or a matchingvariable keyword changes the current value, and
distributed to the components in the succeeding calculation.

Emittance[option] returns a set of rules as
{keyword1>value1, keyword2>value2, ..} .
Its options and default values are Matrix(False), Orbit(False),
OneTurnInformation(False), Emittance(True), ExpandElementValues(True),
SaveEMIT(False), InitialOrbit(Null), InitialBeamMatrix(Null), and Output(0).
If Emittance>False is specified, the resulting keywords are
Stable True if all modes are stable and the closed orbit
is found.
Tunes {nux, nuy, nuz} .
EnergyLossU0
RfVoltageVc
EquilibriumPosition dz in meter.
MomentumCompaction
OrbitDilation ds in meter.
BucketHeight dV/E0
HarmonicNumber
OrbitAtExit physical c.o.d. at the end of line.
If None of the options is given, the following keywords are added:
DampingRate {T0/taux, T0/tauy, T0/tauz}
Emittances {emitx, emity, emitz}
MomentumSpread sigma p/p0
BunchLength sigma_z
TuneShiftByRadiation {dnux, dnuy, dnuz}
If OneTurnInformation>True, or Orbit>True, or Matrix>True, the followings
are added.
OrbitAtEntrance physical c.o.d. at the entrance of the ring.
OneTurnTransferMatrix symplectic part of the oneturn transfer matrix.
OneTurnDampingMatrix deviation of transfer matrix due to radiation.
NormalCoordinates conversion matrix from physical to normal coords.
OneTurnExcitation excitation matrix by radiation.
EquilibriumBeamMatrix equilibrium beam matrix.
ExtendedTwissParameters list of rules giving the extended Twiss parameters
at the entrance of the ring.
If Orbit>True or Matrix>True,
ClosedOrbit List of physical closed orbit at every element in the
ring.
joins.
If Matrix>True,
TransferMatrices List of physical transfer matrix from the beginning
of the beam line to all elements.
IntrabeamExcitation List of the change of the 6 x 6 beam matrix due to
the intrabeam scattering (only when INTRA),
converted to the beginning of the beam line.
join the result.
If the flag TRPT or NORING is set, the calculation assumes a transport line
so that several quantities such as damping rate, eigen modes, equilibrium beam
matrix, etc. are meaningless. Use RING or NOTRPT for such calculation.
In the case of TRPT or NORING, the incoming beam envelope must be given by
the option InitialBeamMatrix with a 6 x 6 symmetric matrix. TRPT is useful for
calculation of space charge and intrabeam in a transport line.
Please do not forget to put semicolon at the end of Emittance[] function,
otherwise the output will be huge especially when Orbit or Matrix is True.
If ExpandElementValues>False, calculation is made using the present
values of each component (i.e., including machine errors).
If SaveEMIT>True, the calculated values of emittances are stored in
EMITX, EMITY, EMITZ variables. The default is SaveEMIT>False.
InitialOrbit>{x0,px0,y0,py0,z0,dp0/p0} specifies the incoming orbit
which is valid when NOCOD is set. The option Output>filenum enables the
print out of EMITTANCE(EMIT) to filnum.

With MAP elements, ExternalMap defines a userdefined map of particles.
It also allows a user to do anything (doing statistics, etc.) at any
point of a beam line during a tracking.
Usage: First define a MAP element at MAIN level:
MAP name=(L=leng);
Right now L is the only keyword. Insert it at the location(s)
where you want to use it.
1) Tracking
In FFS, define the function ExternalMap as
ExternalMap["TRACK",n,nt_,x_]:=body;
The second argument n is the position of MAP counting from the beginning,
which can be obtained using LINE["POSITION","name.m"]. The third
argument nt_ is used to receive the number of turns which is incremented
by the tracking. The last argument x_ is used to receive the coordinates
of particles. It is a (7, np) list of real numbers. The elements
(1..6, i) are (x, px ,y ,py ,z ,dp/p0) of the ith particle. The (7, i)
element is True(==1) if the ith particle has been survived, and False(==0)
if it has been lost.
You can define ExternalMap to change the coordinates of each particle as
you like by returning a new x in the same format as above. If you do
not return it or you return in a different format, the tracking routine does
not change the particle coordinates. You can neither rebirth a lost
particle nor kill a surviving particle.
After defined ExternalMap, tracking calls it in every turn.
Example:
MAP P1=();
....
LINE A=(... P1 ... P1 ...);
....
FFS USE=A;
ExternalMap["TRACK",LINE["POSITION","P1.2"],nt_,x_]:=
(Print[x];x*2);
....
TRACK USE=A ....;
This example defines ExternalMap to print out the coordinates of all
particles at the second P1 in the line A. It also makes all coordinates
of all particles twice in every turn.
2) Emittance
In FFS, define the function ExternalMap as
ExternalMap["EMIT",n,cod_]:=body;
The second argument n is the position of MAP counting from the beginning,
which can be obtained using LINE["POSITION","name.m"]. The last
argument cod_ is used to receive the orbit at the entrance of the element,
as a list of 6 real numbers.
ExternalMap must return a list, either {cod1, trans} or
{cod1, trans, dtrans, dbeam}, where cod1 is the orbit at the exit,
trans is the 6 by 6 transfer matrix of this element, dtrans is the
radiation damping part of the transfer matrix (6 by 6), and dbeam
is the radiation excitation of the beam matrix (6 by 6).
Only j >= i parts of dbeam[[i, j]] are taken into account.
Example:
ExternalMap["EMIT",LINE["POSITION","P1"],cod_]:=(
Print[cod];
{cod+{0,0.001,0,0,0,0},IdentityMatrix[6]});
3) Optics
In FFS, define the function ExternalMap as
ExternalMap["OPTICS",n,cod_]:=body;
The second argument n is the position of MAP counting from the beginning,
which can be obtained using LINE["POSITION","name.m"]. The last
argument cod_ is used to receive the orbit at the entrance of the element,
as a list of 6 real numbers. ExternalMap must return a list {cod1, trans},
where cod1 is the orbit at the exit and trans is the 6 by 6 transfer matrix
of this element. So far only the 4 by 5 transfer matrix is effective.
Example:
ExternalMap["OPTICS",LINE["POSITION","P1"],cod_]:=(
Print[cod];
{cod+{0,0.001,0,0,0,0},IdentityMatrix[6]});
4) Geometry
In FFS, define the function ExternalMap as
ExternalMap["GEO",n,geo_,pos_]:=body;
The second argument n is the position of MAP counting from the beginning,
which can be obtained using LINE["POSITION","name.m"]. The argument
geo_ receives the geometry of the beam line at the MAP element, in the
same format as LINE["GEO",n], i.e., {{GX,GY,GZ},{CHI1,CHI2,CHI3}}.The last
argument pos_ receives the orbit length S at the element.
ExternalMap must return an updated list {geo1, pos1},
as { {{GX,GY,GZ},{CHI1,CHI2,CHI3}}, S} as the values at the exit of the
element.
Example:
ExternalMap["GEO",LINE["POSITION","P1"],geo_,pos_]:=(
Print[cod];
{ {geo[[1]]+{1,0,0}, geo[[2]]}, pos+0.1})

FFS[commandstring] executes commandstring as FFS commands. Any commands
can be used. Some commands CALCULATE(CAL), GO, VARIABLES(VAR), SHOW
returns their result, otherwise Null is returned. All outputs of the
commands are suppressed.
FFS[commandstring,lo] directs the output of the commands to filenumber
lo. The filenumber lo may be given by OpenWrite or OpenAppend.
The IF structure and REPEAT(REP) loop must be closed in a single FFS.

Usage:
(1) FitValue[component, function, {id_,dp_}, goal_, now_] := body
modifies the goal of the matching of function at component. The argument
id_ is the orbit id for MatchingAmplitude or InitialOrbits. The
argument dp_ receives the value of dp/p0. The argument goal_ is the value
of the goal of the matching set by matchingfunctioncommands. The argument
now_ is the current value of function.
Example: FitValue["$$$", "NX", {_,dp_}, goal_, now_] := goal + dp * xix * 2 * Pi
sets the tune NX to have chromaticity xix.
(2) FitValue[component1, component2, function, {id_,dp_}, goal_, now1_, now2_] := body
modifies the value of the function at component1 for a twocomponent matching.
Component1 is assumed upstream in the beam line. The value of body is
used in place of the current value, now1. The argument id_ is the orbit id
for MatchingAmplitude or InitialOrbits. The argument dp_ receives the value of dp/p0.
The argument goal_ is the value of the goal of the matching set by
matchingfunctioncommands. The argument now1 and now2 are the current
values of the function at component1 and component2, respectively.
Example: FitValue["QF1", "QF2", "NX", _, goal_, now1_, now2_] :=
If[Abs[now2(now1+goal)] < 0.01*2*Pi , Null, now1]
sets the tune difference between QF1 and QF2 gaol + 0.01.
During the matching process the matching routine calls FitValue with
arguments, then if body returns a number, it overrides the goal give by
matchingfunctioncommands. If body returns Null, the matching of function
is ignored.
sets the tune NX to have chromaticity xix.
The matchingfunctioncommand is necessary besides FitValue to perform
the matching. Only defining FitValue does not do the matching.

A defined function to modify the weight of matching of particular function
at particular component with particular momentum offset.
Usage: FitWeight[component, function, {id_,dp_}, default_] := weight;
where
component is the name of the location of the fit, like "QF.2", etc.
function is the name of the matchingfunction, like "BX", "LENG", etc.
id_ is the id number of the orbit for MatchingAmplitude or
InitialOrbits.
dp_ is a variable to receive the momentum deviation of the fit.
default_ is a variable to receive the default fit weight.
weight is an expression which returns the desired weight.
Example: FitWeight["$$$","LENG",{_,dp_},ws_]:=ws*10;
makes the weight of LENG at $$$ 10 times (100 times in MatchingResidual)
bigger than the default.

GeoBase[{chi1, chi2, chi3}] converts the rotation angles
of the coordinate base vectors to a transformation
matrix {{x_gx,x_gy,x_gz}, {y_gx,y_gy,y_gz}, {z_gx,z_gy,z_gz}}

LINE[keystring, {componentpatternstring  componentposition}] returns
values for keystring of components which match componentpatternstring or
located at componentposition. It returns a list if more than one components
match. The keystring and componentpatternstring can be symbols, unless
values are not assigned to them. The second arg can be a fractional number
to denote an intermediate value of two components.
If the second argument is omitted, it means all components.
The componentposition can be known by LINE["POSITION"].
Keystrings "DIR" and componentkeywords allows to be set (i.e.,
LINE[a,b] = v) when componentpatternstring chooses only one component.
The arguments of LINE can be lists. It automatically maps as
LINE[{a,b,c..},y] means {LINE[a,y],LINE[b,y],LINE[c,y]..}
LINE[x,{a,b,c..}] means {LINE[x,a],LINE[x,b],LINE[x,c]..},
where both x and y can be also a list.

The keystring is not casesensitive. Available keystrings are:
"LENGTH" Number of components in the beam line. No second argument.
"POSITION" Position of the component in the beam line.
"NAME" Name of the component.
"TYPE" The internal codenumber of the type of the component.
"TYPENAME" The name of the type of the component.
"ELEMENT" The name of the corresponding element.
"DIR" The orientation of the component, +1.
"S" The orbit length to the entrance from the beginning of the
beam line.
"LENG" Same as "S".
"GEO" Geometricparameters at the entrance of the component,
{{GX, GY, GZ}, {GCHI1, GCHI2, GCHI3}}.
"OGEO" Geometricparameters of the orbit at the entrance of the component,
{{OGX, OGY, OGZ}, {OCHI1, OCHI2, OCHI3}}.
"GX", "GY", "GZ", "GCHI1", "GCHI2", "GCHI3"
Each geometrical parameter.
"OGX", "OGY", "OGZ", "OCHI1", "OCHI2", "OCHI3"
Each geometrical parameter at the orbit.
"GAMMA" Lorentz factor gamma.
"GAMMABETA" Lorentz factor gamma*beta = Sqrt[gamma^2  1].
"SIGab" Beam matrix component, where a and b are one of X, PX,
Y, PY, Z, DP. If b is omitted it returns Sqrt[SIGaa] is
returned. Just "SIG" returns the entire 6 by 6 beam matrix.
"SIZEab" Beam matrix component calculated by (CODPLOT;EMIT),
where a and b are one of X, PX, Y, PY, Z, DP.
If b is omitted it returns Sqrt[SIZEaa] is returned.
Just "SIZE" returns the entire 6 by 6 beam matrix.
"MULT" The ordered number of each component belonging to the
same element, starting from 1.
keyword The value of the keyword of the component (see below).
"EXPAND" Distribute the value of the defaultkeywords and the
keywords used in the matching to all components in the
beam line. No second argument.
Setting by LINE[keyword,..] to the DEFAULT keyword for the FIRST component
changes the current value of the corresponding element, because the value
of an element is stored in the first component.

Usage: OptimizeOptics[options]
optimizes (1 + MatchingResidual) or any function using DownhillSimplex
with variables specified by FREE. Unlike GO, any keyword of any
element can be a variable.
OptimizeOptics returns the final simplex. The variables are set to
the values which give the minimum of the function so far at the end.
Options:
All options for DownhillSimplex are valid.
OptimizeFunction > fun is the function to be minimized. The default is
((FFS["CALC"];1+MatchingResidual)&).
InitialSimplex > initial sets the initial simplex to initial. The
default is Null, which mean to create initial from the current value
of the variables. Its format is same as for initial of
DownhillSimplex
SimplexSize > size is the initial size of the simplex. Each variable
is relatively shifted by this amount from the current value.
Example:
free Q* Q* L
fit nx .3 ny .2
OptimizeOptics[]
optimizes the optics by changing the lengths of quads which are not allowed
by GO, as well as K1 of quads.

OrbitGeo[location] returns the geometry {GX, GY, GZ}
of the current (not design) orbit.

To calculate the field of the synchrotron radiation from particles,
first record trajectories of particles. This is done by the function
TrackParticles with a new flag RADLIGHT on. When RADLIGHT is on,
TrackParticles returns a list
{beam, trajectory} ,
where beam is a list as {location, coordinates}, and trajectory is a list
{ {t1 .. tm}, {x1 ..xm}, {y1 .. ym}, {z1 .. zm} }, ..
where {t,x,y,z}_i is the coordinates of the particle at ith point in the
trajectory. The origin and the direction of the spatial coordinates are
the same as GEO coordinat {GX, GY, GZ}. One can track many particles at the
same time by TrackParticles, so the trajectory has the dimensions {np, m},
where np is the number of particles.
After the trajectory is obtained, one can calculate the field in time domain
at any observation point. This is done by the function RadiationFiled as
field = RadiationField[ trajectory[[i]], obs];
where trajectory[[i]] is the trajectory of the ith particle, and obs is the
spatial coordinate of the observation point in the GEO coordinate. The
output field is a list
{ {tau1 .. taum},
{Ex1 .. Exm}, {Ey1 .. Eym}, {Ez1 .. Ezm},
{Hx1 .. Hxm}, {Hy1 .. Hym}, {Hz1 .. Hzm},
{Sx1 .. Sxm}, {Sy1 .. Sym}, {Sz1 .. Hzm} }
where H = (n x E)/(c mu0) and S = E x H , and tau is the observation time.
RadiationField uses the FeynmannHeviside formula
E = (mu0 e/4pi) (c^2n/R^2 + R/c d(c^2n/R^2)/dt + d^2n/dt^2) ,
where n and R are the direction vector and the distance from the electron
at the retarded time to an observation point.
The derivatives in the above formula is calculated using the spline
interpolation.
Next one can calculate the spectrum of the field by RadiationSpectrum as
spect = RadiationSpectrum[ {field[[1]], field[[k]]},
{lambda1, lambda2, dlambda} ] ,
where filed[[k]] is one of the fields calculated by RadiationField. The range
of the wavelength is given as a list above. The output spectrum spect is a
list as
{ {k1 .. kk}, {c1 .. ck}, {s1 .. sk} } ,
where k1 .. kk is the wave number k = omega/c, c1 .. ck and s1 .. sk are the
cosine and sine integrals of the field in tau1 .. taum , i.e.,
ck + I sk = Integrate[ field[tau] Exp[I c k tau] dtau] .
An example is seen in /users/oide/WORK/oldsad/sad/examples.sad .

To calculate the field of the synchrotron radiation from particles,
first record trajectories of particles. This is done by the function
TrackParticles with a new flag RADLIGHT on. When RADLIGHT is on,
TrackParticles returns a list
{beam, trajectory} ,
where beam is a list as {location, coordinates}, and trajectory is a list
{ {t1 .. tm}, {x1 ..xm}, {y1 .. ym}, {z1 .. zm} }, ..
where {t,x,y,z}_i is the coordinates of the particle at ith point in the
trajectory. The origin and the direction of the spatial coordinates are
the same as GEO coordinat {GX, GY, GZ}. One can track many particles at the
same time by TrackParticles, so the trajectory has the dimensions {np, m},
where np is the number of particles.
After the trajectory is obtained, one can calculate the field in time domain
at any observation point. This is done by the function RadiationFiled as
field = RadiationField[ trajectory[[i]], obs];
where trajectory[[i]] is the trajectory of the ith particle, and obs is the
spatial coordinate of the observation point in the GEO coordinate. The
output field is a list
{ {tau1 .. taum},
{Ex1 .. Exm}, {Ey1 .. Eym}, {Ez1 .. Ezm},
{Hx1 .. Hxm}, {Hy1 .. Hym}, {Hz1 .. Hzm},
{Sx1 .. Sxm}, {Sy1 .. Sym}, {Sz1 .. Hzm} }
where H = (n x E)/(c mu0) and S = E x H , and tau is the observation time.
RadiationField uses the FeynmannHeviside formula
E = (mu0 e/4pi) (c^2n/R^2 + R/c d(c^2n/R^2)/dt + d^2n/dt^2) ,
where n and R are the direction vector and the distance from the electron
at the retarded time to an observation point.
The derivatives in the above formula is calculated using the spline
interpolation.
Next one can calculate the spectrum of the field by RadiationSpectrum as
spect = RadiationSpectrum[ {field[[1]], field[[k]]},
{lambda1, lambda2, dlambda} ] ,
where filed[[k]] is one of the fields calculated by RadiationField. The range
of the wavelength is given as a list above. The output spectrum spect is a
list as
{ {k1 .. kk}, {c1 .. ck}, {s1 .. sk} } ,
where k1 .. kk is the wave number k = omega/c, c1 .. ck and s1 .. sk are the
cosine and sine integrals of the field in tau1 .. taum , i.e.,
ck + I sk = Integrate[ field[tau] Exp[I c k tau] dtau] .
An example is seen in /users/oide/WORK/oldsad/sad/examples.sad .

Create/set/read a MAINlevel element.
Usage: SetElement[ elementname, elementtype, options]
where
elementname: name of the element, either a symbol or a string
elementtype: type of the element, a symbol, a string, or a number
options: one or more rules or list of rules of the form
keyword > value or keyword :> value, to set the corresponding
value of keyword of the element.
SetElement returns a list of information of the element, in the suitable
form for applying SetElement again.
You can define a new element by SetElement.
You can change the values of keywords of the element. You cannot,
however, change the type of the element, nor cannot delete the element.
The elementtype can be Null. If so, a null type is assumed for a new
element.
Examples:
LINE A = ( .. );
QUAD QF = (K1 = 0.2);
...
FFS USE = A;
...
SetElement["QF"] ! reads values of QF.
SetElement["QF","QUAD"] ! same as above.
SetElement["QF","BEND"] ! error because QF is QUAD.
SetElement["QF",,{"K1">0.1}] ! set K1 of QF to 0.1 .
SetElement["QF","QUAD",{"K1">0.1}] ! same as above.
!Assuming QF1 and QF2 are undefined yet:
SetElement["QF1","QUAD",{"K1">0.1}] ! create a new QUAD QF1 with K1=0.1 .
SetElement["QF2",,{"K1">0.1}] ! error because no type with key.
SetElement["QF2"] ! This is OK.
SetElement["QF2","QUAD"] ! Now the type of QF2 is defined.

SurvivedParticeles[x]
returns the list of 6 coordinates and the flag of the survivied particles in x.
The form of x is {x, px/p0, y, py/p0, z, dp/p0, flag}, where each is a list of
length of the number of particlse. If all particles are lost, it is a list of
seven null lists.

SymplecticJ[n] returns a n by n symplectic matrix like
{{0, 1, ...}, {1, 0, ...}, {0, 0, 0, 1, ...}, {0, 0, 1, 0, ...}, ...} .

SynchroBetaEmittance calculates equilibrium emittance under influence of
synchrotron motion and chromaticity.
Usage:
SynchroBetaEmittance[{nus0, nus1, dnus},options]
or
SynchroBetaEmittance[nus0,options]
where nus0, nus1, and dnus are the starting, ending and step size of
synchrotron tune, respectively. If only nus0 is given, calculation is done
only for nus0. The returned value is a list:
{{nus, emitx, emity, conv}, ... }
where nus, emitx, emity, conv are the synchrotron tune, equilibrium horizontal
and vertical emittance, and the convergence. When conv is negative, calculation
failed to converge, and the returned emittances are not reliable.
Options Type Default Meaning

AzimuthalModes Real 9 Number of azimuthal modes

TouschekLifetime interpolates the data calculated by EMIT or Emittance[].
There are three ways of usage:
TouschekLifetime[Infinity, Infinity, nz]: Touschek lifetime in seconds
with momentum aperture nz * SIGE.
TouschekLifetime[nx, Infinity, nz]: Touschek lifetime in seconds
with acceptance 2Jx/(nx * (EMITX+EMITY)) + 2Jz/(nz * EMITZ) < 1.
TouschekLifetime[Infinity, ny, nz]: Touschek lifetime in seconds
with acceptance 2Jy/(ny * (EMITX+EMITY)) + 2Jz/(nz * EMITZ) < 1.
EMIT or Emittance[] with INTRA must precede TouschekLifetime.

TrackParticles[beam, destinationcomponent, nbegin, nend]
returns a beam after the tracking at the entrance of the destination
component. The destination can be specified by the name of the component
or by a number obtained by LINE["POSITION", component].
If destination is omitted, the end of the line is assumed.
The argument nbegin is the initial turn number to be passed to tracking to indicate
it is in the nth turn. The number is increased by 1 when it passes the end of beam line.
If nbegin is omitted, 1 is assumed.
The argument nend is the last turn number. The default is nbegin.
The variable beam and also the result of TrackParticles are lists of the
form
{location, coordinates}
where location is the positionnumber of the starting point. If location is
same as or in the downstream of destination, the tracking is done by
folding across the beginning of the beam line. The coordinates are in a list of {7, np}
form, where np is the number of particles. The first 6 elements of
coordinates specifies
{x, px/p0, y, py/p0, z, dp/p0}
in this order. The {7, i} is the flag which is True(==1) when the
particle is alive, and False(==0) when lost.
When a flag RADLIGHT is on, TrackParticles returns the trajectories of
particles which are used to calculate the radiation fields. See
RadiationField and RadiationSpectrum.
When PHOTONS is ON (default is OFF), TrackParticles generates a list of all
photons radiated through the tracking. The list is assigned to a symbol PhotonList.

Twiss[opticalfunction, component] returns the value of the opticalfunction
at the entrance of component. The values are those calculated by the last
CALCULATE(CALC) or GO commands, or CalculateOptics function.
The second argument, component can be a name of component, a component
number, or a list of them. If the number has a fraction, the intermediate
value in the component is calculated.
Twiss["ALL",component] or Twiss["*",component] returns all 27
opticalfunctions at the entrance of component as a list:
{AX, BX, NX, AY, BY, NY, EX, EPX, EY, EPY, R1, R2, R3, R4, DX, DPX, DY, DPY,
DZ, DDP, AZ, BZ, NZ, ZX, ZPX, ZY, ZPY},
which can be directly used in CalculateOptics. In the current version,
however, parameters after AZ are uninteresting, because it always returns 1
for BZ and zeros for the others.
Keywords "PEX", "PEPX", "PEY", "PEPY" return dispersions in the
physical coordinate.
Keywords "LENGTH", "GAMMA", "GAMMABETA", "S", "SIGab" return
the same results as for the function LINE.
The units of NX, NY, NZ are radian.

Usage: VariableRange[element, keyword ,v_] := expression
where the current value of the element:keyword is passed in v_, and
expression should give False when the value is out of range.
Example: VariableRange["QF","ROTATE",v_]:= 0.1 < v < 0.1;
This restricts the range of the rotation angle of QF within +100 mrad.
VariableRange[_,"ROTATE",v_]:= 0.1 < v < 0.1;
This specifies the same for all elements.
The expression can also return the range as a list {vmin, vmax}, which
may give more chance of solutionfinding for the matching routine.
VarableRange only acts for variables used in the matching with the
FREE command.

Usage: VariableWeight[element, keyword ,v_] := expression
where the default weight for matching with element:keyword is passed in v_, and
expression should return a modified value of weight. If nonreal is returned,
the default weight is used.
Example: VariableWeight["QF","K1",v_]:= 0.1*v;
reduces the weight of QF1:K1 to 1/10 of the default value.
The weight also affects the step size of the numerical derivative
of the response. A smaller weight makes the step size larger.
VarableWeight only acts for variables used in the matching with the
FREE command.

WakeFunction[Longitudinal, comp]={{z1, wl1}, ..., {zn, wln}};
WakeFunction[Transverse, comp]={{z1, wt1}, ..., {zn, wtn}};
specify logitudinal and transverse dipole wake functions at a component comp
(string). Each functions is a list of {z, w} where z is the distance (z>=0)
and w is the value of the wake, in the unit of either V/C or V/C/m.
The wake functons are applied at the componet comp, giving kicks to each
orbit whose initial conditions are given by InitialOrbits. The sufficient
number of orbits depends on the situation.
WakeFunction is valid only when TRPT and INS, and also either TWAKE or
LWAKE is ON.
For tracking, it is only valid in TrackParticles. If a wake is given by
the WAKE command to the same component, WakeFunction supersedes.


Difference[list] returns Rest[list]  Drop[list, 1]

FixedPoint[f, e] starts from f[e] then applies f repeatedly until the result
no longer changes. FixedPoint[f, e, n] specifies the maximum number of iterations
by n. An option SameTest>s specifies the test function.
Threshold>re, and AbsoluteThreshold>ae set the relative and absolute
accuracy, respectively, when SameTest>NearlySameQ (default).

FixedPointList[f, e] returns the intermediate values of FixedPoint[f, e] as a list.
FixedPointList[f, e, n] and options for FixedPoint are valid.

Usage: SelectCases[list, {test1,..}]
returns a list {list1, .. }, where list1 is a list of subexpressions which
makes test1 True, etc. If the second argument is like {c1, .. , True&},
the last of the returned list contains subexpressions which make none of c1,
... True.

Usage: SwitchCases[list, {case1,..}]
returns a list {list1, .. }, where list1 is a list of subexpressions which
match case1, etc. SwitchCases does what are done by Cases and DeleteCases
simultaneously. If the second argument is like {c1, .. , _}, the last of
the returned list contains subexpressions which match none of c1, ...

Graphics represents an object for 2D graphics with the form
Graphics[primitives, options]. Up to now available primitives are:
Circle[{cx,cy},rx, options] : Circle.
Circle[{cx,cy},{rx,ry}, options] : Oval.
Points[{{x1,y1} .. {x2,y2}}, options] : Points.
Points[{{x1,y1,dx,dy} .. {x2,y2,dx,dy}}, options] : Points with error bars.
Line[{{x1,y1} .. {x2,y2}}, options] : Line.
Line[{{x1,y1,dx,dy} .. {x2,y2,dx,dy}}, options] : Line with error bars.
Rectangle[{x1,y1}, {x2,y2}] : A box.
Rectangle[{x1,y1}, {x2,y2}, graphic] : Graphics in a box.
Polygon[{{x1,y1} .. {x2,y2}}, options] : Polygon.
Text[{string, {x,y}}, options] : Textstring at {x,y}.
Possible options and their defaults values of Graphics are:
option default optional values

AspectRatio GoldenRatio any positive number
DisplayFunction $DisplayFunction Identity or Null to suppress display
Detach False True to run tdr asynchronously
Epilog {} List of primitives
Frame True False to erase outline, ticks, ticklabels.
FrameClick True to allow click on frame to change options.
FrameLabel {"","","",""} List of strings
FrameTicks {Both,Both,Ticks,Ticks}
None to turn off ticks and labels
Both to turn on ticks and labels
Ticks to turn on ticks only
<< For bottom tick >>
False is same as Ticks
True is same as Both
<< For top tick >>
False is same as None
True is same as Ticks
<< For left & right ticks >>
False is same as None
True is same as Both
If a form {___, _List} is given where
the List is a list of {coord, label, opt___}
label is displayed at coord with option opt.
If a form {___, fun} is given and
fun[coord,exp,org] returns a list of options
for Canvas[Create$Text], it is displayed at major
ticks at coord. exp is the exponent and org is the
original label.
GridLines Automatic Automatic to draw grid lines at major ticks
{Automatic,None} for only x
{None,Automatic} for only y
Both, Minor, and Major can be also used.
PlotLabel "" string
PlotRange Automatic {ymin,ymax} or {{xmin,xmax},{ymin,ymax}}
Prolog {} List of promitives
Scale {Linear,Linear} Log, Date
TickSize 1 relative size of ticks.
FrameThickness Automatic thickness of the frame line incl. ticks.
Options for primitives:
For Text:
option default optional values

TextAlign "" "CENTER"
TextCases "" string to represent CASES of TopDrawer
TextPosition "" "DATA" to represent the position by data
coordinates
TextRotate 0
TextSize 1 relative size of a character
PlotColor "Black" one of "White", "Black", "Red",
"Green","Blue","Yellow",
"Magenta","Cyan"
For Point
option default optional values

PointSize 1 relative size of a point
PointSymbol "1O" Symbol for PLOT of TopDrawer, or Bar
"6O","7O","8O","9O" are triangles
in CanvasDrawer.
PlotColor "Black" one of "White", "Black", "Red",
"Green","Blue","Yellow",
"Magenta","Cyan"
ErrorBarTickSize 1 length of error bar ticks.
For Line
option default optional values

Dashing "1" character string or a list of numbers to
represent the dashing of the line.
Plot True whether plot symbols at data points.
If True, PointSize and PointSymbol are
effective (see above).
PlotColor "Black" one of "White", "Black", "Red",
"Green","Blue","Yellow",
"Magenta","Cyan"
ErrorBarTickSize 1 length of error bar ticks.
Thickness 1 thickness of line
For Polygon
option default optional values

Plot False whether plot symbols at data points.
If True, PointSize and PointSymbol are
effective (see above).
PointSize 1 relative size of a point
PointSymbol "1O" Symbol for PLOT of TopDrawer, or Bar
"6O","7O","8O","9O" are triangles
in CanvasDrawer.
PointColor "forest green" point fill color.
PointBorderColor Automatic point border color.
Automatic measn PointColor.
PointTags Null points tag string or list of tag strings.
PlotJoined True whether plot border line of polygon.
Thickness 1 thickness of border line
Dashing "1" character string or a list of numbers to
represent the dashing of the line.
PlotColor "black" border line color.
LineTags Null border line tag string.
FillColor Null polygon fill color.
Null means empty polygon.
Tags False polygon tag string.
ListPlot accepts options for Graphics, Point, and Line. Show accepts
options for Graphics. The output is written to file #9 (fort.9 in OSF1 and
ftn09 in HPUX) in TopDrawer commands. If SAD is running on X, the plot is
also done immediately.
Examples:
g1=ListPlot[{{1,2},{10,20}},Scale>Log,PlotJoined>True,
DisplayFunction>Identity];
g2=ListPlot[{{1,15},{10,3}},Scale>Log,PlotJoined>True,Dashing>"1 0.3",
DisplayFunction>Identity,Plot>False];
g3=ListPlot[{{1,2.5},{5,10},{10,12}},Scale>Log,
DisplayFunction>Identity];
Show[g1,g2,g3,FrameLabel>{"X (mm)","Log(Y)"},PlotLabel>"Test Plot",
AspectRatio>1];

Usage: ListPlot[{{x1,y1},..,{xn,yn}}, options]
makes a graphic with points.
ListPlot[{y1,..,yn}, options] assumes 1,..n for the xxoordinate.
ListPlot[{{x,y,dy}, ..}, options ] plots error bars of length dy in y.
ListPlot[{{x,y,dx,dy}, ..}, options ] plots error bars in x and y.
option default optional values

PlotJoined False True
Step
StepRatio 1 ratio of stepping position
between two data points
Type ? to see other options for Graphics.

Usage: ColumnPlot[data, options, ...]
plots a column plot.
1) If data is a 1D vector, it makes a simple column plot.
2) If data is a 2D matrix, it makes a multiplecolumn plot.
3) If data is a 3D list, it makes a stacked, multiplecolumn plot.
Besides options common for all plotting functions, ColumnPlot has its own
options:
Option Value Default Action

ColumnOffset 0

Usage: HistoPlot[data, options, ...]
plots a histogram using ColumnPlot(default) or ListPlot.
Data can be a single list, or list of lists, which results in a multicolumn
histogram on a common axis.
Besides options common for all plotting functions and ColumnPlot, it has
its own options:
Option Value Default Action

Bins number Automatic number of bins
BinRange {min,max} Automatic Range of bins
PlotStyle ColumnPlot ColumnPlot plot function
ListPlot
FitPlot
Orientation Vertical Vertical orientation of columns
Horizontal
FitParameters args for FitPlot in a list

Usage: ListContourPlot[list, options, ...]
plots a coutour plot by list which is a 2D List of Real data.
Option Value Default Action

Contours Real 10 number of contoure
PlotRange {min,max} Automatic depth of contours
MeshRange {{x0,x1},{y0,y1}}
Automatic Range of x and y axes
AspectRatio Real 1
ColorFunction Function or String
Automatic Null or None means "white"
ContourColorFunction
Function or String
Automatic Null or None to hide
Example:
cf[x_]:=If[0.09{{4,4},{4,4}},ContourColorFunction>cf,
ColorFunction>Automatic, FrameLabel>{"x","y"}]

Usage: ListDensityPlot[list, options, ...]
plots a density plot by list which is a 2D List of Real data.
Option Value Default Action

PlotRange {min,max} Automatic depth of density
MeshRange {{x0,x1},{y0,y1}}
Automatic Range of x and y axes
AspectRatio Real 1
ColorFunction Function or String
Automatic Null or None means "white"
Mesh True or False False True to draw mesh
MeshColor Function or String
Automatic Null or None to hide
Example:
data = Table[Sin[x]/Cos[x^2 + y^2], {x, 2, 2, 0.1}, {y, 2, 2, 0.1}];
ListDensityPlot[data,PlotRange>{5,5}, MeshRange>{{2,2},{2,2}},
FrameLabel>{"x","y"}]

Usage: GeometryPlot[options]
plots a geometry of beam line.
options defaults

Region {1,LINE["LENGTH"]} {begin, end}, begin and end can be strings.
Both begin and end point of drawing region
could be given by "S" unit by using S[beginend] form.
Names "*" A pattern of component names to be plotted.

Usage: BeamPlot[loc, axes, options]
plots a beam ellipse at a location loc, for axes. Axes are given by a list
{ax, ay}, where ax and ay are one of "X", "PX", "Y", "PY", "Z", "DP".
The beam envelope should be calculated by (CODPLOT;EMIT) or BEAM commands before
BeamPlot.
options defaults

Orbit True Uses Twiss["DX",loc], etc. as the center of
ellipse.
SizeFunction "SIZE" If "SIG", LINE["SIG"] is used.
LINE["SIZE"] is the default.
AspectRatio 1
DataRange Default If Default, PlotRange becomes square for
axes = {"X", "Y"} or {"PX", "PY"}

Usage: OpticsPlot[fun_list, options]
makes a plot of builtin optical functions, userdefined functions, or
list of data at components on the beam line. The parameters are
fun_list: a list of objects to be plotted in a window.
The number of windows in a plot is the length of fun_list.
object plotted in a window MUST have same dimensions.
An element of fun_list is one of fun_label, fun, list_data or
a list as {object, options}, where
fun_label: one of "AX", "BX", "NX", "EX", "EPX", "DX", "DPX",
"AY", "BY", "NY", "EY", "EPY", "DY", "DPY", "R1", "R2", "R3",
"R4", "DETR","DZ","DDP","PEX", "PEPX", "PEY", "PEPY",
"GAMMA", "GAMMABETA","SIGab",
where a and b in "SIGab" are one of X, PX, Y, PY, Z, DP.
fun: Any function of the component number. A fractional number
may be used to obtain the intermediate value.
list_data: a list of {{pos1, val1}..{posn,valn}}.
options defaults

Region {1,LINE["LENGTH"]} {begin, end}, begin and end can be strings.
Both begin and end point of drawing region
could be given by "S" unit by using S[beginend] form.
Lattice True False to turn of drawing lattice
LatticeRegion Automatic {low,high}, the region where lattice is drawn
FrameHeight Automatic List of relative heights of each frame
InfoLabel False If True, pressing Button shows Twiss, etc.
Names "*" A pattern of component names to be plotted.
Tags False True to attach tags "C$"//(component name)
to each rectangle for the lattice, and
"L$"//(component name) to the component
label (CanvasDrawer only).
Legend False If Automatic, Legend is composed from FrameLabel
Automatically.
options in a fun_list element:
options defaults

Unit 1 Unit of the object. "Meter", "InvMeter",etc.
FrameLabel "" Left frame label.
Legend False If Automatic, Legend is composed from FrameLabel
Automatically.
Example:
p2=OpticsPlot[
{{"BX","BY"},
{"DX",{{{10,0.001},{20,0.002}},FrameLabel>"DX meas.",
Unit>Meter}}}];

Usage: FitPlot[data, fun, var, {par1,ini1}, .. , {parn, inin}, opt].

Usage: Plot[fun, range, options] or Plot[{fun1, .. }, range, options],
where fun is a function and range is a list given as {x, xmin, xmax}.
options defaults

MaxBend 0.04
PlotPoints 25
PlotDivision 250
Dashing {"1","0.8 0.24","0.4 0.12","0.2 0.08","0.1 0.08",
"0.8 0.08 0.08 0.08","0.4 0.08 0.08 0.08"}
Options for ListPlot and Graphics are also available
The independent variable should have been cleared (i.e., no value should
not be set) when Plot is called.
Example: Plot[{Cos[x],Check[Sin[x]/x,1]}, {x,0,10}]


Forks the process into a parent and a child processes.
Fork[]
returns 0 and the pid of the child for the child and the parent, respectively.

Allocated shared memory of n bytes.
s = OpenShared[n] ,
where s is a file number to be used by Shared function.
The allocated memory can be released by Close[s].

Read/Write to the shared memory.
Shared[s]
Shared[s] = x
Shared[s] := x
where s is given by OpenShared, and x is Real, builtin function,
String, defined symbol, or list of them.

Returns the size of an object for OpenShared.
n = SharedSize[x]

Environment for an objectorientedprogramming is supplied by:
Class: The function to define a class.
context: A class defines a context to define its all symbols for
the variables and methods within the context.
This automatically avoids conflicts of symbols between
classes, Global, and System. When c = Class[ ... ] is
done, a context c` is defined.
members: The set of Members of a class is a union of class variables,
instance variables, and class methods of the class.
operator @: A special operator to access class member. In a notation
f@g, g's context defaults the class of the class of f.
f@g@h[x] is recognized as ((f@g)@h)[x] , thus the context of
h defaults the class of f.
superclasses: A class inherits all class variables, instance variables,
class methods from its superclasses which are give by the
first argument of Class. If a null list is given, Object`
is set as the default superclass. Multiple inheritance is
allowed.
class variable: Class variables are given by the second argument of Class
as a list of symbols. They are unique in the class.
They can be initialized by declaring in a way such as
{a=1, {b, c} = {2, 3}} like Module. A form like
{a = b = c =1} is allowed.
instance variable:
Instance variables are given by the third argument of Class
as a list of symbols. An instance has those symbols
separately. They can be initialized by declaring in a way
such as {a=1, {b, c} = {2, 3}} like as Module. A form like as
{a = b = c =1} is allowed. Also they
are initialized at the creation of instance by rules as
x = c[ a>1, b:>Print[d]], etc.
class methods: Class methods are given by the fourth(last) argument of
Class. They must be in the form of either one of
f_[arg___] := g_;
With[_, f_[arg___] := g_];
With[_, f_[arg___] := g_; .. ];
If[_,
ft_[argt___] := gt_; ..,
ft_[argf___] := gf_; ..,];
h_[f_[arg___], b___] ^:= g_; .
where f is the symbol for the method to be defined.
Set may be used instead of SetDelayed if necessary.
This: A symbol This in the definition of the method, it is
translated to the object (the instance or the class) which
refers the member.
default reference:
In the definition of the class methods, whenever a member of
the class is appeared, it is recognized as This@member.
When a symbol of the member conflicts the symbol in System`,
the system symbol should be wrapped by Literal.
reference of member of superclasses:
Members of the superclasses (denote cc) are referred by
cc`member in the definition of the method.
copying an instance:
An instance c of a class can be copied to another symbol
by c1 = c. After the copying, c1 and c refer the identical
instance. Destructing one of them by such as c1=. clears
the instance and also all the assigned symbols.
Constructor: When an instance is defined, by x = c[arg], a method
x@Constructor[arg] is always invoked.
In evaluation of instance definition under class scope,
class member symbol appeared 1st slot of Rule or RuleDelayed
argument is sent to Constructor of new class instance
without evaluation. (In other term, class member symbol on
1st slot of Rule or RuleDelayed argument behaves like
evaluating with implicit Literal[]) One can configure
Constructor[] in the definition of the class.
x = c[arg] returns the returned value of Constructor[arg].
The rules in the argument work in two ways: (1) A rule for an
instance variable or a class variable sets the initial value
of the variable, (2) Other rules are stored in an instance
variable Options as a list.
Destructor: An instance x is cleared by (x=.), which invokes
x@Destructor[]. The default Destructor is Object`Destructor,
but one can reconfigure it in the definition of the class.
Short: When an instance x is returned as the result of expression
for Out[], x@Short[] is invoked to show the result. The
default Short is Object`Short, but one can reconfigure it
in the definition of the class.
other methods: Class[] gives the class of the instance.
Parents[] gives the immediate superclasses.
AllParents[] gives the all superclasses.
Members[] gives a list of class variables, class methods,
and instance variables of the class.
AllMembers[] gives a list of class variables, class methods,
and instance variables of the class and its all parents.

Class sets up a class of objects.
Usage: a = Class[
list of superclasses,
list of classvariables,
list of instancevariables,
classmethods];
Example: a = Class[
{aa, bb}, (* aa and bb are superclasses *)
{a1, a2}, (* classvariables *)
{v1, v2}, (* instancevariables *)
Constructor[arg__] := (Print[{arg}]; v1 = Plus[arg]);
sum[] := v1 + v2 (* defining Constructor and method "sum"*)
];
a1 = a[1, 2] (* creating an instance of a *)
a1@v1 (* accessing an instance variable *)
a1@v2 = 3 (* setting an instance variable *)
a1@sum[] (* calling a method "sum" *)
a1=. (* delete an instance *)

The random number functions use common seed given by SEED command or
SeedRandom function. It has an initial value 17 at the beginning of FFS.
The cutoff value of GaussRandom[] is given by variable GCUT.

Random[] gives a uniform random number between 0 and 1.
Random[n] gives a list of n uniform random numbers.
Random[n1, n2, ..] gives a (n1 * n2 * .. ) tensor of uniform random numbers.

GaussRandom[] gives a Gaussian random number with average 0,
standard deviation 1, cutoff at GCUT.
GaussRandom[n] gives a list of n Gaussian random numbers.
GaussRandom[n1, n2, ..] gives a (n1 * n2 * .. ) tensor of Gaussian random
numbers.

ParabolaRandom[] gives a parabola random number between 1 and 1.
ParabolaRandom[n] gives a list of n parabola random numbers.
ParabolaRandom[n1, n2, ..] gives a (n1 * n2 * .. ) tensor of parabola random
numbers.

SeedRandom[plugin_String] selects new pseudo randomnumber generator
plugin named as plugin.
SeedRandom[seed_Real] initializes the internal state of the current
pseudo randomnumber generator plugin by seed.
SeedRandom[{seeds__Real}] initializes the internal state of the current
pseudo randomnumber generator plugin by {seeds}.
SeedRadnom[state_List] restores both the selection of the pseudo randomnumber
generator plugin and the internal state of the selected
plugin by using state dumped by SeedRandom[].
SeedRandom[] returns List containing both the current selected pseudo
randomnumber generator plugin name and its internal state.

ListRandom[] returns List of available pseudo randomnumber generator plugins.



DateString[] returns the current date and time as string
"mm/dd/CCYY HH:MM:SS".
DateString[date] converts date to string as above. The date can be either
a real number (in second, date=0 is 1/1/1900 0:0:0) or a list of
6 reals {Y,m,d,H,M,S}.
Usage: (1) FIT [component]
(2) FIT component1 component2
sets the current location where the matching condition is applied.
The component is given with the form name[.order][{+}offset] (see
components). If component is omitted, the end of the beam line is chosen.
If two components are given, it means a relativefitting or zonefitting.
If the fitting condition is not maximumfitting, the condition means to
make values at two components equal (for AX, BX, AY, BY, EX, EPX, EY, EPY,
R1, R2, R3, R4, DX, DPX, DY, DPY, PEX, PEPX, PEY, PEPY, CHI1, CHI2, CHI3),
or have the specified difference (for NX, NY, LENG, GX, GY, GZ).
If the fitting condition is maximumfitting, the condition means a
zonefitting (for AX, BX, AY, BY, EX, EPX, EY, EPY, R1, R2, R3, R4, DX, DPX,
DY, DPY, PEX, PEPX, PEY, PEPY, CHI1, CHI2, CHI3), which
suppress the maximum of the function in the region between component1 and
component2, or maximumfitting for the difference of the function (for NX,
NY, LENG, GX, GY, GZ).
The fit region is shown in the first part of the prompt when FFSPRMPT is
ON.
Example: (1) FIT QF.210
sets the current fit point at 10 components upstream from the entrance of
the second QF.
(2) FIT QF QD NX 0.5 BXM 10
sets the twopoint fitting between QF and QD, then set the difference of NX
between QF and QD to be 0.5, and the maximum of BX to be 10 in the region
between QF and QD.
FITP n sets n to the number of offmomentum points in the offmomentum
matching. If the fitting condition is onmomentum only, it is not affected.
Usage: (1) FIX elementpattern [keyword] [elementpattern1 [keyword1]..]
removes elements which match elementpattern from the matching variables.
The optional keyword specifies the nondefault variables. If the keyword
is omitted, all keywords are removed.
For the MARK element at the beginning of the beam line, a special form
can be used for the FIX command. That is a form I
(appending "I" to a matchingfunction name).
Example: FIX AXI BXI AYI BYI
removes incoming AX, BX, AY, and BY from the matching variables.
Usage: (2) FIX
sets the standard optics for the orbit correction commands.
Usage: FREE elementpattern [keyword] [elementpattern1 [keyword1]..]
specifies elements which match elementpattern as the matching variables.
The optional keyword specifies the nondefault variables. See
defaultkeyword.
For the MARK element at the beginning of the beam line, a special form
can be used for the FREE command. That is a form I
(appending "I" to a matchingfunction name) which means the incoming
condition of the matchingfunction is varied in the matching.
Example: FREE AXI BXI AYI BYI
changes incoming AX, BX, AY, and BY to find the solution.

The default and available nondefault variable keywords are:
type defaultkeyword nondefault variable keyword
DRIFT L 
BEND ANGLE K1,K0,E1,E2
QUAD K1 ROTATE
SEXT K2 ROTATE
OCT K3 ROTATE
DECA K4 ROTATE
DODECA K5 ROTATE
MULT K1 K0,K2..K21,SK0,SK1,SK2..SK21,ROTATE,ANGLE
MARK  AX,BX,EX,EPX,AY,BY,EY,EPY,R1,R2,R3,R4,DX,DPX,DY,DPY
DZ,DDP
Available geometricalfunctions are:
GX geometrical coordinate xi
GY geometrical coordinate eta
GZ geometrical coordinate zeta
CHI1 geometrical rotation angle ch1_1
CHI2 geometrical rotation angle ch1_2
CHI3 geometrical rotation angle ch1_3
The geometrical coordinate {xi, eta, zeta} is set by the ORG command, and
its default origin is at the entrance of the beam line, and the default
directions are xi in sdirection, eta in (xdirection), and zeta in
(ydirection) at the entrance. The set {xi, eta, zeta} forms a righthand
system.
The rotation angles are defined so as to give the local {x,y,s} is
written
{x, y, s}_local
= rotate[s, chi3] rotate[x, chi2] rotate[y, chi1]{x, y, s}_origin,
where rotate[a, b] reads "rotate around the newa vector by b
righthandedly".
prints out the TopDrawer commands for the geometric plot of the beam line.
Usage: GO [[NO]EXPAND]
Does matching for fitting conditions given by matchingfunctioncommands
with variables specified by FREE.
If an option EXPAND is given (default), it expands the beam line before the
calculation. If NOEXPAND is given, it avoids any expansion.
FFS["CAL"] and FFS["GO"] returns the result as a list, whose format
is
{dp, kind, reslist, functionvalues},
where
dp: a list contains dp/p0 .
kind: a list of kind of the orbit (ususally 0, but 1 to 6 for the
finite amplitude matching, see specialvariables:MatchingAmplitude).
reslist: a list of {residual, xstab, ystab}, where
residual: matching residual,
xstab: True when the matrix is stable in X,
ystab: True when the matrix is stable in Y, for each orbit.
Above are lists with length nf (== number of orbits).
functionvalues: a list of length nc (== number of calculated items). Each
element has the form:
{component1, component2, function, listofvalues},
where
component1, component2: fit locations (see FIT).
function: name of the function (see matchingfunctioncommands).
listofvalues: list of the value of the function for each orbit.
Length nf.
The central orbit comes at the Floor[(n+1)/2]th element.
Usage: IF expr1 body1 [ELSEIF expr2 body2 [ELSEIF ..]] [ELSE body3] ENDIF
This is a FORTRAN77 like IFstructure. If the expression expr1 is
True(==1) or nonzero, executes commands in body1. If it is False(==0), skip
commands until ELSE, ELSEIF or ENDIF appears at the same level of the
IFstructure, and executes commands after ELSE or ENDIF, or executes the
ELSEIF command. If expr1 is not a real number, an error message is printed
and ignores the command line.
IN {filename  filenumber} switches the input stream to the specified
file or the filenumber. The original stream is kept and to be returned
by TERMINATE(TERM). The input file is not rewound.
Usage: machineerrorcommand [options] amount componentpattern ..
where machineerrorcommand is one of
command keyword affected applicable types
DELX DX BEND QUAD SEXT OCT DECA DODECA SOL CAV
DELY DY BEND QUAD SEXT OCT DECA DODECA SOL CAV
DL L DRIFT SOL
DTHETA ROTATE QUAD SEXT OCT DECA DODECA CAV
DTHETA DROTATE BEND
DK defaultkeyword DRIFT BEND QUAD SEXT OCT DECA DODECA MULT SOL CAV
DDK K0 or DBZ BEND SOL
amount is the amount of the error,
componentpattern is the pattern to specify the components to be applied.
Options are
RANDOM(R) Set amount*GaussRandom[] to the keyword.
UNIFORM(U) Set the specified amount to the keyword without random number.
INCOHERENT(INC) GaussRandom[] is called for each component. Default.
COHERENT(C) GaussRandom[] is called once for each componentpattern.
PUT(P) Set the error to the keyword. Default.
ADD(A) Add the error to the keyword.
Usage: (1) matchingfunction goalvalue [offmomentumpoints]
(2) matchingfunctionM goalvalue [offmomentumpoints]
(3) matchingfunctionI incomingvalue
(4) matchingfunctionSCALE scale
(1) sets the matching condition for matchingfunction at the current
fitting point or region with the goalvalue and the
offmomentumpoints (see offmomentummatching).
If offmomentumpoints is omitted, the previous value for this
matchingfunction at this fittingpoint is assumed. If the previous value
is not defined, 1 is assumed. If 1 is given for offmomentumpoints,
the matchingfunction is rejected from the matching (see REJECT(REJ)).
If "*" is given for goalvalue, the previous value is used if exists.
Example: BX 10 3 (beta_x to be 10 at 3 momenta)
BX 20 (now beta_x to be 20 at 3 momenta (previous setting))
BX * 5 (now beta_x to be 20 (previous setting) at 5 momenta)
(2) If the letter "M" is appended to matchingfunction, it means the
maximumfitting for the function. The maximum of either the value (for
positivedefinite functions) or the absolute value (for bipolar functions)
are to be limited in the matching.
(3) If the letter "I" is appended to matchingfunction, it specifies
the value of the incoming beam.
(4) If SCALE is appended to matchingfunction, it sets the scale of
the input/output of the function to scale. This scale is used in the
matchingfunction commands, DISPLAY(DISP), SHOW, etc.
Available matchingfunctions are:
opticalfunctions (see opticalfunctions):
AX BX NX AY BY NY EX EPX EY EPY R1 R2 R3 R4 DX DPX DY DPY DZ DDP
PEX PEPX PEY PEPY TRX TRY LENG
geometricalfunctions (see geometricalfunctions):
GX GY GZ CHI1 CHI2 CHI3
The multiturn tracking can be done by the TRACK command of the MAIN
level, the TRACK command in FFS, or the DynamicApertureSurvey[] function
in FFS. The latter only perform the DAPERT mode.
The multiturn tracking uses the closed orbit, normal coordinate, and
the equilibrium emittances. Therefore One of EMITTANCE(EMIT), the
Emittance[] function, or the EMIT command in the MAIN level are necessary to
be done once in prior to the multiturntracking. The values of EMITX,
EMITY, EMITZ, SIGE can be changed between EMITs and the multiturntracking.
Usage: MATRIX [{SYMPLECTIC(S)  PHYSICAL(P)}] [from to]
prints out the 4 by 5 transfer matrix from fromcomponent to tocomponent.
If SYMPLECTIC(S) is specified (default), the symplectic transfer matrix on
{x,px/p0,y,py/p0,dp/p0} where p0 is the nominal momentum at the entrance,
is given. Otherwise, in the case of TRPT, the transfer matrix on
{x,px/p0(s),y,py/p0(s),dp/p0(s)} is printed out.
If the from and to components are omitted, entire beam line is assumed.
If tocomponent is upstream the fromcomponent, it gives the inverse matrix
(TRPT) or oneturnwrapped matrix (RING).
Usage: MEA [endcomponent] [OUT file plotspaces]
tracks particles from the entrance to endcomponent and prints out the
statistics at the end. If endcomponent is omitted, the component end
used in the last MEASURE(MEA) (default: end of the beam line) is assumed.
If OUT file plotspaces are attached, it plots phase space
disribution on file. The phasespaces are specified like as XPX,
or XY, etc., (up to any numbers).
Parameters for the tracking are specified by specialvariables and flags:
seed for the randomnumber generator:
SeedRandom[seed_Real] or SeedRandom[{seeds__Real}]
specialvariables (can be set with =):
NP number of particles
EMITX horizontal emittance
EMITY vertical emittance
DP relative momentum spread
DP0 relative momentum offset dp/p0
GCUT cutoff value of the Gaussian tail
flags:
GAUSS/UNIFORM Gaussian/uniform(default) momentum distribution
JITTER/NOJITTER off(default)/on nullifying the incoming centroid offset
RFSW/NORFSW switch on(default)/off the rfcavities
RAD/NORAD synchrotron radiation on/off
RADCOD/NORADCOD off/on compensation of energy loss due to radiation
FIXSEED/MOVESEED keep(default)/unkeep the initial randomnumber seed
The initial transverse distribution is Gaussian.
FFS matches the optical functions for an orbit with finite momentum
deviation.
Example:
DP=0.01; sets the range of momentum to DP00.01 < dp/p0 < DP0+0.01 .
BX 10 9; sets the goal of betax to 10 m, at 9 points.
in the range above, i.e.,
dp/p0 = {0.01,0.0075,0.005,0.0025,0,
0.0025,0.005,0.0075,0.01} + DP0 .
GO starts the matching.
As this example, the offmomentum points are chosen with equal separation.
If the offmomentum point n is an even number, the chosen points are same as
the case of n+1, but the onmomentum point (==DP0) is excluded.
Available optical functions for matching are:
AX alpha_X
BX beta_X
NX psi_X, the default scale is 1/(2Pi)
AY alpha_Y
BY beta_Y
NY psi_Y, the default scale is 1/(2Pi)
EX eta_X (dispersion_X)
EPX eta_Px (dispersion_PX)
EY eta_Y (dispersion_Y)
EPY eta_Py (dispersion_PY)
R1 R_1 (see xycoupling)
R2 R_2 (see xycoupling)
R3 R_3 (see xycoupling)
R4 R_4 (see xycoupling)
DX dx
DPX dpx
DY dy
DPY dpy
DZ dz
DDP delta=dp/p0
PEX eta_x (dispersion_x)
PEPX eta_px (dispersion_px)
PEY eta_y (dispersion_y)
PEPY eta_yy (dispersion_py)
TRX trace(T_X), only defined at the end of the beam line.
TRY trace(T_Y), only defined at the end of the beam line.
LENG length of the design orbit
In the above, upper case X, Px, Y, Py represents the xy decoupled
coordinate. EX, EPX, EY, EPY refer the decoupled coordinate, while
PEX, PEPX, PEY, PEPY are in the physical coordinate. On the other hand,
DX, DPX, DY, DPY refer the physical coordinate.
OUT {filename  filenumber} switches the output stream to the specified
file or the filenumber. The file is written from the beginning.
PRI expression evaluates expression and prints out the result.
Exits FFS and return to SAD/MAIN level, without saving the values of
the elements.
RADINT prints out the radiation integrals involving the xcoupling
for all components of the beam line.
READ {filename  filenumber} switches the input stream to the specified
file or the filenumber. The original stream is kept and to be returned
by TERMINATE(TERM). The input file is rewound.
REC exchanges the values of FREEd elements with those when the last
GO command was issued. FIXed elements are not affected.
Usage: (1) REJ matchingfunctionpattern [matchingfunctionpattern1..]
(2) REJ TOTAL
(3) REJ TOTALFIT
rejects the matchingfunctions which match matchingfunctionpattern at the
current FIT location. If TOTAL or TOTALFIT is given, the entire matching conditions in
all locations are rejected, then output parameters by CALCULATE are reset when TOTAL
is given.
Usage: REP [n] body UNTIL [expr1]
executes commands in body n times until expr1 gives nonzero. The number n
can be any expression which gives a number. If n is omitted, infinity is
assumed. If expr1 is omitted, False(==0) is assumed.
Usage: RESET [ALL] [elementpattern]
restores the value of the elements. What are restored are the value
of the default keyword of all elements, the values of the nondefault
keywords which have been changed manually or by the matching. If ALL
is given, it resets all keywords. If elementpattern is given, reset is
limited to the elements which match the pattern.
REV changes the sign of AX, AY, EPX, EPY, R2, R3, DPX, DPY at the
entrance of the beam line.
Usage: elementpattern [keyword] [{MIN  MAX  MINMAX  MAXMIN}] value
sets value to the specified keyword of the elements which match
elementpattern. If keyword is omitted, the defaultkeyword is assumed.
If MIN, MAX, MINMAX, MAXMIN are specified, it sets the limit of the
defaultkeyword. Both MINMAX and MAXMIN means MIN=Abs[value] and
MAX=+Abs[value].
If the keyword is not the defaultkeyword, it affects both the current
and the saved value.

Available keywords are:
type keywords
DRIFT L RADIUS
BEND L ROTATE DROTATE DX DY ANGLE K0 K1 E1 E2 AE1 AE2
F1 FB1 FB2 FRINGE DISFRIN
DISRAD EPS RANKICK
QUAD L ROTATE DX DY K1 F1 F2 FRINGE DISFRIN DISRAD EPS
SEXT L ROTATE DX DY K2 DISFRIN DISRAD
OCT L ROTATE DX DY K3 DISFRIN DISRAD
DECA L ROTATE DX DY K4 DISFRIN DISRAD
DODECA L ROTATE DX DY K5 DISFRIN DISRAD
MULT L DX DY DZ CHI1 CHI2 ROTATE(=CHI3) K0..K21 SK0..SK21
DISFRIN F1 F2 FRINGE DISRAD EPS VOLT HARM PHI DPHI FREQ
RADIUS ANGLE E1 E2 AE1 AE2 DROTATE
SOL BZ DX DY DZ DPX DPY BOUND GEO CHI1 CHI2 CHI3 DBZ DISFRIN
CAVI L ROTATE DX DY VOLT V1 V20 V11 V02 FREQ PHI HARM RANVOLT RANPHASE
DISFRIN FRINGE
TCAVI L ROTATE DX DY K0 V1 FREQ PHI HARM RANKICK RANPHASE
COORD DX DY CHI1 CHI2 CHI3 DIR
MARK AX BX AY BY EX EPX EY EPY R1 R2 R3 R4 DX DPX DY DPY DZ DDP
EMITX EMITY DP AZ SIGZ GEO OFFSET
APERT DX1 DX2 DY1 DY2 DP AX AY DX DY

The default and available nondefault variable keywords are:
type defaultkeyword nondefault variable keyword
DRIFT L 
BEND ANGLE K1,K0,E1,E2
QUAD K1 ROTATE
SEXT K2 ROTATE
OCT K3 ROTATE
DECA K4 ROTATE
DODECA K5 ROTATE
MULT K1 K0,K2..K21,SK0,SK1,SK2..SK21,ROTATE,ANGLE
MARK  AX,BX,EX,EPX,AY,BY,EY,EPY,R1,R2,R3,R4,DX,DPX,DY,DPY
DZ,DDP
There are predefined special symbols in FFS:
symbol value
True 1
False 0
Infinity INF
INF INF
NaN NaN
Pi ArcSin[1]*2
E Exp[1]
I Complex[0,1]
Degree Pi/180
GoldenRatio (1+Sqrt[5])/2
SpeedOfLight 299792458
There are several variables which have special rolls in FFS. Some
of them are also accessible in the MAIN level.

$FORM is a characterstring to specify the format of the output of a real
number.
Usage: $FORM="w.f"
$FORM="Sw.f"
$FORM="Fw.f"
$FORM="Mw.f"
where w is the width of the output, and f is the length of the fractions.
If S is attached, trailing zeroes are omitted. If F is attached, it becomes
same as FORTRAN's Fformat. If M is attached, the exponent is expressed as 10^n.
If w and f are omitted, 17.15 is assumed.
The default is S17.15 .

CASE is a characterstring to be attached with TITLE to issue
the CASE command of TopDrawer in DRAW or GEO commands.

CHARGE contains the charge of the particle. The default is +1.
Currently many parameters such as VOLT, BZ, etc. are not consistent with
CHARGE<>1 . Do not change CHARGE.

CONVERGENCE is the goal of the convergence(==MatchingResidual) in the
matching. If MatchingResidual becomes smaller than CONVERGENCE times the
effective number of the conditions, the matching by GO terminates. The
flag CONV is set when MatchingResidual is smaller than CONVERGENCE after
GO or CALCULATE(CAL). The default value is 10^9.

DAPWIDTH is the width of the xamplitudes to quit the tracking to judge
the aperture is enough.

DP represents the relative momentum spread of the beam.
It is automatically set by the keyword DP of the MARK element at the
beginning of the beam line. The value of EMITY affects the default
weight of variables in the matching. In the offmomentum matching, the
range DP0  DP < dp/p0 < DP0 + DP is used for the matching. The assumed
momentumdistribution in the BEAMSIZE(BEAM), MEASURE(MEA), etc. commands,
is Gaussian with the standard deviation DP and the mean DP0 if the flag GAUSS
is on, otherwise uniform (square) in the range DP0  DP < dp/p0 < DP0 + DP.

DP0 represents the central value of the relative momentum offset
in the optics calculation, or the center of the momentum distribution of
the beam. The onmomentum optics has the relative momentum deviation
dp/p0 == DP0, and the offmomentum calculation is done in the range
DP0  DP < dp/p0 < DP0 + DP.

Shift of the origin of z of the closed orbit (default: 0). Set by EMITTANCE or
Emittance[]. Effective with RING only.

Ratio of (effective voltage)/(Sum[VOLT_k,{k}]) (default: 1),
where effective voltage V_eff is defined as
V_eff = Sqrt[(Sum[VOLT_k Cos[PHI_k],{k}])^2 + (Sum[VOLT_k Sin[PHI_k],{k}])^2] .
EFFVCRATIO is set by EMITTANCE(EMIT) or Emittance[]. Effective with RING only.

ElementValues is a symbol to assign rules to determine values of keywords
of elements or components. This is used to give a dependence between
keywords of different elements or components, or determine then by a
parameteric expression.
Useage: ElementValues = { key[elem] :> expr, ...}
where
key: keyword to specify a value (string).
elem: String to specify the elements or components,
wildcards are allowed.
expr: an expression which returs a real number to be set to
the elements or components.
Example: ElementValues =
{ "DX"["QF1"] :> "DX"["QD1"]0.001,
"DY"["QF2.3"] :> "DY"["QD1.2"],
"ROTATE"["QF*"] :> f[x] }
Remarks:
1. Iff elem contains ".", it is recognized as components, otherwise as
elements.
2. In the r.h.s. of the rule, an expression like key[elem] is evaluated as
either LINE[key, elem] or Element[key, elem], depending on elem has ".".
3. The expression expr can be any expression returning a real number.
4. Later rules overrides the former, if many rules apply on the same keyword
of the same element.
5. The rule given by ElementValues overrides the relation given by
COUP_LE command.
6. Use a[b] in stead of a@b.

EMITX is a real variable for the horizontal physical emittance.
It is automatically set by the keyword EMITX of the MARK element at the
beginning of the beam line. The EMITTANCE(EMIT) command returns its
calculated value in EMITX. The value of EMITX affects the default
weight of variables in the matching. Accessible in MAIN.

EMITXE specifies the minimum horizontal emittance for EMITTANCE(EMIT)
and Emittance[] calculations. It is useful to give emittance
determined externally, such as for proton machines.

EMITY is a real variable for the vertical physical emittance.
It is automatically set by the keyword EMITY of the MARK element at the
beginning of the beam line. The EMITTANCE(EMIT) command rerns its
calculated value in EMITY. The value of EMITY affects the default
weit of variables in the matching. Accessible in MAIN.

EMITYE specifies the minimum vertical emittance for EMITTANCE(EMIT)
and Emittance[] calculations. It is useful to give emittance
determined externally, such as for proton machines.

EMITZ is a real variable for the longitudinal physical emittance.
It is automatically set by the keyword EMITZ of the MARK element at the
beginning of the beam line. The EMITTANCE(EMIT) command rerns its
calculated value in EMITZ. Accessible in MAIN.

EMITZE specifies the minimum longitudinal emittance for EMITTANCE(EMIT)
and Emittance[] calculations. It is useful to give emittance
determined externally, such as for proton machines.

If False (default), the calculation of response matrix for each matchingvariables usus analytical expressions as much as possi
ble. If True, it ussenumerical difference, which is faster than analytic especially when thereare many coupled variables defined by
ElementValues.

FitFunction is a symbol to assign userdefined functions for
matching with the GO command.
Usage: FitFunction := fun,
where fun is a function that returns a real number or a list of real
numbers, to be matched to zero by GO. The goal of GO is to make fun zero
or a list of zeros, together with builtin matching conditions. Thus the sum of
fun^2 is added to MatchingResidual. GO also evaluates FitFunction to obtain the
derivatives numerically. The function fun can refer the value of variables
by Element or LINE functions, and the optical functions at DP0 by Twiss.
The algorithm of matching is same as that for builtin conditions, but
it is slower because of the numerical differentiation, when the beam line
is long and the number of variables large.
Example: FitFunction := {Twiss["BX","$$$"]20, Twiss["BY","$$$"]20};
which puts the same goal as
FIT $$$ BX 20 BY 20 .

FSHIFT is the relative shift df/f0 of the revolution (or rf)
frequency in a ring. This is only valid in EMITTANCE(EMIT) or the
particletracking. In the optics calculation DP0 should be used instead.

GCUT specifies the cutoff value of Gaussian distribution in unit of
the standard deviation. Accessible in MAIN.

Usage: InitialOrbits = { {x1, px1, y1, py1, z1, dp1}, ...};
or InitialOrbits = { {ax1, bx1, nx1, ay1, by1, ny1,
ex1, epx1, ey1, epy1, r11, r21, r31, r41,
x1, px1, y1, py1, z1, dp1, 0, 0, 0, 0, 0, 0, 0}, ...};
specifies initial conditions of a number of orbits for the optics
calculation by CALCULATE(CAL) and GO. Those coordinates are offset from
the central orbit. If six numbers are given, only the offsets of the
orbits are affected. If 27 numbers are given, all Twiss parameters are
set (values for nonorbit params are used directly. Orbits are giving offsets.)
If InitialOrbits are given, the offmomentum matching and
finiteamplitude matching is disabled.
InitialOrbits is also necessary to calculate optics with wake field.

LOSSAMPL is the transverse amplitude beyond which a particle is judged
to have been lost. The default is 1 m. Accessible in MAIN.

LOSSDZ is the longitudinal position z beyond which a particle is judged
to have been lost. The default is 100 m. Accessible in MAIN.
LOSSDZ is effective only when SPAC is ON.

MatchingAmplitude is a list of amplitudes for the finiteamplitude matching.
Usage: MatchingAmplitude := { {dp1,x1,y1}, ..};
where dp1 is the momentum deviation to be matched, x1 and y1 are the
horizontal and vertical amplitudes at the beginning of the beam line,
normalized by Sqrt of the sum of the emittance, i.e., Sqrt[(EMITX+EMITY)].
Three orbits are chosen in each dimension. The initial conditions
of the orbit is chosen as
{X,Px,Y,Py} =
{ {x1,0,0,0}, {x1/2,Sqrt[3]/2 x1,0,0}, {x1/2,Sqrt[3]/2 x1,0,0},
{0,0,y1,0}, {0,0,y1/2,Sqrt[3]/2 y1}, {0,0,y1/2,Sqrt[3]/2 y1} },
and when x1==0 or y1==0 corresponding orbits are excluded. The above
are labeled {x1,x2,x3,y1,y2,y3} in the output of CALCULATE(CAL) or GO,
and also labeled 1 to 6 in the second element of FFS["CALC"] and
FFS["GO"].
This matching is done when dp1 is within the offmomentum range given by
DP, i.e., Abs[dp1] < DP. If dp1 is in the range, the nearest zero
amplitude optics is chosen. The maching conditions for the finite
amplitude optics are same as those for the zeroamplitude one.
Th orbit with finte initial condition never close after one revolution,
but FFS simply ignores it and obtain the periodic optics around the open
orbit.

MatchingResidual holds the convergence in the last GO or
CALCULATE(CAL) commands. It is calculated by
sw*(Sum[(w_i*df_i)^ExponentOfResidual,{i}]/sw)^(2/ExponentOfResidual)
+penalty
where w_i is the weight of the ith condition, df_i is the differe�ce of
the ith function from the goal, penalty is an additional big number
(typically 10), when the optics is unstable or closed orbit is not found in
the case of CELL. The parameter sw is defined as
sw=Sum[(OffMomentumWeight/2/woff)^2,{i}]
with
woff = 1 for onmomentum optics
= Sqrt[numberofmomentumpoints] for offmomentum optics.
The weight of the function is lighter in the case of offmomentummatching
so that all offmomentum deviations functions weight equal to the
onmomentum one. However, the relative weight for the offmomentum part
can be changed by setting OffMomentumWeight.
The weight of each function at each point with each momentum can be
specified by defining the FitWeight function.

MASS is the rest mass of the particle. The default is electron mass.

MINCOUP is the minimum emittance ratio (EMITY/EMITX) to be assumed in the
calculation of intrabeam effects in EMITTANCE(EMIT). Accessible in MAIN.

MOMENTUM is the nominal momentum of the beam line at the entrance
in eV. Accessible in MAIN.

NBUNCH is the number of bunches for the calculation of
WakeFunction. Accessible in MAIN.

The net residual of convergence except the penalty for unstable optics.

NP is the number of particles in the tracking. Accessible in MAIN.

Relative weight of the offmomentum deviation for the offmomentum
matching. The default is 1.

OMEGA0 is 2*Pi*SpeedOfLight/LINE["s","$$$"] . Accessible in MAIN.

OpticsEpilog is a variable to assign a userdefined function which is to be
executed everytime after an optics calculation is done in CALCULATE(CAL)
or GO commands. In GO, OpticsEpilog is called at the end of each
iteration. This function is useful, for instance, for setting parameters
which depends on the result of optics calculation itself.

OpticsProlog is a variable to assign a userdefined function which is to be
executed every time before an optics calculation is done in the CALCULATE(CAL)
or GO commands. In GO, OpticsProlog is called at the beginning of each
iteration. This function is useful, for instance, for setting parameters
which depends on the result of optics calculation itself.

PageWidth is the number of columns of the output. The default is set from
GetEnv["WIDTH"].

PBUNCH is the number of particles/bunch for the calculation of the
intrabeam and space charge effects in EMITTANCE(EMIT), and WakeFunction.
Accessible in MAIN.

When PHOTONS is ON (default is OFF), TrackParticles generates a list of all
photons radiated through the tracking. The list is assigned to a symbol PhotonList.
PhotonList is a list of
{en, gx, gy, gz, nx, ny, nz, xi1, xi2, xi3, np, nele}
where
en: photon energy [eV]
gx: GX coordinate of the emission point [m]
gy: GY coordinate of the emission point [m]
gz: GZ coordinate of the emission point [m]
nx: GX component of the photon direction vector
ny: GY component of the photon direction vector
nz: GZ component of the photon direction vector (nx^2+ny^2+nz^2)=1.
xi1: Stokes' parameter for polarization 45 degree to the GZ=0 plane.
xi2: Stokes' parameter for righthanded polarization
xi3: Stokes' parameter for polarization in the GZ=0 plane.
np: particle number
nele: component number in the beam line
The probability of each polarization is given by each Stokes' parameter as
(1+xi)/2 . TrackParticles always updates PhotonList. The length of PhtonList
is the number of emitted photons.
Remember that the {GX, GY, GZ} = {0, 0, 0} and their directions are {z, x, y}
at the entrance of the beam line by default. It is changeable by the GEO command anyway.

Shift of cavity phase PHI when variation exists among cavities (default: 0). Set by
EMITTANCE(EMIT) or Emittance[] as
{Cos[PHICAV], Sin[PHICAV]} == {Sum[VOLT_k Cos[PHI_k],{k}], Sum[VOLT_k Sin[PHI_k],{k}]} .
Effective with RING only.

SpeedOfLight is 299792458.

Number of unstable planes in the optics calculations. Equal to zero if
all x and y optics are stable for on/offmomentum and finite amplitude matching.

STACKSIZ has the size of the stack for SADScript interpreter. It can be setby user at the MAIN level, right before the first
FFS session. The defaultvalue is 200000.

TITLE is a characterstring to make the title of the plot in
DRAW or GEO commands.
Usage: SAVE [elementpattern]
saves the values of the elements. What are saved are the value of the
default keyword of all elements, the values of the nondefault keywords
which have been changed manually or by the matching. If ALL is given it
resets all keywords. If elementpattern is given, it is only limited
to the elements which match the pattern, otherwise all elements are saved.
SEED command is removed. Use SeedRandom[] function instead of SEED command.
SHOW prints out the current matching conditions.
FFS["SHOW"] returns the current matching conditions as a list.
Each element has a form of
{component1, component2, function, goalvalue, numberofmomentums, scale},
which corresponds to the new format of the printout by SHOW.
Usage: SPLIT component length
splits the component into two pieces at the point where the distance from
the entrance is length. The new components have the same name as the
original, and the strengths are proportional to the new lengths.
Only magnets and cavities can be split. You should CALCULATE(CAL) after
SPLIT to get optical parameters after SPLIT. Matching using SPLIT element
as a variable may degrade the speed of convergence.
STAT shows the current settings of flags, fit points,
specialvariables, the region for DISPLAY, seed of the random number
generator, and elapsed CPU time, etc.
Exits FFS and returns to SAD/MAIN level, with saving the values of
the elements.
Usage: TDR {filename  file_number}
runs TopDrawer (tdr) using the file specified by filename or file_number as
the input. It supports both Tek terminal and Xwindow.
Example: OUT 'a' DRAW bx by & ex ey q* CLOSE OUT TDR 'a'
TDR does not work when SAD is running under EMACS without Xwindow.
TERM [INPUT(IN)] suspends the current input stream and switches it to the
previous input stream.
TERM OUTPUT(OUT) suspends the current output and switches it to the
previous output stream.
Usage: TYPE [elementpattern [elementpattern1..]]
prints out the values of elements which match elementpattern in the
SAD MAIN input format. Keywords which have zero values are omitted unless
it is the default variable. If non elementpattern is given, all elements
are printed out.
Usage: REP [n] body UNTIL [expr1]
executes commands in body n times until expr1 gives nonzero. The number n
can be any expression which gives a number. If n is omitted, infinity is
assumed. If expr1 is omitted, False(==0) is assumed.
Usage: USE [[NO]EXPAND] beamline
switches the beam line used in FFS to the beam line given by beamline.
beamline can be an BeamLine object or the name of a beam line defined
in MAIN. All information specific to the current beam line, such as matching
conditions is lost. If the keyword EXPAND is given (default), the new
beam line is expanded, i.e., the values of components are refreshed to the
saved values.
If a BeamLine object is used by USE or VISIT, the new beam line becomes a
new LINE in the MAIN level, with a name which is created automatically.
VARIABLES displays a list of current matchingvariables and their present,
previous, saved, minimum, and maximum values together with the COUPLEd master
elements and their coefficients.
When executed in the FFS function, it returns the result as a list.
Usage: FFS["VAR"]
returns a list of nvar elements, where nvar is the number of current
matchingvariables given by the FREE command. Each element has the form
{name, keyword, present, previous, saved, minimum, maximum,
coupledmasterelement, couplingcoefficient} ,
which corresponds to the output of the VARIABLES(VAR) command.
Usage: VARY keyword elementpattern
changes the defaultkeyword of the elements which match elementpattern to
keyword.
Usage: VISIT [[NO]EXPAND] beamline
switches the beam line used in FFS to the beam line given by beamline.
beamline can be an BeamLine object or the name of a beam line defined
in MAIN. All information specific to the current beam line, such as matching
conditions are reserved, and the previous beam line is restored when BYE
command is issued. If the keyword EXPAND is given (default), the new beam
line is expanded, i.e., the values of components are refreshed to the saved
values.
If a BeamLine object is used by USE or VISIT, the new beam line becomes a
new LINE in the MAIN level, with a name which is created automatically.
Many commands and functions accept the wildcards as a specification
for the name of elements or components.
The valid wildcards are:
* matches any zero or more characters.
% matches one character.
{..} matches any character enclosed.
{^..} matches any character not enclosed.
.... alternative pattern.
The transformation matrix from the physical coordinate {x,px,y,py} to
the xy decoupled coordinate {X,Px,Y,Py} is written as
R = {{mu I, J . Transpose[r] . J}, {r, mu I}},
with the submatrix r={{R1, R2},{R3, R4}}, where mu^2 + Det[r] = 1,
I = {{1,0},{0,1}}, and J={{0, 1}, {1, 0}}.
Let T stand for the physical
transfer matrix from location 1 to location 2, then the transformation in
the decoupled coordinate is diagonalized as
R_2 . T . Inverse[R_1] = {{T_X ,0}, {0, T_Y}} .
The Twiss parameters are defined for the matrices T_X and T_Y.
If Det[r] >= 1, the above condition for mu is violated. In such a case, an
alternative matrix is used:
R = {{J . Transpose[r'] . J, mu' I}, {mu'I, r'}},
where
r' = {{R3, R4}, {R1, R2}}/Sqrt[Det[r]],
and mu'^2 + Det[r'] = 1.
Back to top