R.C. Fernow *et al*

Brookhaven National Laboratory

.

*Caveat Emptor*

ICOOL is under active development at the present time. It is being made available as a potential

aid to members of the Neutrino Factory and Muon Collider Collaboration for studying ionization

cooling problems. Although considerable effort has gone into making the code give accurate

answers, it is ultimately the user’s responsibility to check that the program gives reasonable

answers to any specific problem.

Acknowledgments

I would like to thank my colleagues here at Brookhaven National Laboratory and in the Neutrino Factory and Muon Collider Collaboration for pointing out errors, making useful suggestions for improvements, and contributing new software to ICOOL.

Contents

1. Introduction

1.1 Comments in the ICOOL simulation control file for001.dat

1.2 Name substitution in the control file for001.dat

1.5 Keyboard input during execution

2.1 Problem title

2.4 Physics interactions control variables

2.5 Histogram definition variables

2.6 Scatterplot definition variables

2.7 Z-history definition variables

2.8 R-history definition variables

2.9 Emittance plane definition variables

2.10 Covariance plane definition variables

3. Region definition variables

SECTION start
of problem description

BEGS begin
repeating part of section

REPEAT start
of repeated

CELL start
of cell

SREGION start
of region

ENDREPEAT end of
repeating

ENDCELL end
of cell

ENDSECTION end
of problem description

APERTURE transverse
cut

BACKGROUND start
of background field definition

BFIELD defines background field

CUTV cut on ICOOL variable

DENP set
variable density profile

DENS adjust
material density

DISP randomly
displaces coordinates

DUMMY place
holder (do nothing) command

DVAR change
particle variable

EDGE fringe
field and other kicks for hard-edge fields

ENDB end
of background field definition

GRID define magnetic field
grid

OUTPUT writes
data to for009.dat

REFP RF
reference particle parameters

REF2 2nd
RF reference particle

RESET force
particle time to reference time

RKICK random
field kick

ROTATE rotates coordinates around specified axis

TAPER use
solenoid lattice with tapered currents

TILT randomly
rotates coordinates in 3D

TRANSPORT transforms
beam coordinates by matrix

! comment line

& name
substitution

3.3 Regular and pseudoregion command parameters

4. Field, material and geometry parameters

NONE no field

ACCEL accelerator

BLOCK thick solenoidal current block

BROD bent axial current rod

BSOL “bent solenoid” – combined solenoid and transverse fields

COIL coil

DIP vertical field sector dipole

EFLD electric field

FOFO alternating solenoid lattice

HDIP horizontal field sector dipole

HELIX
he

HORN magnetic horn

KICK kickers, deflection cavity

QUAD quadrupole

ROD current carrying rod

SEX sextupole

SHEET current sheet

SOL solenoid

SQUA skew quadrupole

STUS static user magnetic field

WIG wiggler

4.2 Material tags

VAC vacuum

GH gaseous hydrogen

GHE gaseous helium

LH liquid hydrogen

LHE liquid helium

LI lithium

BE beryllium

B boron

C carbon

TI titanium

FE iron

CU copper

W tungsten

HG mercury

PB lead

LIH lithium hydride

CH2 polyethylene

4.3 Geometry tags and parameters

NONE no material

ASPW azimuthally symmetric polynomial wedge

ASRW azimuthally symmetric radial wedge

CBLOCK cy

HWIN hemispherical absorber end

NIA non-isosceles absorber

PWEDGE asymmetric polynomial edge wedge

RING annular block

WEDGE
asymmetric

5. Other files

5.1 Input files

5.1.1 Beam input data

5.1.2 r-z grid magnetic field input data

5.1.3 RF cavity parameters

5.2 Output files

5.2.1 Program log file

5.2.2 Beam information at specified region

5.2.3 Postprocessor data file

5.2.4 Field
values on cy

5.2.5 Field values on 3D grid

5.2.6 RF diagnostics

5.2.7 Neutrino production data

5.2.8 Beam moments

5.2.9 Region summary table

ICOOL is a 3-dimensional tracking program that was originally written to study ionization

cooling of muon beams^{[1]}
. The program simulates particle -by- particle propagation through

materials and electromagnetic fields. Particles are tracked and regions are described using

"accelerator" coordinates. The program was written with low energy (1 MeV/c -- 1 GeV/c)

muons in mind, but tracking of electrons, pions, kaons, and protons is also possible.

The physics processes included are decays, delta rays, multiple scattering, energy loss and

straggling. Large sections of the physics interaction code was taken from GEANT v3.21 with

minimal interface changes.

Information is input to the code via an ASCII data file, described in section 2.

The incident beam particles can be generated from uniform or Gaussian distributions or read from an input file. The code can read its own output, so simulations can be staged. The particles are tracked through a sequence of regions that have a fixed length in z. In general a region is

cylindrical in shape and may be subdivided radially. Every region has a specified material and

field type associated with it. Groups of regions can be

can be superimposed over the region fields when tracking is done. In general the program takes

user-defined steps along the reference trajectory. For each step it updates the particle position and momentum, taking into account the local field, and corrects the particle's momentum for energy loss and multiple scattering in the step. There is an option for letting the program make adaptive step sizes.

ICOOL uses analytic and other procedures to compute field strengths at a given location. There are in general several model levels for each field type that gives the approximation used to calculate the field.

The program always generates an output log file. In addition, depending on control variable

settings, it may generate several other output files.

The quantities to plot come from a list of predefined quantities. Plots can be made at the

origin and after each region. Z-histories are plots made at user-defined steps in z. There are

options to save information about each particle after every region (or step) in an "n-tuple" file.

This manual defines all the parameters used by ICOOL. For an introduction to using ICOOL see the User’s Guide, ICguide.pdf

1.1 Comments
in the ICOOL simulation control file for001.dat

“Comments and blank lines can help format a control file so that it is more understandable to

human readers. The computer subroutines that read and parse control files don't want to see the

comments and blank lines. A new subroutine in ICOOL removes comments and blank lines

before the command processor parses them.

**Rules for commenting a control file**

A *comment* is any string of printable characters whose
leftmost character is an exclamation

point.

! This is a comment.

!So is this.

! Additional exclamation points !! in a comment don't matter.

A *whitespace *is either a space or a horizontal tab.

A *blank line *either has no characters (except for the
end-of-line terminator) or no characters

except whitespaces. Blank lines may be placed anywhere in the control file. They are ignored by

the command parser.

A *comment line *contains a comment, preceded by zero
or more whitespaces. Comment lines

may be placed anywhere in the control file. They are ignored by the command parser.

An *end-of-line comment *is a comment placed to the
right of a normal input line. End-of-line

comments may be placed at the end of any input line, separated from the data ICOOL is to parse

by zero or more whitespaces.

1.2342.345 !This is an end-of-line comment.

3.4564.567!So is this (valid but hard to read).

RING!This is valid even though "RING" will be read into a 6-character field.

RING !This is a more readable end-of-line comment.

**The Use of Informal Comments**

Though it is not forbidden, users are strongly discouraged from using "informal comments" --

those without leading exclamation points that are imagined to be out of view of the parser. There

are numerous ways to go wrong. For example, free format reads can extract data from more than

one input line; an informal comment on the end of any but the last line will generally produce an

error. An informal comment following a text string must come with enough preceding spaces to

fill the input field with spaces. All of these potential problems are avoided by using formal

comments with leading exclamation points.” {S.B.}

Any parameter in the input command file for001.dat can be defined symbolically using the command

&SUB name value

Following this command any occurrence of the text string

&name

is replaced with its value. Do not use

A variant allows
sca

&SCL NameString type value

*NameString* is a set of characters. All previously
defined names that begin with this character string will be scaled. The
variables may be either additively or multiplicatively scaled, depending on the
value of *type* = {*, +}. The amount of scaling is determined by *value*.

Drift space example with a
scatterplot of x vs. y

&cont npart=500 / ! control variables

&bmt /
! beam definition

1 2 1. 1
! Gaussian definition of muon beam

0. 0. 0. 0. 0. 0.200 ! means

3e-3 3e-3 0.01 0.005 0.005 0.010 ! sigmas

0
! no imposed beam correlations

&ints /
! use default interactions

&nhs /
! no histograms

&nsc nscat =1 /
! define 1 scatter plot

-0.10 5e-3 40 1 2 -0.10 10e-3 20 2 2

&nzh /
! no z-histories

&nrh /
! no r-histories

&nem /
! no 2-D emittance calculations

&ncv /
! no covariance calculations

SECTION
! start problem definition

SREGION
! define a region

1.00 1 0.003 ! length, 1 radial subregion, step

1 0. 0.10 ! radial extent

NONE
! no associated field

0. 0. 0. 0. 0. 0. 0. 0. 0.
0. 0. 0. 0. 0. 0.

VAC ! vacuum material

CBLOCK
! cylindrical block geometry

0. 0. 0. 0. 0. 0. 0. 0. 0.
0.

ENDSECTION
! end of problem definition

More complicated example
with REFP, GRID, and CELL commands

&cont npart=500 / ! control variables

&bmt /
! beam definition

1 2 1. 1
! Gaussian definition of muon beam

0. 0. 0. 0. 0. 0.200 ! means

3e-3 3e-3 0.01 0.005 0.005 0.010 ! sigmas

0
! no imposed beam correlations

&ints /
! use default interactions

&nhs /
! no histograms

&nsc /
! no scatter plots

&nzh /
! no z-histories

&nrh /
! no r-histories

&nem /
! no 2-D emittance calculations

&ncv /
! no covariance calculations

SECTION
! start problem definition

REFP
! define a reference particle

2 0.186 0. 0. 3

GRID
! save field from file of current

1
! sheets in grid array #1

SHEET
! use current sheets

0 20 0.01 0.01 1.51
0.11 15. 0 21 0 0 0 0 0 0

CELL
! begin cell structure

16
! repeat 16 times

.true.
! alternate field polarity

SHEET
! define the associated cell field

5 1 2 0 0 0
0 0 0 0 0 0 0 0 0

SREGION
! define the region inside the cell

1.50 1 0.003 ! length, 1 radial subregion, step

1 0. 0.10 ! radial extent

ACCEL
! rf cavity field

2 805 36 0. 0. 0. 0.
0. 0. 0. 0. 0. 0. 0. 0.

VAC ! vacuum material

CBLOCK
! cylindrical block geometry

0. 0. 0. 0. 0. 0. 0. 0. 0.
0.

ENDCELL ! end this cell structure

ENDSECTION
! end of problem definition

1.5 Keyboard input during execution

ICOOL recognizes two keyboard inputs while it is executing.

p pauses execution until the Enter key is pressed

x stops execution with the current particle and region and executes any end of run diagnostics.

The input file consists of:

1. problem title

2. general control variables

3. beam generation variables

4. physics interactions control variables

5. histogram definition variables

6. scatterplot definition variables

7. Z-history definition variables

8. R-history definition variables

9. emittance plane definition variables

10. covariance plane definition variables

11. region definition variables

The first 10 types of these variables are discussed in this section. Region definition variables are discussed in section 3.

A 79 character title for the problem. This title is written onto files 2, 4, and 9, described

below.

Namelist: CONT

BETAPERP (R) beta value to use in calculating
amplitude variable A^{2}

BGEN (L) if .true. => generate initial beam particles, otherwise read input from

FOR003.DAT (true)

BUNCHCUT (R) maximum time difference allowed between a particle and the reference

particle [s] (1E6)

BZFLDPRD (R) Bz for solenoid at location of production plane (0.) This is used for output to file for009.dat and for canonical angular momentum correction.

DECTRK (L) if .true. => continue tracking daughter particle following decay (false)

DIAGREF (L)
if .true. => specify p_{Z} and t relative to the reference
particle for ICOOL internal diagnostics
(F)

EPSF (R) desired tolerance on fractional field variation, energy loss, and

multiple scattering per step (0.05)

EPSREQ (R) required tolerance on error in tracking parameters (1E-3) This parameter is only used if varstep = true

EPSSTEP (R) desired tolerance in spatial stepping to reach each destination plane

[m] (1E-6)

FFCR (L) if .true. => inserts form feed and carriage returns in the output log file

so there are two plots per page starting at the top of a page (false)

FORCERP (L) if .true. => set x, y, Px, and Py for reference particle to 0 for each

new REFP command and for each ACCEL region with phasemodel=4. (true)

FSAV (L) if .true. => store particle info at plane IZFILE into file

FOR004.DAT. (false)It is possible to get the initial distribution of particles that get a given

error flag be setting the "plane"=IFAIL #. It is possible to get the initial distribution of particles

that successfully make it to the end of the simulation by setting the plane= -1.

FSAVSET (L) if .true. => modify data stored using FSAV in FOR004.DAT to have

z=0 and times relative to reference particle at plane IZFILE. (false)

F9DP (I) number of digits after the decimal point for floating point variables in FOR009.DAT {4,6,8,10,12,14,16,17} (4) F9DP=17 gives 16 digits after the decimal point and 3 digits in the exponent.

GOODTRACK (L) if .true. and BGEN=.false. => only accepts input data from

file FOR003.DAT if IPFLG=0.; if .false. => resets IPFLG of bad input tracks to 0 (this allows

processing a file of bad tracks for diagnostic purposes) (true)

IZFILE (I) z-plane where particle info is desired when using FSAV. Use 1 to

store beam at production. Saves initial particle properties for bad tracks if IZFILE=IFAIL #.

Saves initial particle properties for tracks that get to the
end of the simulation if IZFILE=-1.

IZFILE should point to the end of a REGION or to an APERTURE , ROTATE or
TRANSPORT

pseudoregion command.

MAGCONF (I) if 19 < MAGCONF=mn < 100 => reads in file FOR0mn.DAT, which

contains data on solenoidal magnets. Used with SHEET, model 4.(0)

MAPDEF (I) if 19 < MAPDEF=mn < 100 => reads in file FOR0mn.DAT, which

contains data on how to set up field grid. Used with SHEET, model 4.(0)

NEIGHBOR (L) if .true. => include fields from previous and following regions when

calculating field. (false) This parameter can be used with soft-edge fields when the magnitude of

the field doesn't fall to 0 at the region boundary. A maximum of 100 regions can be used with this feature.

NEUTRINO (I) if 19 < NEUTRINO=mn < 100 => writes out file FOR0mn.DAT,

which contains neutrino production data. See section 5.2 for the format. (0)

NNUDK (I) # of neutrinos to produce at each muon, pion and kaon decay. (1)

NPART (I) # of particles in simulation. The first 300,000 particles are stored in memory. Larger numbers are allowed in principle since ICOOL writes the excess particle information to disc. However, there can be a large space and speed penalty in doing so.

NPRNT (I) # of diagnostic events to print out to log file (-1)

NSECTIONS (I) # of times to repeat basic cooling section (1)

This parameter can be used to repeat all the commands between the SECTION and ENDSECTION commands in the problem definition. If a REFP command immediately follows

the SECTION command, it is not repeated.

NTUPLE (L) if .true. => store information about each particle after every

region in file FOR009.DAT. This variable is forced to be false if RTUPLE= true.(false)

NUTHMIN (R) Minimum polar angle to write neutrino production data to file.

