2. Getting Started#

2.1. Obtaining the code#

The Achilles source code is hosted on GitHub. You can clone the repository using:

$ git clone https://github.com/AchillesGen/Achilles.git
$ cd Achilles

If you would like to use a specific release version, you can checkout the corresponding tag:

$ git checkout vX.Y.Z

where X.Y.Z is the desired version number. Available releases can be found on the GitHub releases page.

2.2. Installation#

2.2.1. Building Achilles#

In this section, all the details for building the Achilles code is provided. The Achilles code uses CMake as a means to provide a platform agnositic installation procedure. If you encounter any issues during the build process, please file a github issue.

In order to build Achilles, a C++ compiler with support for C++17 is required. In addition to a C++ compiler, a Fortran90 compiler is required (we recommend using gfortran). Finally, Achilles requires HDF5 for parsing some of the data files. All additional required dependencies will be automatically downloaded and installed for you. If you wish to install them yourself, please see Dependencies for details.

In addition to the required dependencies, Achilles has some additional optional dependencies to extend the functionality of the code. If the user wishes to study Beyond the Standard Model processes or the decay of tau leptons, an additional dependency on Sherpa is required. The interface and current limitations are described in detail in [IHocheLGR22] for BSM and [IHocheSW23] for tau decays. Additional details on the interface can be found in the Sherpa Interface section. Details on enabling the interface and options for finding the Sherpa installation can be found in Build Options.

Building Achilles with the default options can be accomplished with the standard CMake pipeline, assuming you are in the Achilles root directory:

$ cmake -S . -B build <additional options>
$ cmake --build build -- -jN

Where in the above, the additional options can again be found in the Build Options section, and the command -jN tells CMake how many parallel jobs to be launched during the build process. While the above commands will completely build Achilles, it will not do so in a location independent way. To obtain this, the Achilles code needs to be installed with

$ cmake --install build

Then Achilles will be installed into the variable set by CMAKE_PREFIX_PATH, which defaults to /usr/local/ on UNIX machines. Achilles can then be launched anywhere as long as the executable can be found in your PATH.

2.2.2. Dependencies#

2.2.2.1. Required Dependencies#

The following dependencies are automatically downloaded and built by CMake using CPM if they are not already found on the system:

  • fmt (v11.0.0) – Modern C++ formatting library

  • spdlog (v1.14.1) – Fast C++ logging library

  • docopt (v0.6.3) – Command-line interface library

  • yaml-cpp – YAML parser and emitter

  • yaml-fortran – Fortran YAML bindings

  • NuHepMC_CPPUtils (v1-RC10) – NuHepMC C++ utilities (includes HepMC3)

  • HighFive (v2.6.2) – C++ interface for HDF5

2.2.2.2. Optional Dependencies#

2.2.2.2.1. Sherpa#

Sherpa is required for studying Beyond the Standard Model (BSM) processes or tau lepton decays. A custom version of Sherpa with UFO support is needed; contact the Achilles authors for details on obtaining it. To use Sherpa, build it with the -DSHERPA_ENABLE_UFO configure flag and then enable the interface in Achilles with:

$ cmake -S . -B build -DACHILLES_ENABLE_SHERPA=ON -DSHERPA_ROOT_DIR=/path/to/sherpa

For further details on the interface, see the Sherpa Interface section.

2.2.3. Build Options#

Achilles Options

Option

Meaning

Default

ACHILLES_ENABLE_TESTING

Build the Achilles test suite

OFF

ACHILLES_ENABLE_CASCADE_TEST

Build the Achilles cascade executable to run hadron-nucleus interactions or transparency checks

OFF

ACHILLES_ENABLE_POTENTIAL_TEST

Build the Achilles potential executable used to test different nuclear potentials in the cascade

OFF

ACHILLES_ENABLE_PRECOMPUTED

Build the Achilles interface to pass in pre-computed events in order to cascade them using the Achilles cascade

