Survey
The survey
command provides a simple interface to the geometric tracking code. [1] The geometric tracking can be used to place the elements of a sequence in the global reference system in Fig. 14.
mtbl, mflw [, eidx] = survey {
sequence=sequ, -- sequence (required)
range=nil, -- range of tracking (or sequence.range)
dir=1, -- s-direction of tracking (1 or -1)
s0=0, -- initial s-position offset [m]
X0=0, -- initial coordinates x, y, z [m]
A0=0, -- initial angles theta, phi, psi [rad] or matrix W0
nturn=1, -- number of turns to track
nstep=-1, -- number of elements to track
nslice=1, -- number of slices (or weights) for each element
implicit=false, -- slice implicit elements too (e.g. plots)
misalign=false, -- consider misalignment
save=true, -- create mtable and save results
title=nil, -- title of mtable (default seq.name)
observe=0, -- save only in observed elements (every n turns)
savesel=fnil, -- save selector (predicate)
savemap=false, -- save the orientation matrix W in the column __map
atentry=fnil, -- action called when entering an element
atslice=fnil, -- action called after each element slices
atexit=fnil, -- action called when exiting an element
atsave=fnil, -- action called when saving in mtable
atdebug=fnil, -- action called when debugging the element maps
info=nil, -- information level (output on terminal)
debug=nil, -- debug information level (output on terminal)
usrdef=nil, -- user defined data attached to the mflow
mflow=nil, -- mflow, exclusive with other attributes except nstep
}
Command synopsis
The survey
command format is summarized in Listing 1, including the default setup of the attributes. The survey
command supports the following attributes:
- sequence
The sequence to survey. (no default, required).
Example:
sequence = lhcb1
.- range
A range specifying the span of the sequence survey. If no range is provided, the command looks for a range attached to the sequence, i.e. the attribute . (default:
nil
).Example:
range = "S.DS.L8.B1/E.DS.R8.B1"
.- dir
The \(s\)-direction of the tracking:
1
forward,-1
backward. (default:1
).Example:
dir = -1
.- s0
A number specifying the initial \(s\)-position offset. (default:
0
[m]).Example:
s0 = 5000
.- X0
A mappable specifying the initial coordinates
{x,y,z}
. (default:0
[m]).Example:
X0 = { x=100, y=-50 }
- A0
A mappable specifying the initial angles
theta
,phi
andpsi
or an orientation matrixW0
. [2] (default:0
[rad]).Example:
A0 = { theta=deg2rad(30) }
- nturn
A number specifying the number of turn to track. (default:
1
).Example:
nturn = 2
.- nstep
A number specifying the number of element to track. A negative value will track all elements. (default:
-1
).Example:
nstep = 1
.- nslice
A number specifying the number of slices or an iterable of increasing relative positions or a callable
(elm, mflw, lw)
returning one of the two previous kind of positions to track in the elements. The arguments of the callable are in order, the current element, the tracked map flow, and the length weight of the step. This attribute can be locally overridden by the element. (default:1
).Example:
nslice = 5
.- implicit
A logical indicating that implicit elements must be sliced too, e.g. for smooth plotting. (default:
false
).Example:
implicit = true
.- misalign
A logical indicating that misalignment must be considered. (default:
false
).Example:
implicit = true
.- save
A logical specifying to create a mtable and record tracking information at the observation points. The
save
attribute can also be a string specifying saving positions in the observed elements:"atentry"
,"atslice"
,"atexit"
(i.e.true
),"atbound"
(i.e. entry and exit),"atbody"
(i.e. slices and exit) and"atall"
. (default:true
).Example:
save = false
.- title
A string specifying the title of the mtable. If no title is provided, the command looks for the name of the sequence, i.e. the attribute
seq.name
. (default:nil
).Example:
title = "Survey around IP5"
.- observe
A number specifying the observation points to consider for recording the tracking information. A zero value will consider all elements, while a positive value will consider selected elements only, checked with method
:is_observed
, everyobserve
\(>0\) turns. (default:0
).Example:
observe = 1
.- savesel
A callable
(elm, mflw, lw, islc)
acting as a predicate on selected elements for observation, i.e. the element is discarded if the predicate returnsfalse
. The arguments are in order, the current element, the tracked map flow, the length weight of the slice and the slice index. (default:fnil
)Example:
savesel = \e -> mylist[e.name] ~= nil
.- savemap
A logical indicating to save the orientation matrix
W
in the column__map
of the mtable. (default:false
).Example:
savemap = true
.- atentry
A callable
(elm, mflw, 0, -1)
invoked at element entry. The arguments are in order, the current element, the tracked map flow, zero length and the slice index-1
. (default:fnil
).Example:
atentry = myaction
.- atslice
A callable
(elm, mflw, lw, islc)
invoked at element slice. The arguments are in order, the current element, the tracked map flow, the length weight of the slice and the slice index. (default:fnil
).Example:
atslice = myaction
.- atexit
A callable
(elm, mflw, 0, -2)
invoked at element exit. The arguments are in order, the current element, the tracked map flow, zero length and the slice index-2
. (default:fnil
).Example:
atexit = myaction
.- atsave
A callable
(elm, mflw, lw, islc)
invoked at element saving steps, by default at exit. The arguments are in order, the current element, the tracked map flow, the length weight of the slice and the slice index. (default:fnil
).Example:
atsave = myaction
.- atdebug
A callable
(elm, mflw, lw, [msg], [...])
invoked at the entry and exit of element maps during the integration steps, i.e. within the slices. The arguments are in order, the current element, the tracked map flow, the length weight of the integration step and a string specifying a debugging message, e.g."map_name:0"
for entry and":1"
for exit. If the leveldebug
\(\geq 4\) andatdebug
is not specified, the default functionmdump
is used. In some cases, extra arguments could be passed to the method. (default:fnil
).Example:
atdebug = myaction
.- info
A number specifying the information level to control the verbosity of the output on the console. (default:
nil
).Example:
info = 2
.- debug
A number specifying the debug level to perform extra assertions and to control the verbosity of the output on the console. (default:
nil
).Example:
debug = 2
.- usrdef
Any user defined data that will be attached to the tracked map flow, which is internally passed to the elements method
:survey
and to their underlying maps. (default:nil
).Example:
usrdef = { myvar=somevalue }
.- mflow
A mflow containing the current state of a
survey
command. If a map flow is provided, all attributes are discarded exceptnstep
,info
anddebug
, as the command was already set up upon its creation. (default:nil
).Example:
mflow = mflow0
.
The survey
command returns the following objects in this order:
- mtbl
A mtable corresponding to the TFS table of the
survey
command.- mflw
A mflow corresponding to the map flow of the
survey
command.- eidx
An optional number corresponding to the last surveyed element index in the sequence when
nstep
was specified and stopped the command before the end of therange
.
Survey mtable
The survey
command returns a mtable where the information described hereafter is the default list of fields written to the TFS files. [3]
The header of the mtable contains the fields in the default order:
- name
The name of the command that created the mtable, e.g.
"survey"
.- type
The type of the mtable, i.e.
"survey"
.- title
The value of the command attribute
title
.- origin
The origin of the application that created the mtable, e.g.
"MAD 1.0.0 OSX 64"
.- date
The date of the creation of the mtable, e.g.
"27/05/20"
.- time
The time of the creation of the mtable, e.g.
"19:18:36"
.- refcol
The reference column for the mtable dictionnary, e.g.
"name"
.- direction
The value of the command attribute
dir
.- observe
The value of the command attribute
observe
.- implicit
The value of the command attribute
implicit
.- misalign
The value of the command attribute
misalign
.- range
The value of the command attribute
range
. [4]- __seq
The sequence from the command attribute
sequence
. [5]
The core of the mtable contains the columns in the default order:
- name
The name of the element.
- kind
The kind of the element.
- s
The \(s\)-position at the end of the element slice.
- l
The length from the start of the element to the end of the element slice.
- angle
The angle from the start of the element to the end of the element slice.
- tilt
The tilt of the element.
- x
The global coordinate \(x\) at the \(s\)-position.
- y
The global coordinate \(y\) at the \(s\)-position.
- z
The global coordinate \(z\) at the \(s\)-position.
- theta
The global angle \(\theta\) at the \(s\)-position.
- phi
The global angle \(\phi\) at the \(s\)-position.
- psi
The global angle \(\psi\) at the \(s\)-position.
- slc
The slice number ranging from
-2
tonslice
.- turn
The turn number.
- tdir
The \(t\)-direction of the tracking in the element.
- eidx
The index of the element in the sequence.
- __map
The orientation matrix at the \(s\)-position. [5]
Geometrical tracking
Fig. 8 presents the scheme of the geometrical tracking through an element sliced with nslice=3
. The actions atentry
(index -1
), atslice
(indexes 0..3
), and atexit
(index -2
) are reversed between the forward tracking (dir=1
with increasing \(s\)-position) and the backward tracking (dir=-1
with decreasing \(s\)-position). By default, the action atsave
is attached to the exit slice, and hence it is also reversed in the backward tracking.
Slicing
The slicing can take three different forms:
A number of the form
nslice=
\(N\) that specifies the number of slices with indexes0..N
. This defines a uniform slicing with slice length \(l_{\text{slice}} = l_{\text{elem}}/N\).An iterable of the form
nslice={lw_1,lw_2,..,lw_N}
with \(\sum_i lw_i=1\) that specifies the fraction of length of each slice with indexes0..N
where \(N=\)#nslice
. This defines a non-uniform slicing with a slice length of \(l_i = lw_i\times l_{\text{elem}}\).A callable
(elm, mflw, lw)
returning one of the two previous forms of slicing. The arguments are in order, the current element, the tracked map flow, and the length weight of the step, which should allow to return a user-defined element-specific slicing.
The surrounding P
and P
\(^{-1}\) maps represent the patches applied around the body of the element to change the frames, after the atentry
and before the atexit
actions:
The misalignment of the element to move from the global frame to the element frame if the command attribute
misalign
is set totrue
.The tilt of the element to move from the element frame to the titled frame if the element attribute
tilt
is non-zero. Theatslice
actions take place in this frame.
These patches do not change the global frame per se, but they may affect the way that other components change the global frame, e.g. the tilt combined with the angle of a bending element.
Sub-elements
The survey
command takes sub-elements into account, mainly for compatibility with the track
command. In this case, the slicing specification is taken between sub-elements, e.g. 3 slices with 2 sub-elements gives a final count of 9 slices. It is possible to adjust the number of slices between sub-elements with the third form of slicing specifier, i.e. by using a callable where the length weight argument is between the current (or the end of the element) and the last sub-elements (or the start of the element).
Examples
Footnotes