[radians] (0.)

NUTHMAX (R) Maximum polar angle to write neutrino production data to file.

[radians] (3.14)

OUTPUT1 (L) if .true. => write particle information at production (plane 1) to the

postprocessor output file for009.dat. (false)

PHANTOM (L) if .true. => force particle to keep initial transverse coordinates after

every step. This is useful for making magnetic field maps. (false)

PHASEMODEL (I) controls how the phase is determined in rf cavities. (1)

1: takes phase directly from ACCEL command [degrees]

2 - 6: takes phase model from REFP command

7: reads phases in from file FOR0mn.DAT, where RFPHASE=mn. See sec. 5.1.

PRLEVEL (I) controls level of print information to log file (for NPRINT

events);higher # gives more print(1)

1: values at end of region

2: + values at end of each time step

3: + E,B values at each step

4: + information in cylindrical coordinates

PRNMAX (I) Sets maximum number of steps to generate print out inside a region

(300)

PZMINTRK (R) Sets the value of Pz below which tracking stops. [GeV/c] (0.001)

RFDIAG (I) if 19 < RFDIAG=mn < 100 => writes rf diagnostic information at the

end of each accelerator region to file FOR0mn.DAT. (0)

RFPHASE (I) if PHASEMODEL=5 => reads rf phases, frequencies and gradients

for the cavities from file FOR0mn.DAT, where RFPHASE=mn

and 19 < mn < 100 (0)

RNSEED (I) random number seed (-1) Set to a negative integer.

RTUPLE (L) if .true. => particle information in file FOR009.DAT is generated after

every RTUPLEN steps. (false)

RTUPLEN (I) # of steps to skip between RTUPLE generated outputs. (5)

RUN_ENV (L) if true => run ICOOL in beam envelope mode, i.e. no tracking (false)

For solenoidal channels only.

SCALESTEP (R) factor that modifies all step sizes in a problem simultaneously (1.0)

Only works in fixed stepsize mode.

SPIN (L) if .true. => include calculation of polarization. (false)

SPINMATTER (I) controls whether muon depolarization effects in matter are simulated

(0)

0: no depolarization simulation

1: depolarization simulation using Rossmanith model

2: depolarization simulation using spin flip probabilities

SPINTRK (I) controls whether spin variables are tracked (0)

0: no spin tracking

1: track spin in muon rest frame using BMT equations

STEPMAX (R) maximum step size that can be used for variable stepping [m]

(1)

STEPMIN (R) minimum step size that can be used for variable stepping [m]

(1E-5)

STEPRK (L) if .true. => use 4^{th}
order Runge-Kutta integrator for tracking.

Otherwise it uses the Boris push method in straight regions. (true)

SUMMARY (L) if true => writes region summary table to for007.dat (true)

TERMOUT (L) if .true. => write output to terminal screen (true)

TIMELIM (R) time limit for simulation [min] (1E9)

VARSTEP (L) if .true. => use adaptive step size; otherwise use fixed step ZSTEP

(until reaching the last step in a region). This variable is forced to be false (1) in wedge material

regions, (2) when the number of radial regions is greater than 1, and (3) when PHASEMODEL=2. (true)

2.3 Beam generation variables

Namelist: BMT

NBEAMTYP (I) # of beam types, e.g. particles of different mass {1-5} (1)

BMALT (L) if true => flip sign of alternate particles when BGEN = true. (false)

Other input variables

The following input is only read if BGEN = .true.

(2-4 repeated for each beam type)

2.1) PARTNUM (I) particle number

2.2) BMTYPE (I) beam type { magnitude = 1:e 2:mu 3:pi 4:K 5:p; sign = charge}

2.3) FRACBT (R) fraction of beam of this type {0-1} The sum of all fracbt(i) should =

1.0

2.4) BDISTYP (I)beam distribution type {1:Gaussian 2:uniform circular segment}

If BDISTYP = 1

3.1) X1BT(i),i=1,3 (R) mean value of x,y,z for this beam type [m]

3.2) P1BT(i),i=1,3 (R)mean value of px,py,pz for this beam type [GeV/c]

4.1) X2BT(i),i=1,3 (R)standard deviation of x,y,z for this beam type; assumes Gaussian [m]

4.2) P2BT(i),i=1,3 (R)standard deviation of px,py,pz for this beam type;

assumes Gaussian [GeV/c]

If BGEN=false, VARSTEP=false, and a particle in the input
file has a starting z location z_{0} greater than 0, then the particle
will not be tracked until the z stepping logic in the code reaches z_{0}.

If BDISTYP = 2

3.1) X1BT(1),X2BT(1) (R)r_low,r_high [m] {>0}

3.2) X1BT(2),X2BT(2) (R) phi_low,phi_high [degrees]

3.3) X1BT(3),X2BT(3) (R) z_low,z_high [m]

4.1) P1BT(1),P2BT(1) (R) Pr_low,Pr_high [GeV/c] {>0}

4.2) P1BT(2),P2BT(2) (R) Pphi_low,Pphi_high GeV/c]

4.3) P1BT(3),P2BT(3) (R) Pz_low,Pz_high [GeV/c]

5) NBCORR (I) # of beam correlations {0-10}

(6-repeated NBCORR times)

6.1) CORRTYP (I) correlation type

6.2) CORR1(i) (R) correlation parameter 1

6.3) CORR2(i) (R) correlation parameter 2

6.4) CORR3(i) (R) correlation parameter 3

CORRTYP = 1 angular momentum appropriate for constant solenoid field

= 2 Palmer amplitude correlation

= 3 rf bucket, small amplitude ellipse

= 4 rf bucket, small amplitude separatrix

= 5 rf bucket, large amplitude separatrix

= 6 Twiss parameters in x Px

= 7 Twiss parameters in y Py

= 8 (not used)

= 9 equal time in solenoid

=10 Balbekov version of amplitude-energy

=11 dispersion

For CORRTYP = 1

2 solenoid field [T]

Value should equal effective solenoid field in the body of the magnet.

For CORRTYP = 2

2 correlation strength

3 effective β_{^}_{ }[m]

dPz = CORR1 * ( (r/CORR2)^2+X'^2 + Y'^2)

For CORRTYP = 3,4

2 peak electric field on axis[MV/m]

3 synchronous phase [degrees]

4 rf frequency [MHz]

Set desired σ_{Z} in input beam definition. Set
σPz = 0.

For CORRTYP = 5

2 peak electric field on axis[MV/m]

3 synchronous phase [degrees]

4 rf frequency [MHz]

Set σ_{Z} and σPz = 0 in input beam
definition.

For CORRTYP = 6

2 Twiss alpha parameter

3 Twiss beta parameter [m]

4 Twiss epsilon parameter[m]

The spread in x and Px in the beam definition are ignored. For Gaussian distributions epsilon is

the rms geometrical emittance. For uniform distributions it specifies the limiting ellipse.

For CORRTYP = 7

2 Twiss alpha parameter

3 Twiss beta parameter [m]

4 Twiss epsilon parameter[m]

The spread in y and Py in the beam definition are ignored. For Gaussian distributions epsilon is

the rms geometrical emittance. For uniform distributions it specifies the limiting ellipse.

For CORRTYP = 9

2 desired axial beta (=v/c) value βo

3 azimuthal angle of transverse momentum [deg]

Set up with pz and σPz such that βz > βo. Set up initial pt = 0. This correlation determines the pt

for a given pz that gives all the initial particles the same βo. If parameter 3 is 0, the azimuthal

angle is chosen randomly.

For CORRTYP = 10

2 E_{ref} [GeV]

3 B_{abs} [ T ]

4 σ_{E} [GeV]

A_{B}^{2} = (p_{T}/mc)^{2} +
(e B_{abs} r / 2 mc^{2})^{2}

E = E_{ref} { 1 + A_{B}^{2} }^{0.5}
+ σ_{E}

dE: random
energy deviation taken from GAUS(0, σ_{E})

Enter the
normal beam input σ_{Pz} = 0.

For CORRTYP = 11

2 value [m or rad]

3 p_{REF} [GeV/c]

4 type flag

1: x

2: y

3: x’

4: y’

2.4 Physics interactions control variables

LDEDX (L) if .true. => simulate mean ionization energy loss dE/dx (true)

LSCATTER (L) if .true. => simulate multiple scattering (true)

LSTRAG (L) if .true. =>
simulate energy stragg

LDECAY (L) if .true. => simulate particle decays (true)

LDRAY (L) if .true. => simulate discrete energy loss from delta rays (true)

When LDRAY is true, the program forces the parameters DELEV=3 and STRAGLEV=5.

LINTERACT (L) if .true. => simulate inelastic nuclear interactions of pions, kaons and protons (false)

LSPACE (L) if .true. => consider effects of space charge (false)

LELMS (L) if .true. => use ELMS model^{[2]}
for energy loss and scattering (false).

When this command is true an external file ELMSCOM.TXT must
be provided. This file consists of two

\muon\elmsdb\rundirectory.txt

\muon\elmsdb\elmsfv3run

ELMS only works in regions containing hydrogen (the SCATLEV model is used in other regions). For hydrogen regions use a stepsize around 5 mm for maximum accuracy. A stepsize of 1 mm gives significantly worse results.

LSAMCS (L)
if .true. => use SAMCS model^{[3]}^{
}of correlated stragg

DELEV (I) model level for dEdx (2)

1: Bethe-Bloch

2: Bethe-Bloch with density effect

3: restricted Bethe-Bloch with density effect

4: test mode with dE = const * dz, independent of velocity and angle

SCATLEV (I) model level for multiple scattering (6)

1: Gaussian( 0, Rossi-Greisen )

2: Gaussian( 0,

3: Gaussian( 0, Lynch-Dahl )

4: Bethe version of Mo

5:

6: Fano (with

7: Tollestrup (with

Level 2 contains a logarithm term in computing the Gaussian width, so it is not useful for general monte carlo work. It gives an accurate estimate of the width of the distribution when the step size is the same as the region size. In models 4, 6, and 7 when the effective number of scatters is less than 20 Rutherford scattering is used with the actual number of scatters in a given step taken from a Poisson distribution.

STRAGLEV (I) model level for stragg

1: Gaussian( Bohr )

2: Landau distribution

3: alternate routine for Landau distribution

4: Vavilov distribution (with
appropriate Landau and Gaussian

program)

5: restricted energy fluctuations from continuous processes with energy below DCUTx.

DECLEV (I) model level for particle decays (1)

1: uniform polar decay angle for daughter particle in parent rest frame

2: 90 degree polar decay angle for daughter particle in parent rest frame

3: uniform polar decay angle for daughter particle in parent rest frame; no mu-->e decays.

4: 90 degree polar decay angle for daughter particle in parent rest frame; no mu->e decays

5: uniform polar decay angle for daughter particle in parent rest frame; no mu-->e decays;

save accumulated fractional decay length in POL(1).

INTLEV (I) model level for nuclear interactions (1)

1: stop tracking after an interaction

2: stop tracking after an interaction, except for protons which generate a pion from the Wang distribution.

SPACELEV (I) model level for space charge (3)

1: image charge of moving bunch in
cy

2: crude transverse space charge
for free space app

3: Gaussian bunch space charge
(transverse and longitudinal) for free space app

regions

4: same as model 3 for single bunch in a bunch train. All the particles are superimposed

on 1 bunch given by parameter FRFBUNSC. Adjust PARBUNSC accordingly.

DCUTE (R) kinetic energy of electrons, above which delta rays are discretely

simulated[GeV] (1E-1)

DCUTM (R) kinetic energy of muons and other heavy particles, above which delta

rays are discretely simulated [GeV] (1E-1)

ELMSCOR (I) 0: run ELMS without correlations (0)

1: run ELMS with correlations

FACFMS (R) factor to correct the Z(Z+1) term in the characteristic angle squared

χ_{C}^{2}
in Mo

FACMMS (R) factor to correct
screening angle squared χ_{A}^{2} in Moliere multiple

scattering theory (1.0)

FASTDECAY (L) if true => use unphysical decay constants to make {μ,π,K} decay

immediately. (false)

FRFBUNSC (R) RF frequency used for space charge model 4. [MHz] (201.)

PARBUNSC (R) number of muons per bunch for space charge calculation (4E12)

PDELEV4 (R) momentum for DELEV=4 calculation (0.200)

WANGA (R) Wang parameter A (90.1) The Wang distribution is given by

d^{2}s/dp dW = A p_{MAX} x (1-x) exp{-Bx^{C} – Dp_{T}} where x = p_{L} / p_{MAX }.

WANGB (R) Wang parameter B (3.35)

WANGC (R) Wang parameter C (1.22)

WANGD (R) Wang parameter D (4.66)

WANGPMX (R) Wang parameter p_{MAX} (1.500)
The sign of this quantity is used to select π^{+} or π^{-}
production.

WANGFMX (R) The maximum value of the Wang differential cross section (13.706)

2.5 Histogram definition variables

NHIST (I) # of histograms{0-20} (0)

HAUTO (L) if .true.=>histograms are scaled for no overflows (true)

HCPRN (I) if 19 < HCPRN < 100 => histogram contents are written to file FOR0nm.DAT

Other input variables

(2-repeated for each histogram)

2.1) HXMIN (R) minimum value

2.2) HDX (R) step size

2.3) NHBINS (I) total # of bins {1-50}

2.4) IHVAR (I) a flag indicating variable to histogram

2: Y 12: Y'

3: Z 13: (space angle)

4: Px 14: r 24: 34: Ex

5: Py 15: phi 25: 35: Ey

6: Pz [2] 16: Pr 26: 36: Ez

7: ct[2] 17: Pphi 27: 37: Sx

8: Pmag 18: Lz 28: A^2 [1] 38: Sy

9: E 19: L^2 29: r^2 39: Sz

10: KE 20: (arclength) 30: muon helicity 40:(phase)

2.5) IHDES (I) the s-plane location for the histogram

Note that s-regions are not the same as physical regions, since they also count any pseudoregions, such as OUTPUT or ROTATE, that may be present. You can find the s-region listed in the left most column of the region summary table (FOR007.DAT).

1: variables at production

s: variables at s-region s

-1: variables at production that make it to the end of the simulation

(only IHVAR=1..7 are defined )

ifail : variables at production for events when this ifail occurs {< -10}

(only IHVAR=1..7 are defined )

[1] To plot A^{2}, use the BETAPERP control
variable.

[2] If DIAGREF is true, the difference with respect to the reference particle is used.

2.6 Scatterplot definition variables

NSCAT (I) # of scatterplots {0-20} (0)

SAUTO (L) if .true. => scatterplots are scaled for no overflows (true)

Other input variables

(2-repeated for each scatterplot)

2.1) SXMIN (R) minimum x value

2.2) SDX (R) step size in x

2.3) NSXBIN (I) total # of x bins {1-50}

2.4) ISXVAR (I) a flag indicating x variable to scatterplot

(see definitions in IHVAR above)

2.5) ISXDES (I) the s-plane location for the x variable in the scatterplot (see below)

2.6) SYMIN (R) minimum y value

2.7) SDY (R) step size in y

2.8) NSYBIN (I) total # of y bins {1-23}

