ICOOL USER'S Manual

Abstract

ICOOL is a 3-dimensional tracking program that was originally written to study ionization cooling of muon beams. Analytic models are used to describe magnetic field configurations and RF cavities. Simulations of decays and interactions in matter of 1 MeV/c to 1 GeV/c muons are provided.

Table of Contents

1. Introduction
1. Electromagnetic field specifications
2. Reference particle
2. Command file input
1. Minimal deck structure
2. Problem title
3. Control variables
4. Beam generation variables
5. Physics interactions control variables
6. Histogram definition variables
7. Scatterplot definition variables
8. Z-history definition variables
9. R-history definition variables
10. Emittance plane definition variables
11. Covariance plane definition variables
12. Region definition variables
3. Other files
1. Input files
2. Output files
4. Program execution flags

1. Introduction

ICOOL is a 3-dimensional tracking program that was originally written to study ionization cooling of muon beams. 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 grouped in cells and a separate cell field can be superimposed over the region fields when tracking is done. In general the program takes user-defined steps in time. 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 models 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.

1.1 Electromagnetic field specification

ICOOL uses three methods for specifying the field environment of the tracked particles.
(1) Each region has a field associated with it. For simple problems this may provide a sufficient description of the field.
(2) Groups of regions are associated together in cells. Each cell has a field associated with it that applies to all the regions in the cell. This can be used for example to describe rf cavity regions inside a solenoid field over the cell.
(3) A background field grid can be defined over a specified region of s from any combination of region fields. This can be used to build a complicated field pattern from the basic region field types provided by the program. The actual field seen by a particle at a certain location is the superposition of any or all of these field specifications.
 

1.2 Reference particle

ICOOL uses the pseudoregion command REFP to define a reference particle. This command can be used to specify the particle type (REFPAR), starting momentum (PZ0REF), starting time (T0REF), and average accelerating gradient (GRADREF). The reference particle can be redefined later in a problem, if desired, by using another REFP command. When a reference particle has been defined, the internal diagnostics in ICOOL compute time and longitudinal momentum as the difference from the reference particle value at a given location. In addition when the control variable PHASEMODEL is 3 or 4, the phases of the RF cavities are initialized from the reference particle. The reference particle is started on axis with no divergence. Stochastic processes, such as multiple scattering and straggling are temporarily turned off. The time when the reference particle crosses the center of the cavity is used to initialize the cavity electric field to 0 (zero crossing). When PHASEMODEL=3 the reference particle is assumed to move with constant velocity (determined from the parameter PZ0REF). When PHASEMODEL=4 the reference particle is tracked thru all regions except RF cavities. The reference particle velocity drops due to the mean dE/dx in any material that may be present. It is assumed that the reference particle gains energy linearly in the cavity region. The amount of energy it gains is determined by the parameter GRADREF.

You can use (1) the mean value of the initial z position or (2) the parameter PHASE0 for the ACCEL field type to adjust the phase of the non-reference particles. If you are reading in an existing file (BGEN =false), the reference particle data is taken from the file, provided that REFP is the first region command and that the input reference momentum in the file is greater than 0.

file: FOR001.DAT

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
 

2.1 Minimal deck structure

2.2 Problem title

2.3 Control variables

Namelist: CONT

