The thin-lens tracking module of MAD-X performs element per element tracking of (one to many)
particle trajectories in the last used sequence.
Only thin elements are allowed (apart from the element drift), which guarantees
the symplecticity of the coordinate transformation. Any lattice can be converted into a "thin element" lattice
by invoking the makethin command.
- Synopsis
-
TRACK, onepass, deltap= double, dump;
START, x= double, px= double, y= double, py= double, t= double, pt= double;
RUN, turns= integer;
ENDTRACK;
- Commands
-
-
TRACK, deltap= double, onepass, dump, onetable, file= string; (MAD-X version 1)
TRACK, deltap= double, onepass, damp, quantum, dump, aperture, onetable, file= string; (MAD-X version 2)
TRACK, deltap= double, onepass, damp, quantum, dump, aperture, onetable, recloss, file= string; (MAD-X version 3)
[commands];
ENDTRACK;
-
- Description
-
The TRACK command initiates trajectory tracking by entering the
thin-lens tracking module. Several options can be specified, the most
important being dump, deltap and
aperture.
Inside the block TRACK-ENDTRACK a series
of initial trajectory coordinates can be specified by the START
command (as many commands as trajectories). This will be usually done in a
while-loop. Note that the coordinates are either
canonical coordinates or action-angle variables!
-
For usual tracking (single/multi-turn), all coordinates are specified with respect to the actual closed
orbit (possibly off-momentum, with magnet errors) and NOT with respect
to the reference orbit.
-
If the option onepass is used, the coordinates are specified with respect
to the reference orbit. The name "onepass" might be misleading: Still tracking can be single- or multi-turn!
The tracking is actually started with the RUN command, where the option
turns defines for how many turns the particles will be tracked in the
given sequence.
If the option dump is used, the particle coordinates are written
to files at each turn. The output files are named automatically. The name given by the user is followed
by .obsnnnn(observation point), followed by .pnnnn(particle number). Hence filenames look like
track.obs0001.p0001.
Tracking is terminated by the command ENDTRACK.
- Options
-
| Option |
Meaning |
Default Value |
Value Type |
| DELTAP |
relative momentum offset for reference closed orbit (switched off for onepass) |
0.0 |
double |
| ONEPASS |
the sequence is treated as transfer line (no stability test, ie. no closed-orbit search) |
.FALSE.= closed-orbit search |
logical |
| DAMP |
introduce synchrotron damping (needs RF cavity, RADIATE in BEAM) |
.FALSE.= no damping |
logical |
| QUANTUM |
introduce quantum excitation via random number generator and tables for photon emission |
.FALSE.= no excitation |
logical |
| DUMP |
write the particle coordinates in files (names generated automatically) |
.FALSE.= no file generated |
logical |
| APERTURE |
particle is lost if its trajectory is outside the aperture of the current element.
Notes. |
.FALSE.= no aperture check |
logical |
| ONETABLE |
write all particle coordinates in a single file |
.FALSE.= one file per particle |
logical |
| RECLOSS |
create a table named "trackloss" in memory with lost particles' coordinates |
.FALSE.= no table |
logical |
| FILE |
name for the track table |
"track", "trackone" |
string |
| UPDATE |
parameter update per turn |
.FALSE.= no update |
string |
- Remarks
-
IMPORTANT: If an RF cavity has a no zero voltage, synchrotron
oscillations are automatically included. If tracking with constant
momentum is desired, then the voltage of the RF cavities has to be set
to zero. If an RF cavity has a no zero voltage and DELTAP is non zero,
tracking is done with synchrotron oscillations around an off-momentum
closed orbit.
Defining a non-zero deltap results in a change of the
beam momentum/energy without changing the magnetic properties in the sequence. This
leads to a new closed orbit, the off-momentum closed orbit. Particle coordinates are
then given with respect to this new closed orbit, unless the option onepass
is used!
If the option onepass is used, no closed orbit is searched, which also means
that no stability test is done. Use this option if you want to get the particles' coordinates with
respect to the reference orbit rather than the closed orbit. Unfortunately the name is misleading,
but for backwards compatibility it is kept. "onepass" does NOT restrict the tracking
to one turn only!
- If the aperture option is applied, the apertype
and aperture
information of each element in the sequence is used to check whether the particle is lost or not.
For further information on the definition of apertures and different aperture types,
see the documentation of the APERTURE
module.
- In case no aperture information was specified for an element,
the following procedure will currently take place:
→ No aperture definition for element →
Default apertype/aperture assigned (currently this is
apertype= circle, aperture = {0})
→
If tracking with aperture is used and an
element with apertype= circle AND aperture= {0}
is encountered, then the first value of the maxaper vector
is assigned as the circle's radius (no permanent assignment!).
See option maxaper for
the default values.
⇒
Hence even if no aperture information is specified by the user for certain elements,
default values will be used!
Traditionally, when a particle is lost on the aperture, this information is written to stdout. To allow more flexible
tracking studies, the lost particles' coordinates and further information can also be saved in a table in memory.
Usually one would save this table to a file using the WRITE command after the tracking run has finished.
The following information is available in the TFS table "trackloss":
- Particle ID (number)
- Turn number
- Particle coordinates (x,px,y,py,t,pt)
- Longitudinal position in the machine (s)
- Beam energy
- Element name, where the particle is lost
Changed behaviour for time variation in tracking. Use
track command option 'update' (e.g.: 'track, onepass,
update;') to use the following additions:
- Introduced special variable ('tr$turni') that can be
used in expressions like 'KICK:= sin(tr$turni)' and is updated at each turn during tracking.
- Introduced special macro ('tr$macro') that can be
user-defined ('tr$macro(turn): macro = {whatever
depending on turnnumber;};') and is executed/updated at each turn during tracking.
(Macro is necessary e.g. for table access.)
- START, x= double, px= double, y= double, py= double, t= double, pt= double;
START, fx= double, phix= double, fy= double, phiy= double, ft= double, phit= double;
-
- Description
-
After the TRACK command, a series of initial trajectory coordinates has to be given
by means of a START command (as many commands as trajectories). The coordinates can
be either canonical coordinates,
START, X= double, PX= double, Y= double, PY= double, T= double, PT= double;
or action-angle coordinates,
START, FX= double, PHIX= double, FY= double, PHIY= double, FT= double, PHIT= double;
For this case the normalised amplitudes are expressed in number
of r.m.s. beam size FX, FY, FT (the actions being computed with the
emittances in the BEAM
command) in each mode plane. The phases are PHIX, PHIY and PHIT
expressed in radian.
In the uncoupled case, we have in the plane mode labelled z,
Z = Fz sqrt(Ez) cos(PHIz),
Pz= Fz sqrt(Ez) sin(PHIz),
where Ez is the r.m.s. emittance in the plane Z.
- Options
-
| Option |
Meaning |
Default Value |
Value Type |
Unit |
| X, PX, Y, PY, T, PT |
canonical coordinates |
0.0 |
double |
m |
| FX, PHIX, FY, PHIY, FT, PHIT |
action-angle coordinates |
0.0 |
double |
rad |
- Remarks
-
-
For usual tracking (single/multi-turn), all coordinates are specified with respect to the actual closed
orbit (possibly off-momentum, with magnet errors) and NOT with respect
to the reference orbit.
-
If the option onepass is used, the coordinates are specified with respect
to the reference orbit. The name "onepass" might be misleading: Still tracking can be single- or multi-turn!
- OBSERVE, place= string;
-
- Description
-
Coordinates can be recorded at places that have names. Such observation points are
specified by the command OBSERVE (as many commands as places).
The output files are named automatically. The name given by the user is followed
by .obsnnnn(observation point), followed by .pnnnn(particle number). Hence filenames look like
track.obs0001.p0001.
- Options
-
| Option |
Meaning |
Default Value |
Value Type |
| PLACE |
name of the observation point |
|
string |
- Remarks
-
If no OBSERVE command is given, but the dump option in the
TRACK command is used, the particles trajectory coordinates are still recorded.
The observation point is then the starting point of the sequence.
- RUN, maxaper= double array, turns= integer, ffile= integer;
-
- Description
-
The actual tracking itself is launched by the RUN command. Via the option
turns the user can specify how many turns will be tracked.
- Options
-
| Option |
Meaning |
Default Value |
Value Type |
| MAXAPER |
upper limits for the six coordinates |
{0.1, 0.01, 0.1, 0.01, 1.0, 0.1} |
double array |
| TURNS |
number of turns |
1 |
integer |
| FFILE |
periodicity for printing coordinates |
1 |
integer |
- Remarks
-
The limits defined by the maxaper option are only being taken into account if the
aperture option of the TRACK command is used.
- Remarks
-
- Plotting is possible in MAD-X, however it can also be done
externally by using the files created by TRACK.
- The following internal tables are created while tracking:
tracksumm, trackloss, and trackone or track.obs$$$$.p$$$$
(depending on option onetable).
These internal tables can be accessed via the
table-access functions.