2.9) ISYVAR (I) a flag indicating y variable to scatterplot

(see variable definitions in IHVAR above)

2.10) ISYDES (I) the s-plane location for the y variable in the scatterplot

Note that s-planes are not the same as physical regions, since they also count any pseudoregions,

such as OUTPUT or ROTATE, that may be present. You can find the s-region listed in the left

most column of the region summary table (FOR007.DAT).

1: variables at production

s: variables at s-plane s

-1: variables at production that make it to the end of the simulation

(only IHVAR=1..7 are defined at production)

ifail: make scatterplot of events when ifail occurs. Both ISXDES and

ISYDES must equal ifail.

2.7 Z-history definition variables

NZHIST (I) # of Z-histories {0 - 20} (0)

ZHAUTO (L) if .true. => z-histories data is scaled to fill plot (true)

ZHPRIN (L) if .true. => values printed in log file (false)

Other input variables

(2-repeated for each z-history)

2.1) NZHPAR (I) # of particles to plot {1-10}

2.2) ZHXMIN (R) minimum value of z to plot [m]

2.3) ZHDX (R) z distance between plot values [m]

2.4) NZHXBIN (I) #of z points {1-70}

2.5) ZHYMIN (R) minimum value of variable to plot

2.6) ZHYMAX (R) maximum value of variable to plot

2.7) IZHYVAR (I) variable flag (see definitions in IHVAR above)

2.8 R-history definition variables

Computes minimum, maximum, mean and standard deviation of the distribution of all particles

for a variable at the end of regions

NRHIST (I) # of R-histories {0 - 10} (0)

RHAUTO (L) if .true. => R-histories data is scaled to fill plot (true)

RHPRIN (L) if .true. => values printed in log file (false)

Other input variables

(2-repeated for each R-history)

2.1) IRHZMIN (I) starting region number

2.2) IRHDZ (I) increment in region number along horizontal axis

2.3) RHYMIN (R) minimum value of variable to plot

2.4) RHYMAX (R) maximum value of variable to plot

2.5) IRHYVAR (I) variable flag (see definitions in IHVAR above)

2.9 Emittance plane definition variables

Calculates 2-D emittances at specified planes

NEMIT (I) # of s-planes where the emittance or polarization should be

calculated {0-100}(0)

DISCORR (L) if .true. => correct x and y emittance calculations for dispersion (false)

PXYCORR (L) if .true. => Px and Py are corrected (for the emittance calculation) for

the vector potential in a solenoid field.(false)

IPZCOR (I) flag for correcting the normalized longitudinal emittance for the

Pz versus transverse amplitude correlation. (0)

0: no correction

1: correct using Palmer amplitude, A_{P}

_{ } A_{P}^{2}
= x’^{2} + y’^{2} +(x/β_{T})^{2} + (y/ β_{T})^{2}

2: correct using Balbekov transverse amplitude,
A_{B}

A_{B}^{2}
= (p_{T}/mc)^{2} + (eBr/2mc)^{2}

SIGMACUT (L) if .true. => tails of {x ... Pz} are cut at SIG_CUT sigmas before the

emittance is calculated. (true)

SIG_CUT (R) # of sigmas to cut off tails of {x ... Pz} for the emittance calculation.

(4.)

Other input variables

(repeated for each emittance plane)

2) IEMDES(i),i=1,N (I) s-plane identification # where emittance or POLARIZATION is

calculated. Note that s-planes are not the same as physical regions, since they also

count any pseudoregions, such as OUTPUT or ROTATE, that may be present. You can find the

s-region listed in the left most column of the region summary table in the log output file

(FOR002.DAT).

1: variables at production

s: variables at s-plane s

Output data is normalized relative to first plane in IEMDES list. Note that in a solenoidal field

emittances are only correctly computed when PXYCORR=true or at s-planes where B = 0. For emittances at the production plane use the control variable BZFLDPRD. A returned emittance value of -998 or -999 indicates the program could not calculate a sensible emittance.

2.10 Covariance plane definition variables

Calculates covariance matrices and related “LBNL” emittances

NCOVAR (I) # of s-planes where the covariance should be calculated {0-100} (0)

Other input variables

2) ICVDES(i),i=1,N (I) s-plane identification # where covariance is

calculated. Note that s-planes are not the same as physical regions, since they also

count any pseudoregions, such as OUTPUT or ROTATE, that may be present. You can find the

s-region listed in the left most column of the region summary table in the log output file

(FOR002.DAT).

1: variables at production

s: variables at s-plane s

Region commands (A4)** Use UPPER
case.**

Start of cooling section region definition; the data must end with an ENDSECTION ; it can

enclose any number of other commands. If it is desired to repeat the section definitions, the

control variable NSECTIONS should be set >1 and a BEGS command is used to define where to

start repeating.

This marks the beginning of the part of region definitions that will be repeated with the NSECTIONS control variable. This command doesn’t do anything if NSECTIONS = 1.

3) REPEAT

Start of a repeating

command. This can be used to repeat regions inside a cell. The repeat loop can enclose any

number of {SREGION, APERTURE, DENS, DISP, DUMMY, DVAR, EDGE, OUTPUT, REFP, REF2, RESET, RKICK, ROTATE, TILT, TRANSPORT} commands. Repeat sections cannot be nested in other repeat sections. (see parameters below)

4) CELL

Start of a repeating

command. The cell loop can enclose any number of commands listed above under REPEAT plus REPEAT and ENDREPEAT commands. It has an associated cell field, which is superimposed on the individual region fields. Cell sections cannot be nested in other cell sections. (see parameters below)

5) SREGION

Start of new s-region. Describes field and material properties. (see parameters below)

6) ENDREPEAT End of REPEAT data block.

7) ENDCELL End of CELL data block.

8) ENDSECTION

End of region data definition; the section of data is repeated NSECTIONS times.

These commands are read in (A4) format.

APERTURE Collimates beam at aperture (see parameters below)

CUTV Cut on ICOOL variable (see parameters below)

DENP Set variable density profile (see parameters below)

DENS Adjust material density (see parameters below)

DISP Randomly displaces particle coordinates (see parameters below)

Dummy placeholder in the problem definition. This can be used to save a place for an OUTPUT

command in the problem definition. This makes it more convenient to keep the size of the for009.dat file manageable. (no parameters)

DVAR Change parameter value for all particles (see parameters below)

EDGE Fringe field and other kicks for hard-edged field models (see parameters below)

GRID Defines new magnetic field grid (see parameters below)

Enables the writing of particle information at the end of the following region to FOR009.DAT.

This command will only function if both NTUPLE and RTUPLE are false. (no parameters).

REFP Define RF reference particle properties (see parameters below)

REF2 Define 2^{nd} RF reference
particle properties (see parameters below)

RESET Change time of all particles to reference particle time (no parameters)

RKICK Random magnetic kicks (see parameters below)

ROTATE Coordinate system rotation (see parameters below)

TAPER Solenoid lattice with tapered currents (see parameters below)

TILT Randomly rotates particle coordinates in 3D (see parameters below)

TRANSPORT

User input of transport matrix. A reference particle must be defined to use this command. (see

parameters below)

BACKGROUND

Start of a background field definition section. the data must end with an ENDB command. This

section may include any number of BFIELD commands. (see parameters below)

BFIELD Define background field (see parameters below)

ENDB End definition of background field (see parameters below)

! (see discussion on comments in the Introduction)

& (see discussion on name substitution in
the Introduction)

3.3 Regular and
pseudoregion command parameters

It is important that parameters listed like 1.1 to 1.4 below
appear on the same line in

the input file and that parameters like 2.1 start a new line.

1.1) IAPERTYPE (I) 1:elliptical, 2:rectangular, 3:normal quad, 4:skew quad

For IAPERTYPE = 1

1.2) APERLIM1 (R) x half-width [m]

1.3) APERLIM2 (R) y half-width [m]

1.4) 0. (R) parameter not used

For IAPERTYPE = 2

1.2) APERLIM1 (R) lower limit [m]

1.3) APERLIM2 (R) upper limit [m]

1.4) 1:x 2:y (R) direction

For IAPERTYPE = 3 or 4

1.2) RPOLE (R) distance from axis to pole piece [m]

1.3) ROUT (R) distance from axis to outer useful radius [m]

1.4) PARAB (R) distance from vertex to focus of parabola [m]

1.1) BENTBKG (L) set TRUE if reference trajectory is curved

1.2) PREFBKG (R) reference momentum thru background grid [GeV/c]

1.3) ZTOTALBKG (R) total incremental length in z to use this BG field [m]

2.1) XLOBKG (R) low x value of background grid [m]

2.2) DXBKG (R) bin size in x for background grid [m]

2.3) NXBKG (I) number of x bins {<31}

2.4-6) YLOBKG, DYBKG, NYBKG(similar to corresponding x parameters)

2.7) ZLOBKG (R) minimum distance into background region before using

background field, i.e. the
background field is 0 for distances

into background region less than ZLOBKG.

The maximum distance to use the background field is ZLOBKG+ZTOTALBKG.

Distances in z are in relative units, i.e. they start at 0.

2.8) DZBKG (R) bin size in z for background grid [m]

2.9) NZBKG (I) number of z bins{<201}

2.10) INTERBKG (I) interpolation order for background grid {1-3}

(Command parameters continued)

BFIELD

1.1) ZOFFBKG (R) offset in z before starting edge of this field contribution [m]

This can be used to start field contributions at varying distances from the beginning of the current

background field.

1.2) RMAXBKG (R) maximum radius at which this field should be applied to the

background grid [m]

1.3) ZMINBKG (R) Starting z location at which to consider this field contribution [m]

1.4) ZMAXBKG (R) Ending z location at which to consider this field contribution [m]

ZMINBKG and ZMAXBKG are measured from the start of the current background field. If

round-off error causes the last BG field point to be in error, increase ZMAXBKG by a small

amount, e.g. by 0.001.

..

2) BFTAG (A4) background field tag (see FTAG values below)

3) BFPARM (R) 15 parameters describing field (see specific field type below)

1) NCELLS (I) Number of times to repeat the commands in this cell block.

2) CELLFLIP (L) If .true. => flip cell field for alternate cells

3)CFTAG (A4) Field tag for field that is superimposed over all the regions

in this cell; see FTAG values below.

4) CFPARM (R) 15 parameters describing field (see specific field type below)

1.1) ICOOL variable index {1-12}
See variable

1.2) relational test

1: < (less than)

2: > (greater than)

1.3) value (R)

(Command parameters continued)

1.1) material (A4) material tag

1.2) direction (I) 1:x 2:y 3:r

1.3) coefficient a (R)

1.4) coefficient b (R)

1.5) coefficient c (R)

1.6) coefficient d (R)

Let v be the variable determined by the direction parameter. Then the density is a function of v given by

ρ = a + b v + c v^{2}
+ d v^{3}

This command can only affect the density of one material at a time. To
disable this function execute a DENP command with direction=-1.

DENS

1.1) material (A4) material tag

1.2) factor (R) factor to change current density value

1.1) D (R) σ of displacement distribution [m]

1.2) PHI (R) angle of rotation w.r.t. x axis in x-y plane [deg]

If PHI = -1 => angle of rotation axis is chosen randomly from a uniform distribution.

DVAR

1.1) variable
index (I) see variable

1.2) change (R) amount to change variable [m, GeV/c, s, GeV]

1.3) apply to (I) {0,1,2}

0: all particles

1: reference particle only

2: normal particles only

(Command parameters continued)

1) edge type (A4) {SOL, DIP, HDIP,DIP3,QUAD,SQUA,SEX, BSOL,FACE}

2.1) model # (I) {1}

2.2-5) p1, p2, p3,p4 (R) model-dependent parameters

Edge type = SOL

p1: B_{S } [T]

If the main solenoid field is B, use p1=-B for the entrance edge and p1=+B for the exit edge.

Edge type = DIP

p1: B_{Y
}[T]

Edge type = HDIP

p1: B_{X
}[T]

Edge type = DIP3

p1: rotation angle_{ }[deg]

p2:
B_{Y}^{0} [T]

p3: flag 1:in 2:out

Edge type = QUAD

p1: gradient [T/m]

Edge type = SQUA

p1: gradient [T/m]

Edge type = SEX

p1: b_{2} [T/m^{2}] (cf. C. Wang & L. Teng, MC 207)

Edge type = BSOL

p1: B_{S
}[T]

p2: B_{Y
}[T]

p3: 0 for entrance face, 1 for exit face

Edge type = FACE

This gives vertical focusing from rotated pole faces.

p1: pole face angle [deg]

p2: radius of curvature of reference particle [m]

p3: if not 0 => correct kick by the factor 1 / (1+δ)

p4: if not 0 => apply horizontal focus with strength = (-vertical strength)

If a FACE command is used before and after a sector dipole ( DIP ), you can approximate a rectangular dipole field.

The DIP, HDIP, QUAD, SQUA, SEX and BSOL edge types use Scott Berg’s HRDEND routine to find the change in transverse position and transverse momentum due to the fringe field.

(Command parameters continued)

1) (I) file # of field output on the grid {20-99}. Set this <20 if you

don't want an output file. See output file section 5.2.

GRID

This can be used to define a 2D r-z grid, a 2D x-y grid, or a 3D x-y-s grid, depending on the value of the field type.

(1) r-z grid

1) grid number (I) {1-4}

2) field type (A4) { BLOCK , COIL , SHEET , SOL }

3) field parameters (R) (enter 0. for unused parameters)

3.2) file # of input COIL , SHEET , etc. data {20-99}

If the file number is entered as a negative number, the current densities in the external file are all reversed in polarity. The external file formats are described under the field models BLOCK(2), COIL(3), SHEET(3) and SOL(6).

3.3) dz for grid [m]

3.4) dr for grid [m]

3.5) total z length of grid [m] The maximum number of z grid points is 5000.

3.6) total r length of grid [m] The maximum number of r grid points is 100.

3.7) z cut parameter for ignoring current elements ( COIL and SHEET only)

3.9) file # for field output on the grid (or 0 for none) {20-99}

The format of the output file generated by parameter 9 is listed in section 5.2.

3.10) Longitudinal shift parameter. If a longitudinal grid index JZ is entered here, the field grid stored in memory starts at JZ, wraps through the beginning of the grid and ends at longitudinal index JZ-1.

3.11) Current element scaling factor. Set to 1.0 for no scaling.

3.12) Calculation algorithm for BLOCK only.

0: from numerical integration

1: from series

(Command parameters continued)

(2) x-y grid

1) grid number (I) {1-4}

2) field type (A4) { BROD }

3) field parameters (R) (enter 0. for unused parameters)

3.3) dx for grid [m]

3.4) dy for grid [m]

3.5) starting x value for grid [m]

3.6) starting y value for grid [m]

3.7) number of x grid points. The maximum number of x grid points is 100.

3.8) number of y grid points. The maximum number of y grid points is 5000.

3.9) file # for field output on the grid (or 0 for none) {20-99}

The format of the output file generated by parameter 9 is listed in section 5.2.

3.12) radius of ring [m]

3.13) cross sectional radius of bent rod [m]

3.14) total current [A]

3.15) B_{dipole} superimposed dipole
field [ T ]

