This manual is intended to be viewed in a web browser, and is extensively hyper-linked. It can be printed (Help/OpenHelpInBrowser, and print from there), but the static page loses much of its utility. This document is self-contained except for the external links in the References section and the accompanying images directory.

MuSim is a graphical user interface for running multiple particle-simulation programs. It provides user-friendly methods for creating, modifying, executing, optimizing, and analyzing simulations in a unified and intuitive way. MuSim makes it easy to compare results from multiple programs simulating the same system, and to perform parameter scans and plot results. An integrated event display works with all simulation programs. At present it interoperates with G4beamline and MCNP, but more simulation programs are expected to be added.

The primary problem that MuSim addresses is specifying the geometry, sources, and detectors of a simulation, in a manner that can be used by multiple simulation programs. As each simulation program has its own methods for specifying these, MuSim converts its internal representation into that of each simulation program. Moreover, MuSim is generally much easier to use than the simulation programs themselves (especially MCNP).

The secondary problem that MuSim addresses is data conversion among different simulation programs, and analyzing data in a unified way.

The basic idea is to define the simulated world by analogy with how systems are constructed in the real world: by placing objects into the world. Each object has a geometrical shape, a material of which it is composed, and a position and orientation in space. As in the real world, objects must not overlap (intersect); objects can also be parents of other objects, to a high level of nesting -- the child essentially replaces the material of the parent within its volume. There is an important restriction: no child can extend outside the volume of its parent (this is used to optimize tracking in complex geometries). Complex electromagnetic fields are also supported (but not all simulation programs support them).

Once the geometry of the simulated world is configured, particle source(s) must be added. MuSim implements a variety of sources, including particle beams, isotropic point sources, cosmic-ray muons, and radioactive decay sources. Multiple sources can be combined in a single simulation.

Once the geometry and source(s) are configured, detectors must be added to obtain simulation results. MuSim implements a variety of detectors capable of sampling particle fluxes and energy depositions. In addition, a graphical 3-d event display is provided, integrated with the display of the system; a slider permits the transparency of solids to be varied, making tracks inside them visible.

All the above is done in a straightforward and intuitive manner that is independent of any simulation program. MuSim can be used to run a simulation in each simulation program that is installed and configured. Multiple runs can easily be compared, using different programs or using different values of parameters. It is easy to perform a parameter scan and plot results vs. the parameter value.

MuSim also implements the concept of Library -- a collection of pre-built objects that can be placed into simulations. Libraries can be accessed via the local filesystem, HTTP, and FTP, promoting sharing among collaborators and unrelated users.

Quick Start Guide

Before using MuSim, you need to:

• Read the chapter on Basic Concepts to learn how MuSim is organized.
• Install MuSim (see appendices for Mac OS X, Linux, and Windows).
• Create a (writable) directory to use as the Default Library; the first time MuSim is run it will prompt you for this.
  
• Install and configure one or more Simulation Programs into MuSim, to actually perform the simulations. These are installed separately.
  
• Perform the Regression Tests, to ensure that MuSim is installed correctly and can use the simulation programs you have configured.

Then a good place to start is the Examples. They will be copied to a writable directory so you can modify them and get experience using MuSim. You can also explore the physics of these examples by varying their parameters and observing how the results change -- that is a good way to learn how MuSim can assist you in performing analysis.

License

License terms for MuSim have not yet been determined. It is NOT an open source program.

Library Licenses
Coin3D is used via a BSD-style 3-clause license.
Qt is used via the LGPL.
Both licenses are copied in the file "doc/LibraryLicenses.txt" in the MuSim distribution.

Basic Concepts

MuSim is a graphical user interface for running particle-simulation programs. As an interface, it does not implement any physics itself, but the things it does implement can certainly affect the physics of a simulation.

The primary problem that MuSim addresses is specifying the geometry, sources, and detectors of a simulation, in a manner that can be used by multiple simulation programs. As each simulation program has its own methods for specifying these, MuSim converts its internal representation into that of each simulation program. Moreover, MuSim is generally much easier to use than the simulation programs themselves (especially MCNP).

MuSim models the world geometry as a hierarchical set of volumes, each with its own shape, orientation, position, and material. We describe this as each volume having a parent, and zero or more children. Each child replaces the parent's material with its own, within its own volume. The world volume is merely the outermost parent volume. The user defines the geometry of the simulation by creating volumes and placing them into the world, or into each other. The World volume is completely automatic, and expands to hold whatever volumes are placed into it.

MuSim uses three types of objects to describe a simulation; each object is contained in a single file:

Simulation

A simulation specifies the overall simulation, except for any Library objects it uses. Filename: name.sim. Exactly one Simulation file is open at any given time.

SimObject

A SimObject specifies a single object, or a collection of multiple objects, except for any Library objects it uses. SimObject-s can be placed into a simulation or other SimObject. Filename: name.simobj.

SimDef

A SimDef contains definitions global to a simulation or SimObject, such as materials and simulation-program-specific features. Filename: name.simdef.

Each object is named by the filename that contains it; as each object is wholly contained in a single file, they can be renamed and copied freely. The file formats are ASCII, and are amenable to being directly edited via a text editor (i.e. not based on XML). There is a command-line tool, musim_run, that can run a simulation from the command line. When coupled with the parameterization of a simulation file, this permits advanced scripting, because parameter values can be set on the musim_run command line.

Electromagnetic fields can also be defined; they are completely independent of the volume hierarchy. For convenience and good organization, fields can be defined within the geometry -- you can define a magnet that has both a volume of iron and a field; by making it a SimObject it can be placed multiple times into the world, with different parameter values for each placement (e.g. different locations, orientations, and field values).

A Source will generate initial particle tracks for the simulation program(s) to track. These can also be placed within the volume hierarchy.

A Detector will generate output from the simulation. These can also be placed within the volume hierarchy.

SimObjects can be used to implement common or repeated elements or things. In particular a SimObject can contain solids, electromagnetic fields, sources, detectors, and other SimObjects; each SimObject can be placed multiple times into the simulation, with each placement having its own position, orientation, and parameter values. SimObjects can be used in multiple simulations, and can be shared in libraries with other users. So a SimObject could be a single magnet (perhaps an iron volume plus a field), and another SimObject could be a single cell of a particle accelerator (containing multiple magnets, RF cavities, detectors, etc.).

For simplicity in defining an accelerator or beam line, MuSim implements Beamline Coordinates. These are coordinates {U,V,S} in which S runs along the center of tbe beamline, bending appropriately. You can easily define these coordinates and place objects into the simulation using them (e.g. the SimObject representing a bending magnet can bend the S axis appropriately). For beam optics programs like MAD-X, you must use these beamline coordinates.

Files Used to Implement a Simulation

Three types of files are used to implement a simulation. Each represents a distinct type of object:

Simulation

Defines the overall simulation. Everything about the simulation is contained in this file (and the files it uses).

SimObject

Is an object that can be placed into the simulated world, or into other SimObject-s.

SimDef

Is an object containing definitions needed by the simulation or its SimObject-s (e.g. material definitions).

All objects (Simulations, SimObjects, and SimDefs) are parameterized. This means that whenever they are used, specific values for the parameters can be given. Every parameter has a default value, which not only is the value used when the parameter is not explicitly set, it also defines the units that values must have.

Every object is contained in a single file. In particular, the icon image is inline, and any images in the description must also be inline (i.e. use data: URLs; this is handled automatically by MuSim).

All objects (files) have a set of common attributes:

Name

The name of an object comes from the name of the file that contains it. The path and file extension are omitted.

Filename

Every object retains the name of the file that contains it, including path.

Synopsis

The synopsis is a short description of the object. It is usually displayed whenever the object is being edited.

Description

The description is a potentially long description of the object. It can be in plain ASCII text or in HTML with inline images. It usually requires pushing a button to see it in a separate window.

Icon

The icon is a small image representing the object. It can be generated from the Coin3D viewer or from an external image file. It is contained inline in the file.

Parameters

The parameters are a set of variables that can be used in the definition of the object. For a Simulation they can be set whenever the simulation is to be run, and the SimulatePage has the ability to perform an automatic scan of a parameter. For a SimObject or SimDef the parameters can be set whenever the object is placed or included in an object.

ModifiedFlag

Each object remembers when it has been modified, and the editor will prompt the user to save it when appropriate.

For a SimObject, the name used in the place command is the name of the SimObject. But the SimObject also has an element name parameter -- this is passed to the Simulation Program, which often uses it for error messages or traces (all solids also have an element name). For example, the SimObject name could be the (generic) type of a magnet (e.g. BM109, Type2Quad), while each placement of the SimObject is given an element name corresponding to its usage in the system (e.g. B2, Q12).

Note that the icon image data are contained inline in the file, as are any images in the description. As this can make these entries quite long, they are placed at the end of the file. This makes it easier for users to directly edit these files in a text editor (note that is advanced usage not covered in this document).

Simulation

A Simulation is an object that describes an entire simulation. This includes the General Definitions of the simulation, the Global Geometry, and the Beamline Coordinates (optional). Everything about the simulation is contained in this file (and the files it uses). In MuSim, exactly one Simulation is open at any given time.

To run a simulation program, MuSim will parse the Simulation file and convert it into the format required by the input file of the simulation program. It also generates auxiliary files needed by the simulation program and/or by MuSim itself.

SimObject

A SimObject is a self-contained object that can be placed into the geometry of the simulated world (via %place, %multiplace, %bcplace, or %bcnext). It can contain all types of geometry commands, including using Beamline Coordinates (but if it uses them, then it can only be used in a simulation that has them).

Note that SimObjects are strictly MuSim constructs, and no simulation program ever sees them or needs to know about them. As MuSim parses the Simulation file to generate the input file for a simulation program, all SimObjects are parsed into their constituent solids (etc.) and these are written into the input file in the manner appropriate for the simulation program.

SimDef

A SimDef is a self-contained object that can be included in a simulation (via %include). It can contain only Definition commands.

Note that SimDefs are strictly MuSim constructs, and no simulation program ever sees them or needs to know about them. As MuSim parses the Simulation file to generate the input for a simulation program, all SimDefs are parsed and become appropriate definitions for the simulation program and/or for MuSim itself as it processes later commands. All %include commands (i.e. all included SimDefs) are processed before anything else. The need for this ordering is why SimDefs and SimObjects are separate, and are limited in what they can contain.

Units

Because different simulation programs use different sets of units, MuSim supports all common units. In general, any unitsful quantity must be specified with units attached. So a length might be 1m, 100cm, or 39.37in; an energy might be 1MeV or 1.602E-13joule. Note that there cannot be a space between the real number and the unit name. A number without a unit name appended is considered to be unitless.

Units are arranged in groups of compatible units. So mm, cm, m, ft, mile are all compatible and will be inter-converted automatically; cm and ns are not compatible, and attempting to mix them will generate an error "incompatible units". Unitless is essentially a group with a single member.

Arithmetic expressions can be used throughout MuSim, and units are handled appropriately. They are indicated by "${...}", where the '$' introduces a substitution or evaluation, and the braces delimit the expression. So for instance: ${1cm+1in}=3.54cm, ${1GeV+100MeV}=1.1Gev, ${10*1ns}=${1ns*10}=10ns, ${1m/10}=0.1m, ${1m/1cm}=100, etc. For addition and subtraction the unit on the left is used (the right-hand term is converted to it). For multiplication, one factor must be unitless and the other's unit is used. For division, either the denominator must be unitless and the numerator's unit is used, or the numerator and denominator must have compatible units and the result is unitless. Note that the only units conversions implemented are those among compatible units: dividing a length by a time to obtain a speed is not allowed; multiplying two lengths to get an area is not allowed. It is possible to specify the unit to use in an expression, and to remove it, so such calculations can be performed manually (they are rarely, if ever, needed).

