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 three prerequisites needed to build MARLEY:

• A C++14-compliant compiler. The following compilers are officially supported:

  • GNU Compiler Collection (GCC) ≥ 4.9.4

  • Clang ≥ 3.5.2

• GNU Make

• GNU Scientific Library (GSL)

  • MARLEY’s Makefile verifies that GSL is installed by checking that the gsl-config script is available on the system PATH.

On Linux machines, all three of these prerequisites will likely be available through the standard package manager. On macOS, installing GSL may be done using Homebrew:

brew install gsl

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.

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 v1.2.0 release in tar.gz format, this may be done via the command

tar xvfz marley-1.2.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-1.2.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, enter the build/ folder

cd build

and then run GNU make

make

If the build is successful, then executing

./marley

should produce the following output:

Usage: marley [OPTION...] CONFIG_FILE

  -h, --help     Print this help message
  -v, --version  Print version and exit

MARLEY home page: <http://www.marleygen.org>
E-mail bug reports to: <[email protected]>

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 executing (“sourcing”) the setup_marley.sh Bash script using the source command. From within the build/ folder, for example, one may source the setup script via

source ../setup_marley.sh

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.

For user convenience, the setup_marley.sh script also adds the build/ folder to the system PATH and to either LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS).

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 (and only) command-line argument:

marley CONFIG_FILE

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

marley ../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.ascii will be present in the build/ folder. This file contains the generated events in MARLEY’s native ASCII output 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.

Full documentation for configuring MARLEY is available in section 6 of the MARLEY implementation paper.