This command uses the same grid arrays as the r-z commands.

(Command parameters continued)

(3) x-y-s grid

1) grid number (I) {1}

2) field type (A4) { STUS }

3) field parameters (R) (enter 0. for unused parameters)

3.2) file # of input 3D field values or spline coefficients {20-99}

See file formats under STUS.

3.3) curvature flag

0: straight grid

1: curved grid

3.4) reference momentum [GeV/c]

3.5) field scaling factor Set to 1.0 for no scaling.

3.8) curvature sign flag

if parameter=1 => flip sign of HREF in input file

3.9) file format flag

0: formatted B grid

1: unformatted B grid

2: unformatted spline coefficients of B grid

For a curved grid (parameter 3.3 = 1): if href in the input file is not 0, then href is used as the constant curvature; if href in the input file is 0, then pref is used with the local Bx and By on-axis fields to determine the curvature.

3.10) Longitudinal shift parameter. If a longitudinal grid index JZ is entered here, the field grid stored in memory starts at JZ, wraps through the beginning of the grid and ends at longitudinal index JZ-1.

(Command parameters continued)

1.1) REFPAR (I) Use BMTYPE particle code to specify reference particle type. {1 - 5}

1.2-1.4) see below

1.5) PHMODREF (I) phase model

2: uses iterative procedure to find 0-crossing phase; tracks thru all regions; only works with ACCEL models 1, 2 and 13.

3: assumes constant reference particle velocity

4: takes into account energy loss in absorbers and gain in cavities

5: allows quadratic energy change in cavities

6: allows quadratic energy change for any region

1.1) REFPAR2 (I) Use BMTYPE particle code to specify reference particle type {1-5}

1.2-1.4) see below

n.b. when using the REF2 command in conjunction with ACCEL model 10, the momentum of the two reference particles should be different.

The meaning of parameters 1.2 – 1.4 in REFP and REF2 depend on the value of PHMODREF according to the following table.

PHMODREF |
2 |
3 |
4 |
5 |
6 |

1.2 = |
- |
pZ0 |
pZ0 |
E0 |
E0 |

1.3 = |
- |
t0 |
t0 |
dE/dz |
dE/dz |

1.4 = |
- |
- |
dE/dz |
d |
d |

app |
RF only |
any region |
RF only |
RF only |
any region |

The units are pZ0 [GeV/c], E0 (total
energy) [GeV], t0 [s], dE/dz [MeV/m], and d^{2}E/dz^{2} [MeV/m^{2}].
If a command has t0, pZ0 or E0 set to 0., the corresponding quantity keeps its
existing value.

(Command parameters continued)

REPEAT

1) NREP (I) # of times to repeat following region commands

RKICK

1.1) field type (A4) {SOL, DIP, HDIP, QUAD, SQUA, SEX; SCAL}

1.2) mean strength (R)
integrated multipole strength [ T / m^{n}
* m ]

1.3) σ (strength) (R) [ T
/ m^{n} * m ]

1.4) coupling parameter (R)

1.5) azimuth or length (R)

This generates a random momentum kick based on the magnetic
field configuration given in *field type*.
The output of this command can be given for longitudinal fields (SOL) and
transverse fields independently. The SCAL field type is used to scale the
strengths of all following RKICK commands. In this case the 2^{nd}
parameter is a scaling factor for the mean values and the 3^{rd}
parameter is a scaling factor for the standard deviations, as follows.

SCAL mean_factor sigma_factor 0. 0.

The *coupling parameter* can be used to
correlate RKICK commands. This parameter can have the following four values.

0: generate a random value

1: generate a random value and save it

2: used the saved random value

3: used the saved random value with the opposite sign

One value can be saved for longitudinal kicks and one value
can be saved for transverse kicks. For solenoidal fields the 5^{th}
parameter is the solenoid length in meters. For transverse fields the 5^{th}
parameter determines the azimuthal angle around the beam direction in which the
kick takes place. If the 5^{th} parameter = -1, the kick direction is
chosen randomly from a uniform distribution. Otherwise the kick direction is
determined by the field type. The coupling parameter is also used here to
correlate kick directions. The random kicks are only computed for NSECTIONS =
1. When NSECTIONS > 1 the same kick
is applied at some given location as its kick for NSECTIONS = 1. There can be a
maximum of 100 RKICK commands in a job.

(Command parameters continued)

ROTATE

1.1) ANGLE (R) Rotation angle [degrees]

1.2) axis (I) {1,2,3}

1: x

2: y

3: z

1.3) apply to (I) {0,1,2}

0: all particles

1: reference particle only

2: normal particles only

This command can be used to make vertical bends, e.g.

ROTATE
! switch x and y coordinates

90. 3. 0.

SREGION
! usual horizontal bend region

...........

ROTATE
! switch x and y coordinates back

-90.
3. 0.

SREGION

1.1) SLEN (R) Length of this s region [m]

1.2) NRREG (I) # of radial subregions of this s region {1-4}

1.3) ZSTEP (R) step for tracking particles [m]

Note that for fixed-stepping the program may modify this value slightly to get an integral number of steps in the region.

(following repeated for each r subregion)

2.1) IRREG (I) r-region number

2.2) RLOW (R) Inner radius of this r subregion[m]

2.3) RHIGH (R) Outer radius of this r subregion[m]

3) FTAG (A4) Tag identifying field in this r subregion

(see specific field type below)

4) FPARM (R) 15 parameters describing field(see specific field type below)

These 15 parameters must be on one input line.

5) MTAG (2A4) Tag identifying
material composition in this r subregion

The wedge geometry can accept a second MTAG parameter. The
first material refers to the interior of the wedge. The second material, if
present, refers to the exterior of the wedge. If a second MTAG parameter is not
present, vacuum is assumed. (see specific material type below)

6) MGEOM (A6) Tag identifying material geometry in this r subregion.

(see specific material type below)

7) GPARM (R) 10 Parameters describing material geometry.

These 10 parameters must be on one input line.

(see specific material type below)

(Command parameters continued)

1.1) NCELLS (I) number of consecutive following cells with tapered parameters

This command must be used in conjunction with BLOCK(4) or BSOL(5).

TILT

1.1) PSI (R) σ of tilt angle distribution [deg]

1.2) PHI (R) angle of rotation w.r.t. x axis in x-y plane [deg]

If PHI = -1 => angle of rotation axis is chosen randomly from a uniform distribution.

TRANSPORT

1) 1st row of transport matrix (variables x, x', y, y', d(length), dp/p )

2) 2nd row of transport matrix,......

6) 6th row of transport matrix

You must define a reference particle in order to use this command.

4. Field, material and geometry parameters

Enter FTAG in UPPER case. Unused parameters should be set to 0.

NONE drift in field free region

( set all parameters to 0 )

**ACCE**(L) linear accelerator fields

1 model

1: E_{Z} only with no
transverse variation

2: cylindrical TM01p pillbox resonator

3: traveling wave cavity

4: approximate fields for symmetric circular-nosed cavity

5: user-supp

6: induction linac model - waveform from user-supplied polynomial coefficients

7: induction linac model - internally generated waveform

8: induction linac model - waveform from user-supplied file

9: sector-shaped pillbox cavity (circular cross section)

10: variable {frequency, gradient} pillbox cavity

11: straight pillbox or SuperFish cavity in dipole region

12: sector-shaped pillbox cavity (rectangular cross section)

13: open cell standing wave cavity

The initial phase parameter can be used for any PHASEMODEL and ACCEL models 1-5.

For **model = 1**

2 frequency [MHz]

3 gradient on-axis at center of gap [MV/m]

4 phase shift [deg] {0-360}.

5 parameter to approximate a rectangular cavity in
cylindrical geometry; if set to radius of curvature ρ, then E_{Z}
is scaled by 1-x/ ρ, where x is the horizontal distance from the reference
circle.

6 (not used)

7 (not used)

8 mode

0 : time-independent

1: sinusoidal time variation

For **model = 2**

2 frequency f [MHz]

3 gradient on-axis at center of gap [MV/m]

4 phase shift [deg] {0-360}.

5 parameter to approximate a rectangular cavity in cylindrical geometry; if set to radius of curvature ρ, then the field components are scaled by 1-x/ ρ, where x is the horizontal distance from the reference circle.

6 x offset of cavity [m]

7 y offset of cavity [m]

8 longitudinal mode p {0,1}

For mode = 0 Rcav = 0.383 * λ

For mode = 1 Rcav =
2.405 / {(2 π f)^{2} - (π /SLEN)^{2} }^{1/2}

For **model = 3**

2 frequency f [MHz]

3 gradient on-axis at center of gap [MV/m]

4 phase shift [deg] {0-360}.

5 (not used)

6 (not used)

7 (not used)

8 phase velocity of RF wave β_{W} . {0 <
β_{W} < 1}

For **model = 4**

2 frequency [MHz]

3 gradient on-axis at center of gap [MV/m]

4 phase shift [deg] {0-360}.

5 (not used)

6 (not used)

7 (not used)

8 total length of cavity [m]

9 total gap [m]

10 radius of drift tube [m]

11 radius of nose piece [m]

For **model = 5**

2 frequency[MHz]

4 phase shift [deg] {0-360}.

8 file ## of azimuthally symmetric RF input file (see below) {20-99}

9 field strength normalization factor [MV/m] This multiplies the value in the SuperFish file.

10 radial cutoff for cavity [m]

11 axial distance from start of region to center

12 axial symmetry through center of cavity

0: symmetric

1: not symmetric

The contents of the user-supp

1.1 zmin Start of axial grid [cm]

1.2 zmax End of axial grid [cm]

1.3 Nz # of z grid points {<151}

2 frequency [MHz]

3.1 rmin Start of radial grid [cm]

3.2 rmax End of radial grid [cm]

3.3 Nr # of r grid points {<151}

for ir=1,Nr

for iz=1,Nz

4.1 Ez axial electric field [MV/m]

4.2 Er radial electric field [MV/m]

4.3 E magnitude of electric field [MV/m]

4.4 Hphi azimuthal magnetic field [A/m]

next iz

next ir

The grids should extend beyond the region where tracking will occur.

For **model = 6**

2 time offset from start of voltage pulse[s]

3 accelerator gap [m]

4 time reset parameter (see below)

5 V0 term in polynomial expansion of voltage pulse [V ]

6 V1 term in polynomial expansion of voltage pulse [V / μs]

7 V2 term in polynomial expansion of voltage pulse [V / μs^2]

8 V3 term in polynomial expansion of voltage pulse [V / μs^3]

9 V4 term in polynomial expansion of voltage pulse [V / μs^4]

10 V5 term in polynomial expansion of voltage pulse[V / μs^5]

11 V6 term in polynomial expansion of voltage pulse[V / μs^6]

12 V7 term in polynomial expansion of voltage pulse[V / μs^7]

13 V8 term in polynomial expansion of voltage pulse[V / μs^8]

This model generates an E_{Z} field across the
accelerator gap. The field is time dependent, but does

not depend on z or r. The radial electric field and azimuthal magnetic fields are assumed to be

negligible. When the time reset parameter is 1, the start time for the voltage pulse is determined

from the time the reference particle entered the cell. The user can adjust this time using

parameter #2 above. Subsequent cells should use parameter #4 set to 0 to sample later portions of the same voltage pulse. A new pulse shape can be started at any time by setting parameter #4

back to 1.

For **model = 7**

2 number of gaps

3 starting voltage [GV]

4 voltage swing [GV]

5 time offset [s]

6 target kinetic energy [GeV]

7 pulse duration [s]

8 parameter to adjust slope at end of voltage pulse

9 number of bins in voltage pulse

10 gap length [m]

11 file # of output diagnostic file {20-99} (Set this <20 for no diagnostic output.)

12 kill particle flag (Set=1 to eliminate non-useful particles)

13 restart flag (Set =1 to restart calculation)

For **model = 8**

2 time offset from start of voltage pulse[s]

3 accelerator gap [m]

4 time reset parameter [s](see below)

5 file number of waveform input (see format below) {20-99}

6 polynomial interpolation order, 1=> linear, 2=>quadratic, etc. {1-3}

7 file # for output diagnostic file (see format below){20-99}

8 time increment between diagnostic outputs to file [s]

This model generates an E_{Z} field across the
accelerator gap. The field is time dependent, but does

not depend on z or r. The radial electric field and azimuthal magnetic fields are assumed to be

negligible. The gap parameter is used to convert the voltage profile into an electric field. The field is applied everywhere in the region.

When the time reset parameter is 1, the start time for the voltage pulse is determined

from the time the reference particle entered the cell. The user can adjust this time using

parameter #2 above. Subsequent cells can use parameter #4 set to 0 to sample later portions of

the same voltage pulse. A new pulse shape can be started at any time by setting parameter #4

back to 1.

The contents of the waveform input file FOR0##.DAT is

1) number of points N {1-100}

This is followed by N pairs

2) t(i) V(i) [s] [V]

An output diagnostic file is initialized for an induction linac region where the time reset

parameter=1 and parameter 7 above is in the range {20-99}. Output occurs when the elapsed

time from the previous output exceeds the increment given in parameter 8. Output continues for

subsequent induction linac regions provided parameter 7 remains in the specified range. The

contents of the file are

1) column id header

2) region particle z t Ez

For **model = 9**

2 frequency f[MHz]

3 gradient on-axis at center of gap [MV/m]

4 phase shift [deg] {0-360}.

For **model = 10**

2 (not used)

3 (not used)

4 phase shift [deg] {0-360}.

5 number of wavelengths separating the two reference particles

6 reset parameter (see below)

7 Total length L of buncher [m]

8 g0 [MV/m]

9 g1 [MV/m]

10 g2 [MV/m]

11 (not used)

12 phase model

0: 0-crossing time set by t_{REFP}

1: 0-crossing time set by ˝ * (t_{REFP}
+ t _{REF2})

This model uses a TM010 mode pillbox cavity. It can only be used with REFP and REF2 defined and phasemodel=2,3,4. The cavity frequency is set using the number of wavelengths (parameter 5) and the time difference between the two reference particles. When the reset parameter is 1, the starting location of the buncher is determined from the current position of the reference particle. Subsequent ACCEL commands should use parameter #6 set to 0 to sample later portions of the gradient waveform, which is given by

G = g0 + g1*(z/L) + g2*(z/L)^2

A new pulse shape can be started at any time by setting parameter #6 back to 1.

For **model = 11**

2 frequency f [MHz]

3 gradient on-axis at center of gap for a pillbox cavity [MV/m]

4 phase shift [deg] {0-360}.

5 radial offset of center of cavity from reference trajectory [m]

6 axial length of cavity [m] If this entered as 0, the program computes the largest pillbox cavity that fits in the sector shaped region

7 cavity type

0: pillbox

1: SuperFish

8 file ## of azimuthally symmetric SuperFish RF input file (see model 5) {20-99}

9 SuperFish field normalization [MV/m] This multiplies the value in the SuperFish file.

10 SuperFish radial cut off [m]

11 axial displacement of center of SuperFish cavity from start of the region [m]

12 SuperFish axial symmetry

0: symmetric

1: not symmetric

For **model = 12**

