Allpix<sup>2</sup> is a generic simulation framework for silicon detectors, written in modern C++. The goal of the Allpix<sup>2</sup> framework is to provide a comprehensive and easy-to-use package for simulating the performance of silicon detectors from incident ionizing radiation to the digitization of pixel hits in the detector ASIC.
Allpix<sup>2</sup> is a flexible and modular simulation framework for semiconductor radiation detectors, written in modern C++. The goal of the Allpix<sup>2</sup> framework is to provide a comprehensive and easy-to-use package for end-to-end simulations of the performance of patterned semiconductor radiation detectors, from incident ionizing radiation to the digitization of pixel hits in the detector ASIC.
For more details about the project please have a look at the website at https://cern.ch/allpix-squared.
@@ -18,73 +18,93 @@ For more details about the project please have a look at the website at https://
*[ROOT](https://root.cern.ch/building-root)(required, with the GenVector component)
*[Boost.Random](https://www.boost.org/doc/libs/1_75_0/doc/html/boost_random/reference.html)(required, version >= 1.64.0)
*[Geant4](http://geant4-userdoc.web.cern.ch/geant4-userdoc/UsersGuides/InstallationGuide/html/installguide.html)(optional, but required for typical purposes, multithreading capabilities should be enabled)
*[Eigen3](http://eigen.tuxfamily.org/index.php?title=Main_Page)(optional, but required for typical purposes)
## Using Allpix<sup>2</sup>
### Docker Images
Docker images are provided for all releases and the latest development version of the framework.
To create a container from the latest Docker image and start an interactive shell session with the current host system path mounted to `/data`, run:
## Usage on machines with CVMFS
```sh
$ docker run --interactive--tty--volume"$(pwd)":/data --name=allpix-squared \
Ready-to-run installations of Allpix<sup>2</sup> are provided via the CERN Virtual Machine File System (CVMFS) for use on SLC6 and CentOS7 machines supported by CERN. In order to use Allpix<sup>2</sup>, the respective environment has to be set up by sourcing the appropriate file:
Alternatively it is also possible to directly start the simulation instead of an interactive shell:
```sh
$ docker run --tty--rm--volume"$(pwd)":/data --name=allpix-squared \
To run a tagged version, append the tag to the image name, e.g. `gitlab-registry.cern.ch/allpix-squared/allpix-squared:v2.2.1`.
More detailed information on the Docker images can be found in the user manual.
### Machines with CVMFS
Machines with a supported OS and the [CERN Virtual Machine File System (CVMFS)](https://cernvm.cern.ch/portal/filesystem) can load Allpix<sup>2</sup> and its dependencies from there by sourcing the respective environment:
where `<version>` should be replaced with the desired Allpix<sup>2</sup> version and `<system>` with the operating system of the executing machine (either `slc6` or `centos7`). The compiler versions available via the `<compiler>` tag depend on the selected operating system.
where `<version>` should be replaced with the desired Allpix<sup>2</sup> version, e.g. `2.2.1` and `<system>` with the operating system of the executing machine (`centos7`, `centos8` or `mac11`). The compiler versions available via the `<compiler>` tag depend on the selected operating system.
After this, the `allpix` executable is in the `$PATH` environment variable and can be used.
It should be noted that the CVMFS cache of the executing machine has to be populated with all dependencies when running the program for the first time.
This can lead to a significant start-up time for the first execution, but should not affect further executions with the cache already present.
More information can be found in the [CVMFS documentation](https://cernvm.cern.ch/portal/filesystem).
When running for the first time, the CVMFS cache of the executing machine has to be populated with all dependencies.
This can lead to a significant start-up time for the first execution, it does not affect simulation performance or subsequent executions with the cache already present.
## Installation
The CMake build system is used for compilation and installation. The install directory can be specified by adding `-DCMAKE_INSTALL_PREFIX=<prefix>` as argument to the CMake command below. Other configuration options are explained in the manual (see the documentation section below).
### Compilation from Source
Allpix<sup>2</sup> uses the CMake build system, version 3.6.3 or later, to configure and compile the framework.
It requires a compiler with full C++17 support.
More detailed instructions on how to compile the framework from source can be found in the user manual.
The framework has the following external dependencies:
The dependencies need to be initialized for the build to succeed. Currently there are two methods to load these:
*[ROOT](https://root.cern.ch/building-root)(required, with the GenVector component)
*[Boost.Random](https://www.boost.org/doc/libs/1_75_0/doc/html/boost_random/reference.html)(required, version >= 1.64.0)
*[Geant4](http://geant4-userdoc.web.cern.ch/geant4-userdoc/UsersGuides/InstallationGuide/html/installguide.html)(optional, but required for typical purposes, multithreading capabilities should be enabled)
*[Eigen3](http://eigen.tuxfamily.org/index.php?title=Main_Page)(optional, but required for typical purposes)
### Prerequisites on CERN LXPLUS
In order to install Allpix<sup>2</sup> on the CERN LXPLUS batch cluster, a LXPLUS setup script is provided:
For machines with CVMFS, e.g. the CERN LXPLUS or DESY NAF clusters, all dependencies and required compiler versions can be satisfied via:
```
$ source etc/scripts/setup_lxplus.sh
```
Then, continue as described under the compilation section.
### Prerequisites on a private machine
The dependencies listen above have to be satisfied. Both ROOT6 and Geant4 libraries and headers have to be in the path, this is usually achieved by sourcing the `thisroot.sh` or `geant4.sh` scripts. After this, continue as described below.
### Compilation
To compile and install a default installation of Allpix<sup>2</sup>, run the following commands
Compilation TL;DR:
```
```sh
$ mkdir build &&cd build/
$ cmake ..
$ make install
```
For more detailed installation instructions, please refer to the documentation below.
## Documentation
The most recently published version of the User Manual is available [from the website](https://cern.ch/allpix-squared/usermanual/allpix-manual.pdf).
The Doxygen reference is published [online](https://cern.ch/allpix-squared/reference/) too.
The latest PDF version of the User Manual can also be created from source by executing
```
$ make pdf
```
After running the manual is available under `usermanual/allpix-manual.pdf` in the build directory.
The User Manual of the most recent release version of Allpix<sup>2</sup> is available [from the website](https://cern.ch/allpix-squared/usermanual/allpix-manual.pdf).
The respective Doxygen reference is [published online](https://cern.ch/allpix-squared/reference/) as well.
To build the HTML version of the latest Doxygen reference, run the following command
```
$ make reference
```
The main page of the reference can then be found at `reference/html/index.html` in the build folder.
## Citing Allpix<sup>2</sup>
## Development of Allpix<sup>2</sup>
Allpix<sup>2</sup> is distributed freely and openly under the MIT license, but the authors kindly ask to cite the reference paper and the Zenodo record in scientific publications:
* The reference paper of Allpix<sup>2</sup> has been published in *Nuclear Instrumentations and Methods in Physics Research A* with open access and can be obtained from https://doi.org/10.1016/j.nima.2018.06.020.
A preprint version is available on [arxiv:1806.05813](https://arxiv.org/abs/1806.05813).
Please cite this paper when publishing your work using Allpix<sup>2</sup> as:
> S. Spannagel et al., “Allpix<sup>2</sup>: A modular simulation framework for silicon detectors”, Nucl. Instr.
> Meth. A 901 (2018) 164 – 172, doi:10.1016/j.nima.2018.06.020, arXiv:1806.05813
* The versioned Zenodo record can be found at https://doi.org/10.5281/zenodo.3550935. Please cite the version used for the published work. For example, the latest version should be cited as:
> S. Spannagel, K. Wolters & P. Schütze. (2022). Allpix Squared - Generic Pixel Detector Simulation Framework (2.2.0).
> Zenodo. https://doi.org/10.5281/zenodo.6387859
Further papers with algorithm validations as well as tutorials and seminar talks can be found [on the website](https://cern.ch/allpix-squared/page/publications/).
## Developing Allpix<sup>2</sup>
Allpix<sup>2</sup> is developed and maintained by
@@ -137,42 +157,23 @@ The following authors, in alphabetical order, have developed or contributed to A
* Morag Williams, University of Glasgow, @williamm
## Citations
The reference paper of Allpix Squared describing the framework and providing first validation results using test beam data has been published in *Nuclear Instrumentations and Methods in Physics Research A*.
The paper is published with open access and can be obtained from here:
https://doi.org/10.1016/j.nima.2018.06.020
Please cite this paper when publishing your work using Allpix Squared as:
## Contributing to Allpix<sup>2</sup>
> S. Spannagel et al., “Allpix<sup>2</sup>: A modular simulation framework for silicon detectors”, Nucl. Instr.
> Meth. A 901 (2018) 164 – 172, doi:10.1016/j.nima.2018.06.020, arXiv:1806.05813
A preprint version is available on [arxiv.org](https://arxiv.org/abs/1806.05813).
In addition, the software can be cited using the [versioned Zenodo record](https://doi.org/10.5281/zenodo.3550935) or the current version as:
> S. Spannagel, K. Wolters, P. Schütze. (2021, June 10). Allpix Squared - Generic Pixel Detector Simulation Framework
All types of contributions, being it minor and major, are very welcome. Please refer to our [contribution guidelines](CONTRIBUTING.md) for a description on how to get started.
Before adding changes it is very much recommended to carefully read through the documentation in the User Manual first.
## Licenses
This software is distributed under the terms of the MIT license. The documentation is distributed under the terms of the CC-BY-4.0 license.
The following third-party codes are included in the repository:
* The LaTeX, Pandoc and CodeCoverage CMake modules used by Allpix<sup>2</sup> are licensed under the BSD 3-Clause License.
* The octree library by Jens Behley is made available under the MIT license, the original source code can be found [here](https://github.com/jbehley/octree).
* The cereal C++11 serialization library used by Allpix<sup>2</sup> is published under the BSD 3-Clause License, the original source code can be found [here](https://github.com/USCiLab/cereal).
* The combination algorithms by Howard Hinnant are published under the Boost Software License Version 1.0, the code can be found [here](https://github.com/HowardHinnant/combinations) and the documentation of the class is published [here](https://howardhinnant.github.io/combinations/combinations.html).
* The CTest to JUnit XSL template is published under the MIT License, the original source code can be found [here](https://github.com/rpavlik/jenkins-ctest-plugin).
* The Magic Enum library by Daniil Goncharov is published under the MIT license, the code can be found [here](https://github.com/Neargye/magic_enum).
This repository follows the [REUSE](https://reuse.software/) specification, a full copyright report can be created via `reuse spdx`.
A copy of all licenses can be found in the [LICENSES](LICENSES/) folder.
This repositroy follows the [REUSE](https://reuse.software/) specification, a full copyright report can be created via `reuse spdx`.
The following third-party codes are included in the repository:
* The LaTeX, Pandoc and CodeCoverage CMake modules, BSD 3-Clause License.
* The octree library by Jens Behley, MIT license, [original source code](https://github.com/jbehley/octree).
* The combination algorithms by Howard Hinnant, Boost Software License Version 1.0, [original source code](https://github.com/HowardHinnant/combinations) and [class documentation](https://howardhinnant.github.io/combinations/combinations.html).
* The CTest to JUnit XSL template, MIT License, [original source code](https://github.com/rpavlik/jenkins-ctest-plugin).
* The Magic Enum library by Daniil Goncharov, MIT license, [original source code](https://github.com/Neargye/magic_enum).
