10.124 UKICKMAP—An undulator kick map (e.g., using data from RADIA).

An undulator kick map (e.g., using data from RADIA).
Parallel capable? : yes
GPU capable? : no
Back-tracking capable? : yes

Parameter NameUnitsType Default


L M double 0.0


TILT RADdouble 0.0

rotation about longitudinal axis

DX M double 0.0


DY M double 0.0


DZ M double 0.0



Factor by which to multiply the magnetic fields.

XY_FACTOR double 1

Factor by which to multiply the x and y values in the input file.

YAW double 0.0

Yaw angle of the device. Meaningful only if N_KICKS is not 1.


Name of SDDS file with undulator kickmap data.

N_KICKS long 1

Number of kicks into which to split the element.

PERIODS long 0

Number of periods (for radiation integral computations only).

KREF double 0.0

Reference value of undulator parameter. K=KREF*FIELD_FACTOR is used for radiation integral calculations only assuming period=L/PERIODS.

KACTUAL double 0.0

Value of undulator parameter, used for radiation integral calculations only assuming period=L/PERIODS.

SYNCH_RAD short 0

include classical, single-particle synchrotron radiation?

ISR short 0

include incoherent synchrotron radiation (quantum excitation)?

UKICKMAP continued

An undulator kick map (e.g., using data from RADIA).

Parameter Name UnitsType Default


YAW_END short 0

-1=Entrance, 0=Center, 1=Exit


if non-zero, the map file is for a single period. L still pertains to the full device. Set N_KICKS to the number of periods.


Optionally used to assign an element to a group, with a user-defined name. Group names will appear in the parameter output file in the column ElementGroup

This element provides simulation of undulators using kick maps [27]. For general-purpose kickmaps, use the KICKMAP element.

A script (km2sdds) is provided with the elegant distribution to translate RADIA [28] output into SDDS for use by elegant.

The input file has the following columns:

The values of x and y must be laid out on a grid of equispaced points. It is assumed that the data is ordered such that x varies fastest. This can be accomplished with the command

% sddssort -column=y,increasing -column=x,increasing input1.sdds input2.sdds

where input1.sdds is the original (unordered) file and input2.sdds is the new file, which would be used with UKICKMAP.

The data file is assumed to result from integration through a full device. If instead it results from integration through just a single period of a full device, one should set the SINGLE_PERIOD_MAP parameter to 1 and N_KICKS equal to the number of periods. (One can also use the FIELD_FACTOR parameter to get the same result, but this is confusing and is discouraged.)

elegant performs radiation integral computations for UKICKMAP and can also include radiation effects in tracking. This feature has limitations, namely, that the radiation integral computations assume the device is horizontally deflecting. However, in tracking, no such assumption is made. To obtain synchrotron radiation integral effects (e.g., in output from twiss_output), the KREF and PERIODS parameters must be given. Care must be taken when using the FIELD_FACTOR parameter in this case, particularly if it is adjusted to account for using a single-period kickmap multiple times. To obtain synchrotron radiation effects in tracking, the SYNCH_RAD and/or ISR flags must additionally be used.

N.B.: at present this element is not included in beam moments computations via the moments_output command (the CWIGGLER element is an option for that).

The YAW and YAW_END parameters can be used in the simulation of canted IDs. Normally, steering magnets are used to create an angle between the devices. The devices are thus oriented in the reference coordinate system, meaning the beam tranverses the IDs at an angle. If it is desirable to align the IDs to the beam, the IDs can be yawed. A positive yaw will tilt the ID so that it is colinear with a beam that has been kicked by a positive horizontal steering angle. The YAW_END parameter defines which end of the ID is held fixed when the yaw is applied.

This element was requested by W. Guo (BNL), who also assisted with the implementation and debugging.