BETAPERP	(R)	beta value to use in calculating amplitude variable A2
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)
DECTRK	(L)	if .true. => continue tracking daughter particle following decay (false)
EPSSTEP	(R)	desired tolerance in spatial stepping to reach each destination plane [m] (2E-5)
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-4)
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)
FSAV	(L)	if .true. => store particle info at plane IZFILE into file FOR004.DAT; also works for "plane"=IFAIL #. (false)
FSAVSET	(L)	if .true. => modify data stored using FSAV in FOR004.DAT to have z=0 and time relative to reference particle at plane IZFILE. (false)
GOODTRACK	(L)	if .true. and BGEN=.false. => only accepts input data from file FOR003.DAT if IFAIL=0. (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 IZFILE=IFAIL #. IZFILE should point to the end of a REGION or to an APERTURE, ROTATE or TRANSPORT psuedo-region command.
NEIGHBOR	(L)	if .true. => include fields from previous and following regions when calculating field. (false) This parameter can be used with analytic fields when the magnitude of the field doesn't fall to 0 at the region boundary.
NPART	(I)	# of particles in simulation
NPRNT	(I)	# of diagnostic events to print out to log file (-1)
NSECTIONS	(I)	# of times to repeat basic cooling section (1)
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)
PHASEMODEL 1: takes phase directly from input deck 2: uses multi-cavity phase shift algorithm from input deck (cf. ACCEL) 3: takes phase from reference particle, ignoring energy loss and gain 4: takes phase from reference particle, using loss in absorbers and gain in cavities 5: reads phases in from file FOR0mn.DAT, where RFPHASE=mn.	(R)	controls how the phase is determined in RF cavities.
PRLEVEL 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	(I)	controls level of print information to log file (for NPRINT events); higher # gives more print (1)
PZMINTRK	(R)	Sets the value of Pz below which tracking stops. [GeV/c] (0.)
RFDIAG	(I)	if 20 < RFDIAG=mn < 100 => writes RF diagnostic information at the end of each region to file FOR0mn.DAT. (0)
RFPHASE	(I)	if PHASEMODEL=5 => reads RF phases for the cavities from file FOR0mn.DAT, where RFPHASE=mn. (0)
RTUPLE	(L)	if .true. => particle information in file FOR009.DAT is generated after every RTUPLEN steps. This variable should be used with caution, since it can generate an enormous amount of output. (false)
RTUPLEN	(I)	# of steps to skip between RTUPLE generated outputs (5)
RNSEED	(I)	negative random number seed (-1)
SPIN	(L)	if .true. => include spin tracking and calculation of polarization. (false)
STEPMIN	(R)	minimum step size that can be used for variable stepping [m] (1E-5)
STEPMAX	(R)	maximum step size that can be used for variable stepping [m] (1)
TIMELIM	(R)	time limit for simulation [min] (120.)
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 in wedge material regions and when the number of radial regions is greater than 1. (true)

 

2.4 Beam generation variables

2.5 Physics interactions control variables

Namelist: INTS

LDEDX (L)	if .true. =>	simulate mean ionization energy loss dE/dx (true)
LSTRAG (L)	if .true. =>	simulate energy straggling (true)
LSCATTER (L)	if .true. =>	simulate multiple scattering (true)
LDRAY (L)	if .true. =>	simulate discrete energy loss from delta rays (false)
LDECAY (L)	if .true. =>	simulate particle decays (false)
LSPACE (L)	if .true. =>	consider effects of space charge (false)
DELEV (I)	model level for dEdx (2)
	1:	Bethe-Bloch
	2:	Bethe-Bloch with density effect
	3:	restricted Bethe-Bloch with density effect
STRAGLEV (I)	model level for straggling (4)
	1:	gaussian( Bohr )
	2:	Landau distribution
	3:	restricted Landau distribution
	4:	Vavilov distribution (with Landau and gaussian limits)
SCATLEV (I)	model level for multiple scattering (4)
	1:	gaussian( 0, Rossi-Greisen )
	2:	gaussian( 0, Highland )
	3:	gaussian( 0, Lynch-Dahl )
	4:	Moliere distribution (with Rutherford limit)
	5:	Rutherford
DECLEV (I)	model level for particle decays
SPACELEV (I)	model level for space charge
	1:	image charge of moving bunch in cylindrical, metallic can
ENGMIN (R)	kinetic energy of particle, below which tracking stops [GeV] (1E-3)
DCUTE (R)	kinetic energy of electrons, above which delta rays are discretely simulated [GeV] (1E-3)
DCUTM (R)	kinetic energy of muons and other heavy particles, above which delta rays are discretely simulated [GeV] (1E-3)
FACFMS (R)	factor to correct the Z(Z+1) term in the characteristic angle squared C2 in Moliere multiple scattering theory (1.0)
FACMMS (R)	factor to correct screening angle squared A2 in Moliere multiple scattering theory (1.0)

 