Available Units
Group	Units
(unitless)	(no unit specified)
length	in, ft, yd, mile, mm, cm, m, micron, um, km, meter
speed	mps, fps, kmph, MPH, mph
angle	rad, deg, mr
time	sec, s, ms, us, shakes, ns, ps, min, hr
mass	g, kg, mg, ug
magnetic field	tesla, T, gauss, G, kilogauss, kG
voltage	volt, V, kV, MV
electric field	Vpm, MVpm, kVpm, Vpmm
density	gpcc
energy	MeV, eV, keV, GeV, TeV, joule, J, amu
charge	e, coulomb, uC, nC
current	a, ma, ka

(Note that 'u' is an abbreviation for "micro-", and "p" is an abbreviation for "per".)

There are a few places in the AnalyzePage where standard units must be used, because helper programs like Root do not understand unitsful quantities. When needed, the standard units are: mm, MeV, ns, rad, g.

Commands

The files that define MuSim objects (Simulation, SimObject, SimDef) are ASCII, and are organized into commands (lines). Each command has its own set of positional and named arguments, followed by an optional set of data lines. Command names all begin with '%', which uniquely distinguishes them from data lines in the simulation file. Most commands do not use data lines. Command or data lines longer that 4,000 characters (except inline images) may cause problems; lines can be continued by escaping the end-of-line with '\'.

Individual commands do very different things. Some specify solids that are placed into the simulated world; some specify electromagnetic fields in the simulated world; some define materials used by those solids; etc. Each command has its own set of arguments that vary the size, shape, composition, etc. of what the command does.

A list of commands is here.

Parameters

The files that define a simulation (Simulations, SimObjects, and SimDefs) can all have user-specified parameters. Each parameter has a name, a default value, and a synopsis (brief description).

In the commands that comprise an object (Simulation, SimObject, or SimDef), you insert the value of a parameter with "$name" -- this can be concatenated with other text on the left of the "$", but there must be a delimiter on the right (to terminate the name). The special case "${name}" is replaced by the value of parameter name, and can be concatenated on both sides with other text (e.g. a specific unit). Note that units are handled automatically in parameter expansion. You can insert an arithmetic expression involving constants and parameters like this "${$a+$b*100}" or this "${a+b*100}" -- here a and b are parameters; the braces are required and within them "$" is optional. Quoting does not affect $-expansion.

Parameters are almost essential when defining SimObjects. For a Simulation file they are useful to specify overall aspects (e.g. beam energy), and are needed if you want to perform optimizations or parameter scans.

Note that $ expansion is performed for both command lines and data lines.

Global Parameters

Global parameters are defined by the %global command. This is just like the %param command except it uses a namespace valid throughout the simulation (i.e. valid everywhere, including inside SimObjects and SimDefs).

While not required, we find it useful to distinguish global parameters from ordinary ones by beginning their names with "G_". The need for global parameters is not very common.

Arithmetic expressions

You can use an expression involving constants and parameters like this "${$a+$b*100}" or this "${a+b*100}" -- here a and b are parameters; the braces are required and within them "$" is optional. Note that units are handled automatically in expressions. The special case "${name}" is replaced by the value of parameter name, but can be concatenated on both sides with other text (e.g. a specific unit). Quoting does not affect $-expansion.

In rare cases, usually when dealing with a specific simulation program, you can also specify the format and units of an expression: "${format;expression;unit}" -- the semicolons are required unless format or unit is empty. Any printf format can be used as long as it is appropriate for a double value; the default is "%g". The value of the expression will be converted to unit, and the unit name is omitted. So "${1m;cm}" becomes "100"; "${%.3f;1m;cm}" becomes "100.000".

Arithmetic Expressions Here letters represent any expression (not just parameters); all values are doubles. For logical operations, fabs(x)<1E-12 is false and the converse is true.
a+b, a-b	The usual C binary operators. a and b must have compatible units; the result has the units of a.
a*b	The usual C * (multiplication). Either a or b must be unitless; the result has the units of the other.
a/b	The usual C / (division). Either b must be unitless and the result has the units of a, or a and b must have compatible units and the result is unitless.
a==b, a!=b, a<=b, a>=b, a<b, a>b	The usual C comparison operators. a and b must have compatible units; the result is either 0.0 or 1.0 (unitless).
a||b, a&&b	The usual C logical operators. a and b must be unitless; the result is either 0.0 or 1.0 (unitless).
+x, -x	The usual C unary operators. x can have any units.
x^v, pow(x,v)	Exponentiation (not XOR). x and v must be unitless. See note below.
(x)	The usual C parentheses. x can have any units.
sqrt(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), exp(x), sinh(x), cosh(x), tanh(x), log(x), log10(x), ceil(x), floor(x), abs(x), fabs(x)	The usual C functions. x must be unitless.
if(a,b,c), a?b:c	if(a) return b else return c. a must be unitless and b and c must have compatible units. See note below.
atan2(y,x)	The usual C atan2. x and y must have compatible units and the result is unitless. See note below.
min(a,b), max(a,b)	The usual C min and max. a and b must have compatible units, and the result has the units of a. See note below.

NOTE: multi-argument functions cannot have multi-argument functions in their arguments (i.e. expressions with commas cannot be nested). This does not apply to a?b:c or x^v (as neither uses a comma).
NOTE: as all values are doubles, the bitwise C operators are not supported.
NOTE: C operator precedence rules apply, except ^ (exponentiation) is highest.

Simulation Programs

Simulation programs actually perform the simulations. MuSim is specifically designed to support multiple simulation programs. Simulation Programs are configured in Preferences.

Before running a simulation program, MuSim creates a directory in which to run it, and populates the directory with necessary files. The directory for a simulation "SimName.sim" executed by the simulation program "G4beamline-2.17" will be of the form "SimName-date-time-G4beamline-2.17" -- date and time will be used to ensure uniqueness. For parameter scans (that involve multiple runs), ".001", ".002", etc will be appended to the time. The following files are created in the directory:

Filename	Description
simInput.txt	The input to the simulation program, it its own format.
SimName.sim	A copy of the simulation file.
ntuple.txt	A list of any NTuples to be generated.
parameters.txt	A list of the parameter values.
run.sh	A script to execute the simulation program.
source.g4bl	A G4beamline input file to generate all Source-s.

Running the simulation program consists of executing "run.sh" in the directory. This script will:

1. Run "G4beamline source.g4bl" to generate "source.txt" -- the file containing the source tracks.
2. Run translator asynchronously. This program will translate output files from the simulation program into the standard-format files.
3. Run the simulation program.
4. Tell translator to exit.

The following files will be created by run.sh:

Filename	Description
simOutput.txt	The combined stdout and stderr from run.sh. This includes the simulation program's stdout and stderr.
NTupleName.txt	The data from the NTuple "NTupleName". There can be zero or more of these.
AllTracks.txt	A trace file with data for every step of every track, in BLTrackFile format (which is ASCII).
source.txt	The output from the source run of G4beamline, read by the simulation program to create source tracks.

Note that AnalyzePage will use many of these files, and depends on their names and formats.

G4beamline [1]

G4beamline is a general-purpose particle simulation program that is a "Swiss Army Knife for Geant4 [3]." In addition to implementing common beamline elements such as quadrupole and bending magnets, G4beamline uses Geant4 to implement much of what is known about particle decays and interactions in matter. While it is intended for simulating beamlines, other systems are certainly possible (e.g. it has sources for both cosmic-rays and radioactive decay). Much of the inspiration for MuSim came from G4beamline.

G4beamline is always required to be installed and configured into MuSim, as it is used to generate all Sources.

G4beamline is supported by Muons, Inc., is open source, and is freely available at http://g4beamline.muonsinc.com.

The data file formats used by MuSim are compatible with those used by G4beamline. The translator program makes this possible for all simulation programs, regardless of their file formats.

MCNP [2]

MCNP is the simulation program of choice for simulating nuclear reactors and weapons in the U.S.A. It is a general-purpose particle simulation program that concentrates on low-energy neutrons and photons, but the most recent version (MCNP 6.1) supports other particles up to high energies. The primary impediment to using it is its arcane method of specifying geometry -- indeed its "user hostile" interface was a prime motivator for developing MuSim.

MCNP is written and supported by Los Alamos National Laboratory. It is export controlled, and U.S. users must obtain it directly from the Radiation Safety Information Computational Center (RSICC) at Oak Ridge National laboratory: https://rsicc.ornl.gov. Residents of other countries that are U.S. allies can probably obtain it via local authorities.

Note that you must add the MuSim SOURCE.F90 file into MCNP and build it. This subroutine reads an input file to generate source tracks.

The translator program converts MCNP's PTRAC file into AllTracks.txt, running in parallel with MCNP itself.

There is a special Calculator for MCNP called mcnpcalculator that reads the outp file for tally 6 and computes the total energy deposited in the world. Tally 6 is always added to the MCNP input file, configured to compute the total energy deposited in the entire world, for several time bins.

Libraries

Libraries are collections of SimObjects and SimDefs. Each library is a directory, and the directory name (without path) determines the library name. Libraries are configured in Preferences.

Objects in a library have names of the form LibraryName:ObjectName. The default library has a null name, so objects in it have names starting with ":".

Geometry

Coordinate Systems

These coordinate systems are used:

• Global Coordinates - Cartesian coordinates {X,Y,Z} that span the world.
• Beamline Coordinates - coordinates {U,V,S} that run down the nominal centerline of a beamline. Locally they are Cartesian, but the S axis gets bent by bending magnets and both U and V rotate with it.
• Local Coordinates - Cartesian coordinates {X,Y,Z} specific to each volume placed into the world.
  

In a very real sense, the global coordinates are the local coordinates of the world volume (which is always a rectangular parallelepiped oriented with the {X,Y,Z} axes).

The world volume always expands to include every element that is placed into it.

Global Coordinates

Global coordinates can always be used to place objects into the world; they are the local coordinates of the world volume. When generating the input file to a simulation program, global coordinates are always used (except for elements placed as children into other elements).

The world volume always expands to include every element that is placed into it.

Beamline Coordinates

Beamline coordinates run down the nominal centerline of a beamline. They are named {U,V,S}, with S along the beam centerline, U is nominally beam left, and V is nominally up (i.e. they are analogous to {X,Y,Z}). Defining and using beamline coordinates can greatly simplify the layout of a beamline or particle accelerator, and is required by some simulation programs (e.g. MAD-X).

