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.
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 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.
ICOOL is under active development at the present time. It is being made available as a potential aid to members of the 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.
Users of previous versions should note that the TAPER command is no longer supported and default simulations with LiH or space charge will no longer give identical results.
(7 August 2012)
Version 3.28 includes a new uniformly-charged ellipsoid model for space charge calculations. The longitudinal array shifting routine was modified. The TRANSPORT command was modified to stop automatic OUTPUT. The OUTPUT logic was modified to print out the fields for the initial particle distribution. The calculation of the maximum number of steps in a region was changed. Errors were fixed in the SAMCS routine for correlated scattering and energy loss. Modifications may be necessary in existing input decks that used space charge levels 1, 3, or 4. These are no longer supported. Changes were made in the BUNCH9 and ENDOF9 utilities. A new emittance routine EIGEMIT is provided. (7 July 2011)
Version 3.26 includes a new dipole model 5 from S. Berg and a new solenoid model 11 from K. McDonald. A facility was added so that ICOOL can read nagnetic field grids made with G4Beamline. A new variable DTALT was provided for creating beams with both charges at the same time. Modifications were made in the magnetic field shift logic and in writing OUTPUT with the TRANSPORT command. The STUS(1) model was eliminated. Errors were fixed in the format for the GRID command, in calculating the LBNL emittances for negative particles, and in the radial field direction for the ACCEL(5) command. Modification may be necessary in existing input decks that use the STUS(1) command. Changes were made in the BUNCH9 and ECALC9F utilities. (9 June 2010)
Version 3.23 includes AlBeMet as a new internally defined material. Solenoid model (1) has been modified to allow the creation of a more generally shaped field. The SuperFish accelerator model 5 was modified to allow defining a new cavity shape in every ICOOL region. The method for normalizing the SuperFish cavity fields was also changed. Errors were fixed in the print out from the STUS command. A bug was fixed in the third order polynomial interpolation. Modification may be necessary in existing input decks that use the SOL(1) or ACCEL(5) commands. Changes were made in the ERRSUM2 and ECALC9F utilities. (10 December 2009)
Version 3.20 includes a new kicker model (3) and has a new control variable NPSKIP to skip a given number of events in an external beam file before simulations begin. New particle types are defined for d, He3, and Li7. Stainless steel is a new defined material. The for009 header was modified for compatibility with the HistoRoot program, which is part of the G4Beamline distribution. The material interaction routines were modified to take the particle charge into account. The algorithm for calculating dE/dx for compounds was modified. The maximum number of SuperFish axial grid points was increased. The DENS command was modified to refer to the reference (not the current) value of the density. Output of the LBNL emittances was reassigned to the EMIT command. The old HELIX(5) model was deleted. Errors were fixed in the old HELIX(6) model, which was renamed as the new HELIX(5) model. Errors were fixed in KICK for t=0, in setting up a SuperFish grid, in the CUTV command, in the logic for the DENS command, and in the logic for the DENP command. Errors were fixed using WEDGE with two materials and in WEDGE for steps that partially enter the wedge. Modification may be necessary in existing input decks that use the DENS or HELIX(6) commands. There is a modification of the for009 header generated by the ENDOF9, NOTEND9, EXTREG9 and EXTPAR9 utilities. (22 July 2009)
Version 3.17 includes a modification to the ACCEL(5) and (11) commands to allow SuperFish cavities in dipole regions. The APERTURE command was modified to allow off-center, rectangular cuts. The multipole expansion for orders 1-3 was changed in BSOL for constant curvature. The DIP, HDIP, QUAD, SQUA and SEX commands were modified so that model=1 consistently uses second order expansions. Some IFLD.FOR and IINT.FOR routines were modified to use double precision constants (S. Berg). Errors were fixed in HELIX(6) and in the initialization for decays. Modification may be necessary in existing input decks that use the APERTURE, ACCEL(5), BSOL(2), DIP(1), or HDIP(1) commands. A potential error in the ECALC9F utility has been corrected (C. Yoshikawa). (20 January 2009)
The tables below describe the available files. The code may be accessed using the link at the bottom of the page.
| icool.for | general monte carlo framework |
|---|---|
| ifld.for | field routines |
| iint.for | particle interaction routines |
| idiag.for | built-in diagnostics |
| imath.for | mathematical routines |
| imsoft.for | Windows-specific code |
| icommon.inc | common blocks include file |
| icool.exe | Windows PC executable (binary) |
| icoolman.pdf | ICOOL reference manual |
| ICguide.pdf | ICOOL user's guide |
A number of other files are available to enrich your ICOOL experience. Some files that are useful for running ICOOL on UNIX machines are given in the following table.
| iunix*.* | Scott Berg's UNIX replacements for file imsoft.for |
|---|---|
| Makefile | Scott Berg's UNIX make file |
A number of programs have been written to calculate emittances from the ICOOL output. All these routines obtain the particle distribution information from the for009.dat file.
| ecalc9.for | Gregg Penn's original postprocessor for calculating emittance with standard cuts. |
|---|---|
| ecalc9f.* | A modified version of Gregg Penn's postprocessor that reads a second file containing the parameter values for the analysis. |
| emitcalc.* | Gregg Penn's postprocessor for calculating emittance with standard cuts in all three phase space planes. The routine reads a second file containing the parameter values for the analysis. |
| ecalcxy.* | Dave Neuffer's postprocessor for calculating emittance in channels that are not azimuthally symmetric. This is more suitable for channels containing dipoles and quadrupoles than ECALC9F. The routine reads a second file containing the parameter values for the analysis. |
| eigemit.* | This routine computes eigenemittances along with other emittance and auxilliary quantities. |
A number of utility routines are available for checking ICOOL input and manipulating ICOOL output. For most of these routines the source code, a Windows executable, and a MANual file are provided.
| view1.exe | A Windows graphical preprocessor. This program extracts geometrical information from the ICOOL command file for001.dat. It displays the geometry information from for001.dat and from any other associated magnet data files. The executable works on Windows only. |
|---|---|
| view1man.pdf | VIEW1 user's manual |
| errsum2.* | Makes error message summary from ICOOL log file. This program reads the ICOOL log file for002.dat. It displays a short error summary on the terminal and writes a more detailed error analysis on a file. |
| view9.exe | A Windows graphical postprocessor. This program reads the ICOOL physics output file for009.dat. Scatter plots of user-selected variables are displayed for every region on the file. |
| view9man.pdf | VIEW9 user's manual |
| endof9.* | This program reads the ICOOL physics output file for009.dat. It writes a new file in for009.dat format that only contains information for particles that get to end of simulation. |
| notend9.* | This program reads the ICOOL physics output file for009.dat. It writes a new file in for009.dat format that only contains information for particles that do NOT get to end of simulation. |
| extpar9.* | This program reads the ICOOL physics output file for009.dat and a parameter file. It writes a new file that only contains information for user-selected particles. |
| extreg9.* | This program reads the ICOOL physics output file for009.dat and a parameter file. It writes a new file that only contains information for user-selected regions. |
| bunch9.* | This program reads the ICOOL physics output file for009.dat and a parameter file. It writes an analysis file containing bunching data along with several other auxilliary files. |
Some additional supplemental files are available. These include further descriptions of the code, its revision history, and tutorials. In addition, other programs, such as the HistoRoot program distributed with G4beamline, can be used to examine the Icool for009 output file.
| icool99.pdf | ICOOL description from PAC99 |
|---|---|
| icool05.pdf | ICOOL description from PAC05 |
| changes.txt | History of changes made to code |
| tutor.pdf | Steve Bracker's tutorial on regions, cells, sections |
| wedges.pdf | Steve Bracker's tutorial on wedges |
| elmsdb.zip | Data files needed for running ICOOL with ELMS |
A number of example files have also been included. The example file naming scheme begins with a four character tag to describe a general problem. The 3-character extension defines the type of file. For example, DRIF.F01 should be copied to FOR001.DAT to run the DRIFt space example. This is a minimal-input running deck provided for beginning users. Some examples have additional data files that must also be renamed in order for the example to run, e.g. ASOL.F03 -> FOR003.DAT, etc. These examples are only intended to illustrate the input command structure and to give the user a test output to check if the program is executing properly.
| drif.f## | Drift space example |
|---|---|
| adib.f## | Adiabatic buncher example. This illustrates using two reference particles together with ACCEL model 10 and using &SUB name substitutions. |
| asol.f## | Alternating solenoid example. This is an early transverse cooling lattice. |
| cool.f## | s-fofo 2.75 m cooling lattice from Feasibility Study 2. It uses a "moving grid" (SHEET model 4). |
| tgug.f## | Part of the tapered Guggenheim 6D cooling channel. This also illustrates using the TRANSPORT command to do emittance exchange. |
| ring.f## | Balbekov ring example. This illustrates using the BEGS, multiple GRID, and EDGE commands. |
| *.f01 | Command input |
| *.f02 | Program output |
| *.f03 | Beam input |
| *.f07 | Region summary table |
| *.f20 | Current sheet or other input 20, etc. |
All the above files are contained in the following zip file.
| icool.zip | zip file containing all other files |
|---|
You can download these files from the subdirectory V330 .
The previous release version can be found in V328 .