OFF

ACHILLES_ENABLE_SHERPA

Build the Sherpa interface to Achilles. This requires an installation of Sherpa. Provides the ability for tau decays and BSM. For details see Sherpa Interface

OFF

ACHILLES_BUILD_DOCS

Build the Achilles manual. Requires doxygen, sphinx, and …

OFF

ACHILLES_EVENT_DETAILS

Provides additional event details useful for in-depth debugging.

OFF

CMake Options

Option

Meaning

Default

CMAKE_BUILD_TYPE

Whether to build a Release, Debug, or RelWithDebInfo version of the code.

Release

CMAKE_INSTALL_PREFIX

Specifies the directory where the Achilles will be installed when make install is executed

/usr/local

2.3. Running#

The main Achilles executable for lepton-nucleus interactions can be run by launching the achilles executable, which can either be found in the bin directory of the build directory, or in the bin directory of the install directory. Launching the code with no command line arguments, attempts to find a run card file named run.yml that specifies the setup for the desired run. For a detailed description on the run card can be found here.

If you wish to run with a different run card, then Achilles can be launched as

$ ./achilles <run_card>

In which the <run_card> is the desired YAML configuration file to be used.

Note

Additional executables for other run modes (cascade-only, potential tests, and pre-computed events) are enabled through the options listed in Build Options.

Runtime Options

Option

Meaning

-h --help

Show list of options

--version

Show the version of Achilles

-v / -vv

Increase verbosity level

-l / -ll

Increase log verbosity level

-b

Batch Mode (log-friendly)

--logfile

File to write log info to. Defaults to achilles.log

-s --sherpa

Option to pass to Sherpa

--display-cuts

List available cut options

--display-ps

List available phase spaces

--display-ff

List available form factors

--display-int-models

List available cascade models for cross section evaluations

--display-nuc-models

List available nuclear models

2.4. Dockerized Achilles#

Docker provides a means to run pre-built environments in a containerized way, similar to virtual machines. We provide a basic version of Achilles built with minimum features. This enables users to try out Achilles without having to personally build and install the executable, helping to overcome any system-specific issues.

Note

Docker has a security vulnerability that makes it difficult to run safely on shared computing resources. For this reason, many high-performace computing (HPC) clusters support the use of Apptainer instead. Our images have been built for Docker, but should be convertable to an Apptainer image.

2.4.1. Obtaining a Docker image#

Docker images are automatically built by the GitHub CI. A given version of the code can be obtained by running:

$ docker pull ghcr.io/achillesgen/achilles:vX.Y.Z

where X.Y.Z is the version of Achilles you wish to obtain. You can also obtain the most up-to-date version from the main branch by running:

$ docker pull ghcr.io/achillesgen/achilles:main

Both of the above commands will download and store the Docker image on your system. You are able to obtain multiple versions of the image. Therefore, for the rest of this documentation, we will denote the image without the tag, but you can add the tag to the specific version in each command.

2.4.2. Running the Container#

Once the image has been downloaded, you can run the container with:

$ docker run ghcr.io/achillesgen/achilles

This will launch Achilles with the default run card (run.yml) that is included in the image. To run with a custom run card, you can pass it as an argument:

$ docker run ghcr.io/achillesgen/achilles <run_card>

To get an interactive shell inside the container for exploring or debugging:

$ docker run -it --entrypoint /bin/sh ghcr.io/achillesgen/achilles

2.4.3. Handling files between host and container#

By default, the Docker container is isolated from the host filesystem. To pass files into the container (such as custom run cards or nuclear data files) or to retrieve output files (such as generated events), you can use Docker’s volume mount feature:

$ docker run -v /path/on/host:/achilles/work ghcr.io/achillesgen/achilles work/<run_card>

This mounts the host directory /path/on/host into the container at /achilles/work. Any output files written to /achilles/work inside the container will appear in /path/on/host on the host machine.