PTC Set-up Parameters

The E. Forest s Polymorphic Tracking Code (PTC) is a kick code, allowing a symplectic integration through all accelerator elements giving the user full control over the precision (number of steps and integration type) and exactness (full or extended Hamiltonian) of the results. The degree of exactness is determined by the user and the speed of his computer. The main advantage is that the code is inherently based on the map formalism and provides users with all associated tools.

The PTC code is actually a library that can be used in many different ways to create an actual module that calculates some property of interest. Several modules using the PTC code have been presently implemented in MAD-X. These MADX-PTC modules [b] are executed by the following commands: ptc_twiss, ptc_normal, ptc_track, ptc_track_line. To perform calculations with these MADX-PTC commands, the PTC environment must be initialized, handled and turned off by the special commands within the MAD-X input script.

Synopsis: PTC_CREATE_UNIVERSE, sector_nmul_max=integer, sector_nmul=integer, ntpsa=logical, symprint=logical;; PTC_CREATE_LAYOUT, time=logical, model=integer, method=integer, nst=integer, exact=logical, offset_deltap=double, errors_out=logical, magnet_name=string, resplit=logical, thin=double, xbend=double, even=logical;; .........................; PTC_READ_ERRORS, overwrite=logical;; .........................; PTC_MOVE_TO_LAYOUT, index=integer;; .........................; PTC_ALIGN;; .........................; PTC_END;

Commands

PTC_CREATE_UNIVERSE;

sector_nmul_max=integer, sector_nmul=integer

Description

The "PTC_CREATE_UNIVERSE" command is needed to set-up the PTC environment.

Options

Option Meaning Default Value Value Type

SECTOR_NMUL_MAX Global variable in PTC needed for exact sector bends defining up to which order Maxwell's equation are solved [a, page 76-77]. The value of SECTOR_NMUL_MAX must not be smaller than SECTOR_NMUL otherwise MAD-X stops with an error.
10
integer

SECTOR_NMUL Global variable in PTC needed for exact sector bends defining up to which order the multipole are included in solving Maxwell's equation up to order SECTOR_NMUL_MAX. Multipoles of order N with N > SECTOR_NMUL and N ≤ SECTOR_NMUL_MAX are treated a la SixTrack.
10
integer

NTPSA This attribute invokes the second DA package written in C++ and kindly provided by Lingyun Yang lyyang@lbl.gov. Etienne Forest has written the wrapper to allow both the use of the legendary DA packages written in Fortran by Martin Berz (default) or this new DA package. It is expected that this DA package will allow for the efficient calculation of a large number of DA parameters.
.FALSE.
logical

SYMPRINT This flag allows the supression of the printing of the check of symplecticity. It is recommended to leave this flag set to TRUE.
.TRUE.
logical

PTC_CREATE_LAYOUT,
    time=logical, model=integer, method=integer,
    nst=integer, exact=logical, offset_deltap=double, errors_out=logical, magnet_name=string, resplit=logical, thin=double, xbend=double, even=logical;

Description

The "PTC_CREATE_LAYOUT" command creates the PTC-layout according to the specified integration method and fills it with the current MAD-X sequence defined in the latest USE command.
The logical input variable time controls the coordinate system that is being used.

Options

Option Meaning Default Value Value Type

TIME 5D "time=true": fifth coordinate is PT, p_t=ΔE/p₀c;
.TRUE.
logical

"time=false": fifth coordinate is DELTAP, δ_p=Δp/p₀

6D "time=true": MAD-X coordinate system {-ct, p_t}

"time=false": second PTC coordinate system {-pathlength, δ_p}

MODEL Type of element: 1, 2,or 3.
1
integer

METHOD Integration order (2, 4, 6) [a, Chapter K]
2
integer

NST Number of integration steps: 1, 2, 3, .
1
integer

EXACT Switch to turn on calculations with an exact Hamiltonian,
otherwise the expanded Hamiltonian is used.
.FALSE.
logical

OFFSET_DELTAP
Beware: Expert flag! The relative momentum deviation of the reference particle
(6D case ONLY). This option implies "totalpath=true".

0.0
double

ERRORS_OUT
Flag to write-out multipolar errors in Efcomp table format. Two tables are filled "errors_field" and "errors_total". In the first case only field errors are written out and in the second one also desired field components are added. The latter is useful e.g. to include the strength of correctors. The choice of magnets is defined by the "magnet_name" attribute (see below). As usual the tables can be written to files for later use for read-in via the "ERRORS_IN" flag:

write, table=errors_field,file=Your_Errors_Field_File;
write, table=errors_total,file=Your_Errors_Total_File;

The "ERRORS_IN" flag has precedence over this "ERRORS_OUT" flag.

.FALSE.
logical

MAGNET_NAME
Simple selection for the names of magnet to be used for an error write-out using the "ERRORS_OUT" flag (see above). In fact, the errors are recorded for all magnets with their name starting with the exact string of "MAGNET_NAME".

NULL
string