Beamline coordinates are a strictly MuSim construct, and a simulation program will not normally see them or need to know about them. The exception is MAD-X, which can use only beamline coordinates (as that is inherent in the MAD-X design). In particular, the centerline coordinates of G4beamline are not used (they differ from MuSim's beamline coordinates).

The following commands create, modify, and use beamline coordinates:

Command	Description
%bcstart	Declares that Beamline Coordinates are to be used, and specifies the relationship between the origin of the beamline coordinates and the global coordinates. Can be used only in a Simulation (not a SimObject or Simdef).
%bcbend	Rotates the beamline coordinates through a specified angle around an arc of specified radius. The radius can be zero to give a sharp corner (e.g. for a secondary beamline coming off of a target).
%bcplace	Place a SimObject at a specified value of S in beamline coordinates. The origin of the SimObject's local coordinates will be placed at the specified value of S (with U=V=0), and it will be oriented so the local X,Y,Z axes are parallel to the U,V,S axes at that point.
%bcnext	Place a SimObject along the S axis immediately following the previous element placed via %bcplace or %bcnext. This is just like %bcplace, except the value of S used is obtained from the downstream end of the previous SimObject placed via %bcplace or %bcnext (or the beginning set by %bcstart).
%bcset_ds	Useful only in a SimObject: sets the length (dS) for this SimObject, overriding the usual calculation. Needed only when the standard calculation gets it wrong (rarely, if ever).
%bcsample	Defines a set of values of S for sampling tracks. These samples can be plotted, giving a profile of the beam.
%bcntupledisk	Defines one or more disks to be sampled into NTuples. Similar to %ntupledisk, except uses beamline coordinates to specify the location (the NTuple tracks always use the local coordinates of the disk). The disk is always normal to the S axis and centered on it.

Note that only SimObjects can be placed using beamline coordinates; those SimObjects can contain any geometry command(s). By making a SimObject for each magnet or beamline element, or a SimObject for a cell of an accelerator, this provides a simple and straightforward way to construct a beamline or accelerator hierarchically. By constructing SimObjects for the drifts, possibly including beam pipes, you can layout the entire beamline using %dcnext for each element or cell, analogous to how MAD-X does it.

Note that a SimObject can define a cell of an accelerator. It can include multiple magnets, detectors, these %bc-commands, etc. In the SimObject the elements can be placed using either local or beamline coordinates, and the latter can be modified via %bcbend. Within the SimObject, the S axis initially coincides with the local Z axis, with S=0 corresponding to Z=0; this should be the front (upstream end) of the SimObject (i.e. never place anything at negative values of S or Z). Such a SimObject can be put into the world using %bcplace or %bcnext. A SimObject that uses beamline coordinates internally can only be placed using %bcplace or %bcnext (because the other place commands do not preserve the beamline coordinates).

Local Coordinates

There is a set of local coordinates for every element (i.e. every solid and SimObject). They are {X,Y,Z} and are oriented appropriately for each solid or SimObject. Generally the beam axis is along Z, with X beam left and Y up. So, for example, the symmetry axis of a %cylinder is its local Z axis; ditto for %cone. For simulations without a beam, the meanings of the axes are arbitrary and are determined by the way the simulated world is laid out.

Normally the origin of local coordinates is at the center of the upstream end of the SimObject or solid. For some specific solids (e.g. %extrusion) the origin of X and Y need not be at the center.

Whenever a (child) solid is placed into another (parent solid), the parent's local coordinates are used to place the child volume, and any rotations are relative to the parent's local coordinate axes. Think of this as how you would naturally place an object into a room, with the room standing in for the parent. The origin of the child's local coordinates is placed at the specified value of the parent's {X,Y,Z}, and the child is rotated around its local origin. This also applies to placing solids or SimObjects into SimObjects. Remember that global coordinates are just the local coordinates of the world volume, so placing into the world is no different.

Coordinate Axes

Coordinate axes are drawn in the following colors. The S axis is used (and visible) only when Beamline Coordinates are present in the Simulation. The U and V axes are always invisible.

Axis	Color
X	Red
Y	Green
Z	Blue
S	White

The drawing of axes can be toggled on/off in the View menu and in the View Control window.

To see the {U,V,S} axes, there is a SimObject named "Examples:Axes" included in the Examples Library. It displays red, green, and blue lines aligned with its local X, Y, and Z axes. By using %dcplace or %dcnext to put it into the simulation, it will show the {U,V,S} axes visibly. You can also use %place to show the global (or local) axes. It contains no solids and does not affect the simulation.

Electromagnetic Fields

Electromagnetic fields are used to control and manipulate charged particle beams. They are implemented in very different ways in different simulation programs, and the MuSim commands that define them are basically hints for how to define them in each simulation program. Note that none of these include any volumes, solids, or materials, so they are generally used in a SimObject that packages them with the appropriate iron (etc.).

    G4beamline implements all of these fields.
    Mad-X implements only %quadrupole and %sbend.
    MCNP does not implement any of them.

%quadrupole	A quadrupole magnet, with fringe fields.
%rbend	A rectangular bending magnet, with fringe fields.
%sbend	A sector bending magnet, with fringe fields. Some simulation programs do not implement the fringe fields.
%solenoid	A solenoid magnet; its field extends to infinity in principle; in practice it is usually cut off at 0.01% of its maximum value.
%multipole	A magnet with multipoles up to 12, with fringe fields. Some simulation programs do not implement the fringe fields.
%lilens	A lithium lens, with fringe fields.
%pillbox	A pillbox RF cavity. Fields are constrained to its interior, with optional skin depth.
%fieldexpr_xyz	A field defined by expressions in Cartesian coordinates {x,y,z}.
%fieldexpr_rzp	A field defined by expressions in cylindrical coordinates {r,z,p} (p=\theta).
%fieldmap_xyz	A field defined by an external map file, in Cartesian coordinates {x,y,z}.
%fieldmap_rzp	A field defined by an external map file, in cylindrical coordinates {r,z,p} (p=\theta).

Note that in some cases electromagnetic fields can extend outside the world volume (usually fringe fields); this is not considered an error. Of course they will not be evaluated out there (tracks are killed whenever they leave the world volume).

Sources

MuSim provides a number of particle sources to generate the initial tracks for the simulation.

%beambunch	A single bunch of a particle beam.
%isotropicsource	An isotropic source. Used primarily for testing.
%sourcefile	A source that generates tracks by reading an external file. The file format is BLTrackFile, the ASCII format used by G4beamline [1].
%rdecaysource	A source that generates tracks by making radioactive isotopes decay. All isotopes in the geometry can be used, or just a subset. The user specifies a duration (usually < 1us), and the corresponding number of source tracks are generated, distributed throughout the world wherever radioactive isotopes decay. The required number of tracks can also be specified, and their weights will be adjusted accordingly.

Detectors

MuSim provides a number of detectors to generate output files from the simulation. The file format is Root [4].

%ntupledisk	Defines a disk for sampling all tracks that intersect it.
%ntupleshpere	Defines a sphere for sampling all tracks that intersect it.
%ntuplecreate	Generates an NTuple as each track is created (regardless of why it is created, so this includes source tracks).
%bcntupledisk	Defines a disk for sampling all tracks that intersect it. Like %ntupledisk except uses beamline coordiantes to define the position and orientation of the disk.

Calculators can also be used to compute output from simulations, in a format suitable for plotting in AnalyzePage.

Preferences

Preferences are persistent configuration options for MuSim. How they are saved is OS dependent (but automatic).

General

Value	Default
Icon size	48 (pixels)
Viewer background	black
Lines in a circle	36
Use beamline coordinates	1
Max # tracks to draw	100
Minimum length of drawn tracks	1mm
Directory of Root	$ROOTSYS
Path of last Simulation	(none)
Directory for Examples	(none)

Libraries
Each library has a path to its directory. Except for the default library they can also have a URL (signifying a remote library). The last entry is used by the Examples (when they are installed).

SimPrograms
Simulation programs have a name and a path to the executable file. (Ignore the deprecated SimDef field). The name must start with a known Simulation Program, "G4beamline" or "MCNP", and usually includes a version.

Calculators
Calculators are used in the analysis. They are specified by either absolute path, or path relative to the install directory (usual case). The Calculators that come with MuSim are pre-configured.

Element Names

An element is any item that can be inserted into the Geometry field of the EditPage. This includes: solids, electromagnetic fields, other geometry, sources, detectors, and SimObjects. Each of these can be given a name that will be passed to each simulation program (some of them use these names to identify error messages and particle traces).

Remember the distinction between the SimObject name and the element name: the SimObject name could be the (generic) type of a magnet (e.g. :BM109, Library:Type2Quad), while each placement of the SimObject is given an element name corresponding to its usage in the system (e.g. B2, Q12).

In many cases it is important to concatenate an element's name with its parent's name; this is indicated by starting the name with "+".
In many cases there will be multiple elements generated by the same command or SimObject; a "#" in the name will be replaced by a number that increments as it is used.

In most cases, the default element name for a solid like %box is "+.%box#", etc. This makes the default element names be hierarchical, separated by ".". The default element name for a SimObject named Library:Object is "+.Library:Object#". The World has an empty element name, and an initial "." is removed.

User Interface Components

A Window is a stand-alone rectangular region of the screen, with its own Close/Maximize/Minimize buttons; Windows can be moved independently around the screen with the mouse (via the operating system's window manager).
A Page is displayed on the right side of the MainWindow. A splitter separates it from the left side, which can be used to move the boundary between them.
A Panel is a subset of a Page displayed at the bottom. A splitter separates it from the page, which can be used to move the boundary between them.

Main Window

The Main Window is the primary (top-level) window of the MuSim application. Closing the Main Window will exit the application (if there are unsaved changes in the current object being edited, you will be prompted to save them).

The MuSim Main Window is shown below, with annotations in orange. In this particular simulation the %beambunch is shown as a semi-transparent yellow cone, the %cylinder is blue, and the %ntupledisk is a yellow circle seen edge on.

1. The Coin3D viewer showing the simulated world; it is a full-featured viewer with a friendly user interface.
2. A 3-element tab control that determines the overall mode of the program (and the user interface):
          Edit permits you to edit the simulation geometry and definitions (shown).
          Simulate permits you to run the simulation, including a scan of parameter values.
          Analyze permits you to create and display histograms and plots of simulation results.
3. The EditPage that does editing of the current simulation or object (tab B replaces it with SimulatePage or AnalyzePage).
   
4. The Library Panel that displays the SimObject-s and SimDef-s in the Library (appears only in EditPage).
5. The StatusBar, which transiently displays what is happening. Click it for history.
   

Note this screenshot was taken on Mac OS X, where the menubar is always at the top of the screen, separate from the application window. On Windows and Linux the menubar will be displayed as part of the window, and the visual look of the window will also vary in minor ways.

The small dot at the right center of the Coin3D viewer is a splitter control that can be dragged left/right to move the boundary between the viewer and the current page. The small dot just below the EditPage is a splitter that can be dragged up/down to move the boundary between the EditPage and the LibraryPanel.

The Coin3D Viewer

The Coin3D viewer is a full-featured viewer for 3-D scenes, implementing the Open Inventor interface. You can rotate and pan the image via the mouse, and can select individual objects and edit their properties.

Initially the viewer comes up in rotate/pan mode showing a top view of the entire world. Controls are located around its edges. Note that all rotating, panning, and zooming affect the camera, not the scene or objects being displayed.

In rotate/pan mode: leftclick-and-drag will rotate the display middleclick-and-drag will pan the display rightclick will bring up a context menu

In select mode: leftclick will select an object (EditPage on the right) Option-leftclick-and-drag will rotate the display Option-middleclick-and-drag will pan the display Option-rightclick will bring up a context menu

In both modes: Leftckick-and-drag on the wheels will rotate or zoom the display Leftclick on a control in the upper right or upper left will perform that action. The mouse scroll wheel will zoom in/out. Typing <Esc> will toggle between modes.

 
Dragging the Splitter Handle with the mouse will move the border between the Coin3D Viewer and the current Page.

The View menu also affects the viewer. It can select specific views (e.g. top or side view), toggle the axes, set the background color, make solid objects partially or fully transparent, and most importantly open a View Control window which can do all these things and more.

Rotating the display via leftclick-and-drag is different from the wheels at the lower left; the wheels rotate around the frame-fixed X- and Y-axes, while leftclick-and-drag rotates an imaginary sphere surrounding the image, centered at a point selected by the user (defaults to the visual center of the scene). If you release the mouse button while still dragging, the image will animate and continue the rotation until stopped (by a stationary leftclick in the viewer).

In the right-button context menu the most useful choices are in DrawStyles/StillDrawStyle -- as is draws solids as solid, while wireframe draws an outline; these two functions are available as controls at the upper left. There are many other choices which are rarely, if ever, used. Note the View menu can vary the transparency of all solids, and the View Control window has a slider for that (transparency is usually better than wireframe to look inside solids, as the latter adds lines which can be confusing).

In this particular simulation the %beambunch is represented by the semi-transparent yellow cone (you can see the Z-axis through it), the %cylinder is blue, and the %ntupledisk is a yellow circle seen edge on.

The Coin3D Viewer is normally very responsive to user input, but very complex scenes can slow it down. A scene with several thousand objects generally responds quickly to rotating and panning, but scenes with millions of objects bog down.

Edit Page

The EditPage is shown to the right.

This page is editing a Simulation, but pages for editing SimObjects and SimDefs are quite similar (accessed via the File menu, via buttons in other objects, or by double-clicking on them in the Library Panel). These are separate files, and when opening one of them, if the current object has unsaved changes you will be prompted to save it first. There is a single Simulation open at any given time, but a stack of SimObjects and SimDefs is maintained as they are edited -- their EditPages have buttons to "save and return" and "cancel and return". Opening a Simulation clears this edit stack and starts anew with the Simulation.

At the top are the current object's title, icon, and synopsis, as well as a button to view and edit its description; pushing this button displays the description in a separate window, with a button to edit it. Clicking on the icon or synopsis will edit them.

The name of the Simulation ("Example1") cannot be edited, as it comes from the name of the file containing the object, not from any data in the file. This means you can freely copy and rename files containing objects, and the name of the object will always be the same as its filename (without path or extension). The SaveAs button permits you to save it to a different file with a different filename.

In the EditPage for a Simulation there are four expandable blocks for editing groups of commands (for each, click on the title to expand or collapse the block, and click on the appropriate line or button to edit an existing command or add a new one):

• Parameter Definitions lists the parameters defined for this object, permitting you to edit their properties and add new parameters.
• General Definitions are commands that do not define geometry, such as %material commands, or commands that define custom input lines to specific simulation programs (%g4beamline and %mcnp).
• Global Geometry contains commands that define the geometry of the simulated world, using global coordinates. This includes solids, electromagnetic fields, other geometry, sources, detectors, and SimObject placements. Becomes "Local Geometry" for SimObjects.
  
• Beamline Coordinates and Geometry contains commands to define and use the Beamline Coordinates.

The EditPage can be reached by clicking on the Edit tab in the three-tab control above all pages. From other pages it can also be reached via the File/Edit menu item.

Library Panel

The Library Panel is shown to the right; it is located at the bottom of the EditPage. The small dot at the top center is a splitter control that can be dragged up or down to adjust how much screen space the LibraryPanel takes from the EditPage; it can go all the way down to zero.

This panel displays the icon and name of each SimObject and SimDef contained in all libraries. Remember that objects in a Library have names of the form LibraryName:ObjectName; in this case they are in the default library whose name is null.

Double-clicking on an object will edit it.

Insert Page

Clicking on a SimObject in the LibraryPanel brings up an Insert Page (shown to the right). At the top are the SimObject's name, icon, and synopsis. You can choose to always insert via global coordinates (X,Y,Z), or to use beamline coordinates (S) when they are available (if they aren't available, global coordinates are used).

You can specify the coordinate values by simply typing them in the appropriate fields (remember Units).
Click the Insert button to insert the SimObject at the specified coordinates.
Click the Edit SimObject button to edit the object. You can also double-click the object in the Library Panel.
Click Cancel to make no insertion and return.

After inserting, you are placed into an editor that permits you to edit the parameters of this particular placement of the object. This includes its coordinates, an optional rotation, and the parameters of the SimObject itself.

Drag-and-Drop from Library to World or SimObject

You can also drag-and-drop directly from the LibraryPanel into the Coin3D viewer. When your drag enters the viewer, the coordinate values in the Insert page will display their current values, changing as you drag. Releasing the mouse button will drop the SimObject at the current position, inserting it into the current object.

Note the choice of Global or Beamline coordinates greatly affects how drag-and-drop works:

• For Global Coordinates, the drop position is in the plane parallel to the viewer frame that intersects the origin of global coordinates (local coordinates when editing a SimObject).
  
• For Beamline Coordinates, the drop position is constrained to be on the beamline coordinate S axis. As you use the mouse to slide the SimObject along the S axis, the SimObject rotates appropriately so its local Z axis is always parallel to the beamline S axis at the current position. Note that if the S axis has a significant component in or out of the screen it will be difficult to control the position along S.
  

After dropping the SimObject in the viewer, you can edit its location and parameter values.

If you drop the object on the Insert Page, and beamline coordinates are being used, %bcnext will be used (i.e. the insert position immediately follows the last object placed using Beamline Coordinates). If you drop it anywhere else, the drop will be ignored (i.e. no insertion is performed). The status line of the Main Window displays the current situation as you drag the object around.

Edit Synopsis

Clicking on the synopsis in the EditPage will bring up a page to edit the synopsis. This is a short, single-sentence description of the simulation or object being edited. It is plain text.

Generate Icon

Clicking on the icon in the EditPage will bring up a page to generate the icon. You can adjust the viewer using the mouse, and then push the Refresh button to capture the viewer image into the icon displayed on this page. You can also set the icon from an image file. The reduction in size inherently means that detail will be lost (thin lines can disappear completely). The SaveAndGoBack button saves this icon to the object, but does not save the object to the disk; the CancelAndGoBack button retains the original icon (discarding any change you might have made).

As narrow lines usually do not show up in the icon, you can increase the lineWidth. This applies only for rendering the scene for the icon (in an off-screen buffer). Units are printer's points (1/72 inch), and the line width is always the width on the screen (so zooming in/out has no effect on a line's width, nor does rotating the view point). Note that Coin3D limits LineWidth to 256, Windows limits it to about 10, and Mac and Linux limit it to about 64.