2.6 Histogram definition variables

> NHIST (I) # of histograms {0-20} (0)
> HAUTO (L) if .true.=> histograms are scaled for no overflows (true)
> HCPRN (L) if .true. => histogram contents are written to LOG file (false)

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
1: X 11: X' 21: Xo 31: Bx
2: Y 12: Y' 22: Yo 32: By
3: Z 13: (space angle) 23: Zo 33: Bz
4: Px 14: r 24: Px0 34: Ex
5: Py 15: phi 25: Pyo 35: Ey
6: Pz [2] 16: Pr 26: Pzo 36: Ez
7: t [2] 17: Pphi 27: to 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:
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 in the log output file (FOR002.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 : histogram quantities when this ifail occurs {< -10}

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

[2] If a reference particle is defined, the difference with respect to the reference particle is used.
 

2.7 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 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 in the log output file (FOR002.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.8 Z-history definition variables

Namelist: NZH

> NZHIST (I) # of Z-histories {0 - 10} (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-12}
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.9 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

Namelist: NRH

> 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.7) IRHYVAR (I) variable flag (see definitions in IHVAR above)
 

2.10 Emittance plane definition variables

> NEMIT (I) # of s-planes where the emittance or polarization should be calculated {0-30} (0)
> SIGMACUT (L) if .true. => tails of {x ... Pz} are cut at SIG_CUT sigmas before the emittance is calculated. (true)
> PXYCORR (L) if .true. => Px and Py are corrected (for the emittance calculation) for the vector potential in a solenoid field. (false) > SIG_CUT (R) # of sigmas to cut off tails of {x ... Pz} for the emittance calculation. (4.)
> PZCORR (L) if .true. => the normalized longitudinal emittance is corrected for the Pz versus transverse amplitude correlation (false) > BZFLDPRD (R) Bz for solenoid at location of production plane (0.) This is used for canonical angular momentum correction.

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. A returned emittance value of -998 or -999 indicates the program could not calculate a sensible emittance.
 

2.11 Covariance plane definition variables

> NCOVAR (I) # of s-planes where the covariance should be calculated {0-30} (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
 

2.12 Region definition variables

2.12.1 Regular region commands *****

1) SECTION

Start of cooling section definition; the data must end with an ENDSECTION; it can enclose any number of other commands

2) CELL

Start of a repeating group of region commands; the data must end with an ENDCELL command. The cell loop can enclose any number of {SREGION, REPEAT, ENDREPEAT, OUTPUT, APERTURE, ROTATE, TRANSPORT} 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)

3) REPEAT

Start of a repeating group of region commands; the data must end with an ENDREPEAT command. This can be used to repeat regions inside a cell. The repeat loop can enclose any number of {SREGION, OUTPUT, APERTURE, ROTATE, TRANSPORT} commands. Repeat sections cannot be nested in other repeat sections. (see parameters below)

4) SREGION

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

5) ENDREPEAT End of REPEAT data block.

6) ENDCELL End of CELL data block.

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

2.12.2 Pseudo-region commands (A4) *****

1) APERTURE Collimates beam at aperture (see parameters below)

2) OUTPUT

Writes particle information to FOR009.DAT. This command will only function if both NTUPLE and RTUPLE are false. (no parameters).

3) REFP Define reference particle properties (see parameters below)

4) ROTATE Rotates x and y coordinates (see parameters below)

5) TRANSPORT

User input of transport matrix. A reference particle must be defined to use this command. (see parameters below) 6) 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)

7) BFIELD Define background field (see parameters below)

8) ENDB End definition of background field (see parameters below)
 

2.12.3 Region and pseudoregion command parameters *****
APERTURE
1.1) IAPERTYPE (I) 1:elliptical 2:rectangular
1.2) APERLIM1 (R) x half-width [m]
1.3) APERLIM2 (R) y half-width [m]
BACKGROUND
1.1) GRIDBKG (L) if .true. => calculate field on rectangular grid
1.2) PREFBKG (R) reference momentum thru background grid [GeV/c]. This parameter is used in determining the curvature.
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 {<31}
2.7-9) ZLOBKG, DZBKG, NZBKG {<401}
2.10) INTERBKG (I) interpolation order for background grid {1-3} The z coordinate used in the background grid is in the global coordinate system; e.g. a background region starting at 4 m into the problem must have ZLOBKG=4.

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)

