Getting started¶

MARLEY is regularly tested on both Linux and macOS platforms and is expected to work in any Unix-like environment in which the prerequisites are installed. Building and running MARLEY on Windows is not currently supported.

Prerequisites¶

There are two prerequisites needed to build MARLEY:

A C++17-compliant compiler. The following compilers are officially supported:
- GNU Compiler Collection (GCC) ≥ 9.1.0
- Clang ≥ 9.0.0
GNU Make

On both Linux and macOS, these prerequisites will likely be available through the standard package manager. Note that when CMake is available on the host system, it is used by default. However, an equivalent build configuration using only GNU Make is also provided for user convenience.

Although it is not required in order to build or use MARLEY, the popular ROOT data analysis framework provides convenient tools for plotting and analyzing simulation results. Users who wish to use the optional interface between the two codes should ensure that ROOT is installed before building MARLEY. At build time, the optional MARLEY interface to ROOT is enabled automatically if the root-config script is present on the system PATH.

MARLEY has two additional dependencies that are both optional: the GNU Scientific Library (GSL) and the HepMC3 event record library. If these dependencies are not detected on the host system at build time, then built-in versions will be used instead.

Obtaining the code¶

The source code for MARLEY may be downloaded as a compressed archive file (in either zip or tar.gz format) from the GitHub releases webpage. Both the current release and all official past releases are available for download.

After downloading the source code, the user should unpack the archive file in the desired installation folder. For the v2.0.0 release in tar.gz format, this may be done via the command

tar xvfz marley-2.0.0.tar.gz

After unpacking the source code, the user should navigate to the root of the source code tree before following the build instructions below. For the current example, this may be done via the command

cd marley-2.0.0

Users interested in contributing to MARLEY development should follow the instructions given here instead of downloading and unpacking a release archive file.

Building MARLEY¶

To build the code, run make from the top-level MARLEY directory:

make

The top-level Makefile will auto-detect CMake and use it as the build backend if available; otherwise it falls back to the included GNU Make recipe (make/build.mk). The build/ directory is created automatically by either backend and is removed by running make clean.

If the build is successful, then the marley executable will be located at build/bin/marley. Running it without arguments

build/bin/marley

should produce the following output:

Usage: marley <command> [options]

Commands:
  convert     Convert event files between supported formats
  decay       Simulate nuclear de-excitations
  generate    Generate Monte Carlo events
  help        Show this help message or help for a specific command
  print       Print existing events in a human-readable format
  reweight    Reweight previously generated events
  summarize   Create a ROOT TTree summary of event files [requires ROOT]
  version     Print version information
  xsec        Tabulate total cross section vs. projectile kinetic energy

Options:
  -h, --help     Show top-level help
  -v, --version  Print version information

Run 'marley help <command>' or 'marley <command> --help' for details.
MARLEY home page: <https://www.marleygen.org>

From the top-level Makefile, the user can optionally direct the build system to ignore CMake (thus falling back to a pure GNU Make recipe) as well as any of the optional dependencies. Invoking make with the settings

make IGNORE_CMAKE=1 IGNORE_ROOT=1 IGNORE_GSL=1 IGNORE_HEPMC3=1

will bypass CMake when building the code, disable the ROOT interface even if a ROOT installation is successfully detected, and force the use of built-in versions of GSL and HepMC3 even if system installations are available for both of these libraries. Any combination of these make options may be used in any order according to the user’s preferences.

Setting up the runtime environment¶

The marley executable relies on the system environment variable MARLEY to store the full path to the root folder of the source code. This variable may be set automatically by sourcing the setup_marley.sh Bash script:

source setup_marley.sh

For user convenience, this script also adds build/bin to the system PATH and adds build/lib to LD_LIBRARY_PATH and, on macOS, DYLD_LIBRARY_PATH. After sourcing the setup script, the marley command may be run from any directory.

If generation of events is attempted without setting the MARLEY environment variable first, then MARLEY will halt after printing the error message

[ERROR]: The MARLEY environment variable is not set. Please set it (e.g.,
by sourcing the setup_marley.sh script) and try again.

Generating events¶

The marley executable allows the user to adjust simulation parameters via job configuration files written in a JSON-like format. The name of the configuration file to use appears as the first argument after the generate command:

marley generate CONFIG_FILE

To generate events using an example configuration file, execute the following command after sourcing the setup_marley.sh script:

marley generate examples/config/annotated.js

The program will display the MARLEY logo and diagnostic messages as it runs the simulation. When the program terminates, a new file named events.hepmc3 will be present in the working directory. This file contains the generated events in the standard ASCII representation of the HepMC3 data format.

The annotated.js configuration file mentioned above is heavily commented with explanations of the most commonly-used input parameters. Reading it serves as a good next step for new users. When you are ready to start writing your own configuration files, editing a copy of examples/config/COPY_ME.js is recommended.

Table Of Contents

Contents