MARLEY welcomes contributions of all kinds from new developers. This page provides some basic resources for those who would like to get involved.
The MARLEY source code is written in C++14 with a small number of helper scripts written for the Bash shell. Git is used for version control, and the official source code repository is hosted on GitHub. For new contributors who are unfamiliar with Git, this site provides an excellent tutorial.
A GitHub user account (available free of charge here) is required to contribute changes to MARLEY via the usual workflow. The instructions below assume that you already have an account set up.
Ordinary MARLEY development is carried out using copies of the official repository, called forks, which are managed by individual developers. After code changes have been made and tested using a development branch in a fork, they may be submitted for inclusion in the official repository (and thus in a future MARLEY release) by means of a GitHub pull request. A brief tutorial illustrating this approach to development on GitHub is available here.
Clear communication is essential when contributing to an open source project like MARLEY. This guide presents some great tips on how to communicate most effectively.
Regular contributors to MARLEY may be invited to join the core development team and be given write access to the official repository. Core developers are responsible for reviewing and approving pull requests submitted from forks.
A development copy of the MARLEY source code may be obtained according to the following steps. They need only be executed once.
Visit the webpage for the official repository
Fork button in the upper right corner. If prompted to choose a
location for the fork, select your user account. A fork of MARLEY will be
added to your GitHub user account at
<username> with your GitHub username here and elsewhere).
Clone your GitHub fork to a folder on your local machine:
git clone https://github.com/<username>/marley
Enter the folder for the cloned fork and check that your setup is correct:
cd marley git remote -v
The second command above should yield the following output:
origin https://github.com/<username>/marley (fetch) origin https://github.com/<username>/marley (push)
If the steps above were followed successfully, then the MARLEY source code will
now be present in the
Having checked out the source code in the manner described above, you may now
make changes, build, and test in the usual way. Frequent Git commits will make
your contributions easier to merge into the official
master branch. Some
useful advice on best practices for making commits is available here.
When preparing code for inclusion in MARLEY, please keep in mind the following guidelines.
External dependencies have deliberately been kept to a minimum throughout MARLEY’s history. Beyond the C++ Standard Library itself, the only required external dependency is the GNU Scientific Library (GSL). Even for GSL, only those portions needed to compute the Coulomb wavefunctions are actually used by MARLEY.
New features that impact core MARLEY functionality should avoid introducing new
external dependencies if at all possible. Use of ROOT
classes is acceptable only in analysis macros (e.g.,
in optionally-built portions of the code designed specifically to interface with
MARLEY does not have a formal coding style guide. However, following the list of suggestions below will help to ensure that new code contributions use a style roughly consistent with previous work. Readability, clarity, and consistency are more important than any particular style consideration. Above all, strive for code that is “correct, beautiful, [and] fast (in that order).”
When in doubt, imitate the conventions used in the existing MARLEY source code
Member variable names end with an underscore character (
Class names and enumeration types are written in UpperCamelCase
Variable and function names are written in snake_case
Prefer an explicit namespace specifier (
std::) to a
using namespace std)
constexpr variables to preprocessor
MACRO_CASE for the names of both of these entities.
std::endl when writing newlines to output
streams (see explanation in the
C++ source files have the filename extension
.cc. Header files have the
.hh. An exception to the latter rule occurs for
header files original to another code base (e.g.,
Use whitespace to improve readability, e.g.,
std::cout << x << '\n';
Prefer a maximum line width of 80 columns. Tolerate modestly longer lines if doing so improves code readability.
Use two spaces for each level of indentation. Never use tabs.
// comments to a single
/* */ comment block
All MARLEY classes are defined within the
As described in the API and meta documentation section, Doxygen comments should be used in header files to document class methods and member variables. See this section of the Doxygen manual for a description of the special comment blocks used for API documentation.
After your changes are finished, tested, committed, and pushed to a branch on
your GitHub fork, you are ready to submit a pull request to officially include
them in MARLEY. Please see the instructions for creating a GitHub pull
request if you are unfamiliar with the process. Under most circumstances, you
will want to use the official
MARLEY-MC/marley repository as the “base
repository” and the
master branch as the “base branch.”
After your pull request has been created, the current MARLEY core developer(s) will be notified on GitHub. After reviewing your changes, they may leave comments on your pull request suggesting modifications. GitHub provides a flexible interface for adding both overall and line-by-line comments to a submitted pull request. If you do not receive any comments on your pull request within a day or two, please reach out to the core developer(s) via email.
As the review process proceeds, you may respond to comments from the core developer(s) by leaving comments of your own. New commits may be added to the pull request by pushing them to the same branch on your GitHub fork of MARLEY.
When your changes have been approved, a core developer will merge your
development branch into the
master branch of the official repository.
You have now completed a contribution which will be included in the next
MARLEY release. Congratulations and thanks for your hard work!
As a convenient reference for developers, a set of webpages that provide API documentation for the MARLEY C++ classes, source files, etc. is available here. These webpages are generated automatically from the source code using a tool called Doxygen. Special comment blocks that are written in the MARLEY header files are interpreted by Doxygen during the generation process.
For offline viewing, the API documentation may generated in any environment in which Doxygen is installed. To create the HTML files, simply execute
from within the
build/ folder. After Doxygen executes, open the file
docs/_build/html/doxygen/index.html in a browser to view the local copy of
the API documentation website.
With the exception of the API webpages described above, all other content for
the official MARLEY website (http://www.marleygen.org) is produced from a set
of text files stored in the
docs/ folder of the source code tree. These
text files are written in the reStructuredText (reST) markup language. The
generator is used with the Guzzle theme to produce HTML webpages
from the reST files. Two Sphinx extensions are required to fully build the
website. The sphinxcontrib-bibtex extension is used
to handle citations (see, e.g., the online bibliography). The
extension is used to manage the posts on the news webpage.
Installation of the prerequisites needed to use Sphinx will vary somewhat across different systems. Typically, however, the standard package manager may be used to install Sphinx itself, and the remaining components may be added using pip. For a computer running macOS and Python 3, for instance, Homebrew may be used to install Sphinx and its extensions via the commands
brew install sphinx-doc pip3 install guzzle-sphinx-theme sphinxcontrib-bibtex sphinxcontrib-newsfeed
After these components (and Doxygen) have been installed, one may build the
MARLEY webpages by navigating to the
build/ folder and using the command
When the build completes, an offline copy of the MARLEY website may be viewed
by opening the file
docs/_build/html/index.html in a browser.
An informal list of possible new features that may be added to MARLEY in the future is given below. Feedback from the community about the contents of this list, including suggestions for new items, is welcome.
Additional reaction input files
New channels for 40Ar: NC, 𝜈̄e CC
New nuclear targets: 12C, 16O, 56Fe, 63Cu, 127I, 208Pb, others?
Implementation of an inclusive cross section model that includes forbidden
nuclear transitions. A new class derived from
likely be required.
Handling of new job configuration file keys to vary the parameters used in the nuclear optical model, etc.
As an application of the new configuration options, event reweighting could
be implemented to facilitate assessments of theoretical uncertainties on the
MARLEY physics models. A prerequisite to the reweighting would be upgrades
marley::Event class to allow storage of the full de-excitation
Refinements of the nuclear de-excitation model
Pre-equilibrium particle emission
Realistic angular distributions for evaporated particles
Finite particle emission times
Non-neutrino projectiles (e.g., electrons, MeV-scale dark matter)
Full Doxygen documentation coverage
A full suite of unit tests incorporated into the continuous integration system