View Description

The View/Edit Description button brings up a new window that displays the description of the current object being edited. You can move, resize, minimize, and close the window in the usual way; you can edit the description by pushing the Edit button.

The description can be either plain text or HTML, and the window senses which is used and displays it appropriately. In HTML mode, external links are opened in your default browser.

Edit Description

The description can be either plain text or HTML -- if the first character is '<' then it is HTML, otherwise it is plain text. Images can only be used if it is HTML (and most other HTML formatting can also be used). You may wrap HTML in <html>...</html> tags, but that is not necessary as long as the description begins with some HTML tag (e.g. <P>).

Note that external links in the HTML will be opened in the user's default browser; links to anchors in the description itself simply jump to them. This means that images must be inline with the text in order to be displayed as part of the description.

The Insert Inline Image button inserts an image file into the HTML as an image inline with the text; the image data are inside the tag as a data:URL. This can make the file rather large, so it's best to not use many big images. The button inserts at the current cursor position. The <img>tag is inserted with a newline at the end, so usually the image data just extends far to the right of the editing window (the newline has no effect on the rendered HTML, of course). It's generally best to adjust the image to be the size you want it (generally 400-500 pixels wide) before saving it to an image file or taking a screen shot; scaling images works but can yield unattractive images (unreadable fonts, missing lines, ...). If the image is large, you may want to insert a "width=500" item inside the <img...> tag; by inserting just width (no height), the aspect ratio of the image will be preserved. Of course other attributes can also be edited into the <img...> tag.

Parameter Definitions

Parameters are named text strings that can be used to vary the behavior of a Simulation or SimObject:

• For a Simulation, they can be set whenever the simulation is to be run; the SimulatePage can perform multiple runs scanning the value of a specified parameter, and you can associate a slider to selected parameters and easily vary them manually.
• For a SimObject or SimDef, parameter values can be set on the command that references them.

Note the default value does more than supply a value to be used when the parameter is not explicitly set: it also sets the Units which the parameter uses, and any value must have compatible units. So any parameter representing a unitsful value must have a default value with appropriate units.

Click on a parameter's row to edit it, or click on Add New Parameter to add a new one. Click on the Parameter Definitions header to collapse the section.

Parameters are a powerful way to make your simulations more general and useful.

Edit Parameter

The name of a parameter must consist of letters, numbers, and underscores ("_"); other characters are not allowed in the name. Names consisting of just numbers must not be used, as they will conflict with positional parameters (named "0", "1", "2", ...).

The default value specifies the Units for the parameter, and all values must have compatible units. Of course units are irrelevant for any value that is not a real number (parameters can hold names, etc. as well as numerical values with or without units).

The synopsis is a short description of what the parameter means or does.

General Definitions

Definitions are commands that have no geometry associated with them, such as %material, %include, and %global.

Click on an existing command's row to edit it, or select a new command to add. Click on the General Definitions header to collapse this section.

When parsing a simulation file, the definitions are handled before any geometry.

The list of available definition commands is here.

Global Geometry (Local Geometry)

Global geometry applies to Simulations, Local Geometry applies to SimObjects. This section is where the simulated world is specified (except for the geometry defined in Beamline Coordinates, if any).

Click on an existing command's row to edit it, or select a new command to add. Click on the Global Geometry header to collapse this section.

You can place any of these types of commands here, each of which places some object into the simulated world: Solids, Electromagnetic Fields, Sources, Detectors, SimObject Placements, Other Geometry.

Beamline Coordinates and Geometry

Beamline Coordinates are intended to make laying out a beamline or particle accelerator simple. You can make them bend inside bending magnets, etc. -- their S axis runs down the center of the beamline, and you can easily place SimObjects anywhere on the S axis (%bcplace). It is easy to place an object immediately after the previous one (%bcnext).

If a Simulation does not have Beamline Coordinates already configured, this section contains just a button to add them (puts you into an editor for the %bcstart command). If they are already configured, then this section looks just like the Global Geometry section, except the commands are for Beamline Coordinates, not global/local coordinates.

The list of available commands is here.

SimulatePage

The SimulatePage is shown to the right. It repeats the Simulation's name, icon, synopsis, and view-description button of the EditPage. There are six expandable blocks for controlling the execution of the simulation:

1. Parameter Values - displays and sets the values of parameters for the Simulation.
2. Select Simulation Program - selects a simulation program, and sets a few program-specific parameters.
3. Run Simulation - has a button to run the simulation once.
4. Parameter Scan - scans a paremeter via a list of values and/or a Fortran-like DO loop; can run multiple jobs in parallel (very useful if your system has multiple cores).
5. Sliders for parameters - displays sliders for selected parameters, and runs the simulation when they are changed. Sliders are defined by the %sliders command in General Definitions.
   
