G4beamlineOld         A "Swiss Army Knife" for Geant4, optimized for simulating beamlines.
Getting StartedDocumentationDownloadSupportExampleForumDoxygenNew Feature Requests

G4beamline is a particle tracking simulation program based on Geant4(external link). It is optimized for simulating beamlines, and is especially useful for muon facilities in which decays and/or interactions with matter are important. It can also simulate systems not organized as a beamline, and has a cosmic-ray "beam". G4beamline is an open-source program distributed for Linux, Mac OS X, and Windows; it can also be built from source.


G4beamline is designed to be very user friendly:
  • No C++ programming is required to use it.
  • The system and simulation are described in a single ASCII file
  • The system description uses a self-describing language which can be easily understood by anyone familiar with beamline simulations.
  • Advanced visualization capabilities are available out-of-the-box.
  • Plots and histograms are easily generated using G4beamline commands to write NTuples, and external programs to plot them, such as HistoRoot, Root(external link), and Gnuplot(external link).
  • All common beamline elements are implemented, such as dipole and quadrupole magnets, RF cavities, absorbers and targets, etc.
G4beamline is designed to be versatile and flexible:
  • General objects are implemented, such as boxes, cylinders, polycones and extruded polygons.
  • The NIST database of common materials is implemented; users can also define their own materials.
  • Electromagnetic fields generated by different elements can overlap without restriction, including fringe fields.
  • Objects can easily be placed along the centerline of a beamline, with or without offsets; they can also be placed anywhere within the simulated world without restrictions other than the obvious inability of two objects to occupy the same place.
  • Users can add their own components, using combinations of geometric shapes with different materials, plus electromagnetic fields specified by equations or field maps.
  • Users can add their own C++ code to implement more complex objects (requires building from source).
G4beamline is designed to permit highly realistic simulations:
  • The full power and accuracy of Geant4 can be used.
  • Any Geant4 physics list can be used.
  • Additional collective computations are implemented, such as space charge.
  • While generic components are available, users can implement specific beamline elements in considerable detail.
  • A document describing the physics validation of G4beamline is available here(external link).
G4beamline is used by many accelerator physicists
  • Over 200 people have used it, making it one of the more popular accelerator simulation codes.
  • G4beamline has become one of the primary tools of the Muon Accelerator Program(external link).
  • The range of systems modeled by users is very diverse:
    • The MICE beamline and cooling channel at RAL
    • Muon cooling in a Helical Cooling Channel
    • Muon cooling in a Guggenheim cooling channel
    • Muon cooling in an Epicyclic PIC cooling channel
    • Muon production, capture, and phase rotation in the front end of a neutrino factory or muon collider
    • Neutrino production in several versions of a neutrino factory
    • Neutrino backgrounds and radiation in a muon collider.
    • Muon beam manipulations for several Fermilab experiments, including Mu2E and g-2
    • A large number of speculative muon generation or cooling schemes, including an inverse cyclotron, a particle refrigerator, dipole plus wedge cooling and capture, etc.; its ease of use makes it particularly well suited for quick simulations of "out of the box" ideas
    • Models of CEBAF experimental halls at Jefferson Lab
    • Potential anti-proton experiment(s) at Fermilab
    • Narrowband gamma generation via e+ e- annihilation
    • Cosmic-ray tomography of transportation containers for national security
    • And many more...
Binary distributions are available for:
  • Linux(Scientific Linux 4.X and later)
  • Mac OS X (Snow Leopard and Lion)
  • Windows (Xp, Vista, and 7)
G4beamline can be built from source:
  • To run on other systems
  • To add user code
  • To improve performance via system-specific optmization
G4beamline is open source and is freely available for download (below).


G4beamline is a single-particle tracking program based on the Geant4(external link) simulation toolkit. It is specifically designed for the simulation of beamlines.

The key aspect of g4beamline is that the input file defining the simulation is not significantly more complicated than the problem being simulated (by contrast, any C++ simulation program will inherently be significantly more complicated than the problem) — G4beamline isolates the user from programming complexities. To make this possible, g4beamline does not give the user all of the power and flexibility of the underlying Geant4 toolkit; it does, however, provide enough flexibility to simulate many different systems that can be considered "beamlines" one way or another. For instance, there is a "cosmic-ray beam", and the notion of "beamline" is rather flexible. In use, one normally just lays out the beamline elements along the beam centerline, using "centerline coordinates" that rotate appropriately whenever needed (e.g. when a bending magnet is placed, or at a target to take a secondary beam off at an angle).

Note that no programming at all is required to simulate systems that use beamline elements already in g4beamline's repertoire. This includes bending magnets, quadrupoles, solenoids, materials of all types in the shape of boxes, cylinders, tubes, spheres, and polycones, pillbox RF cavities, and a few specialized elements for muon cooling. The distribution includes an executable program that runs on Windows Xp, Mac OS X (Intel), or on most modern versions of Linux (it has been tested to run on all RedHat-drived distributions since 7.1, including Fedora Core 1-8). Moreover, the visualization capabilities of Geant4 are available with no further effort, including visualization using OpenInventor, OpenGL, HepRep, DAWN, VRML, and other viewers (as long as your system supports X-windows with the GLX extension). The internal design of the program makes it relatively simple to add new commands and beamline elements to its repertoire (this does, however, require C++ programming).

