ABORT
APPEND(APP)
ATTRIBUTE(ATTR)
beam-line
  beam-line-functions
    BeamLine
    BeamLineName
    ExtractBeamLine
    PrintBeamLine
    WriteBeamLine
  orientation-of-an-element
BYE
character-string
  FromCharacterCode
  StringFill
  StringJoin
  StringLength
  StringMatchQ
  StringPart
  StringPosition
  StringReplace
  StringTrim
  Symbol
  ToCharacterCode
  ToExpression
  ToString
command-syntax
components
constants
CALCULATE(CAL)
CHROMATICITY(CHRO)
CLOSE(CLO)
COUPLE(COUP)
data-structure
  Extract
  Head
  Length
  List
  Part
defining-functions
dynamics
  independent-variable
  Lagrangean
  Hamiltonian
  remarks-on-dynamics
  x-y-coupling
  extended-Twiss-parameters
    definitions
DISPLAY(DISP)
  ACCELERATION(A)
  ALL
  BEAM(B)
  DUMPOPTICS(D)
  GEOMETRY(G)
  OGEOMETRY(OG)
  ORBIT(O)
  pattern-string
  PHYSICAL(P)
  region
  RMATRIX(R)
  Z
DRAW
  Draw$Option
DUMP
elements
  APERT
  BEND
    AE1
    AE2
    ANGLE
    DISFRIN
    DISRAD
    DROTATE
    DX
    DY
    E1
    E2
    F1
    FB1
    FB2
    FRINGE
    K0
    K1
    L
    ROTATE
    transformation:BEND
  CAVI
    DISFRIN
    DPHI
    DVOLT
    DX
    DY
    FREQ
    HARM
    L
    PHI
    ROTATE
    V02
    V1
    V11
    VOLT
  COORD
  default-keyword
  DECA
    DISFRIN
    DISRAD
    DX
    DY
    K4
    L
    ROTATE
    transformation:THIN
  DODECA
    DISFRIN
    DISRAD
    DX
    DY
    K5
    L
    ROTATE
    transformation:THIN
  DRIFT
    L
    RADIUS
    transformation:DRIFT
  keywords
  MARK
    OFFSET
  MULT
    AE1
    AE2
    ANGLE
    DISFRIN
    DISRAD
    DPHI
    DVOLT
    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:THIN
  QUAD
    DISFRIN
    DISRAD
    DX
    DY
    F1
    F2
    FRINGE
    K1
    L
    ROTATE
    transformation:QUAD
  SEXT
    DISFRIN
    DISRAD
    DX
    DY
    K2
    L
    ROTATE
    transformation:THIN
  SOL
    BOUND
    BZ
    DISFRIN
    DPX
    DPY
    DX
    DY
    F1
    GEO
expression
  (-)
  (/)
  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(=.)
ELSE
ELSEIF
EMITTANCE(EMIT)
END
ENDIF
EXECUTE(EXEC)
EXPAND
flags
  ABSW
  BIPOL
  CALC4D
  CALC6D
  CELL
  CMPLOT
  COD
  CODPLOT
  CONV
  CONVCASE
  DAMPONLY
  DAPERT
  DIFFRES
  ECHO
  EMIOUT
  FFSPRMPT
  FIXSEED
  FLUC
  GAUSS
  GEOCAL
  GEOFIX
  HALFRES
  IDEAL
  INS
  INTRA
  INTRES
  JITTER
  LOG
  LWAKE
  MOVESEED
  PHOTONS
  POL
  PRSVCASE
  PSPAC
  QUIET
  RAD
  RADCOD
  RADLIGHT
  RADPOL
  RADTAPER
  REAL
  RELW
  RFSW
  RING
  SELFCOD
  SORG
  SPAC
  STABLE
  SUMRES
  TRPT
  TWAKE
  UNIFORM
  UNIPOL
  UNSTABLE
  WSPAC
functions
  Data-Manipulation
    Fit
    FitEmit
    FitGaussian
    NIntegrate
    PolynomialFit
    Spline
  DownhillSimplex
  functional-operations
    Apply
    Cases
    DeleteCases
    Difference
    FixedPoint
    FixedPointList
    level-spec
    Map
    MapThread
    Position
    Scan
    ScanThread
    SelectCases
    SwitchCases
    Thread
  FFS-dedicated-functions
    AccelerateParticles
    BeamMatrix
    DynamicApertureSurvey
    Element
      key-strings:Element
    Emittance
    ExternalMap
    FFS
    FFS$SHOW
    FitValue
    FitWeight
    GeoBase
    LINE
      key-strings:LINE
    OptimizeOptics
    OrbitGeo
    RadiationField
    RadiationSpectrum
    SetElement
    SurvivedParticles
    SymplecticJ
    SynchroBetaEmittance
    TouschekLifetime
    TrackParticles
    Twiss
    VariableRange
    VariableWeight
    WakeFunction
  Graphics
    BeamPlot
    ColumnPlot
    FitPlot
    GeometryPlot
    HistoPlot
    ListContourPlot
    ListDensityPlot
    ListPlot
    OpticsPlot
    Plot
  Input/Output
    $FORM
    $Input
    $Output
    Close
    OpenAppend
    OpenRead
    OpenWrite
    PageWidth
    Print
    Read
    ReadString
    StandardForm
    StringToStream
    Write
    WriteString
  Multiprocessing
    Fork
    OpenShared
    Shared
    SharedSize
  Object-oriented-programing
    Class
  Random-number-functions
    Random
    GaussRandom
    ParabolaRandom
    SeedRandom
    ListRandom
  System-interface
    System
    TemporaryName
  Utilities
    DateString
    MemoryCheck
    TimeUsed
    Timing
    TracePrint
FIT
FITPOINTS(FITP)
FIX
FREE
  default-keyword
geometric-functions
GEO
GO
IF
INPUT(IN)
machine-error-commands
matching-function-commands
multi-turn-tracking
MATRIX(MAT)
MEASURE(MEA)
off-momentum-matching
optical-functions
ORG
OUTPUT(OUT)
pattern
  MatchQ
physical-constants
PRINT(PRI)
QUIT
RADINT
READ
RECOVER(REC)
REJECT(REJ)
REPEAT(REP)
RESET
REVERSE(REV)
set-value-of-element
  keywords
  default-keyword
special-variables
  $Line
  CASE
  CHARGE
  CONVERGENCE
  DAPWIDTH
  DP
  DP0
  DTSYNCH
  EFFRFFREQ
  EFFVC
  EFFVCRATIO
  ElementValues
  EMITX
  EMITXE
  EMITY
  EMITYE
  EMITZ
  EMITZE
  ExponentOfResidual
  FFS$NumericalDerivative
  FitFunction
  FSHIFT
  GCUT
  InitialOrbits
  LOSSAMPL
  LOSSDZ
  MatchingAmplitude
  MatchingResidual
  MASS
  MINCOUP
  MOMENTUM
  NBUNCH
  NetResidual
  NP
  NPARA
  OffMomentumWeight
  OMEGA0
  OpticsEpilog
  OpticsProlog
  PBUNCH
  PhotonList
  PHICAV
  SIGE
  SIGZ
  SpeedOfLight
  StabilityLevel
  STACKSIZ
  TITLE
SAVE
SEED
SHOW
SPLIT
STATUS(STAT)
STOP
TERMINATE(TERM)
TYPE(T)
UNTIL
USE
VARIABLES(VAR)
VARY
VISIT
wildcards

Welcome to SAD/FFS & SADScript with MathJax

SAD/FFS SADScript Version: 1.1.6.7k64, Updated: 6/2/2019
 Please use browser's search to find out an item.

 The FFS commands are shown in uppercases. The minimum abbreviated form of each command is enclosed
in (). Each command can be shorten down to that. The optional arguments for the commands are usually
shown in [].
 The notation ===> reads "equivalent to" below.

SAD

Back to SAD Home Page

SAD/FFS Examples


ABORT

Terminates SAD immediately.
See also:
 STOP QUIT SAVE
 USE VISIT BYE

APPEND(APP)

APP {filename | file-number} switches the output stream to the specified file or the file number.
The output is appended to the existing file.
See also:
 TERMINATE(TERM) CLOSE(CLO) INPUT(IN)
 READ OUTPUT(OUT) END

ATTRIBUTE(ATTR)

Usage: ATTR element-pattern

prints out the current value, minimum and maximum values, COUPLEd element and its coefficient for
elements which match the element-pattern.
See also:
 COUPLE(COUP) set-value-of-element wildcards

beam-line

 A beam line is defined in the MAIN level by LINE command as:

   LINE a = ( [n1*][-]l1 [ [n2*]l2 ...] ) [b = ( ... )];

where l1, l2 are either an element or a line. n1, n2 are positive integers to repeat the same element.
An optional negative sign in fromt of element means the negative orientation of the element of the
line. A negative orientation of a line is inherited by its elements.
 The first element of a beam line must be a MARK element, if it is used by FFS, USE, VISIT.
 Please do not confuse the LINE command in the MAIN level with the LINE function in FFS.
 A beam line can be accessed within FFS via beam-line-functions as shown below.
See also:
 elements orientation-of-an-element USE
 VISIT

beam-line-functions

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

orientation-of-an-element

 An element with negative orientation means a reversal of the element along the z-axis. Thus all