6. Event Display - permits the user to display events while the simulation is running. (The AnalyzePage can also display events.)
   

Parameter Values

This section displays the name, default value, and synopsis of each parameter for the Simulation, as well as its current value (blank if none). Click on a parameter's row to give it a specific value. Note: be sure to give it units compatible with the default value's units (if any). (The parameters for the simulation are defined in the Parameter Definitions block of the EditPage.)

Select Simulation Program

This section permits you to select which simulation program to run, and optionally to ignore syntax errors (not recommended). You can also select the number of events to trace - some Calculators require that all events be traced, and the Event Display can only display traced events. Unless you are running multiple millions of events, you should probably leave this at -1 (trace all events).

Run Simulation

Push the Run Simulation Program (once) button to start the simulation with the given parameter values. A new window will pop up displaying the output from the simulation program; while the program is running it has an Abort button to stop the simulation early (results will be lost); in some cases you may need to push the Abort button twice. A new directory is created to hold the running simulation program and its input and output files; it is created in the same directory as the Simulation's .sim file, and is named "SimulationName-date-time-SimProgramName.dir", where the individual items are replaced by their actual values (time is normally HHMM, but will be HHMMSS if necessary to make it unique). Most of the files placed into this directory have specific names so the AnalyzePage can find them.

Parameter Scan

To perform a scan of a parameter's value, first select the parameter name from the list. Note that all other parameters will retain the values given in the Parameter Values block on the SimulatePage, and the current value field here will give that value for the selected parameter.

You may enter a comma-separated list of values, and/or three values to control a Fortran-like DO loop (there is no default increment). As you type, the number of runs is updated so you can tell how many runs you are requesting. The seven runs of this example will set the parameter P to 100MeV, 150MeV, 180MeV, 200MeV, 220MeV, 240MeV, and 260MeV, in that order. Be sure to use appropriate units for all values.

Push the Start Runs button to create a directory for each run, and to display a the Multiple Runs Window that controls running them. A new directory is created to hold the running simulation program and its input and output files; it is created in the same directory as the Simulation's .sim file, and is named "SimulationName-date-time.nnn-SimProgramName.dir", where the individual items are replaced by their actual values (time is normally HHMM, but will be HHMMSS if necessary to make it unique); nnn is the sequence number in the parameter loop. Most of the files placed into this directory have specific names so the AnalyzePage can find them.

Note: the simulation runs are not yet started; use the Multiple Runs Window to start them, observe their progress, and abort them if necessary.

Multiple Runs Window