2 frequency f[MHz]

3 gradient on-axis at center of gap [MV/m]

4 phase shift [deg] {0-360}.

5 radial offset of center of cavity from reference trajectory [m]

6 cavity width [m]

7 cavity height [m]

For **model = 13**

2 frequency f [MHz]

3 gradient on-axis at center of gap [MV/m]

4 phase shift [deg] {0-360}.

5 flag for hard edge focusing

0: both entrance and exit focusing

1: exit focusing only

2: entrance focusing only

3: no edge focusing

**BLOCK**
field made up from sum of fields
from annular solenoidal current blocks

1 model

1: exact field from single block

2: exact field from sum of blocks in data file

3: interpolate data file field points from predefined grid

4: interpolate data file field points from blocks with tapered currents

For CELL fields repetition of a cell uses the same external file over and over. A new cell block

can use a different external file.

For **model = 1**

2 z offset of center of block from start of region [m]

3 inner radius of block [m]

4 outer radius of block [m]

5 length of block [m]

6 current density [A / mm^2]

7 algorithm

0: from numerical integration

1: from series

For **model = 2**

2 file ##of block input (see below) {20-99}

3 algorithm

0: from numerical integration

1: from series

11 current density scaling factor

If the file number is entered as a negative number, the current densities in the external file are all

reversed in polarity.

The contents of the block data input file FOR0##.DAT is

1 title (a80)

2 NBLOCKS {1-1000}

( 3 repeated for each block)

3.1 block #

3.2 relative z offset of this block [m]

3.3 length of block [m]

3.4 inner radius of block [m]

3.5 outer radius of block [m]

3.6 current density [A / mm^2]

For **model = 3**

2 grid ##of block field {1-4}

3 interpolation level {1-3}

1: bi-linear

2: bi-quadratic polynomial

3: bi-cubic polynomial

For **model = 4**

** **2 file number of block data {20-99} The file format is described under
model 2.

3 grid dz [m]

4 grid dr [m]

5 total length of grid in z [m]

6 total length of grid in r [m]

7 interpolation level {1-3}

1: bi-linear

2: bi-quadratic polynomial

3: bi-cubic polynomial

8 algorithm

0: from numerical integration

1: from series

9 file number of taper current data {20-99}

10 number of r-z grid that contains the calculated field {1-4}

This feature assumes a solenoid lattice like Study 2, i.e. two symmetric “focusing” coils and a “coupling” coil in each cell. It also assumes that the block data file contains information on the two cells before and the two cells after the actual cell of interest in order to get the correct boundary conditions. Thus there should be 15 blocks in the input file.

The format of the tapered current input file FOR0##.DAT is

1 title (a80)

2 ntaper number of cells that follow {1-200}

(3 repeated for each cell)

3.1 cell #

3.2 focus coil current density [A/mm^{2}]

3.3 coupling coil current density [A/mm^{2}]

**BROD**
field from bent axial current
rod

1 model

1: interpolate data file field points from predefined grid

For **model = 1**

2 grid ##of block field {1-4}

10 interpolation level {1-3}

1: bi-linear

2: bi-quadratic polynomial

3: bi-cubic polynomial

12 R, radius of ring [m]

The bent rod field must first be stored in an array with the GRID command. The curvature used for tracking is 1 / R. The parameters here and in the associated GRID command should obey the constraint

1 / R = e / p_{REF} * B_{DIP}

**BSOL**
bent solenoid

1 model

1: hard edge dependence for Bs and By

2: soft edge dependence for Bs, By and g using dTANH(s)

3: user-supplied fields on-axis

4: user-supp

5: tapered lattice cells

For **model = 1**

2 peak value of Bs [T]

3 peak value of By [T]

4 curvature factor

1: use curvature from parameter 7

2: use
local B_{Y} on axis and p_{REF}

5 reference momentum, p_{REF} [GeV/c]

6 quad component of dipole field [T/m]

7 curvature [ m^{-1}
]

Hard-edge field models can include the focusing effects of the missing fringe field by using EDGE commands before and after the hard-edge field region.

For **model = 2**

2 peak value of Bs [T]

3 peak value of By [T]

4 quad component of dipole field [T/m]

5 reference momentum, p_{REF} [GeV/c]

6 central length of solenoid [m]

7 end length of solenoid [m]

8 attenuation length of solenoid [m] {>0}

9 central length of dipole and quad [m]

10 end length of dipole and quad [m]

11 attenuation length of dipole and quad [m]

12 constant offset for Bs [T]

13 curvature factor

1: use curvature from parameter 14

2: use
local B_{Y} on axis and p_{REF}

14 curvature [ m^{-1}
]

15 order of expansion
{1-3}

The attenuation lengths (parameters 8 and 11) must be entered, even if the strength is 0.

For **model = 3**

2 file # of user-supplied input (see contents below) {20-99}

3 reference momentum, p_{REF}
[GeV/c]

4 curvature in horizontal plane,
h [ m^{-1} ]

5 curvature factor

1: use curvature from parameter 4

2:
use local B_{Y} on axis and p_{REF}

_{ }3: take h(s) from input file

6 scale factor for B_{S}

7 scale factor for B_{Y}

8 scale factor for b_{1}

9 scale factor for b_{2}

10
scale factor for b_{3}

11
scale factor for b_{4}

12
scale factor for b_{5}

13
scale factor for a_{0}

14 scale factor for h

15 order of calculation {1-5}

The contents of the input file FOR0##.DAT of on-axis field multipoles is

1 title (a80)

2 # of points {1-2000}

(3, repeated for each point)

3.1 s [m]

3.2 B_{S} [T]

3.3 b_{0} [T]

3.4 b_{1} [T/m]

3.5 b_{2} [T/m^{2}]

3.6 b_{3} [T/m^{3}]

3.7 b_{4} [T/m^{4}]

3.8 b_{5} [T/m^{5}]

3.9 a_{0} [T]

3.10 h [ m^{-1} ]

The s grid should start at 0. Make the s grid at least 1 grid spacing longer than the actual size of

the cell (or the field will be 0 at the boundary points). The off-axis fields can be calculated at up to 5th order in the transverse coordinates. Set the scale factors of unused multipoles to 0 to speed up execution.

For **model = 4**

2 file # of user-supplied input (see contents below) {20-99}

3
reference momentum, p_{REF} [GeV/c]

4 order of field calculation {1-5}

5 curvature factor

1: use curvature from parameter 15

2:
use local B_{Y} and B_{X} on axis and p_{REF}

6 scale factor for solenoid field strength

7
scale factor for b_{0} field strength

8
scale factor for a_{0} field strength

9
scale factor for b_{1} field strength

10
scale factor for a_{1} field strength

11
scale factor for b_{2} field strength

12
scale factor for a_{2} field strength

13
scale factor for b_{3} field strength

14
scale factor for a_{3} field strength

15 curvature, h [ m^{-1} ]

The sign of h in parameter 15 should correspond to the
dipole field. The 5^{th} order calculation does not contain terms for
bending out of the midplane. The multipole expansion for B_{Y} on the
midplane is

B_{Y} = b_{0} + b_{1} x + b_{2}
x^{2} + b_{3} x^{3} + b_{4} x^{4} + b_{5}
x^{5}

Set the scale factors of unused quad and higher multipoles to 0 to speed up execution.

The contents of the input file FOR0##.DAT for model 4 is

1 title (a80)

2.1 period [m]

2.2 field strength for solenoid component [T]

2.3
field strength for b_{0} component [T] (normal dipole term)

2.4
field strength for a_{0} component [T] (skew dipole term, etc.)

2.5
field strength for b_{1} component [T/m]

2.6
field strength for a_{1} component [T/m]

2.7
field strength for b_{2} component [T/m^{2}]

2.8
field strength for a_{2} component [T/m^{2}]

2.9
field strength for b_{3} component [T/m^{3}]

2.10 field strength for a_{3} component
[T/m^{3}]

2.11 field strength for b_{4} component
[T/m^{4}]

2.12 field strength for a_{4} component
[T/m^{4}]

2.13 field strength for b_{5} component
[T/m^{5}]

2.14 field strength for a_{5} component
[T/m^{5}]

3 maximum Fourier order {0-199}

4 2^{ nd}
title (a80)

(5 repeated for each order)

5.1 m order #

5.2 c_{m}
coefficient for solenoid field

5.3 d_{m}
coefficient for solenoid field

5.4 c_{m}
coefficient for b_{0} field

5.5 d_{m}
coefficient for b_{0} field

5.6 c_{m}
coefficient for a_{0} field

5.7 d_{m}
coefficient for a_{0} field

5.8 c_{m}
coefficient for b_{1} field

5.9 d_{m}
coefficient for b_{1} field

5.10 c_{m} coefficient for a_{1} field

5.11 d_{m} coefficient for a_{1} field

…

5.26 c_{m} coefficient for a_{5 }field

5.27 d_{m} coefficient for a_{5 }field

The form of the Fourier series used for each multipole component is

f (s) = S ( c_{m}
COS(u) + d_{m} SIN(u) )

where u = 2πms / λ.

For **model = 5**

2
file # of user-supp

3
reference momentum, p_{REF} [GeV/c]

4 order of field calculation {1-5}

5 curvature factor

1: use curvature from parameter 15

2:
use local B_{Y} and B_{X} on axis and p_{REF}

6 file # of tapering profile (see contents below) {20-99}

7 file # of taper diagnostics {20-99}

15 curvature, h [ m^{-1} ]

The file format for the tapering profile is

1. title (a80)

2. number of tapered cells (I) {<301}

3.1 cell # (I)

3.2 taper factor (R)

Repeat 3 for each tapered cell.

This model must be used as a cell field. It works in
conjunction with the TAPER command. If *f* is the taper factor for a given cell,
then the multipole strengths and RF frequencies are multip*f*, while the multipole period,
region length, radial aperture, *x* and
*z* positions of wedges, and width and
height of wedges are divided by *f*.
Wedge angles and RF gradients are not changed. Only one multipole file can be
used while tapering. Only accelerator models 2 and 11 can be used in the
tapered cells. n.b. the normal diagnostic file (for007) is not correct when
tapering is on. Refer instead to the diagnostic file from parameter 7.

**COIL**
field made up from sum of
fields from circular current loops

1 model

1: exact field from single loop

2: exact field from sum of loops in data file

3: interpolate data file field points from predefined grid

Models 2 and 3 can be used as CELL fields. Repetition of a cell uses the same external

file over and over. A new cell block can use a different external file.

For **model = 1**

2 z offset of the coil from start of region [m]

3 radius a of coil [m]

4 currentI [A]

Baxis = mu_o I / 2a = 2 pi 10^-7 I / a

For **model = 2**

2 file ##of coil input (see below) {20-99}

If the file number is entered as a negative number, the current densities in the external file are all

reversed in polarity.

11 current density scaling factor

For **model = 3**

2 grid ##of coil field {1-4}

3 interpolation level {1-3}

1: bi-linear

2: bi-quadratic polynomial

3: bi-cubic polynomial

The contents of the coil input data file FOR0##.DAT is

1 title (a80)

2 NCOILS {1-1000}

( 3-6repeated for each coil)

3 coil #

4 relative z offset of this coil [m]

5 radius of coil[m]

6 current[A]

**DIP**
vertical sector dipole
field

1 model

1: hard-edge dipole + multipole fields (2nd order)

2:
dTANH(s) B_{Y} with higher multipoles (3^{rd} order)

3: hard-edged combined function dipole

4: hard-edge dipole with adjustable pole face angles

For **model = 1**

2 dipole field strength [T]

3 (not used)

4 reference momentum [GeV/c]

5 quad strength [T/m]

6 sextupole strength [T/m^2]

Hard-edge field models can include the focusing effects of the missing fringe field by using EDGE commands before and after the hard-edge field region.

For **model = 2**

2 dipole field strength [T]

3 curvature factor

h = 1 /
ρ_{geom} [ m^{-1}]

0. =>
use local B_{Y} and B_{X} on axis

4 reference momentum [GeV/c]

5 dipole central length [m]

6 dipole end length [m]

7 dipole end attenuation length[m]

8 quadrupole field component [T / m]

9 sextupole field component [T / m^2]

10 quadrupole central length [m]

11 quadrupole end length [m]

12 quadrupole end attenuation length [m]

13 sextupole central length [m]

14 sextupole end length [m]

15 sextupole end attenuation length[m]

The sign of h in parameter 3 should correspond to the sign of the dipole field.

For **model = 3**

2 dipole field
strength, b_{0} [T]

3 field index, n

4 reference
particle momentum, p_{REF}
[GeV/c]

5 distance
from machine center to reference circle,
r_{0 } [m]

6 curvature factor

h
= 1 / ρ_{geom} [ m^{-1}]

0. =>
use local B_{Y} and B_{X} on axis

7 parameter for reverse-bend magnets; set to 0 for normal sector magnets; set to 1 for radial sector magnets with center on same side as positive bend sectors.

The combined function dipole has a vertical field on axis given by

B_{yo} = b_{o} {r_{o}
/ r}^{n}

This model uses 8^{th} order expansions in y/R to
get the total Bx and By field components. The field is uniform in s. For FFAG
magnets n is negative and the radius of curvature of the particle = p_{REF } / (q b_{o} ) is smaller than r_{0 }.

For **model = 4**

2 dipole strength [ T ]

3 (not used)

4 reference momentum [GeV/c]

5 (not used)

6 (not used)

7 axial center position of dipole from start of region [m]

8 half axial length of dipole along reference trajectory [m]

9 entrance pole rotation angle [deg]

10 exit pole rotation angle [deg]

11 horizontal half width of aperture [m]

12 vertical half width of aperture [m]

A positive pole rotation angle means the edge closest to the center of curvature is decreased by the rotation (TRANSPORT convention). It is up to the user to be sure that the region length extends out as far as the rotated pole faces. Otherwise they will be truncated longitudinally.

1 model

1: static

For **model = 1**

2 E_{X} [V/m]

3 E_{Y} [V/m]

4 E_{Z} [V/m]

5 xmin [ m ]
Bounding box for field

6 xmax [
m ]

7 ymin
[m]

8 ymax
[m]

9 zmin
[m]

10 zmax
[m]

11 C, curvature factor

0: respect curvature

1: force rectangular

2: specify curvature

3: specify curvature and force rectangular

12 curvature [m^-1] for C=2,3 in parameter #11

**FOFO** solenoidal FOFO lattice element

1 model

1: linear end ramp in Bz(Br from div B = 0)

2: sinusoidal Bz with Bessel radial dependence

For **model = 1**

2 bmag [T] (amplitude of varying Bz)

3 bcen [T] (central offset value of varying Bz)

4 period [m]

5 offset from beginning of the cell or region [m]

offset = 0, Bz starts at bcen, rises to bmag at a quarter period, ...

offset=-period/4, Bz starts at bmag, falls to bcen at a quarter period,...

For **model = 2**

2 bmag [T] (amplitude of varying Bz)

3 bcen [T] (central offset value of varying Bz)

4 period [m]

5 offset from beginning of the cell or region [m]

offset = 0 starts at bcen

**HDIP**
horizontal sector dipole
field

1 model

