The PTC-TRACK module [a] is the symplectic
thick-lens tracking facility in MAD-X [b]. It is based
on PTC library written by E.Forest [c]. The
commands of this module are described below, optional parameters are
denoted by square brackets ([ ]). Prior to using this module
the active beam line must be selected by means of a
USE command.
The general PTC
environment must also be initialized.
- Synopsis
PTC_CREATE_UNIVERSE;PTC_CREATE_LAYOUT, model=integer,method=integer,
nst=integer, [exact];..........................
PTC_START, .....;
..........................
PTC_OBSERVE,....;
..........................
PTC_TRACK, .....;
..........................
PTC_TRACK_END;..............................PTC_END;
- Commands
-
- PTC_START,
x=double,
px=double, y=double, py=double,
t=double, pt=double,
fx=double,
phix=double, fy=double,
phiy=double, ft=double, phit=double
;
-
- Description
- To start particle tracking, a series of initial trajectory
coordinates has to be given by means of PTC_START
command (as many commands as trajectories). It
must be done before the
PTC_TRACK command. The coordinates can be either
canonical coordinates (x,
px, y, py,
t, pt) or action-angle coordinates (fx, phix,
fy, phiy, ft, phit), which
are expressed by the normalized amplitude, Fz
and the phase,
Φz
for the z-th mode plane (z={x,y,t}).
The actions are computed with the values of the emittances, Fz,
which must be specified in the preceding
BEAM command.
Fz are expressed in
number of r.m.s. beam sizes and
Φz
are expressed in radians.
- Options
-
| Option |
Meaning |
Default Value |
Value Type |
| X, PX, Y, PY, T, PT |
canonical coordinates |
0.0 |
double |
| FX, PHIX, FY, PHIY, FT, PHIT |
action-angle coordinates |
0.0 |
double |
- Remarks
- 1. If the option
closed_orbit
in the
PTC_TRACK
command is active (see below), 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
closed_orbit is absent, then coordinates are specified with respect
to the reference orbit.
- 2. In the uncoupled case, the canonical
and the action-angle variables are related with equations
z=
Fz(Ez)1/2cos(Φz),
pz= Fz(Ez)1/2sin(Φz).
3. The use of the action-angle coordinates
requires the option
closed_orbit
in the
PTC_TRACK
command.
4. If both the canonical and the action-angle coordinates are
given in the PTC_START command, they
are summed after conversion of the action-angle coordinates to
the canonical ones.
- PTC_OBSERVE,
place=string;
-
- Description
- Besides of the beginning of the beam-line, one can
define an additional observation points along the
machine. Subsequent PTC_TRACK
command will then record the tracking data on all these
observation points.
- Option
-
| Option |
Meaning |
Value Type |
| PLACE |
name of observation point
(markers are very much preferred) |
string |
- Remarks
- 1. The first observation point at the beginning of
the beam-line is marked as "start".
2. It is recommended to use
labels of
markers in order to avoid usage observations at the ends of
thick elements.
3. The data at the observation points other than at
"start" can be produced by two different means:
a) traditional (MADX) element-by-element tracking (use
option element_by_element);
b) coordinate transformation from "start" to the
respective observation point using high-order PTC
transfer maps
(required option
closed_orbit;
turned off options radiation
and element_by_element).
- PTC_TRACK,
deltap=double, icase=integer, closed_orbit,
element_by_element, turns=integer,
dump, onetable, maxaper=double array, norm=integer,
norm_out,
file[=string], extension=string, ffile=integer,
radiation, radiation_model1, radiation_energy_loss,
radiation_quadr,
beam_envelope, space_charge;
-
- Description
- The PTC_TRACK command initiates
trajectory tracking by entering the thick-lens tracking module.
Several options can be specified, the most important are
presented in table "Basic Options". There are also switches to
use special modules for particular tasks. They are presented in
the table "Special Switches".
- The tracking can be done element-by-element using the option
element-by-element, or
"turn-by-turn" (default) with coordinate transformations over the whole
turn. Tracking
is done in parallel, i.e. the coordinates of all particles are
transformed through each beam element (option
element-by-element) or
over full turns.
- The particle is lost if its trajectory is outside the boundaries
as specified by maxaper option.
In PTC, there is a continuous check, if the particle
trajectories stays within the aperture limits.
The Normal Form calculations (required option
closed_orbit) is controlled
by norm_no and
norm_out
are used.
- Basic Options
-
| Option |
Meaning |
Default
Value |
Value
Type |
| ICASE |
user-defined dimensionality
of the phase-space (4, 5 or 6). |
4 |
integer |
| DELTAP |
relative momentum offset for
reference closed orbit
(used for 5D case ONLY). |
0.0 |
double |
| CLOSED_ORBIT |
switch to turn on
the closed
orbit calculation |
.FALSE. |
logical |
| ELEMENT_BY_ELEMENT |
switch from the
default
turn-by-turn tracking to
the
element-by-element tracking. |
.FALSE. |
logical |
| TURNS |
number of turns
to be tracked. |
1 |
integer |
| DUMP |
enforces writing of particle
coordinates to formatted text files |
.FALSE. |
logical |
| ONETABLE |
writing
all particle coordinates
to a single file |
.FALSE. |
logical |
| MAXAPER |
upper limits for the
particle
coordinates. |
{0.1,0.01,
0.1, 0.01,
1.0,0.1} |
double,
array (1:6) |
| NORM_NO |
order of the Normal Form |
1 |
integer |
| NORM_OUT |
switch to transform
canonical
variables to action-angle variables |
.FALSE. |
logical |
| FILE |
omitted |
no output written to a file |
|
|
| present |
file name for printing
the track tables. |
track |
string |
| EXTENSION |
the extension of filename for
the track
table, e.g., txt, doc etc
|
none |
logical |
| FFILE |
printing coordinates
after every FFILE
turns |
1 |
integer |
- Remarks
- ICASE: has a highest
priority over other options:
a) RF
cavity with non-zero voltage will be ignored for
icase=4, 5;
b) A
non-zero deltap will be ignored
for icase=4, 6.
However, if RF cavity has the voltage set to zero and
for icase=6, the code sets
icase=4.
DELTAP: is
ignored for icase=6, but the option
offset_deltap of the command
PTC_CREATE_LAYOUT may
be used, if
- the reference particle should
have an momentum off-set as specified by
offset_deltap.
CLOSED_ORBIT : It must
be used for closed rings only. This option allows to
switch ON
the Normal Form analysis, if required. If CLOSED_ORBIT is off, the sequence is
treated as a transfer line.
NORM_NO=1: makes the
Normal Form linear (always true for MAD8/X).
FILE: The output file endings are:
.obsnnnn(observation
point), followed by .pnnnn
(particle number),
if the onetable option is not
used.
- Special Switches
-
| Option |
Meaning |
Default
Value |
Value
Type |
| RADIATION |
turn on the synchrotron
radiation
calculated by an internal
procedure of PTC |
.FALSE. |
logical |
| RADIATION_MODEL1 |
switch to turn on the radiation
according to the
method given
in the Ref. [d]
|
.FALSE. |
logical |
| RADIATION_ENERGY_LOSS |
adds the energy loss for
radiation_model1 |
.FALSE. |
logical |
| RADIATION_QUADR |
adds the radiation in quadrupoles.
It supplements either
radiation,
radiation_model1 |
.FALSE. |
logical |
| BEAM_ENVELOPE |
turn on the calculations
of the beam
envelope with PTC |
.FALSE. |
logical |
SPACE_CHARGE
(under construction) |
turn on the simulations of the
space
charge forces between particles. |
.FALSE. |
logical |
- Remarks
-
1. RADIATION: Has precedence
radiation model1.
2. RADIATION_MODEL1: Additional
module by F. Zimmermann. The model simulates
quantum excitation via a random number generator and tables for
photon emission. It can be used only with the element-by-element
tracking (option element-by-element).
3. RADIATION_ENERGY_LOSS: Of use for
radiation_model1.
4. BEAM_ENVELOPE: It requires the options
radiation and icase=6.
5. SPACE_CHARGE: This option
is under construction and is reserved for future use.
-
- PTC_TRACK_END;
-
- Description
- The PTC_TRACK_END command terminate
the command lines related to the PTC_TRACK module.
- TRACKSUMM table
The starting and final
canonical coordinates are collected in the internal table "tracksumm" (printed to the file with
WRITE
command).
- Examples
- Several examples are found on the
here.
- The typical tasks
The following table
facilitates the choice of the correct options for a number of tasks.
-
| Option |
1 |
2 |
3 |
4 |
5 |
| CLOSED_ORBIT |
- |
- |
+ |
+ |
+ |
| ELEMENT_BY_ELEMENT |
- |
+ |
- |
+ |
- |
| PTC_START,
X, PX, ... |
+ |
+ |
+ |
+ |
+ |
| PTC_START, FX, PHIX, … |
- |
- |
+ |
+ |
+ |
| NORM_NO |
- |
- |
>1 |
>1 |
>1 |
| NORM_OUT |
- |
- |
+ |
- |
+ |
| PTC_OBSERVE |
- |
+ |
+ |
+ |
- |
| RADIATION |
- |
- |
- |
- |
+ |
| RADIATION_MODEL1 |
- |
- |
- |
- |
- |
| RADIATION_ENERGY_LOSS |
- |
- |
- |
- |
- |
| RADIATION_QUAD |
- |
- |
- |
- |
+/- |
| BEAM_ENVELOPE |
- |
- |
- |
- |
- |
| SPACE_CHARGE |
- |
- |
- |
- |
- |
-
- 1) The tracking of a beam-line with default parameters.
- 2) As “1)”, but with element-by-element tracking and an output
at observation points.
- 3) Tracking in a closed ring with closed orbit search and the
Normal Forms calculations.
Both canonical and action-angle
input/output coordinates are possible. Output at observation
points is produced via PTC maps.
- 4) Similar to "3)" except that output at observation points is
created by element-by-element tracking.
- 5) The with PTC radiation.
- References for PTC-TRACK
- V. Kapin and F. Schmidt, “PTC modules for MAD-X code”, to be published as CERN internal note by the end of
2006
- F. Schmidt, "`MAD-X PTC Integration'',
Proc. of the 2005 PAC Conference in Knoxville, USA, pp.1272.
- E. Forest, F. Schmidt and E. McIntosh,
“Introduction to the Polymorphic Tracking Code”, KEK report 2002-3, July
2002
- G.J. Roy, “A new method for the simulation of
synchrotron radiation in particle tracking codes”, Nuclear Instruments &
Methods in Phys. Res., Vol. A298, 1990, pp. 128-133.
