            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 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 learn 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 (it may also prove helpful when tracking taus). 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 propagateTo(z, e) of the class Propagate returns the energy
of the particle at the border if it has reached the border specified by its
z-component z, or the traveled distance to the point of disappearance with a
minus sign otherwise. As this routine returns, the Particle object, referenced
by Propagate, describes the final state of the particle.

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 just 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 to
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, with the second expression setting the 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.