1: hard-edge skew dipole plus multipoles (2nd order)

2: dTANH(s) BX with higher multipoles

For **model = 1**

2 a_{0} dipole field strength [T]

3 (not used)

4 reference momentum [GeV/c]

5 a_{1} quad strength [ T/m ]

6 a_{2} sextupole strength [ T/m^{2} ]

Hard-edge field models can include the focusing effects of the missing fringe field by using EDGE commands before and after the hard-edge field region.

For **model = 2**

2 dipole field strength [T]

3 (not used)

4 reference momentum [GeV/c]

5 dipole central length [m]

6 dipole end length [m]

7 dipole end attenuation length[m]

8 quadrupole field component [T / m]

9 sextupole field component [T / m^2]

10 quadrupole central length [m]

11 quadrupole end length [m]

12 quadrupole end attenuation length [m]

13 sextupole central length [m]

14 sextupole end length [m]

15 sextupole end attenuation length[m]

**HELI(X****)** helical field

1 model

1: simple rotating dipole

2: infinite he

3: multi-filar helical multipoles

4: user-supp

5: he

6: he

Models 2-5 are only defined here for particle radius less
than the radius of the he

For **model = 1**

** **2 dipole field strength
[T]

3 helix period [m]

4 dipole entrance and exit taper length [m]

8 start value of solenoid field [T]

9 central value of solenoid field [T]

10 end value of solenoid field [T]

11 solenoid entrance taper length, L1 [m]

12 solenoid central length, L2 [m]

13 solenoid exit taper length, L3 [m]

14 reset parameter Set to 1 to reset accumulated helix length.

The total length of the helix must be L1+L2+L3.

For **model = 2**

2 current [A]

3 helix radius [m]

4 helix period [m] Cannot be 0. The sign gives the orientation of the twist.

5 starting azimuthal orientation [degrees]

6 (not used)

7 entrance and exit taper length for transverse field [m]

8 start value of solenoid field [T]

9 central value of solenoid field [T]

10 end value of solenoid field [T]

11 solenoid entrance taper length, L1 [m]

12 solenoid central length, L2 [m]

13 solenoid exit taper length, L3 [m]

14 reset parameter Set to 1 to reset accumulated helix length.

15 number of terms in series expansion

The total length of the he

(HELIX continued)

For **model = 3**

2 helix radius [m]

3 helix period [m] Cannot be 0. The sign gives the orientation of the twist.

4 dipole strength [ T ]

5 quadrupole strength [ T / m ]

6 sextupole strength [ T / m^{2} ]

7 entrance and exit taper length for transverse field [m]

8 start value of solenoid field [T]

9 central value of solenoid field [T]

10 end value of solenoid field [T]

11 solenoid entrance and exit taper length, L1 [m]

12 solenoid central length, L2 [m]

13 octupole strength [ T / m^{3} ]

14 reset parameter Set to 1 to reset accumulated helix length.

15 number of terms in series expansion

The total length of the helix must be 2*L1+L2. The solenoid field can be non-symmetric, but the transverse field tapering is done symmetrically.

For **model = 4**

2 file # of user-supplied multipoles {20-99}

3 reference radius r_{o} [m]

4 helix period [m] Cannot be 0. The sign gives the orientation of the twist.

5 starting azimuthal orientation [degrees]

6 reference magnetic field, B_{REF} [ T ]

7 entrance and exit taper length for transverse field [m]

8 start value of solenoid field [T]

9 central value of solenoid field [T]

10 end value of solenoid field [T]

11 solenoid entrance taper length, L1 [m]

12 solenoid central length, L2 [m]

13 solenoid exit taper length, L3 [m]

14 reset parameter Set to 1 to reset accumulated helix length.

1 title (a80)

2 number of supplied moments {1-20}

( B_{n}(i), A_{n}(i)
), i=1, Nmoments

For **model = 5**

2
file # of user-supp

3 (not used)

4
reference magnetic field, B_{REF} [ T ]

5 reference radius r_{o} [m]_{}

6 scale factor for solenoid field strength

7
scale factor for b_{0} field strength

8
scale factor for a_{0} field strength

9
scale factor for b_{1} field strength

10
scale factor for a_{1} field strength

11
scale factor for b_{2} field strength

12
scale factor for a_{2} field strength

13
scale factor for b_{3} field strength

14
scale factor for a_{3} field strength

15 maximum multipole order to use {1 – 6}

Set the scale factors of unused multipoles to 0 to speed up execution.

The helical fields are given by T. Tominaka et al, NIM A 459:398 (2001), eq. 40. For example the radial magnetic field is

_{}

where I_{n} is a modified Bessel function and

_{}

In principle each multipole can have its own axial period.
However, for a normal he_{n} to λ_{1}, the period of
the fundamental. The initial azimuthal angle of the field can be adjusted by
changing the ratio of normal and skew multipole components. The strength of
each multipole is determined by the Fourier coefficients of a_{n} and b_{n}.

(HELIX continued)

The contents of the input file FOR0##.DAT for model 5 is

1 title (a80)

2 period of lattice cell, λ [m]

3.1
period of 0^{th} order he_{1} (dipole)
[m]

3.2
period of 1st order he_{2} [m]

3.3
period of 2nd order he_{3} [m]

3.4
period of 3rd order he_{4} [m]

3.5
period of 4th order he_{5} [m]

3.6
period of 5th order he_{6} [m]

4.1 field strength for solenoid component [T]

4.2
field strength for b_{0} component [T] (normal dipole term)

4.3
field strength for a_{0} component [T] (skew dipole term, etc.)

4.4
field strength for b_{1} component [T/m]

4.5 field strength for a_{1}
component [T/m]

4.6
field strength for b_{2} component [T/m^{2}]

4.7
field strength for a_{2} component [T/m^{2}]

4.8
field strength for b_{3} component [T/m^{3}]

4.9
field strength for a_{3} component [T/m^{3}]

4.10 field strength for b_{4} component
[T/m^{4}]

4.11 field strength for a_{4} component
[T/m^{4}]

4.12 field strength for b_{5} component
[T/m^{5}]

4.13 field strength for a_{5} component
[T/m^{5}]

5 maximum Fourier order {0-199}

6 2^{ nd} title (a80)

(6 repeated for each order)

6.1 m order #

6.2 c_{m}
coefficient for solenoid field

6.3 d_{m}
coefficient for solenoid field

6.4 c_{m}
coefficient for b_{0} field

6.5 d_{m}
coefficient for b_{0} field

6.6 c_{m}
coefficient for a_{0} field

6.7 d_{m}
coefficient for a_{0} field

6.8 c_{m}
coefficient for b_{1} field

6.9 d_{m}
coefficient for b_{1} field

6.10 c_{m} coefficient for a_{1} field

6.11 d_{m} coefficient for a_{1} field

…

6.26 c_{m} coefficient for a_{5 }field

6.27 d_{m} coefficient for a_{5 }field

The form of the Fourier series used for each he

f (s) = S ( c_{m}
COS(u) + d_{m} SIN(u) )

where u = 2πms / λ.

You must enter non-zero periods for all multipoles up to the highest order used in the calculations.

For **model = 6**

2 file # of user-supp

3 order of calculation {1-3}

4 he

5 he

1 title (a80)

2 number of axial points {1-2000}

3.1 s [m]

3.2
B_{S} [T]

3.3
a_{0} [T]

3.4
b_{0} [T]

3.5
a_{1} [T/m]

3.6
b_{1} [T/m]

3.7
a_{2} [T/m^{2}]

3.8
b_{2} [T/m^{2}]

3.9
a_{3} [T/m^{3}]

3.10
b_{3} [T/m^{3}]

**HORN**
magnetic (toroidal-like) horn

1 model

1: simple analytic model

2: sheet(s) with user-supp

For **model = 1**

2 minimum polar angle [deg]

3 maximum polar angle [deg]

4 current [ A ]

For **model = 2**

** **2 number of horn sheet files to read in {1,2}

3 current sca

4 input file # of first sheet {20-99} (see format below)

5 input file # of second sheet {20-99} (see format below)

6 radial boundary between sheets [m]

The contents of the input file FOR0##.DAT is

1 title (a80)

2 current (R) [A]

3 npoints (I) {1-50}

