more markdownlint fixes

line-length = false

blanks-around-headings = false

link-fragments = false

no-duplicate-heading = false

no-inline-html = false

first-line-heading = false

heading-increment = false

no-bare-urls = false

emphasis-style = false

[no-multiple-blanks]

maximum = 2

SPDX-License-Identifier: CC-BY-4.0

-->

[![](doc/logo_small.png)](https://cern.ch/allpix-squared)

[![ALlpix Squared Logo](doc/logo_small.png)](https://cern.ch/allpix-squared)

# Allpix<sup>2</sup>

### Generic Pixel Detector Simulation Framework

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.

For more details about the project please have a look at the website at [https://cern.ch/allpix-squared](https://cern.ch/allpix-squared).

[![build status](https://gitlab.cern.ch/allpix-squared/allpix-squared/badges/master/pipeline.svg)](https://gitlab.cern.ch/allpix-squared/allpix-squared/commits/master)

[![coverity status](https://scan.coverity.com/projects/21520/badge.svg)](https://scan.coverity.com/projects/allpix-squared)

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:

```shell

$ docker run --interactive --tty --volume "$(pwd)":/data --name=allpix-squared \

docker run --interactive --tty --volume "$(pwd)":/data --name=allpix-squared \

           gitlab-registry.cern.ch/allpix-squared/allpix-squared bash

```

Alternatively it is also possible to directly start the simulation instead of an interactive shell:

```shell

$ docker run --tty --rm --volume "$(pwd)":/data --name=allpix-squared \

docker run --tty --rm --volume "$(pwd)":/data --name=allpix-squared \

           gitlab-registry.cern.ch/allpix-squared/allpix-squared "allpix -c my_simulation.conf"

```

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:

```shell

$ source /cvmfs/clicdp.cern.ch/software/allpix-squared/<version>/x86_64-<system>-<compiler>-opt/setup.sh

source /cvmfs/clicdp.cern.ch/software/allpix-squared/<version>/x86_64-<system>-<compiler>-opt/setup.sh

```

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.

When running for the first time, the CVMFS cache of the executing machine has to be populated with all dependencies.

### 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.

* [Eigen3](http://eigen.tuxfamily.org/index.php?title=Main_Page) (optional, but required for typical purposes)

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

```shell

source etc/scripts/setup_lxplus.sh

```

Compilation TL;DR:

```shell

$ mkdir build && cd build/

$ cmake ..

$ make install

mkdir build && cd build/

cmake ..

make install

```

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.

* 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](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:

* The versioned Zenodo record can be found at [https://doi.org/10.5281/zenodo.3550935](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

    > Zenodo. [https://doi.org/10.5281/zenodo.6387859](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/).

## 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.

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.

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 cereal C++11 serialization library, BSD 3-Clause License, [original source code](https://github.com/USCiLab/cereal).

The following notes should be taken for these fields:

-   `title` is always required displayed in the ToC / sidebar and as main heading of the doc page. For non-weighted markdown

* `title` is always required displayed in the ToC / sidebar and as main heading of the doc page. For non-weighted markdown

  files, the filename should be a lower-cased version of the `title` with spaces replaced by underscores.

-   `description` is optional and always disaplyed below the `title`. In this documentation, it should only be present for

* `description` is optional and always disaplyed below the `title`. In this documentation, it should only be present for

  chapter pages, modules and examples.

-   `weight` is required for all files in the [usermanual folder](./usermanual/). Files always should have weight as

* `weight` is required for all files in the [usermanual folder](./usermanual/). Files always should have weight as

  double-digit prefixed to their file name (see [File tree](#file-tree)). For files that are not in the usermanual folder,

  for example module READMEs, the `weight` field must be omitted so that hugo sorts them alphabetically.

## Testing the website

You can easily test the website of the documentation with your changes yourself by running:

```shell

git clone https://gitlab.cern.ch/allpix-squared/allpix-squared-website.git

./get_artifacts.sh job job_number_from_your_ci your_cern_user_name/allpix-squared

The core framework is compiled separately from the individual modules and Allpix Squared has therefore only two required

external dependencies:

- ROOT 6 \[[@root]\]:

* ROOT 6 \[[@root]\]:

  ROOT is used for histogramming as well as coordinate transformations. In addition, some modules implement I/O using ROOT

  libraries. The latest stable release of ROOT 6 is recommended and older versions, such as ROOT 5.x, are not supported.

  Please refer to \[[@rootinstallation]\] for instructions on how to install ROOT. ROOT has several components of which the

  `GenVector` package is required to run Allpix Squared. This package is included in the default build. ROOT needs to be

  built using C++17, which is accomplished by supplying the CMake flag `-DCMAKE_CXX_STANDARD=17`.

- Boost.Random 1.64.0 or later \[[@boostrandom]\]:

* Boost.Random 1.64.0 or later \[[@boostrandom]\]:

  Random number generator and distribution library of the Boost project, used in order to get cross-platform portable,

  STL-compatible random number distributions. While STL random number generators are portable and guarantee to deliver the

  same random number sequence given the same seed, random distributions are not, and their implementation is

For some modules, additional dependencies exist. For details about the dependencies and their installation see

[Chapter 8](../08_modules/_index.md). The following dependencies are needed to compile the standard installation:

- Geant4 \[[@geant4]\]:

* Geant4 \[[@geant4]\]:

  Simulates the desired particles and their interactions with matter, depositing charges in the detectors with the help of

  the constructed geometry. See the instructions in \[[@geant4installation]\] for details on how to install the software.

  All Geant4 data sets are required to run the modules successfully, and Geant4 must be built using C++17. For

  multithreading to be possible, this must also be enabled in the Geant4 installation. It is recommended to enable the

  Geant4 Qt extensions to allow visualization of the detector setup and the simulated particle tracks. A recommended set of

  CMake flags to build a Geant4 package suitable for usage with Allpix Squared are:

  ```

  ```shell

  -DGEANT4_INSTALL_DATA=ON

  -DGEANT4_USE_GDML=ON

  -DGEANT4_USE_QT=ON

  -DGEANT4_BUILD_BUILTIN_BACKTRACE=OFF

  ```

- Eigen3 \[[@eigen3]\]:

* Eigen3 \[[@eigen3]\]:

  Vector package used to perform Runge-Kutta integration, used in some of the charge carrier propagation modules. Eigen is

  available in almost all Linux distributions through the package manager. Otherwise it can be easily installed, comprising

  a header-only library.

header describing the name used to identify the detector; all names are required to be unique. Every detector has to contain

all of the following parameters:

- A string referring to the `type` of the detector model. The model should exist in the search path as described in

* A string referring to the `type` of the detector model. The model should exist in the search path as described in

  [Section 5.2](../05_geometry_detectors/02_models.md).

- The 3-dimensional `position` in the world frame in the order x, y, z. See

* The 3-dimensional `position` in the world frame in the order x, y, z. See

  [Section 5.1](../05_geometry_detectors/01_geometry.md) for details.

- The `orientation` specified as X-Y-Z extrinsic Euler angles. This means the detector is rotated first around the world's

* The `orientation` specified as X-Y-Z extrinsic Euler angles. This means the detector is rotated first around the world's

  X-axis, then around the world's Y-axis and then around the world's Z-axis. Alternatively the orientation can be set as

  Z-Y-X or Z-X-Z extrinsic Euler angles, refer to section [Section 5.1](../05_geometry_detectors/01_geometry.md) for

  details.

[Section 3.4](./04_framework_parameters.md). Misalignment can be introduced both for shifts along the three global axes and

the three rotations angles with the following parameters:

- The parameter `alignment_precision_position` allows the specification of the alignment precision along the three global

* The parameter `alignment_precision_position` allows the specification of the alignment precision along the three global

  axes. Each value represents the Gaussian width with which the detector will be randomly misaligned along the

  corresponding axis.

- The parameter `alignment_precision_orientation` allows to specify the alignment precision in the three rotation angles

* The parameter `alignment_precision_orientation` allows to specify the alignment precision in the three rotation angles

  defined by the `orientation` parameter. The misalignments are added to the individual angles before combining them into

  the final rotation as defined by the `orientation_mode` parameter.

This configuration is used in the rest of this chapter for explaining concepts. A visualization of the setup is given below.

![](./telescope.png)\

![Telescope](./telescope.png)\

*Visualization of a Pion passing through the telescope setup defined in the detector configuration file. A secondary particle

is produced in the material of the detector in the center.*

Every passive material has to contain all of the following parameters:

- The `position` and `orientation` of the material as described for the detector, see

* The `position` and `orientation` of the material as described for the detector, see

  [Section 3.3](./03_detector_configuration.md).

- A string referring to the `type` of the passive material. The model should be interpreted by the module constructing the

* A string referring to the `type` of the passive material. The model should be interpreted by the module constructing the

  passive material, for example the

  [`GeometryBuilderGeant4` module](../08_modules/geometrybuildergeant4.md#passive-volumes).

- A string referring to the `material` of the passive material. The materials for the `GeometryBuilderGeant4` module are

* A string referring to the `material` of the passive material. The materials for the `GeometryBuilderGeant4` module are

  defined in the [module documentation](../08_modules/geometrybuildergeant4.md#materials).

- A set of size parameters specific for the model that is chosen. All size parameters that describe the total length of

* A set of size parameters specific for the model that is chosen. All size parameters that describe the total length of

  something are placed such that half of this total length extends from each side of the given `position`. If a parameter

  describes the radius, this means the radius will extend from the `position` on both sides, making its total size two

  times the radius in the given direction. The size parameters for the specific models in the `GeometryBuilderGeant4`

role = "passive"

```

![](./passive_materials.png)\

![Passive Materials](./passive_materials.png)\

*Visualization of the setup described in the geometry file.*