CELL
1) NCELLS (I) Number of times to repeat the commands in this cell block.
2) CFTAG (A4) Field tag for field that is superimposed over all the regions in this cell; see FTAG values below.
3) CELLFLIP (L) If .true. => flip cell field for alternate cells
4) CFPARM (R) 15 parameters describing field (see specific field type below)

ENDB 1) (I) file # of field output on the grid {20-99}. Set this <20 if you don't want an output file.

REFP
1.1) REFPAR (I) Use BMTYPE particle code to specify reference particle type or 0 if no reference particle. {0 - 5} (2) If set, this redefines t and Pz relative to the on axis reference particle in histograms, plots, and emittance calculations. 1
.2) PZ0REF (R) start longitudinal momentum for reference particle [GeV/c]
1.3) T0REF (R) start time value for the reference particle [s] (0.)
1.4) GRADREF (R) average energy gradient seen by the reference particle in rf cavities for PHASEMODEL=4. [MeV/m]

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

ROTATE
1) ANGLE (R) Rotation angle around z axis [degrees]

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

ROTATE ! switch x and y coordinates 90.

SREGION ! usual horizontal bend region ........... ROTATE ! switch x and y coordinates back -90.

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 pushing particles [m]

(following repeated for each r subregion)
2.1) RREGN (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)
5) MTAG (A4) Tag identifying material composition in this r subregion (see specific material type below)
6) MGEOM (A4) Tag identifying material geometry in this r subregion. (see specific material type below)
7) GPARM (R) 10 Parameters describing material geometry. (see specific material type below)

TRANSPORT

1) SLENTRP (R) length of this region [m]

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

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

7) 6th row of transport matrix
 
 

2.12.4 Field tags and 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: EZ only with no transverse variation

2: cylindrical TM01p pillbox resonator

3: traveling wave cavity

4: approximate fields for symmetric circular-nosed cavity

For model = 1

2 frequency [MHz]

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

4 phase shift [deg] {0-360}. This is only applied to the first cavity in a string in phasemodel (PM) 2.

5 phase offset of (any) subsequent cavities in same cell [deg] (PM 2 only)

6 phase offset of (any) subsequent cavities in the same cell that have (PM 2 only) non-cavity regions separating them from a previous cavity [deg]

7 phase offset of first cavity in next cell (if any) [deg] (PM 2 only)

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}. This is only applied to the first cavity in a string in phasemodel (PM) 2. 5 phase offset of (any) subsequent adjacent cavities in same cell [deg]. (PM 2 only) 6 phase offset of (any) subsequent cavities in the same cell that have non-cavity regions separating them from a previous cavity [deg]. (PM 2 only) 7 phase offset of first cavity in next cell (if any) [deg] (PM 2 only) 8 longitudinal mode p {0,1} For mode = 0 Rcav = 0.383 * lambda For mode = 1 Rcav = 2.405 / {(2 pi f)^2 - (pi/SLEN)^2 }^1/2 For pi mode, set SLEN = /2 => Rcav -->inf

For model = 3

2 frequency f [MHz]

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

4 phase shift [deg] {0-360}. This is only applied to the first cavity in a string in phasemodel (PM) 2.

5 phase offset of (any) subsequent cavities in same cell [deg] (PM 2 only)

6 phase offset of (any) subsequent cavities in the same cell that have non-cavity regions separating them from a previous cavity [deg] (PM 2 only)

7 phase offset of first cavity in next cell (if any) [deg] (PM 2 only)

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}. This is only applied to the first cavity in a string in phasemodel (PM) 2.

5 phase offset of (any) subsequent cavities in same cell [deg] (PM 2 only)

6 phase offset of first cavity in next cell [deg] (PM 2 only)