4 (i,

n.b. Up to two radially-displaced horn sheets can be active at one time. The z positions in the file are measured relative to the start of the region or cell.

**KICK** kickers and deflection cavities

1 model

1: TM210 rectangular deflection cavity

2: time-dependent transverse kicker

For **model = 1**

2 frequency [MHz]

3 gradient [MV / m]

4 phase [deg] {0-360}

5 width [m]

The width must be > λ. The length is taken from SLEN; height is computed from eigenvalue equation.

For **model = 2**

2 input file #{20-99} (see format below)

3 time offset from start of pulse [s]

4 polynomial interpolation order {1-3}

5 azimuthal orientation of B, φ [deg]

6 magnitude of B, b_{0} [T]

7 slope, m {-1,1}

8 pulse width, τ [s]

9 B offset, b_{off} [T]

If the input file number is in the range {20-99} the magnetic field pulse as a function of time is

taken from the input file. The input file should contain

# of following points

t [sec] b_{0 }[T]
for each point

If an input file is not given, the pulse is computed analytically using parameters 6-9.

b(t) = b_{off}
+ b_{0} m t
/ τ

B_{X}
= b cos φ

B_{Y}
= b sin φ

Times are measured relative to the time the reference
particle entres the kicker region.

**QUAD** quadrupole field

1 model

1: constant gradient over entire region (hard edge) (2nd order)

2: dTANH(s) quad with sextupole

For **model = 1**

2 gradient strength [T/m] (+:focus horizontal, -:focus vertical)

3:
sextupole strength [T/m^{2}]

For **model = 2**

2 gradient strength [T/m] (+:focus horizontal, -:focus vertical)

3 quad central length [m]

4 (not used)

5 quad end length [m]

6 quad end attenuation length [m]

7 sextupole
strength [T/m^{2}]

8 sextupole central length [m]

9 sextupole end length [m]

10 sextupole end attenuation length [m]

**ROD**
axial current carrying rod

1 model level

1: Bphi only, constant in z, all other 0

2: level 1 + linear end fringe field

3: level 2 + minimal nonlinearity in radial dependence

4: dTANH(s) model for Bphi

5: tapered radius

For **model = 1**

2 Bphi [T] at outer radius(note that sign of B causes focus or defocus)

3 radius of rod [m]

For **model = 2 or 3**

2 Bphi [T] at outer radius(note that sign of B causes focus or defocus)

3 radius of rod [m]

4 length of central region[m]

5 length of end field region[m]

For **model = 4**

2 Bphi strength [T]

3 radius of rod [m]

4 central length [m]

5 end length [m]

6 end attenuation length [m]

For **model = 5**

2 Bc [T] (flat central field strength; sign is important!)

3 Rc [m] (flat central rod radius)

4 Lc [m] (central field length)

5 R1 [m] (starting rod radius)

6 L1 [m] (length of entrance transition region)

7 R2 [m] (ending rod radius; set to Rc to prevent /0)

8 L2 [m] (length of exit transition region; set to 0.01 to prevent /0)

**SEX**
sextupole field

1 model

1:
hard edge field (2^{nd}
order)

2:
dTANH(s) sextupole strength (3^{rd}
order)

For **model = 1**

2 sextupole strength [T/m^2]

For **model = 2**

2 sextupole strength [T/m^2]

3 central length [m]

4 (not used)

5 end length [m]

6 end attenuation length [m]

**SHEE(T****)**
field made up from sum of fields from annular solenoidal current sheets

1 model

1: exact field from single sheet

2: exact field from sum of sheets in data file

3: interpolate data file field points from grid

4: interpolate data file field points from “moving” grid

5: interpolate field from predefined r-z grid

This field type is often used as a CELL field. Repetition of a cell uses the same external

file over and over. A new cell block can use a different external file.

For **model = 1**

2 z offset of left edge of sheet from start of region [m]

3 radius of sheet [m]

4 length of sheet [m]

5 current density [A-turns/m]

For **model = 2**

2 file ##of sheet input {20-99} See model 3 for file definition.

If the file number is entered as a negative number, the current densities in the external file are all

reversed in polarity.

11 current scaling factor

For backwards compatibility if this parameter is exactly 0, it is set to 1 by the program.

For **model = 3**

2 file ##of sheet input (see below) {20-99}

reversed in polarity.

3 grid dz [m] (# z grid points < 5000)

4 grid dr [m] ( # r grid points < 100 )

5 total z grid length [m]

6 total r grid length [m]

Make the z and r grids at least 1 grid spacing longer in each direction than the actual size of the

cell or the field will be 0 at the boundary points.

7 cutoff length in z for including sheets [m]

This is the distance between the present location of the particle and the start of a sheet, after

which you can ignore the sheet in the calculation. The intent is not to waste time calculating

sources that are very far away.

8 interpolation level

1: bi-linear

2: bi-quadratic polynomial

3: bi-cubic polynomial

9 file ## of field output on the grid {20-99}

Set this <20 if you don't want the output file. The file format is given in section 4.2.

10 grid calculation suppression parameter{0,1}

Normally leave this set to 0. If it is set to 1, the fields on the grid will not be recomputed.

11 current scaling factor

For backwards compatibility if this parameter is exactly 0, it is set to 1 by the program.

Don't allow grid points to overlap sheet positions. A SHEET field using a grid cannot be

superimposed on a COIL or BLOCK field that also uses a grid.

The contents of the sheet data input file FOR0##.DAT is

1 title (a80)

2 NSHEETS {1-1000}

3 current scaling factor

( 4-8repeated for each sheet)

4 sheet #

5 relative z offset of this sheet[m]

6 length of sheet [m]

7 radius of sheet [m]

8 current density [A-turns/m]

The format of the output file generated by parameter 9 is listed in section 4.2.4.

For **model = 4**

2 file ## of field output on grid {20-99} Set this < 20 if you don’t want output file.

Format of file is described in sec. 5.2.4. Output is only written at the boundaries of grid partitions.

3 interpolation level

1: bi-linear

2: bi-quadratic polynomial

3: bi-cubic polynomial

Use of this model requires the user to specify the control variables MAGCONF and MAPDEF.

The MAGCONF variable specifies the magnet configuration file with the following format.

1 title (a80)

2 # of following solenoid magnet descriptions (I) {1-1000}

(3- 9 repeated for each magnet)

3 id # (I) for user convenience

4 absolute z location of the start of this solenoid (R) [m]

5 length of solenoid (R) [m]

6 inner radius of solenoid (R) [m]

7 radial thickness of solenoid (R) [m]

8 current density (R) [A / mm^2]

9 # of sheets to use in calculating the field (I) {>1}

The coils in this file must be ordered by their starting z locations.

The MAPDEF variable specifies grid partition file to use in the simulation with the

following format.

1 title (a80)

2 # of following grid definitions (I) {1-100}

(3- 9 repeated for each grid)

3 id # (I) for user convenience

4 absolute z location of the start of the partition (R) [m]

5 axial step size of grid (R) [m]

6 # of axial grid points (I) {2-5000}

7 radial step size of grid (R) [m]

8 # of radial grid points (I) {2-100}

9 axial distance to start of solenoid coils within which coils should be used in field

calculations (R) [m]

When using this model the starting value of each partition must correspond with the starting location of an ICOOL region.

Make the z and r grids at least 1 grid spacing longer in each direction than the actual size of the

cell or the field will be 0 at the boundary points. You must include a reference particle with this model.

For **model = 5**

2 grid ##of sheet field {1-4}

3 interpolation level {1-3}

1: bi-linear

2: bi-quadratic polynomial

3: bi-cubic polynomial

4 z mode flag

0: use relative z positions (normal)

1: use absolute z positions (moving grid)

**SOL**
solenoid field

1 model level

1: Bz with constant central region + linear ends

2: dTANH(z) Bz dependence

3: field from sum of circular current loops

4: field from annular current sheet

5: field from thick annular current block

6: interpolate field from predefined USER r-z grid

7: tapered radius

8: hard-edge with adjustable end fields

9: determine field from file of Fourier coefficients

10: determine field from file of on-axis field

For **model = 1**

2 field strength [T]

3 length of central region, CLEN[m] (You can use this to get a tapered field profile)

4 length of entrance end region, ELEN1 [m] This is the displacement of the

upstream end of the solenoid from the start of the region.

5 constant offset for Bz [T]

Use parameter 5 to get an indefinitely long, constant solenoidal field.

6 length of exit end region, ELEN2 [m].

For a symmetric field, set SLEN =CLEN + ELEN1 + ELEN2. Hard-edge field models can include the focusing effects of the missing fringe field by using EDGE commands before and after the hard-edge field region.

For **model = 2**

2 field strength [T]

3 length of central region, CLEN[m]

4 length for end region, ELEN [m] (This is the displacement of the

upstream end of the solenoid from the start of the region; for a symmetric field, set SLEN =

CLEN + 2*ELEN.)

5 order of vector potential expansion {1, 3, 5, 7}

6 end attenuation length, [m] (Set larger than maximum beam size)

7 constant offset for Bs [T]

For **model = 3**

2 field strength [T]

3 length of central region, CLEN[m] (This is the region over which the coils are

distributed)

4 length for end region, ELEN[m] (This is the displacement of the

upstream end of the solenoid from the start of the region; for a symmetric field, set SLEN =

CLEN + 2*ELEN.)

5 # of coils loops (equi-spaced over CLEN)

6 radius of coils [m]

For a symmetric field with 1 loop, set ELEN=0.5 SLEN.

For **model = 4**

2 field strength [T]

3 length of sheet [m]

4 z offset of center of sheet from start of region [m]

5 radius of sheet [m]

For **model = 5**

2 field strength [T]

3 length of block [m]

4 z offset of center of block from start of region [m]

5 inner radius of block [m]

6 outer radius of block[m]

For **model**** = 6**

2 grid ##of user-supplied field {1-4}

3 interpolation level {1-3}

1: bi-linear

2: bi-quadratic polynomial

3: bi-cubic polynomial

The required format of the field map is

title (A80)

# of z grid points (I) {1-5000}

# of r grid points (I) {1-100}

i, j, z_{i}, r_{j}, BZ_{i,j}, BR_{i,j }(I,
R)

For **model = 7**

2 Bc [T] (flat central field strength)

3 Rc [m] (flat central coil radius)

4 Lc [m] (central field length)

5 B1 [T] (starting field strength)

6 R1 [m] (starting coil radius)

7 L1 [m] (length of entrance transition region)

8 B2 [T] (ending field strength)

9 R2 [m] (ending coil radius)

10 L2 [m] (length of exit transition region)

This model applies a geometry cut on particles whose radius exceeds the specified radial taper.

For **model** = 8

2 B_{S} [T]

3 flag on whether to include end focusing

0: both entrance and exit focusing

1: exit focusing only

2: entrance focusing only

3: no edge focusing

4 focusing deficit at
entrance [T^{2} m]

5 focusing deficit at
exit [T^{2} m]

The focusing deficit is B^{2}L - ∫B^{2}
ds. The deficit is independent of the focusing effect chosen with parameter 3.

For **model** = 9

2 file number JK for input data (I) File name is for0JK.dat

3 order of off-axis expansion (I) {1, 3, 5, 7}

4 scale factor (R) Multiplies field strength

The contents of the input file for0JK.dat is

1 title (A80)

2.1 period, λ (R)

2.2 field strength, S (R)

3 maximum Fourier order (I)

(4 repeated for each order)

4.1 order, m (I) {0 – 199}

4.2 c_{m} (R)

4.3 d_{m} (R)

The on-axis field is given by

f (s) = S S ( c_{m} COS(u) + d_{m}
SIN(u) )

where u = 2πms / λ.

For **model** = 10

2 file number JK for input data (I) File name is for0JK.dat

3 order of calculation (I) {3,5,7}

4 scale factor (R) Multiplies field strength

The contents of the input file for0JK.dat is

1 title (A80)

2 number of points (I) {<1001}

3.1 z (R) [m]

3.2 B_{z} (R) [ T ]

**SQUA** skew quadrupole field

1 model

1: constant gradient over entire region (hard edge) (2nd order)

2: dTANH(s) quad only (3^{rd} order)

For **model = 1**

2 gradient strength [T/m] (+:focus horizontal, -:focus vertical)

3 skew sextupole strength [T/m^{2}]

For **model = 2**

2 gradient strength [T/m] (+:focus horizontal, -:focus vertical)

3 central length [m]

4 (not used)

5 end length [m]

6 end attenuation length [m]

**STUS** User
supplied, static 3D magnetic field grid

1 model level

1: set up 3D grid at this location in ICOOL command stream

2: use 3D grid predefined with GRID command

For **model = 1**

2 file ## of input field grid (see below) {20-99}

3 curvature flag

0: straight grid

1: curved grid

4 reference momentum( pref ) [GeV/c]

5 field strength normalization factor (R)

6 interpolation model {0-3}

0: simple linear

1: spline (requires a spline input file, not a field grid!)

2: quadratic polynomial

3: cubic polynomial

7 grid calculation suppression parameter{0,1}

Normally leave this set to 0. If it is set to 1, the fields on the grid will not be recomputed.

8 curvature sign flag if parameter=1 => flip sign of HREF in input file

9 file format flag

0: formatted B grid

1: unformatted B grid

2: unformatted spline coefficients of B grid

10) Longitudinal shift parameter. If a longitudinal grid index JZ is entered here, the field grid stored in memory starts at JZ, wraps through the beginning of the grid and ends at longitudinal index JZ-1.

This command can also be used to input a user-supplied field to a background field definition. It is used as a field type argument for the BFIELD command.

For **model = 2**

2 interpolation model {0-3}

0: simple linear

1: spline

2: quadratic polynomial

3: cubic polynomial

3 curvature flag

0: straight grid

1: curved grid

The grid points must be equally spaced in a given direction. For BACKGROUND fields the value of MXG must agree with the parameter NXBKG of the BACKGROUND command, etc.

For a curved grid (parameter 3 = 1): if href in the input file is not 0, then href is used as the constant curvature; if href in the input file is 0, then pref is used with the local Bx and By on-axis fields to determine the curvature.

For file formats 0 and 1 the contents of the user supplied field file FOR0##.DAT is

title (a80)

mxg (I) number of x grid points {<101}

myg (I) number of y grid points {<101}

mzg (I) number of z grid points {<501}

href (R) curvature
[m^{-1}]

(xgr(i),i=1,mxg) (R) x grid points [m]

(ygr(i),i=1,myg) (R) y grid points [m]

(zgr(i),i=1,mzg) (R) z grid points [m]

i j k Bx By Bz (I,R) x-index, y-index, z-index, corresponding field values [T]

The i variable changes most rapidly, then the j variable, then the k variable.

For file format 2 the contents of the user supplied spline coefficient file FOR0##.DAT is

title (a80)

mxg (I) number of x grid points {<101}

myg (I) number of x grid points {<101}

mzg (I) number of x grid points {<501}

href (R) curvature
[m^{-1}]

(xgr(i),i=1,mxg) (R) x grid points

(ygr(i),i=1,myg) (R) y grid points

(zgr(i),i=1,mzg) (R) z grid points

nbf(3) (I) # of spline basis functions

nord(3) (I) spline orders

sknot (R) array containing knot sequences

cbx (R) array of spline coefficients for Bx

cby (R) array of spline coefficients for By

cbs (R) array of spline coefficients for Bs

1 model level

1: simple rotating dipole

2: he

3: he

4: planar wiggler

5: he

For **model = 1**

** **2 dipole strength [T]

** **3 solenoid strength [T]

4 wiggler period [m]

For **model = 2**

2 length of central region, CLEN[m]

3 length for edge region for ramp, ELEN [m]

4 wiggler period [m].This cannot be 0, >0 => right hand twist, <0 => left hand twist.

5 ramp in solenoid field [T]

6 constant solenoid field [T]

7 field ramp for helical dipole [T]

8 uniform field for helical dipole[T]

9 phase offset for helical dipole, phi0 [deg]

10 field ramp for helical quadrupole [T/m]

11 uniform field for helical quadrupole [T/m]

12 phase offset for helical quadrupole, phi0 [deg]

13 field ramp for helical sextupole [T/m^2]

14 uniform field for helical sextupole [T/m^2]

15 phase offset for helical sextupole, phi0 [deg]

For **model = 3**

2 length of central region, CLEN[m]

3 length for edge region for ramp, ELEN [m]

4 wiggler period [m].This cannot be 0, >0 => right hand twist, <0 => left hand twist.

5 length scale for field ramp, LAMB [m]

6 ramp in solenoid field [T]

7 constant solenoid field [T]

8 ramp in wiggler field [T]

9 constant wiggler field [T]

10 phase offset, PHI0 [deg]

RAMP is given by the average of two TANH functions, one going from -1 to 1 with zero at z=ELEN, the other going from 1 to -1 with zero at z=ELEN+CLEN, both having scale length

LAMB. When the phase shift PHI0=0 => the field component is in the y direction at z=0.

(WIG continued)

For **model = 4**

2 wiggler period, λ [m] λ > 0

3 vertical wavevector, k_{y} [m^-1]
k_{y } > 0

4 (not used)

5 solenoid field strength [T]

6 number of terms in series {1-3}

7 field strength for n=1, C_{1} [T]

8 field strength for n=2, C_{2} [T]

9 field strength for n=3, C_{3} [T]

10 initial azimuth [radians]

The field components are hyperbo

k_{x}
is sinusoidal if k_{y} > 2π / λ

k_{x}
is hyperbo_{y} < 2π /
λ

k_{x} is 0 if k_{y} =
2π / λ

For **model = 5**

2 wiggler period [m]

** **3 dipole strength [T]

** **4 additional solenoid strength [T]

4.2 Material tags and parameters

MTAG (A) material composition tag

**Enter MTAG in upper case.**

VAC vacuum (i.e., no material)

GH gaseous hydrogen

GHE gaseous helium

LH liquid hydrogen

LHE liquid helium

LI BE B C AL TI FE CU W HG PB (elements)

LIH lithium hydride

CH2 polyethylene

MGEOM (A) material geometry tag

GPARM (R) 10 parameters that describe the geometry of the material.

These 10 parameters must be on one input line.

**Enter MGEOM in upper case.
Set unused parameters to 0.**

NONE use for vacuum

10*0.

CBLOCK cylindrical block

10*0.

n.b. the program tracks thru any of the following types of wedge region with fixed step sizes,

regardless of the value of the parameter VARSTEP.

4.3 Geometry tags and parameters

**ASPW** Azimuthally Symmetric Polynomial
Wedge absorber region

Edge shape given by

r(dz) = a0 + a1*dz + a2*dz^2 + a3*dz^3 in the 1st quadrant and

where dz is measured from the wedge center.

1 z position of wedge center in region [m]

2 z offset from wedge center to edge of absorber [m]

3 a0 [m]

4 a1

5 a2 [m^(-1)]

6 a3 [m^(-2)]

**ASRW** Axi-Symmetric Radial
Wedge absorber region

Edge shape given by

dz(r) = a0 + a1*r + a2*r^2 + a3*r^3

This is the half-thickness of the wedge. The wedge is symmetric about the x-y plane located at z=ZV.

The wedge material is filled in from z=ZV-dz to z=ZV+dz at any given radius.

1 distance of symmetry x-y plane from beginning of region, ZV [m]

This is typically half the thickness of the s-region. If =0=> left half of wedge is cut off.

2 maximum half-thickness of wedge along z [m] Needs to be > 0.

3 a0 [m]

4 a1

5 a2 [m^(-1)]

6 a3 [m^(-2)]

**HWIN** hemispherical
absorber end region

1 end flag {-1: entrance, +1: exit}

2 inner radius of window[m]

3 window thickness [m]

4 axial offset of center of spherical window from start of end region [m]

The user must specify three “radial” subregions. The geometry parameters (above) and the

maximum cylindrical radial cut off are taken from the first radial region definition. The material

specified in the first radial subregion is the absorber, the material in the second is the window,

and the material for the third corresponds to the outside of the window, e.g. vacuum.

Example

SREGION ! hemishperical
end region (exit)

0.100 5 30.001

1 0.0.173

NONE

0. 0. 0. 0. 0. 0. 0. 0. 0.
0. 0. 0. 0. 0. 0.

LH !LH

HWIN

1. 0.20 500e-6 0.10 0. 0. 0. 0. 0. 0.

2 0. 0.173

NONE

0. 0. 0. 0. 0. 0. 0. 0. 0.
0. 0. 0. 0. 0. 0.

AL

HWIN

0. 0. 0. 0.0. 0. 0. 0. 0.
0.

3 0. 0.173

NONE

0. 0. 0. 0. 0. 0. 0. 0. 0.
0. 0. 0. 0. 0. 0.

VAC

HWIN

0. 0. 0. 0.0. 0. 0. 0. 0. 0.

1 z_{V} distance of wedge “center” from start
of region [m]

2 z_{0} distance from center to left edge [m]

3 z_{1} distance from center to right edge [m]

4 θ_{0} polar angle from vertex of left
edge [deg]

5 φ_{0} azimuthal angle of left face [deg]

6 θ_{1} polar angle from vertex of right
edge [deg]

7 φ_{1} azimuthal angle of right face [deg]

For description see S. Berg, MC note 261, October 2002.

**PWEDGE** Asymmetric polynomial wedge
absorber region

Imagine the wedge lying with its narrow end along the x axis. The wedge is symmetric about the

x-y plane. The edge shape is given by

dz(x) = a0 + a1*x + a2*x^2 + a3*x^3

where dz is measured from the x axis.

1 (not used)

2 initial position of the vertex along the x axis [m]

3 z position of wedge vertex [m]

4 azimuthal angle of vector pointing to vertex in plane of wedge w.r.t. +ve x-axis [deg]

5 total width of wedge in dispersion direction [m]

6 total height of wedge in non-dispersion direction [m]

7 a0

8 a1

9 a2

10 a3

Assume the wedge is initially positioned with the vertex along the x axis (parameter 2). The

wedge is then rotated azimuthally (parameter 4) in the x-y plane to its final position.

1 inner radius (R) [m]

2 outer radius (R) [m]

This is functionally equivalent to defining a region with two radial subregions, the first of which

has vacuum as the material type. However, the boundary crossing algorithm used for RING is

more sophisticated and should give more accurate simulations.

**WEDGE** Asymmetric wedge absorber
region

1 full angle at vertex, α (or A) [degrees]

2 initial position of the vertex along the x axis, U [m]

3 z position of wedge vertex, Zv [m]

4 azimuthal angle φ of vector pointing to vertex in plane of wedge w.r.t. +ve x-axis [deg]

5 total width of wedge in dispersion direction, w [m]

6 total height of wedge in non-dispersion direction, h [m]

“We begin with an isosceles triangle, sitting on its base, vertex at the top. The base-to-vertex

distance is W. The full opening angle at the vertex is A. Using two of these triangles as sides, we

construct a prism-shaped wedge. The distance from one triangular side to the other is H. The

shape and size of the wedge are now established. We define the vertex line of the wedge to

be the line connecting the vertices of its two triangular sides.

Next, we place the wedge in the right-handed ICOOL coordinate system. The beam travels in the

+Z direction. Looking downstream along the beamline (+Z into the page), +X is horizontal and to the left, and +Y is up.

Assume the initial position of the wedge is as follows: The vertex line of the wedge is vertical

and lies along the Y axis, extending from Y = -H/2 to Y = +H/2. The wedge extends to the right

in the direction of -X, such that it is symmetric about the XY plane. (Note that it is also

symmetric about the XZ plane.) From the beam's point of view, particles passing on the +X

side of the Y axis will not encounter the wedge, while particles passing on the -X side of the Y

axis see a rectangle of height H and width W, centered in the Y direction, with Z thickness

proportional to -X.

By setting parameter U to a non-zero value, the user may specify that the wedge is to be

translated in the X direction. If U>0, the wedge is moved (without rotation) in the +X direction.

For example, if U = W/2, then the wedge is centered in the X direction; its vertex is at X = W/2

and its base is at X = -W/2. Note that the wedge is still symmetric about both the XY plane and

the XZ plane.

Next, the wedge may be rotated about the Z axis by angle PHI. Looking downstream in the beam

direction, positive rotations are clockwise and negative rotations are counter-clockwise. For

example, setting PHI to 90 degrees rotates the wedge about the Z axis so that its vertex line is

parallel to the X axis and on top, while its base is parallel to the XZ plane and at the bottom. In

general this rotation breaks the symmetry about the XZ plane, but the symmetry about the XY

plane is maintained.

Finally, the wedge is translated in the Z direction by a distance Zv, so that its XY symmetry plane lies a distance Zv downstream of the start of the region. Usually Zv should be at least large

enough so that the entire volume of the wedge lies within its region, i.e. Zv .ge. W tan (A/2), the

maximum Z half-thickness of the wedge. As well, the region usually should be long enough to

contain the entire volume of the wedge, i.e. RegionLength .ge. Zv + W tan (A/2). Wedges that do

lie completely within their region retain their symmetry about the XY plane Z=Zv.

If portions of a wedge lie outside their region in Z, then the volume of the wedge lying outside

the region is ignored when propagating particles through the wedge. Such a wedge will grow in

thickness until it reaches the region boundary, but will not extend beyond it. In such cases,

wedges may lose their symmetry about the XY plane Z=Zv.

Wedges may be defined such that they extend outside the radial boundaries of the radial

subregion within which they are defined. However, any portion of the wedge volume lying inside the inner radial boundary or outside the outer radial boundary is ignored when propagating particles through the wedge. For example, if the user intends that an entire radial subregion of circular cross-section be filled with a wedge, then it is clear that the corners of the wedge must extend outside the radial region, but particles passing outside the wedge's radial subregion will not see the wedge at all.

In short, we may say that although it is permitted (and sometimes essential) to define a wedge to

be larger than its subregion, for the purposes of particle propagation the wedge is always trimmed at the region's Z boundaries and the subregion's radial boundaries. Any volume within the region and subregion that is not occupied by the material specified for the wedge is assumed to be vacuum.

---------------------------------------------------------------------------------------------------------------

Example 1: Within a region 0.4 meters long in Z, within a radial subregion extending from the Z axis out to a radius of 0.3 meters, a wedge is to fill the X<0 (right) half of the 0.3 meter aperture of the subregion, and increase in Z thickness proportional to -X, such that it is 0.2 meters thick at the rightmost point in the subregion (X=-0.3, Y=0).

The wedge is to be 0.2 meters thick at a point 0.3 meters from its vertex. The half-thickness is

0.1 meters, the half-opening angle is atan (0.1/0.3) = 18.4 degrees, so the full opening angle of

the wedge A is 36.8 degrees. The width (X extent) of the wedge must be 0.3 meters, and the

height (Y extent) of the wedge must be 0.6 meters. Two corners of the wedge extend well beyond the subregion, but they will be ignored during particle propagation. The wedge does not need to be translated in X (U = 0) nor does it need to be rotated about the Z axis (PHI = 0). For

convenience we center the wedge (in Z) within its region, so Zv = 0.2 meters. Since the

maximum half-thickness of the wedge is only 0.1 meters, the wedge does not extend beyond (or

even up to) the Z boundaries of the region. The volume within the region and subregion but

outside the wedge is assumed to be vacuum.

------------------------------------------------------------------------------------------------------------

Example 2: In the same region and subregion, we need a wedge with the same opening angle,

but filling the entire aperture of the subregion, thickness gradient in the +Y direction, thickness =

0 at the lowest point in the subregion (X=0, Y=-0.3).

The wedge must now have H = W = 0.6 meters so it can fill the entire aperture of the subregion.

From its initial position, it must first be translated 0.3 meters in the +X direction (U = 0.3) to

center it in the subregion's aperture, and then (from the perspective of someone looking

downstream along the beam) rotated counterclockwise 90 degrees (PHI = -90.) so that the Z

thickness increases proportionally to +Y. Since the wedge has the same opening angle as before

but has twice the width, its maximum Z thickness is now 0.4 meters, just barely fitting between

the Z boundaries of the region if Zv = 0.2 meters. All four corners of the wedge now extend

outside the radial subregion's outer boundary, but they will be ignored during particle

propagation.” {S.B.}

5. Other files

5.1 Input files

5.1.1 FOR003.DAT Beam input data

This optional file can be used to start a simulation using previously defined beam data.

Title card (A79)

Reference particle data: ZBREF,PBREF,TBREF,ZB2REF, PB2REF, TB2REF,TYPREF. (R)

{ZB, PB, TB} refer to the z position [m], momentum [GeV/c] and time [s] for the reference particle (and for a second reference particle if present). TYPREF is the particle code for the type of particle (cf. sec. 2.4).

For a new problem set this card to __seven__ 0. fields.

This is followed by an indefinite number of incident particles, each with the following data.

(1) IEVT (I) event #(increase sequentially from 1)

(2) IPNUM (I) particle # for this event (set to 1)

(3) IPTYP (I) particle type code (see BMTYPE in sec. 2.4)

(4) IPFLG (I) particle status flag (set to 0)

(5) TP (R) time [s]

(6) EVTWT (R) event weight (set to 1.)

(7) XP(i),i=1,3 (R) cartesian position [m] (set xp(3)=0.)

(8) PP(i),i=1,3 (R) cartesian momentum [GeV/c]

(9) POL(i),i=1,3 (R) cartesian spin vector

For muons from pion decay this vector should correspond to the muon rest frame if spin tracking

is to be done.

5.1.2 Optional files can be used to define the magnetic field on an r-z grid. See BLOCK, COIL,

SHEET and SOLENOID (USER) for descriptions of the file formats.

5.1.3 Optional file can be used to set the parameters of RF cavities using the control variable RFPHASE.

The following is repeated for every RF cavity region.

(1) ID (I) ICOOL region number of the rf cavity

(2) PHASERF (R) cavity phase[degrees]

(3) FRF (R) cavity frequency [MHz]

(4) GRADRF (R) cavity peak electric field on-axis [MV/m]

5.2 Output files

5.2.1 FOR002.DAT program LOG file

This file is always created. It can consist of:

1. print out of input variables used

2. summary table of region properties

3. diagnostic print out of particle position, momentum, spin, and fields (optional)

4. identification of tracks that fail to reach end of the simulation

5. transverse and longitudinal emittances at specified planes (optional)

6. histogram statistics (optional)

7. scatterplot statistics (optional)

8. covariance of particle distributions at specified planes (optional)

9. character histogram of desired quantities (optional)

10. character scatterplot of desired quantities (optional)

11. Z-history (trace) of desired quantities (optional)

12. elapsed time for simulation

5.2.2 FOR004.DAT Beam information after a specified region

This optional file contains particle information in the same format as described for file

FOR003.DAT above.

5.2.3 FOR009.DAT postprocessor data file

This file contains information about each of the particles at production and at various z locations

under the user’s control. This file is generated using the OUTPUT pseudocommand

or the control variables OUTPUT1, NTUPLE and RTUPLE.

Title card (A79)

Header line with units

Header line with column labels

This is followed by particle information at requested positions.

1) IEVT (I) event #