RESPLIT
Flag to apply the PTC resplit procedure. This is meant to create an "adaptive" setting of the "METHOD" and "NST" attributes according to the strength of the quadrupoles (using the "THIN" attribute) and separatedly the dipoles (using the "XBEND" attribute). Additionally, there is the "EVEN" attribute for even and odd number of splits.

.FALSE.
logical

THIN
This is the main "RESPLIT" attribute. It is meant for splitting quadrupoles according to their strength. The default of "THIN=0.001" has shown in practice to work well without costing too much with respect of performance.

0.001
double

XBEND
This attribute is meant for splitting dipoles, e.g. "XBEND=0.001". It is an optional "RESPLIT" attribute and therefore has the default set to -1, which means no splitting. A splitting by "XBEND=0.001" maybe advisable for dipoles as well.

-1 (off)
double

EVEN
Switch to ensure even number of splits when using the PTC "RESPLIT" procedure. The default is "EVEN=TRUE". This is particularly useful when one attempts to calculate "PTC_TWISS" with then "CENTER_MAGNETS" option, i.e. if one would like to calculate the TWISS parameters in the center of the element. Uneven number of splits will be achieved with "EVEN=FALSE".

.TRUE.
logical

Remarks

TIME: at small energy (β₀ <<1), momentum-dependent variables like dispersion will depend strongly on the choice of the logical input variable "time". In fact, the derivative (∂/∂δ_p) and (∂/∂p_t) are different by the factor β₀. One would therefore typically choose the option "time=false", which sets the fifth variable to the relative momentum deviation δ_p.

MODEL:   1 for "Drift-Kick-Drift"; 2 for "Matrix-Kick-Matrix"; 3 for "Delta-Matrix-Kick-Matrix" (SixTrack-code model).

NST: sets the same value for all "thick" elements (l > 0) of a beam-line. Please note, that each individual element may have its own NST value (see below).

PTC_READ_ERRORS,
    overwrite=logical;

Description

The "PTC_READ-ERRORS" command let's you read any numbers of "errors_read" tables READMYTABLE

Options

Option Meaning Default Value Value Type

OVERWRITE
Flag to either OVERWRITE the read-in errors (on request by using this flag) or by DEFAULT just add them to multipole components already present.

.FALSE.
logical

Remarks

PTC_MOVE_TO_LAYOUT,
    index=integer;

Description

Several PTC layouts can be created within a one PTC-"universe". The layouts are automatically numbered with sequential integers by the MAD-X code. The "PTC_MOVE_TO_LAYOUT" is used for an activation of a requested layout and the next PTC commands will be applied to this active PTC layout until a new PTC layout will be created or activated.

Option

Option Meaning Default Value Value Type

INDEX Number of the PTC layout to be activated.
1

integer

PTC_ALIGN;

Description

The "PTC_ALIGN" command is used to apply the MAD-X alignment errors to the current PTC layout.

PTC_END;

Description

The "PTC_END" command is turning off the PTC environment, which releases all memory back to the MAD-X world proper;

Additional Options for Physical Elements

[SBEND | RBEND | QUADRUPOLE | SEXTUPOLE | OCTUPOLE | SOLENOID ],
    l=double, .....,tilt=double, ...., nst=integer, ...,
    knl:={0, double, double,..}, ksl:={0, double, double,..};

Description

1. The full range of normal and skew multipole components on the bench can be specified for the following physical elements: sbend, rbend, quadrupole, sextupole, octupole and solenoid.Multipole coefficients are specified as the integrated value "∫K ds" of the field components along the magnet axis (see the table below). These multipole components in PTC are spread over a whole element, if l > 0. This is a considerable advantage of PTC input compare to MAD-X which allows only thin multipoles.
2. To preserve the reference orbit of straight elements, dipole components for those elements are ignored, knl(0)=0, ksl(0)=0.
3. Individual NST values for a particular "thick" element (l > 0) can be specified. For example, in MAD-X any RF cavity is represented by a single kick, while PTC splits the RF cavity into (global) NST segments. In this way, PTC considers properly transit-time effects of the cavity. In case, one wants to reproduce the approximate results of MAD-X, one can use NST=1 for RF cavity in PTC.

Multipoles on Bench (PTC only)

Option Meaning Default Value Value Type

KNL The normal multipole coefficient
0 [m^-1]

double
array

KSL The skew multipole coefficient
0 [m^-1]

double
array

Remarks

Length l: Bending magnets (sbend, rbend) are treated as "markers", if l = 0.

Additional Field Errors: A full range of multipole field errors can be additionally specified with EFCOMP command. Errors are added to the above multipole fields on the bench.

Caution

A user has to understand that PTC exists inside of MAD-X as a library. MAD-X offers the interface to PTC, i.e. the MAD-X input file is used as input for PTC. Internally, both PTC and MAD-X have their own independent databases which are linked via the interface.

With the "PTC_CREATE_LAYOUT" command, only numerical numbers are transferred from the MAD-X database to the PTC database.