7 total length of cavity [m]

8 total gap [m]

9 radius of drift tube [m]

10 radius of nose piece [m]

Phase offset parameters are only used for phasemodel=2. The initial phase parameter can be used for phasemodel=1-5. BACK background field

This can be used as a cell field only. It must be preceded by a calculation of a background field, defined over the length of the cell. Set the 15 parameters following this command to 0. BSOL bent solenoid 1 model 1: 1st order dependence for Bs and By 2: 2nd order dependence for Bs and By using dTANH(s)

The geometric curvature of the solenoid is equal to the radius of curvature of the reference particle in the dipole.

For model = 1

2 peak value of Bs [T]

3 peak value of By [T]

4 length [m]

5 reference momentum [GeV/c]

6 quad component of dipole field [T/m]

For model = 2

2 peak value of Bs [T]

3 peak value of By [T]

4 central length of solenoid, CLENS [m]

5 ref momentum [GeV/c]

6 quad component of dipole field [T/m]

7 end length of solenoid, ELENS [m]

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

9 central length of dipole, CLEND [m]

10 end length of dipole, ELEND [m]

11 attenuation length of dipole [m]

12 central length of quad, CLENQ [m]

13 end length of quad, ELENQ [m]

14 attenuation length of quad [m]

15 constant offset for Bs [T]

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 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 current I [A] Baxis = mu_o I / 2a = 2 pi 10^-7 I / a

For model = 2

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

For model = 3

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

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

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

5 total z grid length [m]

6 total r grid length [m]

7 cutoff length in z for including coils [m] This is the distance between the present location of the particle and the location of a coil in the file, after which you can ignore the coil 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.

Don't allow grid points to overlap coil positions. The contents of the coil input data file FOR0##.DAT is 1 NCOILS {1-1000} ( 2-5 repeated for each coil)

2 coil #

3 relative z offset of this coil [m]

4 radius of coil [m]

5 current [A] DEFLECT deflection cavity in x

1 model

1: TE011 rectangular cavity length .ge. lambda/2

2: TM210 rectangular cavity width .ge. lambda

For models 1 and 2

2 frequency [MHz]

3 gradient [MV / m]

4 phase [deg] {0-360}

5 width [m]

Length is taken from SLEN; height is computed from eigenvalue equation.

DIP sector dipole field

1 model

1: constant BY over entire region

2: dTANH(s) BY

For model = 1

2 dipole field strength [T]

3 order {1-4} Order=4 uses exact equation of motion and 3rd order field expansion.

4 reference momentum [GeV/c]

For model = 2

2 dipole field strength [T]

3 order {1-4} (cf. above)

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] ( not used for order=1,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]

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

QUAD quadrupole field

1 model

1: constant gradient over entire region (hard edge)

2: dTANH(s) multipole strengths

For model = 1

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

For model = 2

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

3 central length [m]

4 order {1,2,3}

5 end length [m]

6 end attenuation length [m]

7 sextupole strength [T/m^2]

8 octupole strength [T/m^3]

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

For model = 1

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

3 radius of rod [m]

4 length [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] SEX sextupole field 1

model 1: constant strength over entire region (hard edge) 2: dTANH(s) multipole strengths

For model = 1

2 sextupole strength [T/m^2]

3 length [m]

For model = 2 2

 sextupole strength [T/m^2]

3 central length [m]

4 order {2,3}

5 end length [m]

6 end attenuation length [m]

7 octupole strength [T/m^3] SHEET field made up from sum of fields from annular 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

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 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 (see below) {20-99}

For model = 3

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

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

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

5 total z grid length [m]

6 total r grid length [m]

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.

n.b. be sure that none of the grid points falls on a sheet. The contents of the sheet data input file FOR0##.DAT is 1 NSHEETS {1-1000} ( 2-5 repeated for each coil)

2 sheet #

3 relative z offset of this sheet [m]

4 length of sheet [m]

5 radius of sheet [m] 6 current density [A-turns/m]

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

For model = 1

2 field strength [T]