A major limitation of g4beamline is that at present it does not simulate the performance of real-world detectors. It implements "virtual" detectors which sample the tracks that intersect them with the precision of a float, and measure all tracking variables (X,Y,Z,Px,Py,Pz,t,PDGid). Each virtualdetector generates an NTuple in the output file, which can be histogrammed with the appropriate program. NTuples can be written to Root or ASCII files, and the historoot program is included to make it easy o generate plots using Root. So g4beamline will tell you where the particles go, but won't give details of real-world detector outputs.

Another limitation of g4beamline is that at present it does not implement parameterized placements of volumes. These are required for a practical implementation of the many segments of modern detectors.

Please join and use our G4beamline forum. You can self-register using the LOGIN module at the left (valid email required), and immediately start posting to the forum.

Getting Started

G4beamline is distributed as a tarball for Linux/Intel, as standard installers for Windows and for Mac OS/Intel, all available here. More details are contained in the G4beamline User's Guide(external link), and in the README-*.txt files in the distributions.

Linux (Intel)

If you intend to install and run G4beamline on your Linux desktop, and it is already running either KDE or Gnome (or a similar X Windows desktop), and the OpenGL and Motif extensions are already installed on your system, then this Quick Start Guide is for you. If you are doing something more complicated (e.g. you have a Windows desktop and use Exceed to connect to a Linux server), then this may help, but you'll probably need to read README-Linux.txt. These instructions assume you are using the bash shell; for other shells modify them accordingly.

  • Download the G4beamline tarball from here - get the latest one available, these instructions assume it is named g4beamline-VERSION.tgz.
  • Unpack the tarball in your $HOME directory:
                tar -xzf g4beamline-VERSION.tgz
  • This creates a directory g4beamline-VERSION; cd there and run setup:
                cd g4beamline-VERSION
The setup script will assist you in adding the G4beamline programs into a directory in your PATH. It will also create icons on your desktop to run G4beamline and Historoot.
  • Try the interactive help:
                g4bl -
                ---- configuration information ----
                cmd: help
                ---- list of commands ----
                cmd: help beam
                ---- detailed description of the beam command ----
                cmd: ^C
  • Now move to the test directory and run the tests:
                cd $HOME/g4beamline-VERSION/tests
This takes 5-10 minutes to run more than 70 tests. the output should end with "All Tests Passed".
  • Now move to the examples directory and look at the examples; try the following:
                cd $HOME/g4beamline-VERSION/examples
                # first visualize the system
                g4bl example1.in viewer=best
                # (play with the viewer, then ^C)
                # then generate NTuples for histogramming
                g4bl example1.in
                # and histogram the NTuples
                historoot g4beamline.root
                # (play with HistoRoot, then exit)
                ... similarly for the other examples ...

Windows XP and Vista

This release for Windows XP and Vista includes a standard Windows installer which puts shortcuts onto your desktop and into the start menu, and puts G4beamlineExamples into you Documents folder. It can also be used with the Cygwin command-line.

After installation you can do the things suggested above under Linux.

Macintosh OS X (Intel)

This release for Mac OS X supports only the recent Intel Processors. Simply download the most recent version and double-click the downloaded installer (a .dmg file). Drag the G4beamline and Historoot applications into your /Applications folder. You can then drag them from /Applications into the Dock.

After installation you can do the things suggested above under Linux.


Here is a recent G4beamline User's Guide(external link). It is updated for each release and included in the execution tarball.

Here is a recent G4beamline Validation(external link) document. It is updated for each release and included in the execution tarball.

New Feature Requests

G4beamline is developed in a user-driven methodology that encourages rapid release cycles and user contributions. To request a new feature, simply join the G4beamline forum and post a message describing your request in as much detail as possible.


The installer or tarball contains everything required to run the program, except for the prerequisites listed below, and some physics data needed for Geant4 Physics Lists; there is a helper program to download the data sets.

Please join and use our G4beamline forum. You can self-register using the LOGIN module at the left (valid email required), and immediately start posting to the forum.

G4beamline User Survey and Download

In order to justify funding for continued G4beamline support, we need to know how many users are using G4beamline, what they are doing with it, and how much time and effort they have devoted to using the program. So before downloading G4beamline, please take a minute or two to answer our survey.

We will manually merge duplicate entries, using the largest values you entered (they accumulate over time). So if you answered the survey recently, just enter your name and we'll merge the entries.

You may remain anonymous, but including testimonials from users is a powerful argument for support, and for that we need your name. The only information gathered is what you enter in this form, plus the date you submitted it.

Please enter numerical values in decimal, with at most one digit after the decimal, as in "2.5".

Your Name:
Your email:
You may leave these blank to remain anonymous.

Are you representing a group? If so, enter its name:

Approximately how many years have you been using G4beamline (numeric):

Please estimate how much time you have spent using G4beamline over that period. Include all design and analysis for which G4beamline was an essential tool. This should be a broad-brush estimate; don't spend much effort on it. If you named a group above, indicate in the comments if this is for yourself, or total for the group. The value should be in "full time equivalent" years (numeric):

How are you using G4beamline? What projects are you using it for?
Character Count: Max: 2048

Please enter any comments you have. Testimonials can be useful in justifying future support. This is not a place to request new features.
Character Count: Max: 2048

Thank you for contributing to our survey. Push the Submit button to submit your answers and go to the download page, where you can download any number of G4beamline distributions.
Anti-Bot verification code image


More to come...


More to come...