Any modification to the MAD-X database is ignored in PTC until the next call to "PTC_CREATE_LAYOUT".

For example, a deferred expression of MAD-X after a "PTC_CREATE_LAYOUT" command is ignored within PTC.

Examples

Examples for any MADX-PTC module contain the above PTC set-up commands.

References

E. Forest, F. Schmidt and E. McIntosh, Introduction to the Polymorphic Tracking Code , CERN-SL-2002-044-AP, KEK report 2002-3, July 2002.

F. Schmidt, "`MAD-X PTC Integration'', Proc. of the 2005 PAC Conference in Knoxville, USA, pp.1272.

See Also

ptc_twiss, ptc_normal, ptc_track, ptc_track_line.

Option	Meaning	Default Value	Value Type
SECTOR_NMUL_MAX	Global variable in PTC needed for exact sector bends defining up to which order Maxwell's equation are solved [a, page 76-77]. The value of SECTOR_NMUL_MAX must not be smaller than SECTOR_NMUL otherwise MAD-X stops with an error.	10	integer
SECTOR_NMUL	Global variable in PTC needed for exact sector bends defining up to which order the multipole are included in solving Maxwell's equation up to order SECTOR_NMUL_MAX. Multipoles of order N with N > SECTOR_NMUL and N ≤ SECTOR_NMUL_MAX are treated a la SixTrack.	10	integer
NTPSA	This attribute invokes the second DA package written in C++ and kindly provided by Lingyun Yang lyyang@lbl.gov. Etienne Forest has written the wrapper to allow both the use of the legendary DA packages written in Fortran by Martin Berz (default) or this new DA package. It is expected that this DA package will allow for the efficient calculation of a large number of DA parameters.	.FALSE.	logical
SYMPRINT	This flag allows the supression of the printing of the check of symplecticity. It is recommended to leave this flag set to TRUE.	.TRUE.	logical

Option	Meaning		Default Value	Value Type
TIME	5D	"time=true": fifth coordinate is PT, p_t=ΔE/p₀c;	.TRUE.	logical
	5D	"time=false": fifth coordinate is DELTAP, δ_p=Δp/p₀
	6D	"time=true": MAD-X coordinate system {-ct, p_t}
	6D	"time=false": second PTC coordinate system {-pathlength, δ_p}
MODEL	Type of element: 1, 2,or 3.		1	integer
METHOD	Integration order (2, 4, 6) [a, Chapter K]		2	integer
NST	Number of integration steps: 1, 2, 3, .		1	integer
EXACT	Switch to turn on calculations with an exact Hamiltonian, otherwise the expanded Hamiltonian is used.		.FALSE.	logical
OFFSET_DELTAP	Beware: Expert flag! The relative momentum deviation of the reference particle (6D case ONLY). This option implies "totalpath=true".		0.0	double
ERRORS_OUT	Flag to write-out multipolar errors in Efcomp table format. Two tables are filled "errors_field" and "errors_total". In the first case only field errors are written out and in the second one also desired field components are added. The latter is useful e.g. to include the strength of correctors. The choice of magnets is defined by the "magnet_name" attribute (see below). As usual the tables can be written to files for later use for read-in via the "ERRORS_IN" flag: write, table=errors_field,file=Your_Errors_Field_File; write, table=errors_total,file=Your_Errors_Total_File; The "ERRORS_IN" flag has precedence over this "ERRORS_OUT" flag.		.FALSE.	logical
MAGNET_NAME	Simple selection for the names of magnet to be used for an error write-out using the "ERRORS_OUT" flag (see above). In fact, the errors are recorded for all magnets with their name starting with the exact string of "MAGNET_NAME".		NULL	string
RESPLIT	Flag to apply the PTC resplit procedure. This is meant to create an "adaptive" setting of the "METHOD" and "NST" attributes according to the strength of the quadrupoles (using the "THIN" attribute) and separatedly the dipoles (using the "XBEND" attribute). Additionally, there is the "EVEN" attribute for even and odd number of splits.		.FALSE.	logical
THIN	This is the main "RESPLIT" attribute. It is meant for splitting quadrupoles according to their strength. The default of "THIN=0.001" has shown in practice to work well without costing too much with respect of performance.		0.001	double
XBEND	This attribute is meant for splitting dipoles, e.g. "XBEND=0.001". It is an optional "RESPLIT" attribute and therefore has the default set to -1, which means no splitting. A splitting by "XBEND=0.001" maybe advisable for dipoles as well.		-1 (off)	double
EVEN	Switch to ensure even number of splits when using the PTC "RESPLIT" procedure. The default is "EVEN=TRUE". This is particularly useful when one attempts to calculate "PTC_TWISS" with then "CENTER_MAGNETS" option, i.e. if one would like to calculate the TWISS parameters in the center of the element. Uneven number of splits will be achieved with "EVEN=FALSE".		.TRUE.	logical

Option	Meaning	Default Value	Value Type
KNL	The normal multipole coefficient	0 [m^-1]	double array
KSL	The skew multipole coefficient	0 [m^-1]	double array