3 length of central region, CLEN [m] (You can get a constant solenoid field by setting SLEN=CLEN)

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 constant offset for Bz [T]

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 {0-3}

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 (CLEN) [m]

4 z offset of left edge of sheet from start of region (ELEN) [m]

5 radius of sheet [m]

STUS User supplied, static magnetic field grid This command can 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.

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

The contents of the user supplied field file FOR0##.DAT is title mxg, myg, mzg (I) number of x grid points, etc. i j k Bx By Bz (I,R) x-index, y-index, z-index, corresponding field values [T]

The value of mxg must agree with the parameter NXBKG of the BACKGROUND command, etc.

TROD tapered current-carrying rod n.b. can be used to eliminate end field regions for matching

1 model level (not used)

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)

TSOL tapered solenoidal field n.b. can be used to eliminate end field regions for matching

1 model level (not used)

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)
 
 

2.12.5 Material tags and parameters *****

> MTAG (A) material composition tag

Enter MTAG in upper case.

VAC vacuum (i.e., no material) LH liquid hydrogen LI BE B C AL TI FE CU W LIH

> MGEOM (A) material geometry tag > GPARM (R) 10 parameters that describe the geometry of the material.

Enter MGEOM in upper case. Set unused parameters to 0.

NONE use for vacuum 10*0.

CBLOCK cylindrical block 10*0.

WEDGE asymmetric wedge absorber region

1 full angle at vertex [degrees]

2 position of wedge vertex in dispersive direction [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]

PWEDGE asymmetric polynomial wedge absorber region Edge shape given by dz(x) = a0 + a1*x + a2*x^2 + a3*x^3 in the upper half x-z plane where dz is measured from the x axis.

1 (not used)

2 position of wedge vertex in dispersive direction [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

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

4 a1

5 a2

6 a3

n.b. the program tracks thru any type of wedge region with fixed step sizes, regardless of the value of the parameter VARSTEP.
 
 

3. Other files

3.1 Input files

3.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: XPREF(3), PPREF(3), TPREF (R)

For a new problem set this card to seven 0. fields. The control variables T0REF and PZ0REF take precedence over the values on this card provided that TPREF=0.

This is followed by an indefinite number of incident particles, each with the following data.

(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) TP (R) time [s]

(6) EVTWT (R) event weight

(7) XP(i) (R) cartesian position [m]

(8) PP(i) (R) cartesian momentum [GeV/c]
 

3.1.2 Optional files can be used to define COIL and SHEET data.

3.1.3 Optional file can be used to set phases of RF cavities

The following is repeated for every RF cavity region.

(1) region number (I)

 (2) phase (R)
 
 

3.2 Output files

3.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, 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 of desired quantities (optional)

12. elapsed time for simulation
 

3.2.2 FOR004.DAT particle information after a specified region

This optional file contains particle information in the same format as described for file FOR003.DAT above.
 

3.2.3 FOR009.DAT "N-tuple" data file

Title card (A79)

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) IZP (I) region #

 6) TP (R) time [s]

7) XP(i) (R) position [m]

8) PP(i) (R) cartesian momentum [GeV/c]

 9) BFLD(i) (R) total magnetic field [T]

10) EVTWT (R) event weight

11) EFLD(i) (R) total electric field [V/m]

12) phase (R) RF cavity phase [deg]
 

3.2.4 Optional files can be created of the field on COIL, SHEET, and BACKGROUND grids.

3.2.5 An optional file can be produced of RF diagnostics at the end of every region.

(1) event number (I)

(2) region number (I)

 (3) XP(i) (R)

 (4) PP(i) (R)

 (5) TP (R)

 (6) PZREF (R)

 (7) TPREF (R)

 (8) cavity phase (R)

(9) cavity Ez (R)

 (10) cavity Bphi (R)

 (11) dPz (R)

(12) dt (R)

(13) d(phase) (R) 3.3 Internal program files

(1) FOR007.DAT region data file

This unformatted, direct access file contains region data used by the program.

(2) 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 50000.
 
 

4. Program execution flags

This document was generated on 26 April 1999 using the texi2html translator version 1.51.