This window permits you to control multiple runs of a simulation program. It lets you choose how many instances to run in parallel (# Threads), displays the most recent output line from each, and provides an Abort All button to abort them all.

In this case, 16 threads were made available, but there are only five programs to run. If # Threads is set to 0, any currently-running programs will continue, but no new programs will be started until it is set > 0.

There is one row per program, which displays its most recent output line (blank if not yet started). Scroll bars will appear when necessary. Click on any row to show its complete output in a separate window (this does not affect the running program, nor does closing that window).

This screenshot was taken after all five programs had completed. Initially the "All Completed" text was a "Start" button, and while any programs were running it was an "Abort All" button.

Sliders for Parameters

This sections displays the sliders defined in the %sliders command (editable in General Definitions). In this example (Triplet.sim), two sliders are defined, for parameters QF and QD. To change the value of a parameter, you can either slide its slider with the mouse, or you can click in its edit field and type the new value. Note the units are fixed and given to the right (here Tpm for both).

When you release the mouse button on a slider, or when you type <CR> into an edit field, the Start Simulation and Display button will be pushed. You can also push it with the mouse or keyboard. This will start the simulation using the current values of all parameters, and also display the next set of events. The values of parameters without sliders are taken from the Parameter Values section above. In addition, the Main Window will be brought to the front after the simulation has started, so you can see the Event Display and the first set of events.

Multiple runs are placed into the same directory as the first one, and their outputs are all displayed sequentially in a single Program window. In the AnalyzePage this simulation entry will correspond to the last-run parameter values.

Event Display

The Event Display is one of MuSim's primary features, as it works completely independently of any simulation program, and thus works for all of them. It displays both the solids comprising the simulated world and the events. This section controls displaying the tracks of events in the Coin3D viewer. You can choose how many events to display at one time, and can set Particle Colors. By default, tracks are colored by their charge: negatives are red, neutrals are green, and positives are blue.

In the SimulatePage, while the simulation is Running, events are displayed only as they are available (i.e. pushing Display Next Set will clear the displayed events, but won't display a new event until it is ready). In the AnalyzePage, after the simulation is complete, events are displayed immediately (as soon as the button is pushed). Note, however, that very complex events can take some time to display.

The Display Set Size counts events (not tracks) - some simulation programs distinguish between events and tracks, some don't: for G4beamline and MCNP, an event corresponds to an initial (beam) track plus all of the secondaries it creates; for MAD-X, event and track mean the same thing. Note there are Preferences items that limit the number of tracks displayed per event, and set the minimum length of tracks to be displayed. Charged particles traveling through matter can create large numbers of very short (low-energy) electron tracks (aka "delta-rays").

To see tracks inside solids there are several options:

• Select Wireframe view from the viewer's context menu or the control at the upper left.
• Use the View menu to set the opacity of solids.
• Use the View menu to open the Viewer Control Window, which has a slider to set the opacity of solids.
• Use the Viewer Control Window to setup a Clip Plane. This clips away all solids to one side of the plane, but does not affect tracks.
  

When solids are 0%-50% opaque, tracks inside them can easily be seen, without the distracting extra lines of Wireframe view; that is generally easier to use than a clip plane.

Once one or more events is displayed, with the Coin3D Viewer in select mode (click on the Arrow icon at the upper right of the viewer), you can click on a track to display its parameters and hide any other displayed events. The right side of the Main Window will display the particle type and the track parameters at the step closest to where you clicked, and also when/where it was created. You can also put the viewer into rotate/pan mode (click on the hand icon at the upper right of the viewer), and then use the mouse to rotate, pan, and zoom the viewer. The wheels can rotate and zoom in either mode.

On some displays, tracks are thin and can be difficult to select with the mouse. You may need to be 1 pixel above or to the left of the track. On a Mac, Ctrl-ScrollWheel will normally zoom the physical display and make this easy.

Note that in the EditPage, selecting applies to solids (it cannot display events). In the SimulatePage or the AnalyzePage, when the event viewer is active, selecting applies to tracks.

Particle Colors

For the Event Display you can select the color of tracks for each individual particle type, for all of the common particle types (only about 1/3 of the particle types are shown at the right, use the scroll bar to access the others).

Colors are specified as in HTML: by an HTML color name, or by a "#RRGGBB" value that specifies red, green, and blue values as 2 hex digits (#000000=black, #FFFFFF=white, #FF0000=red, etc.). Solids also specify color this way.

HTML color names: AliceBlue, AntiqueWhite, Aqua, Aquamarine, Azure, Beige, Bisque, Black, BlanchedAlmond, Blue, BlueViolet, Brown, BurlyWood, CadetBlue, Chartreuse, Chocolate, Coral, CornflowerBlue, Cornsilk, Crimson, Cyan, DarkBlue, DarkCyan, DarkGoldenRod, DarkGray, DarkGreen, DarkKhaki, DarkMagenta, DarkOliveGreen, DarkOrange, DarkOrchid, DarkRed, DarkSalmon, DarkSeaGreen, DarkSlateBlue, DarkSlateGray, DarkTurquoise, DarkViolet, DeepPink, DeepSkyBlue, DimGray, DodgerBlue, FireBrick, FloralWhite, ForestGreen, Fuchsia, Gainsboro, GhostWhite, Gold, GoldenRod, Gray, Green, GreenYellow, HoneyDew, HotPink, IndianRed, Indigo, , Ivory, Khaki, Lavender, LavenderBlush, LawnGreen, LemonChiffon, LightBlue, LightCoral, LightCyan, LightGoldenRodYellow, LightGray, LightGreen, LightPink, LightSalmon, LightSeaGreen, LightSkyBlue, LightSlateGray, LightSteelBlue, LightYellow, Lime, LimeGreen, Linen, Magenta, Maroon, MediumAquaMarine, MediumBlue, MediumOrchid, MediumPurple, MediumSeaGreen, MediumSlateBlue, MediumSpringGreen, MediumTurquoise, MediumVioletRed, MidnightBlue, MintCream, MistyRose, Moccasin, NavajoWhite, Navy, OldLace, Olive, OliveDrab, Orange, OrangeRed, Orchid, PaleGoldenRod, PaleGreen, PaleTurquoise, PaleVioletRed, PapayaWhip, PeachPuff, Peru, Pink, Plum, PowderBlue, Purple, Red, RosyBrown, RoyalBlue, SaddleBrown, Salmon, SandyBrown, SeaGreen, SeaShell, Sienna, Silver, SkyBlue, SlateBlue, SlateGray, Snow, SpringGreen, SteelBlue, Tan, Teal, Thistle, Tomato, Turquoise, Violet, Wheat, White, WhiteSmoke, Yellow, YellowGreen.

By default, particles are colored by their charge: negatives are red, neutrals are green, and positives are blue.

AnalyzePage

The AnalyzePage replaces the viewer on the left with a list of available simulation runs, ordered by date-time, and listing their parameter values and calculators. These runs were generated by the Parameter Loop example above.

You can select one or more simulation rows with the mouse -- the choices available on the right depend on whether a single simulation is selected, or multiple simulations are selected.

Calculators

A calculator is a small, stand-alone program that runs in the directory of a simulation run to compute some specific results. Each has a specific list of input files, and generates a specific list of calculated values. These values can then be plotted.

NTuples

An NTuple is a list of tracks, typically ones that intersected a disk or other geometrical surface. They can be plotted and histogrammed. Each row of the NTuple contains the variables for one such track sample. Tracks that intersect the surface multiple times will have multiple rows in the NTuple. Note that unlike most places in MuSim, the units of variables in an NTuple are fixed (mm, MeV, ns). The variables in each row are:

Variable Name	Description
x, y, z	Position of the sampled track; mm.
Px, Py, Pz	Momentum of the sampled track; MeV/c.
t	Time of the sampled track; ns.
PDGid	Particle Data Group identifier of the particle.
EventID	Event number
TrackID	Track number (within the event)
ParentID	Track number of parent track (0 = no parent, source track)
Weight	Weight of the sampled track

Each NTuple is placed in a Root file named the same as the NTuple (extension is .root). Each simulation run directory can contain zero or more NTuple files. They are generated by the translator program that runs in parallel with the simulation program. Note that NTuples are created only for traced events.

Single Selection

When a single simulation run is selected, you can choose among the following:

1. Run Calculator - run a Calculator on this simulation run to compute quantities for plotting.
   
2. Plot Calculator Results - plot the results of already-run calculator(s).
   
3. Plot NTuples - plot variables in one or moer NTuples.
   
4. Display Mesh tallies - display the results of a mesh Tally (MCNP only).
   
5. Event Display - display events.
   
6. Combo Plot - combine multiple existing plots into a single plot frame.
7. Display File(s) - display ASCII files from this simulation run, in a separate window.
8. Delete Selected Simulation Run - delete this simulation run.

Multiple Selection

When multiple simulation runs are selected, you can choose among the following:

1. Run Calculator - run a Calculator on these simulation runs to compute quantities for plotting.
2. Plots - plot parameters and calculator results.
3. Delete selected simulation runs -- delete the selected simulation runs.
4. Combo Plot - combine multiple existing plots into a single plot frame.

Run Calculator

To run a calculator, you must first select the calculator to run. The section will display the appropriate information required to run it, including fields for you to enter options.

Each calculator has a list of required files; if any is missing, there will be no button to run it, but rather a notion "(Missing input files)".

The "Manual" calculator can always be run, because you need to do all the work. Here is an example manual shell script to count the number of errors in the simulation run. As you can see, this requires knowledge of the MuSim internal representation of simulation runs.

cd simulation-run-directory
N=`grep -i error simOutput.txt | wc -l`
echo Nerrors=$N >>Manual.calc.txt

After running this script in a simulation run's directory, the value "Nerrors" will be available for plotting.

Plot Calculator Results

This is for simulations using Beamline Coordinates. It permits you to plot the results of a calculator as a function of S (path length along the beamline). MORE TO COME...

Plot NTuples

A simulation run can contain zero or more NTuples. First select one, and its field names will be displayed. You can select to plot a 1D histogram, or a 2D plot or a 3D plot; corresponding input areas for X, Y, and Z will appear. For X, Y, Z, and Weight, enter an appropriate arithmetic expression using the field names, C operators, and C functions. This is interpreted by Root, not MuSim, so no "$" is used, and no units are allowed (units are implicitly mm, MeV, and ns). For Cut enter a logical expression -- it must be true to enter the NTuple row into the plot (empty is always true). You can select which particles will contribute to the plot, and can enter additional Root options (advanced usage).

Example1 happens to have a single NTuple named "NTuple".

Display Mesh tallies

Mesh tallies are available only for simulation runs using MCNP, via the %meshtally command. They display the energy deposited in the world using a rectangular mesh and pseudo-color to indicate intensity. Mesh tallies are displayed on the left, superimposed on a view of the simulated world; you probably need to set solid transparency to 30% or 0% to see the tally. The tally is displayed in a plane corresponding to the centers of the voxels being displayed; you can rotate, pan, and zoom the viewer to see where this plane is located relative to the objects in the world.

MuSim only supports rectangular meshes.

Plots

Plots permits you to plot the results of calculators vs parameter values, and vs each other. Each selected simulation run will generate one point in the graph. Only fields common to all selected runs are shown.

Example1 does not have much of interest, as the only numerical variables are P and nEvents.

Combo Plot

This section permits you to combine multiple existing plots into one, with common axes.

This example combines four NTuple Plots from Example1 (100MeV, 180MeV, 200MeV, 220MeV), after changing their colors and deleting their statistics blocks (which can be done either before creating the Combo Plot, or in the Combo Plot window itself).

Display File(s)

With a single simulation selected in the AnalyzePage, you can display individual files in a pop-up window by clicking on their name. You cannot edit them. Binary (non-text) files, such as *.root, will contain garbage. Simply close the window when done.

Delete Selected Simulation Run(s)

You can delete one or more simulation directories with this button. All files within each directory will be deleted. Confirmation is required before anytning is deleted. This cannot be undone.

Viewer Control Window

The Viewer Control Window provides additional control over the Coin3D Viewer. You can:

• View All - zoom the viewer to show all of the simulated world (preserves point-of-view).
• Select specific viewpoints (Top, Side, Front).
• Toggle the visibility of the axes.
• Refresh the viewer (almost never needed).
• Set the background color.
• Vary the opacity of all solids with a slider.
• Zoom in X and Y only (useful for beamlines that are much longer than they are wide).
• Control the Event Display.
• Select a Clip Plane (another way to view inside solids).
• Display using Beamline Coordinates - this will use the Beamline Coordinates to display, which effectively straightens out the beamline S axis. Does nothing if Beamline Coordinates are not being used.
  

Many of these controls are available in the view menu as well.

Help Window

The Help Window provides context-sensitive help to the user. It can be opened via the Help/Help menu item. As the user navigates throughout the MuSim user interface, the Help window follows along, providing assistance for the current item.

It is a full-featured web browser for this Users Guide. You can navigate within it via hyperlinks, and via the Back and Forward buttons. External links in the Users Guide will be opened in your default web browser (these appear only in the References section).

You can freeze the help window so it remains on its current page as you continue to navigate the MuSim user interface.

In the Help menu you can open this Users Guide in your default browser. That provides an independent view of the document, and can be used to print it (though the static page loses much of its utility).

Main Menu

The Main Menu is associated with the MuSim Main Window. On a Mac it appears at the top of the screen; on Windows and Linux it appears at the top of the Main Window.

• File - commands to open and save files.
• New Simulation - create a new (empty) Simulation.
  
• New SimObject - create a new (empty) SimObject.
  
• New SimDef - create a new (empty) SimDef.
  
• Open Simulation - open an existing Simulation (close the current one).
  
• Open SimObject - open an existing SimObject (add to the stack of edited objects).
  
• Open SimDef - open an existing SimDef (add to the stack of edited objects).
  
• Save - save the current object.
  
• SaveAs - save the current object in a new file with a new name (Simulation only).
  
• Examples - open a window displaying the available examples and their synopses.
  
• Edit - commands for editing files.
  
• Undo - permits you to undo recent edits. Saving the file clears the Undo stack.
  
• Redo - permits you to redo recently undone edits. Performing a new edit clears the Redo stack.
  
• View - commands to control the Coin3D Viewer.
  
• Viewer Control - opens the Viewer Control Window.
  
• Top View, Side View, Front View - selects the viewpoint.
  
• Toggle Axes - toggle the visibility of the axes.
  
• Set Background - set the backgrund color.
  
• Refresh - refresh the viewer (almost never needed).
  
• Solid Opacity 100%, 50%, 30%, 0%  - set solid opacity (so you can see inside them).
  
• View Solid - sholw solids as solid.
  
• View Wireframe - show solids as wireframes.
  
• Tools - Miscellaneous tools.
  
• P/KE and Bend Calculator - given P or KE computes the other, for any common particle type. Given B or R, computes the other.
  
• Root Console - a direct interface to the Root console (used in the AnalysisPage).
  
• Do Regression Tests - perform the set of regression tests to verify MuSim functionality.
• Cycle Main Window Size - cycles the size of the mani window among popular sizes; the Status Line displays the change.
  
• Debug - commands for debugging MuSim.
  
• Console Window - displays debug and status printouts.
• Draw markers - draws markers in the Viewer at specified positions, which can be entered in a dialog box or read from a file.
  
• ... - additional commands for debugging MuSim.
  
• Help - Help on using MuSim.
  
• Help - opens the Help Window to display context-sensitive help for MuSim.
  
• Show Help in Browser - displays this Users Guide in your default web browser. This is most useful for printing.
  

List of Commands

The source files for Simulations, SimObjects, and SimDefs consist of a sequence of commands. Each command has its own set of positional and named arguments, followed by an optional set of data lines. Command names all begin with '%', which uniquely distinguishes them from data lines in the simulation file.

This list is intended for reference.

With the Help Window open (menu Help/Help), the help window will follow your usage of the MuSim user interface, displaying help for the current item you have open. When you edit a command, it will show you the help for that specific command (etc.).

Object Description

These commands describe an object in a SimFile (Simulation, SimObject, and SimDef).

%synopsis

Sets the synopsis for a SimFile.

The only positional argument is the synopsis text (usually needs to be quoted).

%description

Sets the description for a SimFile.

This command has no arguments. The description follows as data lines. If the first character is < then it is interpreted as HTML; otherwise it is interpreted as plain text.

%icon

Sets the icon for a SimFile.

This command has no arguments.
Normally the image data follow the %icon command, encoded in Base64. Alternatively, a single line '@/path/to/file.png' will use that file. When the SimFile is saved, the image data will be written to the SimFile.

%param

Defines a parameter for a SimFile.

The syntax for this command is special: %param name='value' "synopsis"

Definitions

%global

Defines a global parameter (i.e. one valid throughout the simulation).

The syntax for this command is special: %global name='value' "synopsis"

%include

Includes a SimDef.

The only positional argument is the name of the SimDef.

%isotope

Defines a new isotope.

As all known isotopes are pre-defined from the NIST database, this command is rarely needed.

In addition to the individual isotopes (e.g. Li6, U235), materials are defined for all elements using the _laboratory_ abundances of their isotopes (except for Li and U they are the same as the natural abundances on earth). Pre-defined isotopes are specified by the chemical symbol followed by the number of nucleons (e.g. Li6, U235); the chemical symbol alone specifies the laboratory mixture of isotopes.

This command defines a material which is 100% the specified isotope.

Name	Default	Synopsis
name		Name of the isotope (required).
density	0.0gpcc	density of the isotope (required).
Z	1	Atomic number of the isotope (required).
A	1.007825amu	Atomic weight of the isotope (required).
note		Note about this isotope (e.g. solid or gas, temp, etc.).

%material

Defines a material.

A material is a weighted list of already-known materials (incl. isotopes) with a density. Note that all known isotopes are pre-defined from the NIST database. In addition, materials are defined for all elements using the _laboratory_ abundances of their isotopes (except for Li and U they are the same as the natural abundances on earth). Pre-defined isotopes are specified by the chemical symbol followed by the number of nucleons (e.g. Li6, U235); the chemical symbol alone specifies the laboratory mixture of isotopes.

This command requires additional positional arguments to specify the materials which are mixed into this material, and their fractions: 'material,fraction'. If fraction>0 it is atomic fraction, if fraction<0 it is mass fraction (all fractions must be the same type); their sum will be normalized to 1.0.

If density is not given, it will be computed from the densities of the components; this does not apply to chemical compounds, gases, or some liquids, so their density should always be given.

Name	Default	Synopsis
name		Name of the material (required).
density	0.0gpcc	density of the material (optional).
note		Note about this material (e.g. solid or gas, temp, etc.).
*		Additional arguments as needed.

%asciintuples

Sets the format for all Ntuples to ASCII.

By default, each ntuple is written to 'name.root', with a single TNtuple 'name'. This command makes each ntuple be written to 'name.txt' in BLTrackFile format.

NOTE: the Analyze tab cannot use ASCII ntuples, so this is most useful for tests.

%g4beamline

Generates a specific G4beamline command into the input file.

This command is ignored unless some version of G4beamline is the simulation program. Use with caution.

All lines with a given value of order are output together, in the order in which they were created.

Name	Default	Synopsis
order		An integer 0-100 specifying the order in which the line is to be output. Order   Usage 50         Define beamline elements 60         Place beamline elements
line		The line to be output.

%mcnp

Generates specific MCNP cards into the input file.

This command is ignored unless some version of MCNP is the simulation program. Use with caution.

This command is followed by any number of data lines which will be output.

All lines with a given value of order are output together, in the order in which they were created. Using any order other than order=50 is likely to result in an invalid input deck. For instance, adding either surfaces or cells will conflict with the MuSim assignment of IDs to them.

Name	Default	Synopsis
order		An integer 0-100 specifying the order in which the lines are to be output. Order   Usage 10         Message Block (program arguments) 20         Title Card 30         Cell Cards 39         Blank line (ends cell cards) 40         Surface cards 49         Blank line (ends surface cards) 50         Data cards 60         Material cards 70         MeshTally cards

%sliders

Defines the sliders to be used in the SimulatePage.

The Parameters defined for this Simulation are displayed, one per row, with edit fields for Minimum and Maximum. If either field is left blank, no slider will be used for this parameter. The units of each field must be compatible with the units of the parameter's default value.
The format of this command is:

%sliders ParamName=Minimum,Maximum ParamName=Minimum,Maximum ...

Note that "$ParameterName" must not be used in the value of any Maximum or Minimum, they must be constants (with units as appropriate).

Geometry

Geometry commands consist of all things that exist in the simulated world: Solids, Electromagnetic Fields, Other Geometry, Sources, Detectors, SimObject placements, and Beamline Coordinates.

Solids

Solids define a volume with a material, and its position and orientation within the object in which it appears.

%box

Implements a solid box. It is oriented with its local coordiantes, centered in x and y and extending from z=0 to z=length.

Name	Default	Synopsis
height	0.1m	Height along y.
width	0.1m	Width along x.
length	0.2m	length along z.
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
color	white	Color of the box.
material	Vacuum	Material of the box.
kill	0	Kill all tracks hitting the box, if nonzero.
name	+.%box#	The name of this object.

%cylinder

Implements a solid cylinder. It is centered in x and y, and extends from z=0 to z=length.

Name	Default	Synopsis
radius	0.1m	Radius of the cylinder.
length	0.2m	Length (along z) of the cylinder.
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
color	white	Color of the cylinder.
material	Vacuum	Material of the cylinder.
kill	0	Kill all tracks hitting the cylinder, if nonzero.
name	+.%cylinder#	The name of this object.

%cone

Implements a solid cone. Its axis is along the local z axis; the apex is at z=0 and the base is at z=length.

Name	Default	Synopsis
radius	0.1m	Base radius of the cone.
length	0.2m	Length (along z) of the cone.
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
color	white	Color of the cone.
material	Vacuum	Material of the cone.
kill	0	Kill all tracks hitting the cone, if nonzero.
name	+.%cone#	The name of this object.

%sphere

Implements a solid sphere. It is placed by its center, not its 'front'.

Name	Default	Synopsis
radius	0.1m	Radius of the sphere.
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
color	white	Color of the sphere.
material	Vacuum	Material of the sphere.
kill	0	Kill all tracks hitting the sphere, if nonzero.
name	+.%sphere#	The name of this object.

%tess

Implements a tessellated solid.

The vertices and faces follow as data lines, 'v 1m,2m,3m' is a vertex at x=1m, y=2m, z=3m (local coordinates, before applying x,y,z,rotation); 'f 0,1,2' is a triangular face using vertices 0,1,2; 'f 0,1,2,3' is a quadrangular face using vertices 0,1,2,3. Units must be specified for each vertex value. Every face must be planar.

Name	Default	Synopsis
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
color	white	Color of the tess.
material	Vacuum	Material of the tess.
kill	0	Kill all tracks hitting the tess, if nonzero.
name	+.%tess#	The name of this object.
labelVertices	0	iSet nonzero to label each vertex with its index.

%tube

Implements a cylindrical tube. Its axis is along z, extending from z=0 to z=length; it is centered in x and y.

Children of course are inside the walls of the tube, not its cental hole.

Name	Default	Synopsis
innerRadius	0.18m	The inner radius.
outerRadius	0.2m	The outer radius.
length	1m	The length.
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
color	white	Color of the tube.
material	Vacuum	Material of the tube.
kill	0	Kill all tracks hitting the tube, if nonzero.
name	+.%tube#	The name of this object.

%rtube

Implements a rectangular tube. Its axis is along z, extending from z=0 to z=length; it is centered in x and y.

Children of course are inside the walls of the tube, not its central hole.

Name	Default	Synopsis
innerWidth	0.18m	The inner width.
innerHeight	0.18m	The inner height.
outerWidth	0.2m	The outer width.
outerHeight	0.2m	The outer height.
length	1m	The length.
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
color	white	Color of the rtube.
material	Vacuum	Material of the rtube.
kill	0	Kill all tracks hitting the rtube, if nonzero.
name	+.%rtube#	The name of this object.

%extrusion

Implements extruding along z a polygon in x,y. Its upstream face is at z=0, and its downstream face is at z=length.

For some simulation programs the polygon in x-y is tessellated into triangles (e.g. MCNP); the interior sides may not be equal due to roundoff. So each interior side of each triangle is expanded by the 'heal' distance. As the extrusion solid is the union of all triangle prisms, this ensures the interior sides have no gap. But, of course, near the exterior vertices the solid is slightly wrong, by up to the 'heal' distance. This does not apply to simulation programs that do not tessellate the polygon (e.g. G4beamline), nor to the visual display. 'heal' may be set to 0.0.

Name	Default	Synopsis
length	1m	Length along z of the extrusion.
vertices		List of vertices in X,Y: '0m,0m;1m,1m;0m,1m;...'
scale1	1.0	Scale for polygon at upstream face.
scale2	1.0	Scale for polygon at downstream face.
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
color	white	Color of the extrusion.
material	Vacuum	Material of the extrusion.
kill	0	Kill all tracks hitting the extrusion, if nonzero.
name	+.%extrusion#	The name of this object.
heal	1um	Healing distance for interior faces.

%polycone

Implements a polycone. Its axis is along z, and the cone segments are all centered along z=0. It is placed by the point x=y=z=0, but unlike many other solids, can extend to negative values of the local z coordinates (by putting negative values into zs).

Note that zs, innerRadius, and outerRadius are comma-separated arrays, and must have the same number of entries. If innerRadius is omitted, it is filled with zeros.

Name	Default	Synopsis
zs		Comma-separated list of z values.
innerRadius		Comma-separated list of innerRadius values.
outerRadius		Comma-separated list of outerRadius values.
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
color	white	Color of the polycone.
material	Vacuum	Material of the polycone.
kill	0	Kill all tracks hitting the polycone, if nonzero.
name	+.%polycone#	The name of this object.

%sbendiron

The iron of a sector bending magnet.

Name	Default	Synopsis
angle	30deg	Angle of the sector bend.
centerRadius	2m	Center radius of the sector bend.
apertureWidth	.5m	Width of the aperture (upstream face).
apertureHeight	0.2m	Height of the aperture (upstream face).
ironWidth	1m	Width of the iron (upstream face).
ironHeight	0.7m	Height of the iron (upstream face).
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
color	white	Color of the iron.
material	Vacuum	Material of the iron.
kill	0	Kill all tracks hitting the iron, if nonzero.
name	+.%sbendiron#	The name of this object.

Electromagnetic Fields

Electromagnetic fields are primarily for defining beamline elements.

%quadrupole

The field of a quadrupole magnet.

Name	Default	Synopsis
length	1m	Length of the field.
radius	0.1m	Radius of the field.
gradient	1Tpm	Quadrupole gradient.
fringe		Fringe-field parameters (optional).
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
name	+.%quadrupole#	The name of this object.

%rbend

The field of a rectangular bending magnet.

Name	Default	Synopsis
length	1m	Length of the field.
width	1m	Width of the field.
height	0.5m	Height of the field.
By	1T	Dipole field.
fringe		Fringe-field parameters (optional).
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
name	+.%rbend#	The name of this object.

%sbend

The field of a sector bending magnet.

Name	Default	Synopsis
angle	30deg	Angle of the sector bend.
centerRadius	2m	Center radius of the sector bend.
width	1m	Width of the field (upstream face).
height	0.5m	Height of the field (upstream face).
By	1T	Dipole field.
fringe		Fringe-field parameters (optional).
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
name	+.%sbend#	The name of this object.

%solenoid

The field of a solenoid magnet.

Name	Default	Synopsis
length	1m	Length of the field.
radius	0.1m	Radius of the field.
maxField	1T	Maximum field at the center of the solenoid.
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
name	+.%solenoid#	The name of this object.

%multipole

The field of a multipole magnet.

Name	Default	Synopsis
length	1m	Length of the field.
radius	0.1m	Radius of the field.
dipole	1.0T	Dipole field (T).
quadrupole	1.0Tpm	Quadrupole field (T/m).
sextupole	1.0	Sextupole field (T/m^2).
octopole	1.0	Octopole field (T/m^3).
decapole	1.0	Decapole field (T/m^4).
dodecapole	1.0	Dodecapole field (T/m^5).
fringe		Fringe-field parameters (optional).
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).
name	+.%multipole#	The name of this object.

%lilens

The field of a Lithium lens.

Name	Default	Synopsis
length	1m	Length of the field.
radius	0.1m	Radius of the field.
current	1.0A	Current generating the field.

%pillbox

%fieldexpr_xyz

%fieldexpr_rzp

%fieldmap_xyz

%fieldmap_rzp

Sources

Sources generate particles for the simulation.

%beambunch

Generates one Gaussian bunch of a bunched beam.

Tracks are generated around the origin with the bunch moving nominally in the +z direction, and are then transformed by {x,y,z,rotation}. Note that t and z are generated independently, so normally one of sigmaT or sigmaZ is zero; both can be zero (though that is unrealistic).

If any sigma is negative, a uniform distribution is used with halfWidth=|sigma|.

Name	Default	Synopsis
particle	mu+	Particle of the bunch (name or PDGid).
first	-1	First event number of the bunch (-1 => next).
nEvents	1	Number of tracks in the bunch.
meanT	0ns	Mean time of the bunch.
sigmaT	0ns	Sigma in time of the bunch. If negative, a uniform distribution is used with halfWidth=|sigma|.
meanP	200MeV	Mean momentum of the bunch.
sigmaP	0MeV	Sigma in momentum of the bunch. If negative, a uniform distribution is used with halfWidth=|sigma|.
sigmaX	0m	Sigma in x of the bunch. If negative, a uniform distribution is used with halfWidth=|sigma|.
sigmaY	0m	Sigma in x of the bunch. If negative, a uniform distribution is used with halfWidth=|sigma|.
sigmaZ	0m	Sigma in z of the bunch. If negative, a uniform distribution is used with halfWidth=|sigma|.
sigmaXp	0	Sigma in Xp (dx/dz) of the bunch. If negative, a uniform distribution is used with halfWidth=|sigma|.
sigmaYp	0	Sigma in Yp (dy/dz) of the bunch. If negative, a uniform distribution is used with halfWidth=|sigma|.
maxR	0m	Maximum radius in x-y plane of any particle (6 sigma if 0).
weight	1.0	Weight of each beam track.
x	0m	X position (mean of the bunch).
y	0m	Y position (mean of the bunch).
z	0m	Z position (mean of the bunch).
rotation		Rotation (e.g. X90,Y45).

%isotropicsource

Generates particles isotropically from a point.

If any sigma is negative, a uniform distribution is used with halfWidth=|sigma|.

Name	Default	Synopsis
particle	mu+	Particle of the bunch (name or PDGid).
first	-1	First event number of the bunch (-1 => next).
nEvents	1	Number of tracks to generate.
meanT	0ns	Mean time of the particles.
sigmaT	0ns	Sigma in time of the particles.
meanP	200MeV	Mean momentum of the particles.
sigmaP	0MeV	Sigma in momentum of the particles.
weight	1.0	Weight of each beam track.
x	0m	X position of point source.
y	0m	Y position of point source.
z	0m	Z position of point source.

%sourcefile

Reads a file to generate source events.

Tracks are read from the file in the local coordinates of its %ntuple sample disk; {x,y,z,rotation} specify how those local coordinates are transformed into the coordinates of the current simulation. The file must be a .root file with a TNtuple of the same name (i.e. the same as the %ntuple command writes).

Name	Default	Synopsis
file		Input file name.
x	0m	X position.
y	0m	Y position.
z	0m	Z position.
rotation		Rotation (e.g. X90,Y45).

%rdecaysource

Generates events from radioactive decay.

Scans the world for radioactive isotopes. If the isotopes argument is set, only those are used, otherwise all unstable isotopes are used. Unstable isotopes are decayed in place, wherever they appear in the geometry.

The argument 'duration' specifies over what time interval (from t=0) generation will take place. The weighted sum of all generated tracks will be appropriate for the radioactive decay of the unstable nuclei in the world over that duration.

this source generates all ordinary particles that are produced within duration of t=0. Unstable nuclei with lifetimes < 1us have their kinetic energy saved, set to 0, and then are tracked so they decay. Stable nuclei, and unstable nuclei with lifetime >= 1us are output and killed, adding any saved KE. This makes the approximation that no unstable nucleus moves significantly, but the energy deposited by ions is preserved, including its time dependence (within 1us).

This source generates the appropriate weighted number of events for duration; if nEvents is not set, they will have weight=1; if nEvents is set, that many events will be generated with weight set appropriately; duration and nEvents apply to the first radioactive decay, but not to subsequent decays in the chain.

Name	Default	Synopsis
isotopes		List of isotopes to decay (comma separated, default=all).
duration	1us	Duration over whch to decay isotopes.
nEvents	0	Number of events to generate.
first	-1	First event number to generate (-1 => next).

Detectors

Detectors sample particle tracks in the simulation and write them to an NTuple. In all cases except %meshtally the NTuple is a file in Root [4] format consisting of the NTuple in the top directory of the file.

%ntupledisk

Defines a sampling disk for an ntuple beam.

By default, only tracks intersecting the disk and moving in the local +z direction will be included; bothDirections=1 means tracks moving in both directions will be included. Tracks are written to the file using the local coordinates of the sample disk, in root TNtuple format. Tracks that intersect the disk multiple times will get multiple entries in the TNtuple. In most cases it is appropriate to ensure that tracks are killed shortly after intersecting the ntuple disk, either by leaving the world or hitting a solid with kill=1. Note the actual writing of the file occurs in the auxiliary program 'translator', which reads the track-trace file while the simulation is running.

Name	Default	Synopsis
name	+.ntuple#	Name of the ntuple (file=name.root).
radius	0m	Radius of the disk.
bothDirections	0	Non-zero to include tracks in both directions.
x	0m	X position of the disk center.
y	0m	Y position of the disk center.
z	0m	Z position of the disk center.
rotation		Rotation of the disk (e.g. X90,Y45).

%ntuplesphere

Defines a sampling sphere for an ntuple beam.

Tracks intersecting the sphere and moving in the correct direction will be included. If you want both directions, use two %ntuplesphere-s. Tracks are written to the file using the local coordinates of the sphere, in root TNtuple format. Tracks that intersect the disk multiple times will get multiple entries in the TNtuple. In most cases it is appropriate to ensure that tracks are killed shortly after intersecting the ntuple sphere, either by leaving the world or hitting a solid with kill=1. Note the actual writing of the file occurs in the auxiliary program 'translator', which reads the track-trace file while the simulation is running.

Name	Default	Synopsis
name	+.ntuple#	Name of the ntuple (file=name.root).
radius	0m	Radius of the sphere.
direction	outgoing	Must be incoming or outgoing.
x	0m	X position of the sphere center.
y	0m	Y position of the sphere center.
z	0m	Z position of the sphere center.
rotation		Rotation of the local coordinates (e.g. X90,Y45).

%ntuplecreate

Generates an Ntuple for each track as it is created.

%meshtally

Generates a mesh tally for energy deposit.

Currently supported only in MCNP.

If tbins is non-empty, each time bin will create a new meshtally, adding 10 to the tally number for subsequent bins.

Name	Default	Synopsis
tally	3	Tally number (must end in 3)
Xmin	-1m	Minimum in X.
Xmax	1m	Maximum in X.
nX	10	Number of mesh bins in X.
Ymin	-1m	Minimum in Y.
Ymax	1m	Maximum in Y.
nY	10	Number of mesh bins in Y.
Zmin	-1m	Minimum in Z.
Zmax	1m	Maximum in Z.
nZ	10	Number of mesh bins in Z.
tbins		Comma-separated list of bin edges in time.

%bcntupledisk

Defines a sampling disk for an ntuple beam.

Just like %ntupledisk, except uses Beamline Coordinates.

Name	Default	Synopsis
name	+.ntuple#	Name of the ntuple (file=name.root).
radius	0m	Radius of the disk.
bothDirections	0	Non-zero to include tracks in both directions.
s	0m	S position of the disk center.

SimObject Placement

SimObject-s can be placed into a Simulation or into another SimObject. Placement includes specifying position and orientation in the local coordinates of the object in which it is placed. SimObject placements can be nested up to 32 levels deep.

%place

Places a SimObject into the current SimObject/Simulation.

Name	Default	Synopsis
1		SimObject to place.
x	0.0m	X position.
y	0.0m	Y position.
z	0.0m	Z position.
rotation		Rotation (e.g. X90,Y90).
*		Any arguments to the SimObject.

%multiplace

Places multiple copies of a SimObject into the current SimObject/Simulation.

Generates loops in i,j,k; use @i,@j,@k in any other argument value. i,j,k hold double values with or without units, and can contain comma-separated lists and colon-separated loops, like 'i=1,2,3:8:1,9' => 1,2,3,4,5,6,7,8,9. Units must be specified for unitsful quantities (including loops). It is often easiest to use integers for i,j,k, and multiply @i by an appropriate unitsful value in an expression (inside '${...}').

Name	Default	Synopsis
1		SimObject to place.
i	0	First (outermost) loop variable.
j	0	Second loop variable.
k	0	Third (innermost) loop variable.
x	0.0m	X position (expressions can use @i,@j,@k).
y	0.0m	Y position (expressions can use @i,@j,@k).
z	0.0m	Z position (expressions can use @i,@j,@k).
rotation		Rotation (e.g. 'X90,Y90'); can use @i, @j, @k.
*		Any arguments to the %place command (including the SimObject); expressions can use @i,@j,@k.

Other Geometry

Other geometry items appear in the viewer, but do not have any physical volume and are not sent to any simulation program.

%label

A text label that always faces the camera.

Name	Default	Synopsis
text	Label	The text to display.
x	0.0m	X position.
y	0.0m	Y position.
z	0.0m	Z position.
color	white	Color of the text.

%marker

A set of markers that always face the camera (small geometric symbols).

The marker positions are contained in the data lines and/or the file, one vertex per line: '1m,2m,3m' is a vertex with x=1m, y=2m, z=3m; commas or blanks can separate components, and extra values are ignored. Global coordinates are always used. If units are not given for each value, the value of the unit argument will be used. This means the file can be in BLTrackFile format (though a large number of events can make the display very confusing).

Name	Default	Synopsis
color	white	Color of the marker.
id	0	ID of the marker symbol.
file		filename to read for vertices.
unit	mm	Default unit if none is given.

%polyline

Implements a line connecting multiple points.

The vertices are contained in the data lines, one vertex per line: '1m,2m,3m' is a vertex with x=1m, y=2m, z=3m; commas or spaces can separate the values. Units must be given for each vertex value.

lineWidth is a unitless float representing the width of the line in printer's points (1/72 inch); this is always the width on the screen, so zooming in/out has no effect on a line's width, nor does rotating the view point. Note that Coin3D limits LineWidth to 256, Windows limits it to about 10, and Mac and Linux limit it to about 64. lineWidth=2.0 is a reasonable value; thinner lines can be hard to see.

Name	Default	Synopsis
color	white	Color of the polyline.
style	solid	solid, dotted, or dashed.
lineWidth	2.0	Line width in points.
name	+.%polyline#	The name of this object.

Beamline Coordinates

Beamline Coordinates commands define and use the Beamline Coordinates of a simulation.

%bcstart

Starts Beamline Coordinates.

Name	Default	Synopsis
s	0.0m	The initial value of s.
x	0.0m	X position.
y	0.0m	Y position.
z	0.0m	Z position.
rotation		Rotation (e.g. X90,Y90).

%bcbend

Specifies a bend in the Beamline Coordinates.

Name	Default	Synopsis
s	0.0m	Value of s at the start of the bend.
angle	0.0deg	The angle of the bend in the u-s plane.
radius	0.0m	The radius of the bend (can be 0m).
phi	0.0	Rotation of bend axis around the current s axis.

%bcplace

Places a SimObject using Beamline Coordinates.

Name	Default	Synopsis
1		Name of the SimObject to place
s	0.0m	Value of s corresponding to SimObject's local z=0.
*		Any arguments to the SimObject.

%bcnext

Places a SimObject sequentially in Beamline Coordinates.

Name	Default	Synopsis
1		Name of the SimObject to place
*		Any arguments to the SimObject.

%bcset_ds

Sets the value of deltaS.

deltaS is the length of this SimObject along the S axis. Normally it is computed correctly from the contents of the SimObject, but this can be used in cases where that gives an incorrect value.

Name	Default	Synopsis
1	-1.0	The value of deltaS for this SimObject.

%bcsample

Defines one or more values of s for sampling.

NOTE: the value of s is rounded to the nearest millimeter, and duplicates are removed. The value of s becomes part of the names of variables computed by Calculators.

If the positional argument is s1:s2:ds, a FORTRAN-like for loop is used to create multiple values of s for sampling; s1 and s2 must have units, but are rounded to millimeters and the loop is executed using integers.

Name	Default	Synopsis
1	0m	Value of s for sampling, or s1:s2:ds loop.
*	0m	(More positional arguments, same as above.)
radiusCut	100.0mm	Transverse radius cut.

%bcntupledisk

This command defines a detector that samples the beam at a given value of s.

It is described here with the other Detectors.

Examples

Examples can be accessed via the File menu. The first time they are used you will be prompted for a directory in which to install them. After they are installed, a window will open that lists the example simulations -- click on one to see its full description and a button to open it in MuSim..

Regression Tests

The regression tests can be run via the Tools menu. Many of them test all configured simulation programs.

File Formats

Acknowledgments

It is a pleasure to acknowledge the other teams that have made MuSim possible.

The Qt team, led by Trollltech, Inc., has done an outstanding job of designing and developing a versatile and comprehensive C⁺⁺ toolkit.

The Coin3D team has done an outstanding job in developing an Open Inventor compatible 3D graphical viewer, and integrating it into Qt.

The G4beamline team has contributed to the success of MuSim, and G4beamline has become integrated into MuSim in several ways, in addition to serving as an important simulation program.

The MCNP team has contributed to the success of MuSim, and it is an important simulation program.

References

[1] G4beamline: http://g4beamline.muonsinc.com.

[2] MCNP: https://mcnp.lanl.gov.

[3] Geant4: http://geant4.cern.ch.

[4] Root: http://root.cern.ch.

Appendix 1. Installation on Mac OS X

Appendix 2. Installation on Linux

Appendix 3. Installation on Windows

Appendix 4. Command-line Usage

Appendix 5. Calculator Interface

Appendix 6. NTuple Interface