2) IPNUM (I) particle # for this event

3) IPTYP (I) particle type code (see BMTYPE in sec. 2.2)

4) IPFLG (I) particle status flag

5) JSRG (I) ICOOL region #

6) TP (R) time [s]

7) XP(i),i=1,3 (R) position [m]

8) PP(i),i=1,3 (R) cartesian momentum [GeV/c]

9) BFLD(i),i=1,3 (R) total magnetic field [T]

10) EVTWT (R) event weight

11) EFLD(i),i=1,3 (R) total electric field [V/m]

12) SARC (R) total arclength [m]

13) POL(i),i=1,3 (R) spin

For muons from pion decay POL(3) contains the helicity in the LAB frame when SPIN=true and SPINTRK=0.

5.2.4 An optional file can be created of the cy

The contents of the field map is

title (A80)

# of z grid points (I) {1-5000}

# of r grid points (I) {1-100}

i, j, z_{i}, r_{j}, BZ_{i,j}, BR_{i,j }(I,
R)

Note that the z locations in this file are specified relative to the position where the current field

definition was made, i.e. they are not absolute z locations.

5.2.5 An optional 3D magnetic field grid file can be created using the BACKGROUND command. The format of the file is

title (A80)

nx, ny, nz, hcurv (I, R) # of x, y, z grid points; curvature [m]

xgr_{i},
i=1,nx (R)

ygr_{j},
j=1,ny (R)

zgr_{k},
k=1,nz (R)

i, j, k, BX_{i,j,k},
BY_{i,j,k}, BZ_{i,j,k }(I,
R)

Note that the z locations in this file are specified relative to the position where the current field

definition was made, i.e. they are not absolute z locations.

5.2.6 An optional file can be produced of RF diagnostics at the end of every acceleration region.

(See the control variable RFDIAG.)

(1) JSRG (I) region number

(2) id (I) event number

(3) d(phase) (R) difference (particle-reference) phase at cavity center

(4) dt (R) difference (particle-reference) time at cavity center

(5) dPz (R) difference (particle-reference) Pz at cavity center

(6) f (R) rf frequency [Hz]

(7) G (R) gradient [V/m]

(8) PHASERF (R) cavity phase [degrees]

(9) EZRF (R) cavity Ez [V/m]

(10) BPHIRF (R) cavity Bphi [T]

(11) TREFMEAN (R) zero crossing time of reference particle at center of preceding

cavity [s]

(12) T2REFMEAN (R) zero
crossing time of 2^{ nd} reference particle at center of preceding

cavity [s]

(13) Z (R) Z for particle at center of cavity [m]

5.2.7 Neutrino production data

This data appears on the file specified by the control variable NEUTRINO.

Title record (A)

Problem title (A80)

For each neutrino satisfying the polar angle cuts:

1) IEVT (I) event #

2) IPNUM (I) particle # for this event

3) IPTYP (I) particle type code

4) IPFLG (I) particle status flag

5) JSRG (I) ICOOL region #

6) TP (R) time [s]

7) XP(i),i=1,3 (R) position [m]

8) PP(i),i=1,3 (R) cartesian momentum [GeV/c]

9) EVTWT (R) event weight

The particle type uses the following code

6 muon neutrino

-6 muon antineutrino

7 electron neutrino

-7 electron antineutrino

±20 from muon decay

±30 from pion decay

±40 from kaon decay

e.g. IPTYP = -36 for a muon antineutrino from pion decay

Problem title (A80)

At each OUTPUT command

1) region number

2) Bz [T]

3) t [s]

4) Pz [GeV/c]

5) normalized transverse emittance [m rad]

6) Courant-Snyder beta [m]

7) Courant-Snyder alpha

8) angular momentum

9) particle number

10) transverse scraping parameter

11) normalized longitudinal emittance [m rad]

A summary of all regions (and pseudoregions) in the job is
written to the for007.dat if the control variable SUMMARY is true.

(1) FOR008.DAT particle overflow data file

This unformatted, direct access file contains particle data used by the program. It is only created

when the number of requested particles is greater than 300,000.

6. Program execution flags

0 No errors.

-1 Fatal error (with message on the log file)

-10 particle outside dipole aperture

-11 got unphysical momentum from dipole edge focusing

-12 negative argument for SQRT {DERIV]

-13 error setting angular momentum correlation

-14 got unphysical momentum computing random field kick

-15 event failed because of variable cut

-16 error creating initial dispersion

-23 Particle radius not in defined r-region.

-24 failure of Fano scattering model

-25 Illegal LOG argument [DEDX]

-26 failure of Tollestrup scattering model

-27 Illegal LOG argument [SCATTER]

-28 Particle outside an aperture [SIMULATE]

-29 probability error [RESTRICT_LOSS]

-30 error in muon decay

-31 exceeded allowed radius in the tapered solenoid

-32 Vz went negative [GO_REGION]

-33 stuck in stepping loop[GO_REGION]

-36 particle time difference exceeded BUNCHCUT [SIMULATE]

-39 r > r(cav) [ACCEL ]

-40 r > r(rod) [TAPERED_ROD]

-43 Pz of particle is less than control variable PZMINTRK

-47 particle transverse position outside the kicker cavity

-52 particle decayed

-57 radius > Rcav in Superfish model

-58 failed absorber hemispherical end region logic

-61 momentum outside desired band for induction linac

-62 spin tracking error [GO_REGION]

-64 depolarization error [FLIP_ELASTIC]

-72 radius too large in HELIX

-73 hadron had inelastic interaction (tracking stops)

-74 argument out of range in Bessel function I0 or I1

-75 argument out of range in Bessel function K0 or K1

-76 stepping gave result with r > 100 m or pt > 1000 GeV/c

-77 error in ACCEL model 10; two ref particles have same p?

-81 interpolated HORN point lies outside data grid

-82 position error in DIPOLE model 4

-85 failure of MOLIERE scattering algorithm

-86 got unphysical momentum computing hard-edge fringe field kick

-87 unphysical momentum from TRANSPORT matrix

^{[1]}
R.C. Fernow, ICOOL: A simulation code for ionization coo

^{[2]}^{
} W. Al*Ab initio*

^{[3]}