            Muon Propagation Monte Carlo Written in Java
                               or
                     Muon Monte Carlo (mmc)
             by Dima co. R (Copyright Wuppertal, 2000).

This program is designed to fulfill the goal of propagating a energy muon
through matter. Generally, as a muon travels through matter, it looses
energy due to ionization losses, bremsstrahlung, photo-nuclear interaction
and pair production. All of these losses have continuous and stochastic
components, division between which is superficial and is chosen in the
program by selecting an energy cut (ecut) or a relative energy loss cut
(vcut). Ideally, all losses should be treated stochastically. However, that
would bring the number of separate energy loss events to infinity, since
the probability of such events to occur diverges logarithmically for the
ionization losses and as 1/x for all others. The value of the cut should
be chosen carefully, in such a way that you get the best accuracy with the
reasonable calculation time. For example, if the problem is to propagate
a muon until it looses all its energy (disappears), then vcut can be set
to 0.1-0.2. If, however, one needs to propagate 1 TeV muon beam through
only 3 meters of iron, then in order to see a reasonable approximation to
the true final muon energy distribution, the value of vcut may have to be
set as low as 0.01-1.e-3.

The program provides classes for the calculation of all components of the
muon energy loss separately. To see their names and parameters, see the
javadoc generated manual pages. I suggest you start with the class hierarchy
tree - it's easiest to find the energy loss you're looking for by name
there. An example of how to use the classes is contained in the class
TestPropagate. Each of the 4 main components has 3 classes: one is the
entry class that has some definitions, and provides function for evaluating
of the integration limits. It also creates 2 sub-classes and keeps
references to them: one defines continuous part of the loss, and the other
stochastic. Since the sub-classes have all functions of the superclass, it
could be tempting to call the functions of the superclass (or, rather, the
object, standing above) directly. It, however, creates chaos, and the only
case where this is used is with the integration limits. All other
supplementary functions of the superclass are called with the class pointer
dot name of the function. The superclass pointer is created by the
superclass and passed along to the subclass at the initialization stage.
This strategy keeps user, e.g. from having to set the "measured" variable
in the photo-nuclear class three times - once for the superclass, and two
times for the sub-classes.

All superclasses for the cross sections are united under another superclass
CrossSections. In addition to the 4 energy losses mentioned above this
class contains also subclass Decay which is there to make sure that the
tracking integral is non-zero. If initialized, class CrossSections creates
all sub-classes and keeps references to them. It also defines some auxiliary
functions for the displacement integral.

The main class of the program is Propagate. You can create this class by
calling the Propagate(w, ecut, vcut) constructor. It creates the Particle
class, CrossSections, and Medium. All parameters are passed along to the
constructor of the Medium class. They are: name of the medium (e.g. Water),
value of the ecut and vcut. If both ecut and vcut make sense (ecut>0 and
0<vcut<=1), then the lower one is chosen for each particular energy of the
primary (muon). If only one of the cuts makes sense, then only that one is
used. If both parameters are out of their ranges of reasonable values, then
vcut=1 is used instead. Class Particle contains everything this program
needs to know about the particle, like it's location, direction, energy and
mass. All variables except energy show the particle's actual state. Energy
and momentum are used for the all-around calculations, however.

The main routine of the Propagate propagateTo(z, e) class returns the
energy of the particle if it has reached the border specified by x or the
distance to x with a minus sign that shows the location of where the
particle disappeared. As this routine returns, the energy and momentum of
the muon (in the Particle class)  are set to the energy after the last but
one interaction. 

Since the program needs to evaluate up to 3-fold integrals, calculation
time may be quite large (minutes) even for one muon. In its simplest form
the program is designed to be used in the SYMPHONY framework (see class
MPMCWJ for an example of how to do that). For more practical applications,
however, parametrization (interpolation) routines are implemented. Enable
them by calling interpolate("all") after the Propagate class is created.
You may choose to enable just some of the parametrizations by replacing the
word "all" with the list of things to parametrize. E.g. "bremsE trackX"
will enable parametrization of the continuous part of bremsstrahlung loss
and the displacement integral. This example will, however, take a long,
long time to initialize, since trackX will call other (not parametrized)
functions many, many times. In such a case you may be better off by omitting
the trackX parametrization altogether. You can also save parametrization
tables in a file and read them at in at a later time. Just call interpolate
with a second parameter, e.g. interpolate("all", ""). The file will have a
unique name based on the parameters you gave while initializing Propagate
class. If you use any of the "less obvious" features listed below, or do
some other changes in the code, the parametrization tables will become
invalid. In such case you should delete the file with tables, or give it a
different name by setting the second parameter of interpolate to something
other than an empty string.

Among the less obvious features are the possibility to use parametrization
of the photon nucleon cross section that is based on the table of measured
values. Enable it by setting Propagate.s.n.measured=true. You can also
choose to enable the high energy cutoff for the bremsstrahlung photons. It
should in some extent approximate the behavior of the photons if the Lorenz
invariant were not conserved. Enable it by setting
Propagate.s.b.lorenz=true and Propagate.s.b.lorenzCut=1.e6, where is the
default high energy cutoff. You need to change it to a more realistic value
before using. If you choose to enable any of these options, you should of
course do so before any parametrizations are done.

You will also find programs Frejus and Amanda in the package. The first one
gives you an interactive way to set the energy and the distance from the
keyboard after it initializes. This could be useful for using the program in
UNIX pipes. The second program Amanda it an attempt to tailor this mmc
package to the purposes of propagating the muons for the AMANDA mass
production chain. It reads and outputs data in F2000 compliant format to and
from the standard input/output.

We hope that you enjoy using this program and welcome any comments (and bug
reports). The primary design goals while writing this program were
uncompromising computational precision and code clarity (for ease of future
changes and corrections). Since the program was designed to be used in the
SYMPHONY framework, computational speed was only a secondary issue. However,
with full optimization (parametrizations) this code is at least as fast or
even faster than the competition. We hope that the combination of precision,
code clarity, speed and stability will make this program package a useful
tool in the research connected with high energy particles propagating
through matter.