magnets except for a solenoid does not change the polarity. A solenoid changes the polarity. An RF
cavity should change, however, it does not in the current implementation. The edge angles and fringe
parameters of the entrance and the exit swap.
 AX, AY, AZ, EPX, EPY, ZPX, ZPY, R2, R3 of a MARK element are reversed.
 The orientation is printed out by DISP. It can be accessed by LINE["DIR"] . 
See also:
 beam-line LINE

BYE

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.
See also:
 VISIT USE SAVE
 RESET STOP QUIT
 ABORT

character-string

 A character-string is expressed by enclosing in "". Special characters are expressed using \:

\n     new line
\r     carriage return
\t     tab
\"     double quote
\      backslash
\nnn   a character whose octal code is nnn.

 If a character-string is written over multiple lines, \ must be placed at the end of each line.
 The length of a character-string is limited to 2^31-1.

FromCharacterCode

 FromCharacterCode[r_Real] returns a character whose character code is r.
 FromCharacterCode[l_List] returns a character-string whose character codes are l.
See also:
 ToCharacterCode

StringFill

 StringFill[s, sf, n]  with strings s and sf, n > 0, returns (s//sf//sf...)[1,n] .
 StringFill[s, sf, -n] with strings s and sf, n > 0, returns (...sf//sf//s)[-n,-1] .
See also:
 StringJoin StringJoin (//) StringPart

StringJoin

 StringJoin[s1, s2, [,s3...]] ===> s1 // s2 [//s3...] concatenates strings s1, s2 [,s3...].
See also:
 StringJoin (//)

StringLength

 StringLength[s] returns the length of string s.

StringMatchQ

 StringMatchQ[s, spat] returns True/False whether string s matches string-patten spat.
See also:
 wildcards

StringPart

 s_String[n]      returns the n-th character in s.
 s_String[n1, n2] returns the substring from n1-th through n2-th characters of s.

 If n1, n2 are negative, they count from the end of the string.

StringPosition

 StringPosition[s, subs] returns a list of positions of subs in string s.
 StringPosition[s, subs, n] returns a list of first n positions of subs in string s.

Example: StringPosition["abcbcbcbcb","bcb"] returns {{2,4},{4,6},{6,8},{8,10}}.

StringReplace

 StringReplace[s, rules] replaces the parts of string s accoding to rules, which is a Rule or a list
of Rules:

   StringReplace["abcbcbcbc","bcb"->"xyx"] ===> "axyxcxyxc"
   StringReplace["abcbcbcbc",{"bcb"->"xy","cbc"->"pqrs"}] ===> "axypqrsbc" .

StringTrim

 StringTrim[s] removes the leading and trailing spaces and tabs from s.

Symbol

 Symbol[s] returns a Symbol whose name is character-string s.

ToCharacterCode

 ToCharacterCode[s] returns the list of character codes of character-string s.
See also:
 FromCharacterCode

ToExpression

 ToExpression[s] converts a character-string s to an expression and evaluate it.
See also:
 ToString

ToString

 ToString[expr] evaluates an expression expr, then converts to a character-string.
 ToString[expr, [FormatType ->] form [, form1...]] converts expr using one or more formats form [,form1...].
Available formats are:

InputForm          special characters are quoted with \.
HoldForm           converts expr without evaluation.
StandardForm       converts with the standard number format and PageWidth.
GenelicSymbolForm  do not display the generation ($nnn) of local symbols for Module.
See also:
 $FORM PageWidth StandardForm
 Module ToExpression

command-syntax

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 set-value-of-element 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 .
See also:
 expression functions

components

Components are the objects which consist the beam line. A component simulates an individual magnet,
drift space, or rf-cavity. 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 order-th 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 ^^^.
See also:
 elements

constants

There are pre-defined special symbols for constants 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
EulerGamma     0.57721566490153286061
See also:
 special-variables physical-constants flags
 expression

CALCULATE(CAL)

Usage: (1) CAL [[NO]EXPAND]]
       (2) CAL matching-function1[-] [matching-function2[-]..]
 
(1) With no argument or with an option [NO]EXPAND, calculates the optics and the matching-functions
using the current values of the components. It prints out the values of the matching-functions specified
either by the matching-function-commands or the second usage of CAL, 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, function-values},

where

dp:       a list contains dp/p0 .
kind:     a list of kind of the orbit (usually 0, but 1 to 6 for the finite amplitude matching, see
          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).

function-values: a list of length nc (== number of calculated items). Each element has the form:

       {component1, component2, function, list-of-values},

       where

       component1, component2: fit locations (see FIT).
       function: name of the function (see matching-function-commands).
       list-of-values: 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 matching-function names, sets the matching-functions at the current fit point to be printed
out after calculation. If the matching-function is followed by a minus sign, it suppresses the print-out.
\nExample:
CALC BX BY CAL
See also:
 GO DISPLAY(DISP) COUPLE(COUP)
 ATTRIBUTE(ATTR) SHOW FIT
 matching-function-commands EXPAND CONV
 CONVERGENCE MatchingResidual FFS

CHROMATICITY(CHRO)

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 x-y coupling or vertical dispersion.

CLOSE(CLO)

   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.
See also:
 TERMINATE(TERM) INPUT(IN) READ
 OUTPUT(OUT) APPEND(APP) END

COUPLE(COUP)

   Usage: COUP slave-element master-element coefficient

sets the value of the default-keyword of slave-element to be equal to coefficient times the value
of the default-keyword of master-element. COUPLE(COUP) cannot be cascaded. The master-element cannot
be COUPLEd to any other element. To reset COUPLE, say COUP slave-element slave-element 1.
 Consider ElementValues to define universal coupling for any keywords.
See also:
 ATTRIBUTE(ATTR) FREE ElementValues

data-structure

All data and "programs" in SAD Script are expressed either by an atom or a list-structure:

   head[body1 [,body2...]]

where head and body1... are atom or list-structure. Defined atoms are:
Real     a real number
Symbol   a symbol
String   a character-string
Pattern  a pattern structure for argument matching

Currently the lengths of a list-structure, a character-string, and the name of a symbol are limited
to 2^31-1. A real number has an accuracy of 8 bytes.
See also:
 character-string pattern

Extract

   Extract[f, part [,head]]

takes elements specified by part, which is a list of indices or Null. Optional head is applied at
each element before evaluation.

Example: Extract[{a,b,c,d,e},{3}]       returns c
         Extract[{a,b,c,d,e},{3,4}]     is an error
         Extract[{a,b,c,d,e},{{3},{4}}] returns {c,d}
         Extract[Hold[{a,b,c,d,e}],{1,3}, Hold] returns Hold[c]
See also:
 Part

Head

Head[f] takes the head of an expression f.

Length

 Length[f] returns the number of elements in the body of a structure f.

List

 List is a special symbol to be the head of generic list-structure.
 List[a, b, c, ...] is represented as {a, b, c, ...}.
 A list is also used to represent a mathematical vector and matrices.
 Most of mathematical functions are operated at each element of a list.

Part

  Part[f, a [,b ,...]] ===> f[[a, [,b ...]]]

takes the a-th element of structure f. f[[a, b]] is equivalent to f[[a]][[b]].
 If a is zero, it takes the head of f.
 if a is negative, f[[a]] os equivalent to f[[Length[f] + 1 + a]].
 If a is a list of Reals {a1, a2, ...}, f[[a]] returns {f[[a1]], f[[a2]], ...}.
 If a is Null, f[[,b]] is returns {f[[1,a]], ..., f[[Length[f], b]]}.
See also:
 Length Head Extract

defining-functions

 A function is defined by one of the following forms:

f[pat1 [,pat2...]] (:)= body;
f[pat1 [,pat2...]] ^(:)= body;
g//:f[pat1 [,pat2...]] (:)= body;

where pat1 [,pat2...] are patterns (including expressions).
 If UpSet(^=) or UpSetDelayed (^:=) is used, the definition is associated with the symbol in the
first level of l.h.s.
 If TagSet(//:) is used, the definition is associated with the symbol on the left of //: .

 The patters can be an expression including constants. The definition with constant arguments can
be accessed faster than searching a list, in general, so they are suitable for a data base. Definitions
with constant arguments have higher priorities than with patterns.
See also:
 UpSet UpSetDelayed TagSet(/:) pattern

dynamics

independent-variable

SAD uses \(s\), the distance along a reference line as the independent variable. The reference line is either a straight line or an arc through an element. The arc is chosen for elements with nonzero ANGLE such as BEND and MULT, otherwise the reference line is a straight line. The reference line is an abstract object to describe the motion of particles, and not necessarily to be an orbit of a particle. Even the orbit is helical, for instance in a solenoid, the reference line is straight. An arc is always bent locally horizontally.
Such reference lines can be discontinuous at some locations such as an end of tilted SOL or COORD. SAD automatically calculates transformation of variables at such locations.

See also:
 Lagrangean Hamiltonian

Lagrangean

The primary position variables are \((x,y,s)\), where \(x\) and \(y\) are the displacements along the normal and binormal vectors, \({\bm n}\) and \({\bm b}\), respectively. Let \({\bm t}\) denote the tangential vector along \(s\), then \({\bm n}\), \({\bm b}\), \({\bm t}\) consist a right-handed system.
The action in \(t\) is expressed by \[\begin{align} S=&\int L_tcdt\ ,\\ L_t=&-\frac{mc}{p_0}\sqrt{1-\dot x^2+\dot y^2+(1+x/\rho)^2\dot s^2}+a_x\dot x+a_y\dot y+(1+x/\rho)a_s\dot s\ ,\end{align}\] where \(p_0\) and \((a_x,a_y,a_z)=e(A_x,A_y,A_z)/p_0\) are the design momentum and the normalized vector potentials, respectively, and \(\dot\ \) denotes the derivative by \(ct\). Currently SAD dose not handle the electrostatic potential.
As SAD uses \(s\) for the independent variable instead of \(t\), the Lagrangean \(L\) for \(s\) is written as \[\begin{align} L=&L_t\frac{dct}{ds}\ ,\\ =&-\frac{mc}{p_0}\sqrt{c^2t'^2-x'^2+y'^2+(1+x/\rho)^2}+a_xx'+a_yy'+(1+x/\rho)a_s\ ,\end{align}\] where \('\) is the derivative by \(s\).

See also:
 Hamiltonian independent-variable

Hamiltonian

The Lagrangean \(L\) defines the canonical momenta as \[\begin{align} p_x=&\frac{\partial L}{\partial x'}=\frac{mcx'}{p_0\sqrt{c^2t'^2-x'^2-y'^2-(1+x/\rho)^2}}+a_x\ ,\\ p_y=&\frac{\partial L}{\partial y'}=\frac{mcy'}{p_0\sqrt{c^2t'^2-x'^2-y'^2-(1+x/\rho)^2}}+a_y\ ,\\ p_t=&\frac{\partial L}{\partial t'}=-\frac{mc^3t'}{p_0\sqrt{c^2t'^2-x'^2-y'^2-(1+x/\rho)^2}}\ ,\end{align}\]which derives the Hamiltonian as \[\begin{align} H_t=&x'p_x+y'p_y+t'p_t-L\\ =&-\left(\sqrt{-c^2 m^2/p_0^2 + p_t^2/c^2 - (p_x-a_x)^2 + (p_y-a_y)^2}+a_s\right)\left(1+\frac{x}{\rho}\right)\ .\end{align}\] Instead of the canonical variables \((t,p_t)\), SAD uses another set \((z,p)\), The variable \(z\) means the logitudinal postion, and \(p\) the total momentum, which is more convenient than \(p_t\) especially in a low-energy case, ie., \(\gamma \sim 1\). The canonical variables \((z,p)\) as well as the Hamiltonian \(H\) are obtained using a mother function \[\begin{align} G=&G(p_t,z)=\frac{z}{c}\sqrt{p_t^2-m^2c^4/p_0^2}-t_0(s)\ ,\\ p=&\frac{\partial G}{\partial z}=\frac{\sqrt{p_t^2p_0^2-m^2c^4}}{p_0}\ ,\\ t=&\frac{\partial G}{\partial p_t}=-z\frac{\sqrt{p^2p_0^2-m^2c^2}}{c p p_0}+t_0(s)\ ,\\ H=&H_t-\frac{\partial G}{\partial s}\\ =&-\left(\sqrt{p^2 - (p_x-a_x)^2 - (p_y-a_y)^2}+a_s\right)\left(1+\frac{x}{\rho}\right)+\frac{E}{p_0v_0}\ ,\end{align}\] where \(t_0(s)\) is the design arrival time at location \(s\), \(E=\sqrt{m^2c^4+p_0^2p^2}\) the energy of the particle, and \(v_0=1/t_0'(s)\) the design velocity. The longitudinal position \(z\) is written as \[\begin{align} z=&-v\left(t-t_0(s)\right)\ ,\end{align}\] where \(v\) is the total velocity of the particle. Note that \(v>0\) for the head of a bunch.

Thus the canonical variables in SAD are: \[\begin{align} (x,p_x,y,p_y,z,\delta\equiv p-1)\ .\end{align}\]

See also:
 Lagrangean independent-variable

remarks-on-dynamics

There are several remarks on the dynamics in SAD:

See also:
 Hamiltonian

x-y-coupling

The transformation matrix from the physical coordinate \((x,p_x,y,p_y)\) to the \(x\)-\(y\) decoupled coordinate \((X,P_x,Y,P_y)\) is written as \[\begin{align} {\rm R}=\left(\begin{matrix}\mu {\rm I} & {\rm J}{\rm r}^T{\rm J}\\{\rm r}&\mu {\rm I}\end{matrix}\right)\end{align}\] with a submatrix \[\begin{align} {\rm r}=\left(\begin{matrix}{\tt R1}&{\tt R2}\\ {\tt R3} & {\tt R4}\end{matrix}\right)\ ,\end{align}\] where \[\begin{align} &\mu^2 + \det({\rm r}) = 1,\\ &{\rm I}\equiv \left(\begin{matrix}1 & 0 \\ 0 & 1 \end{matrix}\right)\ ,\\ &{\rm J}\equiv\left(\begin{matrix}0 & 1 \\ -1 & 0 \end{matrix}\right)\ .\end{align}\] The value of function DETR is equal to \(\det({\rm r})\) in this case.

Let T stand for the physical transfer matrix from location 1 to location 2, then the transformation in the decoupled coordinate is diagonalized as \[\begin{align} {\rm R}_2{\rm T}{\rm R}_1^{-1} = \left(\begin{matrix}{\rm T}_X & 0 \\ 0 & {\rm T}_Y \end{matrix}\right)\ .\end{align}\]

The Twiss parameters are defined for the 2 by 2 matrices \({\rm T}_X\) and \({\rm T}_Y\).

If \(\det({\rm r})\ge1\), the above condition for \(\mu\) is violated. In such a case, an alternative form of R is used: \[\begin{align} {\rm R}=\left(\begin{matrix}{\rm J}{\rm r}^T{\rm J} & \mu {\rm I} \\\mu {\rm I} &{\rm r}\end{matrix}\right)\ ,\end{align}\] where \(\mu^2 + \det({\rm r}) = 1\). The function DETR shows a number \(a-\det({\rm r})\), where \(a = 1.375\). thus the alternative form is used when \(\det({\rm r}) >= 0.625\).

See also:
 DISPLAY(DISP) optical-functions matching-function-commands

extended-Twiss-parameters

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 rotation angle to set one the coordinate to parallel to the (X,Y,Z) axes. R(1,2,3,4)
are the components of the x-y coupling matrix (see x-y-coupling). E(X,PX,Y,PY) are "dispersions"
which decouples synchro-beta coupling terms together with Z(X,PX,Y,PY). Those parameters should agree
with what FFS calculates in the case of no synchro-beta couplings.
See also:
 x-y-coupling optical-functions

DISPLAY(DISP)

Usage: DISP_LAY [keywords] [pattern-string] [region]

Displays values of various optical-/geometric-functions at the components given by the pattern-string
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 default-keyword 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.
See also:
 TYPE(T) optical-functions geometric-functions

ACCELERATION(A)

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.
See also:
 TRPT RING elements
 CAVI special-variables EMITX
 EMITY DP

ALL

ALL is a word to choose the entire beam line for the region to be displayed.
See also:
 region pattern-string

BEAM(B)

DISP B displays the beam sizes and the projected Twiss parameters calculated either by Twiss parameters
or the EMIT command with the CODPLOT flag.

Example: EMITX=...; EMITY=...;DP=...; 
         BEAMSIZE(BEAM)
         DISP B
See also:
 BEAMSIZE(BEAM) EMITTANCE(EMIT) CODPLOT GAUSS
 UNIFORM special-variables EMITX
 EMITY DP

DUMPOPTICS(D)

DISP D displays all matching-functions in one line suitable to be read by a spread-sheet program.
See also:
 optical-functions geometric-functions matching-function-commands

GEOMETRY(G)

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.
See also:
 geometric-functions matching-function-commands

OGEOMETRY(OG)

DISP OG displays geometric information at the orbit.
See also:
 geometric-functions matching-function-commands

ORBIT(O)

DISP O displays the orbits DX, DPX, DY, DPY together with the other 
optical-functions.
See also:
 optical-functions matching-function-commands

pattern-string

The components in the current region can be selectively displayed by the DISP command using the pattern-string.
The pattern-string 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.
See also:
 DISPLAY(DISP) wildcards components
 region ALL

PHYSICAL(P)

DISP P displays the physical dispersions PEX, PEPX, PEY, PEP, together with the 1D optical parameters.
See also:
 optical-functions matching-function-commands

region

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.2-10 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 pattern-string in DISP are only chosen in the current region.
See also:
 ALL pattern-string components
 STATUS(STAT)

RMATRIX(R)

DISP R displays the components of the x-y coupling matrix R together with the 1D optical parameters.
See x-y-coupling.
See also:
 x-y-coupling optical-functions matching-function-commands

Z

DISP Z displays muatching functions related to the Z plane: AZ BZ NZ DZ DDP ZX ZPX ZY ZPY , which
are obtained by CAL/GO with CALC6D.
See also:
 extended-Twiss-parameters CALC6D CALC4D

DRAW

Usage: DRAW [begin end] fun1 [fun2..] [& fun11 [fun12..]] [element-pattern]

draws a plot of optical functions in multi columns. It calls OpticsPlot internally. Available functions
are all matching-functions (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 end-components are specified, the plot region is limited between them. If the end-component
comes earlier than the begin-components, it wraps the plot around the beam line.
  If the optional element-pattern is given, it draws the beam-line lattice with the labels for elements
which match element-pattern. If LAT is specified for element-pattern, the lattice is drawn without
label.
 A character string assigned to TITLE is shown as the FrameLabel on the top of the plot.

 Example:
   TITLE="FCCee_t_202_nosol_16_ipac.sad";
   Draw$Option={Thickness->2};
   DRAW BX BY & EX EY Q*;


See also:
 OpticsPlot special-variables TITLE
 matching-function-commands OUTPUT(OUT) TERMINATE(TERM)
 GEO DISPLAY(DISP) wildcards

Draw$Option

 Draw$Option is a list of rules to specify Graphics options for the entire DRAW. If you need option
for each column, use OpticsPlot
See also:
 DRAW OpticsPlot Graphics

DUMP

Usage: DUMP component-pattern [component-pattern1..]

prints out the current machine errors of components which match component-pattern.
See also:
 machine-error-commands components wildcards

elements

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 element-save-buffer by SAVE or RESET
commands. Different beam lines can share the same element, and their values can be different to each
other, but they have the common element-save-buffer. Therefore the value of an element can be transferred
between beam lines by SAVE and RESET command through the element-save-buffer.
   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.
See also:
 TYPE(T) set-value-of-element Element

APERT

An aperture. Only valid in tracking. A particle with

\begin{align}\begin{split} &\frac{(x-{\tt DX})^2}{{\tt AX}^2}+\frac{(y-{\tt DY})^2}{{\tt AY}^2}< 1\\ \&\&\ &\min({\tt DX1},{\tt DX2})< x< \max({\tt DX1},{\tt DX2})\\ \&\&\ &\min({\tt DY1},{\tt DY2})< y< \max({\tt DY1},{\tt DY2}) \end{split}\end{align}


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.

BEND

A bending magnet.

CAVI

Accelerating structure.

COORD

An element for an arbitrary coordinate transformation. This element can be used to express an off-axis
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

\begin{align}\begin{split} \left(\begin{matrix} x \\y\\z\end{matrix}\right)_1= \left(\begin{matrix} c_3 & -s_3 & 0\\s_3 & c_3 & 0 \\0&0&1\end{matrix}\right) \left(\begin{matrix}1&0&0\\0&c_2&s_2 \\0&-s_2&c_2\end{matrix}\right) \left(\begin{matrix}c_1&0&s_1\\0&1&0\\-s_1&0&c_1\end{matrix}\right) \left(\begin{matrix} x-{\tt DX} \\y-{\tt DY}\\z\end{matrix}\right)_0\ , \end{split}\end{align}


and if dir is nonzero,

\begin{align}\begin{split} \left(\begin{matrix} x \\y\\z\end{matrix}\right)_1= \left(\begin{matrix} c_3 & -s_3 & 0\\s_3 & c_3 & 0 \\0&0&1\end{matrix}\right) \left(\begin{matrix}1&0&0\\0&c_2&-s_2 \\0&s_2&c_2\end{matrix}\right) \left(\begin{matrix}c_1&0&s_1\\0&1&0\\-s_1&0&c_1\end{matrix}\right) \left(\begin{matrix} x \\y\\z\end{matrix}\right)_0+ \left(\begin{matrix} {\tt DX} \\-{\tt DY} \\0\end{matrix}\right)\ , \end{split}\end{align}


where {x, y, z}_1 are the new coordinates and

\begin{align}\begin{split} c_{1,2,3}=&\cos({\tt CHI1},{\tt CHI2},{\tt CHI3})\ ,\\ s_{1,2,3}=&\sin({\tt CHI1},{\tt CHI2},{\tt CHI3})\ . \end{split}\end{align}


Note that these transformationis 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.
See also:
 SOL DISPLAY(DISP)

default-keyword

The default and available non-default variable keywords are:

type    default-keyword  non-default 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,DETR,
                         DX,DPX,DY,DPY,DZ,DDP,AZ,BZ,ZX,ZPX,ZY,ZPY
See also:
 keywords

DECA

A decapole magnet.

DODECA

A dodecapole magnet.

DRIFT

A drift space.

keywords

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
        DVOLT 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 DVOLT 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 DETR DX DPX DY DPY DZ DDP AZ BZ NZ ZX ZPX ZY ZPY EMITX
        EMITY DP AZ SIGZ GEO OFFSET
APERT   DX1 DX2 DY1 DY2 DP AX AY DX DY
See also:
 default-keyword set-value-of-element Element

MARK

MARK elements play special roles 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 optical-functions, special-variables
     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 optical-functions 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 optical-functions 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 special-variables.
See also:
 SAVE USE optical-functions
 SOL special-variables EMITX
 EMITY DP

MULT

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.
See also:
 multipole_with_nonzero_ANGLE

OCT

A octapole magnet.

QUAD

A quadrupole magnet.

SEXT

A sextupole magnet.

SOL

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 x-direction 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.
See also:
 geometric-functions MARK

expression

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 character-string.
    real number is a number in fortran-line format.
    character-string is a set of characters surrounded by "" or ''.
    special-characters 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.
See also:
 constants functions command-syntax
 character-string

(-)

operator for subtraction or unary minus.

(/)

operator for division.

AddTo(+=)

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

Alternatives(|)

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

And(&&)

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

Apply (@@)

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

CompoundExpression(;)

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

Decrement(--)

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

DivideBy(/=)

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

Dot(.)

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

Equal(==)

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.

Function(&)

 a & is a pure-function whose argument is specified #, #n, ##, ##n.
See also:
 Slot(#) SlotSequence(##) functions Function(&)

Greater(>)

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.

GreaterEqual(>= or =>)

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.

Increment(++)

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

Less(

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.

LessEqual(<= or =

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.

List({})

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

Map (/@)

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

MapAll(//@)

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

Member(@)

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].

MessageName(::)

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

Not(~)

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

Or(||)

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.

Part([[]])

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}.
See also:
 Part

PatternTest(?)

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

Plus(+)

a + b returns the sum of a and b.

Power(^)

a ^ b returns the power of a to b.

Repeated(..)

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

RepeatedNull(...)

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

ReplaceAll(/.)

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

ReplaceRepeated(//.)

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

Rule(->)

pattern->expr represents a rule for ReplaceAll.

RuleDelayed(:>)

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

SameQ(===)

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

Sequence([])

a[b,c,..] means a list of b, c,.. with the head a. It is evaluated as a function-reference when a
is a function or a defined-function. When a is a list with head List, it is interpreted as a part
specification of a list. When a is a character-string, 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.

Set(=)

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.

SetDelayed(:=)

same as Set but the right hand side is not evaluated when it is set.
See also:
 Set(=)

StringJoin (//)

a // b converts a and b to character-strings, then join them.
See also:
 StringJoin

SubtractFrom(-=)

a-=b is equivalent to a=a-b .

TagSet(/:)

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.

Times(*)

a * b returns the product of a and b.

TimesBy(*=)

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

Unequal(<>)

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.

UnsameQ(<=>)

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

Unset(=.)

a=. clears the definition assigned to a.
See also:
 Clear

ELSE

Usage: IF expr1 body1 [ELSEIF expr2 body2 [ELSEIF ..]] [ELSE body3] ENDIF

This is a FORTRAN77 like IF-structure. 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 IF-structure, 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.
See also:
 If ELSEIF ENDIF

ELSEIF

Usage: IF expr1 body1 [ELSEIF expr2 body2 [ELSEIF ..]] [ELSE body3] ENDIF

This is a FORTRAN77 like IF-structure. 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 IF-structure, 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.
See also:
 IF ELSE ENDIF

EMITTANCE(EMIT)

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 multi-turn tracking. See multi-turn-tracking.

(2)
EMIT dp, where dp is |df_rf/f_rf|/(alpha_p == momentum compaction), does EMIT for five rf frequencies:

\begin{align}\begin{split} \frac{1}{\alpha_p}\frac{\varDelta f_{\rm rf}}{f_{\rm rf}}=-|{\tt DP}|, -|{\tt DP}|/2, 0, |{\tt DP}|/2, |{\tt DP}|\ , \end{split}\end{align}


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 special-variables MOMENTUM, CHARGE, FSHIFT, MINCOUP, PBUNCH. The flag TRPT or RING affects
only Emittance[], as EMITTANCE(EMIT) automatically set RING.
   EMITTANCE(EMIT) returns the equilibrium emittances in variables EMITX, EMITY, EMITZ, and the equilibrium
bunch length in SIGZ, the relative momentum spread in SIGE, and the longitudinal equilibrium position
DTSYNCH. 

   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.
See also:
 multi-turn-tracking extended-Twiss-parameters
 COD RADCOD RFSW
 INTRA EMIOUT WSPAC
 CODPLOT TRPT MOMENTUM
 CHARGE FSHIFT MINCOUP
 PBUNCH EMITX EMITY
 EMITZ SIGE SIGZ
 DTSYNCH Emittance

END

Closes the current output-stream 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.
See also:
 TERMINATE(TERM) CLOSE(CLO) INPUT(IN)
 READ OUTPUT(OUT) APPEND(APP)

ENDIF

Usage: IF expr1 body1 [ELSEIF expr2 body2 [ELSEIF ..]] [ELSE body3] ENDIF

This is a FORTRAN77 like IF-structure. 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 IF-structure, 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.
See also:
 IF ELSE ELSEIF

EXECUTE(EXEC)

Usage: EXEC character-string-expression

executes the character-string-expression as FFS commands.
See also:
 expression FFS ToExpression

EXPAND

 EXPAND distributes all variable keys to each corresponding components. Individual deviations (machine
errors) are cleared.
See also:
 GO CALCULATE(CAL) EMITTANCE(EMIT)

flags

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 function-syntax 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.
 Status of all flags are displayed by the STATUS(STAT) command.
See also:
 STATUS(STAT) PatternTest(?)

ABSW

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

BIPOL

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.
See also:
 UNIPOL default-keyword set-value-of-element
 VariableRange

CALC4D

If CALC4D is on, the optics calculation in CAL and GO performs a 4x5 calculation (4D + dispersion).
The antonyms is CALC6D. The Default is CALC4D.
See also:
 CALC6D CALCULATE(CAL) GO

CALC6D

If CALC6D is on, the optics calculation in CAL and GO performs full 6D calculation, which may takes
RADCOD into account. The antonyms is CALC4D. The Default is CALC4D.
See also:
 CALC4D CALCULATE(CAL) GO

CELL

CELL or NOINS sets the periodic condition in calculating the optical-functions.
See also:
 INS CALCULATE(CAL) GO
 optical-functions matching-function-commands

CMPLOT

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

COD

COD turns on finding the closed-orbit in the emittance calculation. Accessible in MAIN level.
See also:
 EMITTANCE(EMIT)

CODPLOT

CODPLOT lets the emittance calculation return the information on the closed-orbit, extended Twiss
parameters, and the beam size along the beam line into the FFS optics buffer, which can be shown
by DISPLAY(DISP) or DRAW commands as well as Twiss and OpticsPlot functions.
See also:
 EMITTANCE(EMIT) DISPLAY(DISP) DRAW
 WSPAC RADTAPER

CONV

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

CONVCASE

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.
See also:
 PRSVCASE

DAMPONLY

DAMPONLY is the antonym of FLUC.
See also:
 FLUC

DAPERT

DAPERT enables the DAPERT procedure in the multi-turn tracking to obtain the dynamic aperture diagram.
Accessible in the MAIN level.
See also:
 functions DynamicApertureSurvey

DIFFRES

In the case of CELL, if the total tune deviates across a difference resonance, it is counted as unstable.
The default is NODIFFRES.
See also:
 INTRES HALFRES SUMRES
 STABLE

ECHO

ECHO enables the echo of the main input in the MAIN level.

EMIOUT

EMIOUT turns on the extended output of emittance calculation.
Accessible in the MAIN level.
See also:
 EMITTANCE(EMIT)

FFSPRMPT

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.
See also:
 $Line LOG

FIXSEED

FIXSEED or NOMOVESEED disables the change of the seed of the random number generator after the particle
tracking.
See also:
 MOVESEED MEASURE(MEA) SEED

FLUC

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

GAUSS

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 Twiss parameters.
See also:
 UNIFORM MEASURE(MEA) BEAM(B)
 special-variables DP

GEOCAL

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.
See also:
 GEOFIX CALCULATE(CAL) GO
 SOL

GEOFIX

GEOFIX is the antonym of GEOCAL.
See also:
 GEOCAL

HALFRES

In the case of CELL, if the total tune deviates across a half-integer resonance, or the traces is
less than -2, it is counted as unstable (~?STABLE). Otherwise the optics is recognized as STABLE.
The default is HALFRES.
See also:
 INTRES SUMRES DIFFRES
 STABLE

IDEAL

IDEAL or NOREAL inhibits to use the component-specific deviations  (i.e., machine-errors) in the
optics calculation.
See also:
 REAL CALCULATE(CAL) GO
 machine-errors

INS

INS is the antonym of CELL.
See also:
 CELL

INTRA

INTRA turns on the calculation of intra-beam scattering in the emittance calculation. Accessible
in MAIN level.
See also:
 EMITTANCE(EMIT)

INTRES

In the case of CELL, if the total tune deviates across an integer resonance, or the trace is larger
than 2, it is counted as unstable (~?STABLE). Otherwise the optics is recognized as STABLE. The default
is INTRES.
See also:
 HALFRES SUMRES DIFFRES
 STABLE

JITTER

JITTER or NOQUIET allows jitter of the center-of-mass of the incoming beam in the case of TRPT. Otherwise
the center-of-mass statistically fluctuates depending on the number of particles.
See also:
 QUIET MEASURE(MEA) TRPT

LOG

LOG enables the echo of all inputs in the MAIN level. Also suppresses the prompt in FFS.
See also:
 ECHO

LWAKE

LWAKE turns on optics calculation with Longitudinal WakeFunction
See also:
 WakeFunction TrackParticles InitialOrbits
 TWAKE

MOVESEED

MOVESEED is the antonym of FIXSEED.
See also:
 FIXSEED

PHOTONS

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.
See also:
 PhotonList TrackParticles

POL

POL turns on spin tracking and the calculation of equilibrium polarization in EMIT/Emittance[].
See also:
 RADPOL EMITTANCE(EMIT) Emittance
 TrackParticles

PRSVCASE

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

PSPAC

When on, performs space-charge simulation in a "Particle-In-Cell" method. PSPAC is effective in tracking
only.
   Do not confuse PSPAC with SPAC/WSPAC.
See also:
 PSPACNX PSPACNY PSPACNZ PSPACDX PSPACDY PSPACDZ

QUIET

QUIET is the antonym of JITEER.
See also:
 JITTER

RAD

RAD turns on the synchrotron radiation in the particle-tracking. Accessible in the MAIN level.
See also:
 RADCOD FLUC

RADCOD

RADCOD turns on the energy loss due to synchrotron radiation at the closed-orbit 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.
See also:
 RAD FLUC TRPT

RADLIGHT

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

RADPOL

If POL is on, RADPOL turns on Sokolov-Ternov effect in tracking.
See also:
 POL

RADTAPER

 Scales all magnets except for solenoids according to the local momentum (DDP) of the closed orbit.
It uses the average of DDPs at the entrance and the exit. For tracking, RADCOD and ( CAL/GO with
CALC6D or EMIT(Emittance[]) ) is necessary. CAL/GO with CALC4D will clear the necessary information
for tracking with RADTAPER.
 RADTAPER sets the momentum deviation of the closed orbit to DP0, which is an arbitrary choice of
an under-deterministic problem of tapering. Thus the difference in the path length around the ring
is adjusted by automatically updating FSHIFT.
See also:
 RADCOD CALC6D CALC4D
 EMITTANCE(EMIT) CALCULATE(CAL) GO
 DP0 FSHIFT

REAL

REAL is the antonym of IDEAL.
See also:
 IDEAL

RELW

RELW is the antonym of ABSW.
See also:
 ABSW

RFSW

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

RING

RING is the antonym of TRPT.
See also:
 TRPT

SELFCOD

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.
See also:
 WSPAC

SORG

SORG sets the origin of S (design orbit length) at the location set by ORG.
See also:
 ORG

SPAC

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.
See also:
 NP PBUNCH WSPAC

STABLE

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.
See also:
 CALCULATE(CAL) GO INTRES
 HALFRES SUMRES DIFFRES

SUMRES

In the case of CELL, if the total tune deviates across a sum resonance, it is counted as unstable.
The default is SUMRES.
See also:
 INTRES HALFRES DIFFRES
 STABLE

TRPT

TRPT or NORING declares that the beam line is a transport line, not a part of a storage ring. The
nominal momentum be changed in the beam 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.
See also:
 DISPLAY(DISP) RING UNIFORM
 GAUSS

TWAKE

TWAKE turns on optics calculation with Transverse WakeFunction
See also:
 WakeFunction TrackParticles InitialOrbits
 LWAKE

UNIFORM

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

UNIPOL

UNIPOL is the antonym of BIPOL.
See also:
 BIPOL

UNSTABLE

UNSTABLE is the antonym of STABLE.
See also:
 STABLE

WSPAC

When on, performs space-charge simulation in a "strong-weak" mode. The beam size through the beam
line is to be calculated by EMIT with CODPLOT. The space-charge 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.
See also:
 EMITTANCE(EMIT) PBUNCH CODPLOT
 MINCOUP SELFCOD SPAC

functions

FFS functions:

Constants:
   Degree GoldenRatio I INF* Infinity NaN* Pi SpeedOfLight
Elementary-functions:
   ArcCos ArcCosh ArcSin ArcSinh ArcTan ArcTanh Cos Cosh Exp Log Sin Sinh
   Sqrt Tan Tanh
Special-functions:
   BesselI BesselJ BesselK BesselY BesselJZero Erf Erfc Factorial 
   Gamma LogGamma LogGamma1 GammaRegularized GammaRegularizedQ*
   GammaRegularizedP* GaussianCoulomb* GaussianCoulombU*
   GaussianCoulombFitted* LegendreP*
Numerical-functions:
   Abs Ceiling Floor Max Min MinMax* Mod Negative NonNegative Positive
   Round Sign FractionalPart
Matrix-operations:
   Det Eigensystem IdentityMatrix Inner LinearSolve Outer SingularValues*
   Transpose
Random-number:
   GaussRandom* Random* SeedRandom
Complex:
   Arg Complex ComplexQ Conjugate Im Re
Rational:
   Rational FromRational ContinuedFraction FromContinuedFraction SmallPrime
   Numerator Denominator
Fourier-Transformation:
   Fourier InverseFourier
Data-Manipulation:
   FindRoot Fit* NIntegrate* PolynomialFit* Spline*
Calculus:
   D NIntegrate
Minimization:
   DownhillSimplex*
List-manipulations:
   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
Character-strings:
   FromCharacterCode CharacterPosition Characters DigitQ LetterQ StringDrop
   StringFill* StringInsert StringLength StringPosition StringTrim*
   Symbol SymbolName ToCharacterCode ToLowerCase ToUpperCase ToExpression
Functional-Operations:
   Apply Cases Count DeleteCases Identity FixedPoint* FixedPointList*
   Fold Function Level Map MapAll MapAt MapIndexed MapThread Nest Position
   Replace Scan ScanThread* SelectCases* SwitchCases* Thread
Object-oriented programing and context:
   Begin BeginPackage Class* End EndPackage
Flow-Control:
   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 Put Read ReadString 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 Environment 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 *.

FFS-dedicated-functions:
   BeamMatrix CalculateOptics DynamicApertureSurvey Element Emittance FFS
   FitValue FitWeight GeoBase LINE OptimizeOptics OrbitGeo RadiationField
   RadiationSpectrum SymplecticJ SetElement TrackParticles Twiss VariableRange
   SynchroBetaEmittance TouschekLifetime WakeFunction
Beam-line-functions:
   BeamLine BeamLineName ExtractBeamLine PrintBeamLine WriteBeamLine
See also:
 expression constants physical-constants
 beam-line-functions

Data-Manipulation

DownhillSimplex

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 corresponding 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 (fmax-fmin)/(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->1e-4,VariableRange->limit]
See also:
 FFS-dedicated-functions:OptimizeOptics

functional-operations

FFS-dedicated-functions

Functions dedicated to the optics calculations and simulations in FFS.

Graphics

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]          : Text-string 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.
Legend           ""              shows legend-string.
FontScale        1               Relative size of fonts for FrameLabel, FrameTicks.
FrameFontScale   1               Relative size of fonts for FrameLabel.
                                 If Real, applied to all frames. If List, applied to
                                 bottom, left, top, right, supplemented 1s to the right.
TickFontScale    1               Relative size of fonts for FrameTicks.
                                 If Real, applied to all frames. If List, applied to
                                 bottom, left, top, right, supplemented 1s to the right.
LegendFontScale  1               Relative size of fonts for Legend.

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 HP-UX) 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];

Input/Output

Multiprocessing

Object-oriented-programing

Environment for an object-oriented-programming 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.
See also:
 Member(@)

Random-number-functions

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 cut-off value of GaussRandom[] is given by variable
GCUT.
See also:
 special-variables: GCUT

System-interface

Utilities

FIT

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 relative-fitting or zone-fitting. If the fitting condition
is not maximum-fitting, 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 maximum-fitting,
the condition means a zone-fitting (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 maximum-fitting 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.

Examples: (1) FIT QF.2-10

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 two-point 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.
See also:
 matching-function-commands components SHOW
 GO CALCULATE(CAL)

FITPOINTS(FITP)

Usage: FITP n

 sets n to the number of off-momentum points in the off-momentum matching. If the fitting condition
is on-momentum only, it is not affected.
See also:
 matching-function-commands

FIX

Usage: (1) FIX element-pattern [keyword] [element-pattern1 [keyword1]..]

removes elements which match element-pattern from the matching variables. The optional keyword specifies
the non-default 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 matching-function 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.
See also:
 FREE FIT SHOW
 GO CALCULATE(CAL) wildcards
 elements

FREE

Usage: FREE element-pattern [keyword] [element-pattern1 [keyword1]..]

specifies elements which match element-pattern as the matching variables. The optional keyword specifies
the non-default variables. See default-keyword. 
   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 matching-function name) which means
the incoming condition of the matching-function is varied in the matching.

Example: FREE AXI BXI AYI BYI

changes incoming AX, BX, AY, and BY to find the solution.
See also:
 FIX FIT SHOW
 GO CALCULATE(CAL) wildcards
 elements

default-keyword

The default and available non-default variable keywords are:

type    default-keyword  non-default 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,DETR,
                         DX,DPX,DY,DPY,DZ,DDP,AZ,BZ,ZX,ZPX,ZY,ZPY
See also:
 keywords

geometric-functions

Available geometric-functions 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 s-direction, eta in -(x-direction),
and zeta in -(y-direction) at the entrance. The set {xi, eta, zeta} forms a right-hand 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 new-a vector by b right-handedly".
See also:
 optical-functions matching-function-commands
 DISPLAY(DISP) GEOCAL GEOFIX

GEO

prints out the TopDrawer commands for the geometric plot of the beam line.
See also:
 DISPLAY(DISP)

GO

Usage: GO [[NO]EXPAND]

Does matching for fitting conditions given by matching-function-commands 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, function-values},

where

dp:       a list contains dp/p0 .
kind:     a list of kind of the orbit (usually 0, but 1 to 6 for the finite amplitude matching, see
          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).

function-values: a list of length nc (== number of calculated items). Each element has the form:

       {component1, component2, function, list-of-values},

       where

       component1, component2: fit locations (see FIT).
       function: name of the function (see matching-function-commands).
       list-of-values: list of the value of the function for each orbit Length nf.
       The central orbit comes at the Floor[(n+1)/2]-th element.
See also:
 FIT SHOW matching-function-commands
 off-momentum-matching FREE FIX
 VARIABLES(VAR) COUPLE(COUP) ATTRIBUTE(ATTR)
 CALCULATE(CAL) VARY SHOW
 CONV CONVERGENCE MatchingResidual
 MatchingAmplitude FitFunction FFS
 OptimizeOptics

IF

Usage: IF expr1 body1 [ELSEIF expr2 body2 [ELSEIF ..]] [ELSE body3] ENDIF

This is a FORTRAN77 like IF-structure. 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 IF-structure, 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.
See also:
 ELSE ELSEIF ENDIF
 expression command-syntax If

INPUT(IN)

IN {filename | file-number} switches the input stream to the specified file or the file-number. The
original stream is kept and to be returned by TERMINATE(TERM). The input file is not rewound.
See also:
 TERMINATE(TERM) CLOSE(CLO) READ
 OUTPUT(OUT) APPEND(APP) END

machine-error-commands

Usage: machine-error-command [options] amount component-pattern ..

where machine-error-command 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         default-keyword      DRIFT BEND QUAD SEXT OCT DECA DODECA MULT SOL CAV
DDK        K0 or DBZ            BEND SOL

   amount is the amount of the error,
   component-pattern 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 component-pattern.
PUT(P)           Set the error to the keyword. Default.
ADD(A)           Add the error to the keyword.
See also:
 components wildcards keywords
 default-keyword DUMP SEED

matching-function-commands

Usage: (1) matching-function  goal-value [off-momentum-points]
       (2) matching-functionM goal-value [off-momentum-points]
       (3) matching-functionI incoming-value
       (4) matching-functionSCALE scale

(1) sets the matching condition for matching-function at the current fitting point or region with
the goal-value and the off-momentum-points (see off-momentum-matching).
   If off-momentum-points is omitted, the previous value for this matching-function at this fitting-point
is assumed. If the previous value is not defined, 1 is assumed. If -1 is given for off-momentum-points,
the matching-function is rejected from the matching (see REJECT(REJ)).
   If "*" is given for goal-value, 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 matching-function, it means the maximum-fitting for the function.
The maximum of either the value (for positive-definite functions) or the absolute value (for bipolar
functions) are to be limited in the matching.

(3) If the letter "I" is appended to matching-function, it specifies the value of the incoming beam.

(4)
If SCALE is appended to matching-function, it sets the scale of the input/output of the function
to scale. This scale is used in the matching-function commands, DISPLAY(DISP), SHOW, etc.
(5) If the current fit location is at a MARK, @ for the goal value refers the save value at the MARK.
@- refers -(save value). These are useful to match between two beam lines.

   Available matching-functions are:
optical-functions (see optical-functions):
AX BX NX AY BY NY EX EPX EY EPY R1 R2 R3 R4 DETR DX DPX DY DPY DZ DDP PEX PEPX PEY PEPY TRX TRY LENG
geometric-functions
(see geometric-functions):
GX GY GZ CHI1 CHI2 CHI3
See also:
 FIT GO SHOW MARK
 optical-functions geometric-functions off-momentum-matching
 x-y-coupling REJECT(REJ) special-variables
 DP functions FitValue
 MatchingAmplitude

multi-turn-tracking

The multi-turn 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 multi-turn 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 multi-turn-tracking. The values of EMITX, EMITY, EMITZ,
SIGE can be changed between EMITs and the multi-turn-tracking.
See also:
 EMITTANCE(EMIT) RFSW RAD
 FLUC RADCOD SPAC
 WSPAC special-variables

MATRIX(MAT)

Usage: MATRIX [{SYMPLECTIC(S) | PHYSICAL(P)}] [from to]

prints out the 4 by 5 (w/CALC4D) or 6 by 6 (w/CALC6D) transfer matrix from from-component to to-component.
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 to-component is upstream the from-component, it gives the inverse matrix (TRPT) or one-turn-wrapped
matrix (RING).
See also:
 DISPLAY(DISP) TRPT RING
 CALC4D CALC6D TransferMatrix

MEASURE(MEA)

Usage: MEA [end-component] [OUT file plot-spaces]

tracks particles from the entrance to end-component and prints out the statistics at the end. If
end-component is omitted, the component end used in the last MEASURE(MEA) (default: end of the beam
line) is assumed.
   If OUT file plot-spaces are attached, it plots phase space distribution on file. The phase-spaces
are specified like as X-PX, 
or X-Y, etc., (up to any numbers).
   Parameters for the tracking are specified by special-variables and flags:

seed for the random-number generator:
     SeedRandom[seed_Real] or SeedRandom[{seeds__Real}]

special-variables (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      cut-off 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 rf-cavities
     RAD/NORAD        synchrotron radiation on/off
     RADCOD/NORADCOD  off/on compensation of energy loss due to radiation
     FIXSEED/MOVESEED keep(default)/unkeep the initial random-number seed

   The initial transverse distribution is Gaussian.
See also:
 special-variables TrackParticles SeedRandom
 RESULTOFTRACKING

off-momentum-matching

FFS matches the optical functions for an orbit with finite momentum deviation.

Example: 
   DP=0.01;      sets the range of momentum to DP0-0.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 off-momentum points are chosen with equal separation. If the off-momentum point
n is an even number, the chosen points are same as the case of n+1, but the on-momentum point (==DP0)
is excluded.
See also:
 matching-function-commands DP DP0

optical-functions

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 x-y-coupling)
R2    R_2     (see x-y-coupling)
R3    R_3     (see x-y-coupling)
R4    R_4     (see x-y-coupling)
DETR  R_1*R_4 - R_2*R_3 (see x-y-coupling)
DX    dx
DPX   dpx
DY    dy
DPY   dpy
DZ    dz
DDP   delta=dp/p0
AZ    alpha_Z
BZ    beta_Z
NZ    psi_Z, the default scale is 1/(2Pi)
ZX    zeta_X  (z-dispersion_X)
ZPX   zeta_Px (z-dispersion_PX)
ZY    zeta_Y  (z-dispersion_Y)
ZPY   zeta_Py (z-dispersion_PY)
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 x-y 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.
See also:
 geometric-functions x-y-coupling matching-function-commands
 GO CALCULATE(CAL) DISPLAY(DISP)
 SHOW

ORG

Usage: ORG location, dgx, dgy, dgz, dchi1, dchi2, dch3

sets the origin of the geometrical coordinate relative to the location with a relative shift (dgx,
dgy, dgz) and rotation (dchi1, dchi2, dchi3).

OUTPUT(OUT)

OUT {filename | file-number} switches the output stream to the specified file or the file-number.
The file is written from the beginning.
See also:
 TERMINATE(TERM) CLOSE(CLO) INPUT(IN)
 READ APPEND(APP) END

pattern

 Pattern is a special expression for mathing arguments in function definitions and rules with several
forms:

_           matches any single argument.
__          matches a sequence of 1 or more arguments.
___         matches a sequence of 0 or more arguments.
x_          matches any single argument, which is names x.
x__         matches a sequence of 1 or more arguments, which is named x.
x___        matches a sequence of 0 or more arguments, which is named x.
x:pattern   a pattern which is named x.
pattern:v   a pattern which has a default value v when matching is failed.
pattern..   a non-null sequence of arguments each of which matches pattern.
pattern...  a sequence, which can be null, of arguments each of which matches pattern.
expression  matches expression.
See also:
 MatchQ defining-functions rules

MatchQ

 MatchQ[x, pat] returns True if x matches pat

physical-constants

Physical constants available in FFS are:

SpeedOfLight           299792458
FineStructureConstant  alpha
ElectronCharge         e in Coulomb
ElectronMass           m_e in eV
ElectronRadius         classical radius of electron, in m
ElectronGminus2        electron g-2
ProtonMass             m_p in eV
ProtonRadius           classical radius of Proton, in m
SIMu0                  4 Pi 10^{-7}
SIEpsilon0             1/SIMu0/SpeedOfLight^2
BoltzmannConstant      k_B in J/K
See also:
 constants expression special-variables

PRINT(PRI)

PRI expression evaluates expression and prints out the result.
See also:
 expression Print

QUIT

Exits FFS and return to SAD/MAIN level, without saving the values of the elements.
See also:
 STOP SAVE ABORT
 USE VISIT BYE

RADINT

RADINT prints out the radiation integrals involving the x-coupling for all components of the beam
line.

READ

READ {filename | file-number} switches the input stream to the specified file or the file-number.
The original stream is kept and to be returned by TERMINATE(TERM). The input file is rewound.
See also:
 TERMINATE(TERM) CLOSE(CLO) INPUT(IN)
 OUTPUT(OUT) APPEND(APP) END

RECOVER(REC)

REC exchanges the values of FREEd elements with those when the last GO command was issued. FIXed
elements are not affected.
See also:
 GO FREE FIX RESET
 SAVE

REJECT(REJ)

Usage: (1) REJ matching-function-pattern [matching-function-pattern1..]
       (2) REJ TOTAL
       (3) REJ TOTALFIT

rejects the matching-functions which match matching-function-pattern 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.
See also:
 matching-function-commands FIT wildcards

REPEAT(REP)

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.
See also:
 UNTIL

RESET

Usage: RESET [ALL] [element-pattern]

restores the value of the elements. What are restored are the value of the default keyword of all
elements, the values of the non-default keywords which have been changed manually or by the matching.
If ALL is given, it resets all keywords. If element-pattern is given, reset is limited to the elements
which match the pattern.
See also:
 SAVE USE VISIT
 wildcards RECOVER(REC)

REVERSE(REV)

REV changes the sign of AX, AY, EPX, EPY, R2, R3, DPX, DPY at the
entrance of the beam line.
See also:
 matching-function-commands

set-value-of-element

Usage: element-pattern [keyword] [{MIN | MAX | MINMAX | MAXMIN}] value

sets value to the specified keyword of the elements which match element-pattern. If keyword is omitted,
the default-keyword is assumed. keyword can be a wildcard to apply all matching keywords.
   If MIN, MAX, MINMAX, MAXMIN are specified, it sets the limit of the default-keyword. Both MINMAX
and MAXMIN means MIN=-Abs[value] and MAX=+Abs[value].
   If the keyword is not the default-keyword, it affects both the current and the saved value.
See also:
 ATTRIBUTES(ATTR) SAVE elements default-keyword
 wildcards Element

keywords

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
        DVOLT 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 DVOLT 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 DETR DX DPX DY DPY DZ DDP AZ BZ NZ ZX ZPX ZY ZPY EMITX
        EMITY DP AZ SIGZ GEO OFFSET
APERT   DX1 DX2 DY1 DY2 DP AX AY DX DY
See also:
 default-keyword set-value-of-element Element

default-keyword

The default and available non-default variable keywords are:

type    default-keyword  non-default 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,DETR,
                         DX,DPX,DY,DPY,DZ,DDP,AZ,BZ,ZX,ZPX,ZY,ZPY
See also:
 keywords

special-variables

There are several variables which have special rolls in FFS. Some of them are also accessible in
the MAIN level.
See also:
 constants expression flags

$Line

 %Line counts the number of the results in FFS Shown with Out[]:= . Out remembers all outputs up
to Out[$Line]. $Line = 0 resets the counter and forgets the outputs.

CASE

CASE is a character-string to be attached with TITLE to issue the CASE command of TopDrawer in DRAW
or GEO commands.
See also:
 TITLE DRAW GEO

CHARGE

CHARGE contains the charge of the particle. The default is +1.

CONVERGENCE

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.
See also:
 GO MatchingResidual CONV

DAPWIDTH

DAPWIDTH is the successive width of the x-amplitudes to terminate the tracking assuming that the
aperture is enough. The default is 7.
See also:
 DynamicApertureSurvey

DP

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 off-momentum matching, the range DP0 - DP < dp/p0 < DP0 + DP
is used for the matching. The assumed momentum-distribution 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.
See also:
 DP0 off-momentum-matching GAUSS
 UNIFORM elements MARK

DP0

 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 on-momentum optics has the relative momentum
deviation dp/p0 == DP0, and the off-momentum calculation is done in the range DP0 - DP < dp/p0 <
DP0 + DP.
 DP0 sets the momentum deviation of the closed orbit at the entrance for EMIT with RADTAPER.
See also:
 DP off-momentum-matching matching-function-commands
 EMITTANCE(EMIT) RADTAPER

DTSYNCH

 DTSYNCH is the equilibrium arrival time advance (= -c*delta t, in meter) where the synchrotron radiation
loss balances with the RF, calculated by EMIT/Emittance[SaveEMIT->True]. This corresponds to the
origin of the RF phase. The default is zero.
See also:
 EMITX EMITY EMITZ
 SIGZ SIGE EMITTANCE(EMIT)
 Emittance PHICAV

EFFRFFREQ

 The effective angular frequency weff (= 2 Pi EFFRFFREQ) is obtained using the second derivative

  d^2Vcacc/dt^2 == -weff^2 Vcacc ,

ehere Vcacc is the total acceleration voltage at the equilibrium phase PHICAV. These quantities Vcacc
and its derivatives are summed over all CAVIs and MULTs.
 It is set by EMITTANCE(EMIT) or Emittance[]. Effective with RING only.
See also:
 EFFVC PHICAV

EFFVC

 Effective peak rf voltage EFFVC is given by

  Abs[ weff Vcacc + I dVcacc/dt ] / weff ,

where Vcacc, weff are total acceleration voltage at the equilibrium phase PHICAV and the effective
RF angular frequency (=2 Pi EFFRFFREQ). DVcacc/dt is the time derivative of Vcacc. The quantity Vcacc
and its derivatives are summed over all CAVIs and MULTs.
 It is set by EMITTANCE(EMIT) or Emittance[]. The unit is Volt. Effective with RING only.
See also:
 EFFVCRATIO EFFRFFREQ PHICAV

EFFVCRATIO

 Ratio of (effective voltage)/(Sum[VOLT_k,{k}]) (default: 1). Set by EMITTANCE(EMIT) or Emittance[].
Effective with RING only.
See also:
 PHICAV EFFVC

ElementValues

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 parametric 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.
7.  ElementValues is cleared by USE. It is hidden by VISIT and restored by BYE.
See also:
 COUPLE(COUP)

EMITX

EMITX is a real variable for the horizontal emittance (not normalized by gamma beta). 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.
See also:
 EMITY EMITZ SIGZ
 SIGE DP elements
 MARK

EMITXE

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.
See also:
 EMITYE EMITZE

EMITY

EMITY is a real variable for the vertical emittance (not normalized by gamma beta). It is automatically
set by the keyword EMITY of the MARK element at the beginning of the beam line. The EMITTANCE(EMIT)
command returns its calculated value in EMITY. The value of EMITY affects the default wei÷ht of variables
in the matching. Accessible in MAIN.
See also:
 EMITX EMITZ SIGZ
 SIGE DP elements
 MARK

EMITYE

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.
See also:
 EMITXE EMITZE

EMITZ

EMITZ is a real variable for the longitudinal emittance (not normalized by gamma beta). It is automatically
set by the keyword EMITZ of the MARK element at the beginning of the beam line. The EMITTANCE(EMIT)
command returns its calculated value in EMITZ. Accessible in MAIN.
See also:
 EMITX EMITY SIGZ
 SIGE DP elements
 MARK

EMITZE

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.
See also:
 EMITXE EMITYE

ExponentOfResidual

The exponent to calculate MatchinResidual. The default is 2.
See also:
 MatchingResidual GO

FFS$NumericalDerivative

If False (default), the calculation of response matrix for each matching variables uses analytical
expressions as much as possible. If True, performs numerical differentiation during the matching
by GO. It is useful for some variables and matching functions in some cases. It is slow, so should
be avoided for off-momentum-matching for a large beam line.
See also:
 GO off-momentum-matching

FitFunction

FitFunction is a symbol to assign user-defined 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 built-in 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 built-in 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 .

   FitFunction is cleared by USE. It is also hidden by VISIT and restored by BYE.
See also:
 GO FREE MatchingResidual
 DP0 Element LINE
 Twiss

FSHIFT

FSHIFT is the relative shift df/f0 of the revolution (or rf) frequency in a ring. This is valid in
EMITTANCE(EMIT), the particle-tracking, and CAL/GO with CALC6D. For CAL/GO with CALC4D, DP0 should
be used instead.
See also:
 EMITTANCE(EMIT) CALCULATE(CAL) GO
 CALC6D CALC4D DP0

GCUT

GCUT specifies the cut-off value of Gaussian distribution in unit of the standard deviation. Accessible
in MAIN.
See also:
 SEED GAUSS GaussRandom

InitialOrbits

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 non-orbit
params are used directly. Orbits are giving offsets.)
  If InitialOrbits are given, the off-momentum matching and finite-amplitude matching is disabled.

 InitialOrbits is also necessary to calculate optics with wake field.
See also:
 CALCULATE(CAL) GO off-momentum-matching
 finite-amplitude-matching

LOSSAMPL

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

LOSSDZ

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.
See also:
 LOSSAMPL APERT SPAC

MatchingAmplitude

MatchingAmplitude is a list of amplitudes for the finite-amplitude 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 off-momentum 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 zero-amplitude 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.
See also:
 DP EMITX EMITY
 off-momentum-matching CALCULATE(CAL) GO

MatchingResidual

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 i-th condition, df_i is the difference of the i-th 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 on-momentum optics
          = Sqrt[number-of-momentum-points] for off-momentum optics.
 The weight of the function is lighter in the case of off-momentum-matching so that all off-momentum
deviations functions weight equal to the on-momentum one. However, the relative weight for the off-momentum
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.
See also:
 ExponentOfResidual CONVERGENCE OffMomentumWeight
 off-momentum-matching FitWeight

MASS

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

MINCOUP

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

MOMENTUM

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

NBUNCH

NBUNCH is the number of bunches for the calculation of WakeFunction. Accessible in MAIN.
See also:
 PBUNCH

NetResidual

The net residual of convergence except the penalty for unstable optics.
See also:
 MatchingResidual StablilityLevel

NP

NP is the number of particles in the tracking. Accessible in MAIN.
See also:
 MEASURE(MEA)

NPARA

NPARA specifies the maximum number of parallel processes for various calculations such as CALC, GO,
TrackParticles, DynamicApertureSurve, etc.
See also:
 CALCULATE(CAL) GO TrackParticles
 DynamicApertureSurvey

OffMomentumWeight

Relative weight of the off-momentum deviation for the off-momentum matching. The default is 1.
See also:
 ExponentOfResidual CONVERGENCE MatchingResidual
 off-momentum-matching FitWeight

OMEGA0

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

OpticsEpilog

OpticsEpilog is a variable to assign a user-defined function which is to be executed every time 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.
See also:
 OpticsProlog

OpticsProlog

OpticsProlog is a variable to assign a user-defined 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.
See also:
 OpticsEpilog

PBUNCH

PBUNCH is the number of particles/bunch for the calculation of the intra-beam and space charge effects
in EMITTANCE(EMIT), and WakeFunction. Accessible in MAIN.
See also:
 EMITTANCE(EMIT) INTRA WSPAC
 WakeFunction

PhotonList

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 right-handed 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.
See also:
 PHOTONS TrackParticles

PHICAV

The equilibrium RF phase (in radian, = 2 Pi EFFRFFREQ DTSYNCH/c) where the synchrotron radiation
loss and acceleration balances. If there are phase, voltage, frequency variations in RF cavities,
it is calculated based on "effective voltage". Effective with RING only.
See also:
 EFFVC EFFRFFREQ DTSYNCH
 CAVI MULT

SIGE

 SIGE is the equilibrium momentum spread at the entrance of the beam line calculated by EMIT/Emittance[SaveEMIT->True].
See also:
 EMITX EMITY EMITZ
 SIGZ EMITTANCE(EMIT) Emittance

SIGZ

 SIGZ is the equilibrium bunch length at the entrance of the beam line calculated by EMIT/Emittance[SaveEMIT->True].
See also:
 EMITX EMITY EMITZ
 SIGE EMITTANCE(EMIT) Emittance

SpeedOfLight

SpeedOfLight is 299792458.

StabilityLevel

Number of unstable planes in the optics calculations. Equal to zero if all x and y optics are stable
for on/off-momentum and finite amplitude matching.
See also:
 NetResidual MatchingResidual

STACKSIZ

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

TITLE

TITLE is a character-string to make the title of the plot in DRAW or GEO commands.
See also:
 CASE DRAW GEO

SAVE

Usage: SAVE [element-pattern]

saves the values of the elements. What are saved are the value of the default keyword of all elements,
the values of the non-default keywords which have been changed manually or by the matching. If ALL
is given it resets all keywords. If element-pattern is given, it is only limited to the elements
which match the pattern, otherwise all elements are saved.
See also:
 RESET USE VISIT
 BYE STOP QUIT
 wildcards

SEED

The SEED command is obsolete. Use SeedRandom[] function instead of SEED.
See also:
 MEASURE(MEA) machine-errors FIXSEED MOVESEED
 SeedRandom

SHOW

SHOW prints out the current matching conditions.

   FFS["SHOW"] or FFS$SHOW[] returns the current matching conditions as a list. Each element has
a form of

{component1, component2, function, goal-value, number-of-momentums, scale},

which corresponds to the format of the print-out by SHOW.
See also:
 matching-function-commands FIT FFS
 FFS$SHOW

SPLIT

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.

STATUS(STAT)

STAT shows the current settings of flags, fit points, 
special-variables, the region for DISPLAY, seed of the random number generator, and elapsed CPU time,
etc.
See also:
 special-variables flags

STOP

Exits FFS and returns to SAD/MAIN level, with saving the values of the elements.
See also:
 QUIT SAVE ABORT
 USE VISIT BYE

TERMINATE(TERM)

   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.
See also:
 CLOSE(CLO) INPUT(IN) READ
 OUTPUT(OUT) APPEND(APP) END

TYPE(T)

Usage: TYPE [element-pattern [element-pattern1..]]

prints out the values of elements which match element-pattern in the SAD MAIN input format. Keywords
which have zero values are omitted unless it is the default variable. If non element-pattern is given,
all elements are printed out.
See also:
 DISPLAY(DISP) VARIABLES(VAR) elements

UNTIL

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.
See also:
 REPEAT(REP) expression command-syntax
 functions Do

USE

Usage: USE [[NO]EXPAND] beam-line

switches the beam line used in FFS to the beam line given by beam-line. beam-line 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.
See also:
 VISIT BYE EXPAND
 BeamLine BeamLineName

VARIABLES(VAR)

VARIABLES displays a list of current matching-variables 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 matching-variables given by
the FREE command. Each element has the form

  {name, keyword, present, previous, saved, minimum, maximum, coupled-master-element, coupling-coefficient}
,

which corresponds to the output of the VARIABLES(VAR) command.
See also:
 FREE COUPLE(COUP) FFS

VARY

Usage: VARY keyword element-pattern

changes the default-keyword of the elements which match element-pattern to keyword.
See also:
 FREE elements wildcards

VISIT

Usage: VISIT [[NO]EXPAND] beam-line

switches the beam line used in FFS to the beam line given by beam-line. beam-line 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.
See also:
 USE BYE EXPAND
 BeamLine BeamLineName

wildcards

   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.
See also:
 elements components DISPLAY(DISP)
 TYPE(T) SAVE RESET
 FREE FIX machine-errors ATTRIBUTE(ATTR)
 REJECT(REJ) CALCULATE(CAL) functions
 Element LINE Twiss