MARLEY (Model of Argon Reaction Low Energy Yields)

Introduction

MARLEY (Model of Argon Reaction Low Energy Yields) is a Monte Carlo event generator for neutrino-nucleus interactions at energies of tens-of-MeV and below. The current version computes inclusive neutrino-nucleus cross sections employing the allowed approximation: the nuclear matrix elements are evaluated while neglecting Fermi motion and applying the long-wavelength (zero momentum transfer) limit. De-excitations of the final-state nucleus emerging from the primary interaction are simulated using a combination of tabulated γ-ray decay schemes and an original implementation of the Hauser-Feshbach statistical model.

Input files are provided with the code that are suitable for simulating the charged-current process

ν_e + ⁴⁰Ar → e⁻ + ⁴⁰K^*,

coherent elastic neutrino-nucleus scattering (CEvNS) on spin-zero target nuclei, and neutrino-electron elastic scattering on any atomic target. Inclusion of additional reactions and targets is planned for the future.

MARLEY follows an open-source development model and welcomes contributions of new input files and code improvements from the community. A partial list of potential projects for future MARLEY development is available on the developer documentation webpage.

See the FILEMAP file for a description of the full contents of the MARLEY source code distribution.

Copyright and License

MARLEY is distributed under the terms of version 3 of the GNU General Public License ("GPLv3") as published by the Free Software Foundation. For the full text of that license, please see the COPYING file.

As a matter of professional courtesy, MARLEY users are also requested to follow the MCnet Guidelines for Event Generator Authors and Users. Nevertheless, these guidelines are not legally binding and do not limit your rights guaranteed under the GPLv3. See the GUIDELINES file for more details.

Citing MARLEY

If you refer to MARLEY in academic work, please always cite the following reference:

S. Gardiner, Simulating low-energy neutrino interactions with MARLEY, arXiv:2101.11867 (2021).

In publications which use the official reaction input files for charged-current scattering on argon-40 (i.e., any of the files in data/react whose names begin with ve40ArCC), please also cite the paper describing their preparation:

S. Gardiner, Nuclear de-excitations in low-energy charged-current ν_e scattering on ⁴⁰Ar, Phys. Rev. C 103, 044604 (2021).

Providing a citation for the MARLEY code itself is also encouraged and appreciated. To maximize reproducibility of published calculations, such citations should include the digital object identifier (DOI) associated with the code release that was used. The DOIs for recent versions of MARLEY are listed on the GitHub releases webpage and in the right-hand column of the Zenodo "concept DOI" webpage.

For convenience, recommended BibTeX citations to use for the latest MARLEY release are given in the CITATION.bib file.

If you use the default nuclear structure data files (strongly recommended) for published calculations, please also give proper attribution to the developers of the TALYS nuclear code (see data/structure/README.md for more information).

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.

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: <support@marleygen.org>

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.

Core Developers

Steven Gardiner - sjgardiner

See also the list of contributors who participated in this project.

Website

Further documentation for the latest version of MARLEY may be found on the official webpage at http://www.marleygen.org/.

Acknowledgements

Special thanks go to

The TALYS developers (Arjan Koning, Stéphane Hilaire, and Marieke Duijvestijn) for sharing their nuclear structure data
Zero Anixter for providing an illustration of Bob Marley to be used in the official MARLEY logo

sjgardiner/marley