MAD-X PITFALLS

Find a loose collection of pitfalls that may be difficult to avoid in particular for new users but also experienced user might profit from this list.

Twiss calculation is 4D only!

The Twiss command will calculate an approximate 6D closed orbit when the accelerator structure includes an active cavity. However, the calculation of the Twiss parameters are 4D only. This may result in apparently non-closure of the beta values in the plane with non-zero dispersion. The full 6D Twiss parameters can be calculated with the ptc_twiss command. Presently, the Thinlens Tracking module suffers from this deficiency since it requires the true 6d closed orbit and not the approximate one as calculated by Twiss. In this context one has to mention that the coordinate system for the Twiss module is not x, px in the horizontal plane as the advertised canonical coordinates instead x, x' have been used (same for the vertical plane).

Mind you that for TWISS with the "CENTRE" attribute activated, i.e. looking inside the element, the closed orbit includes the misalignment of the element.

Dispersion for machines with small relativistic beta

The MAD-X uses the PT coordinate as the canonical momentum in the longitudinal plane. The derivative of e.g. dispersion is therefore not delta-p over p but PT. Therefore one unfortunately finds the dispersion being divided by the relativistic beta which is annoying for low energy machines. PTC allows to change the coordinate system to delta-p over p with the "time=false" option of the PTC_CREATE_LAYOUT command which delivers the proper dispersion with the ptc_twiss command.

Non-standard definition of DDX, DDPX, DDY, DDPY

The MAD-X proper defintion of DDX, DDPX, DDY, DDPY is not the second order derivative with respect to deltap/p but multiplied by a factor of 2. The corresponding values from ptc_normal and in ptc_twiss are the proper derivaties to all orders.

Chromaticity calculation in presence of coupling

Chromaticity calculations are typically in order and agree with PTC and other codes. However, it was recently discovered that in presences of coupling MAD-X simply seems to ignore coupling when the chromaticity is calculated. This is surprising since the eigentunes Q1, Q2 are properly calculated for a given (small!) dp/p. The issue is under investigation.

Field errors in thick elements

Only a very limited number of field error components are considered in TWISS calculations for some thick elements. Find below a complete list of all those field error components that are taking into account for a particular thick element. It should be mentioned that BENDs also allow a skew quadrupole component k1s but NOT in the body of the magnet. It is only active in the edge effect for radiation (expert use only).

Magnet Type	Normal Field Components	Skew Field Components
Bend	Dipole Quadrupole Sextupole	--- --- ---
HKicker	Dipole	---
VKicker	---	Dipole
Quadrupole	Quadrupole	Quadrupole
Sextupole	Sextupole	Sextupole
Octupole	Octupole	Octupole

MAD-X versus PTC

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

When introducing a cavity with the "harmon" instead of the "freq" attribute (highly discouraged!) a problem arises for ptc_twiss due to the fact that internally "harmon" is transferred to "freq" too late. A simple "twiss" command executed before PTC start-up will help. However, avoiding "harmon" is advantageous.

SLOW attribute in matching

The "slow" attribute enforces the old matching procedure and is considerably slower. Therefore we did not make it the default option. Recently a number of parameters, like "RE56", have been added to the list of matchable parameters in the default and fast version. Nevertheless, some parameters are only available when using the "slow" attribute. Therefore it is advisable to check with the "slow" attribute if there are doubts about the matching procedure.

Validity of Twiss parameters

The standard Teng-Edwards Twiss parameters suffer from a deficiency near full coupling: i.e. the "donuts" of linear motion in x-x' and y-y' phase space have no hole anymore. This means that all energy is transfered from one plane to the other. In this case the Twiss parameters and the coupling matrix (R11, R12, R21, R22) become large or even infinite or the beta functions might become negative. The Ripken-Mais Twiss parameters are always well defined (they are the "average" amplitude functions of their proper phase space region), i.e. at full coupling we have: beta11 ~ beta12 and beta21 ~ beta22. Using the "RIPKEN" flag Twiss calculates the Mais-Ripken parameters via a transformation from the Teng-Edwards Twiss parameters. Obviously this fails when the Teng-Edwards Twiss parameters are ill defined. In this case one has to rely on ptc_twiss.