Simulation Geometry
Simulations are frequently performed for a set of different detectors (such as a beam telescope and a device under test). All of these individual detectors together form what Allpix Squared defines as the geometry. Each detector has a set of properties attached to it:

A unique detector
name
to refer to the detector in the configuration. 
The
position
in the world frame. This is the position of the geometric center of the sensitive device (sensor) given in world coordinates as X, Y and Z s defined in Section 5.1.1 (note that any additional components like the chip and possible support layers are ignored when determining the geometric center). 
An
orientation_mode
that determines the way that the orientation is applied. This can be eitherxyz
,zyx
orzxz
, wherexyz
is used as default if the parameter is not specified. Three angles are expected as input, which should always be provided in the order in which they are applied.
The
xyz
option uses extrinsic Euler angles to apply a rotation around the global X axis, followed by a rotation around the global Y axis and finally a rotation around the global Z axis. 
The
zyx
option uses the extrinsic ZYX convention for Euler angles, also known as PitchRollYaw or 321 convention. The rotation is represented by three angles describing first a rotation of an angle $\phi
$ (yaw) about the Z axis, followed by a rotation of an angle $\theta
$ (pitch) about the initial Y axis, followed by a third rotation of an angle $\psi
$ (roll) about the initial X axis. 
The
zxz
uses the extrinsic ZXZ convention for Euler angles instead. This option is also known as the 313 or the “xconvention” and the most widely used definition of Euler angles [@eulerangles].
Note
It is highly recommended to always explicitly state the orientation mode instead of relying on the default configuration. 

The
orientation
to specify the Euler angles in logical order (e.g. first X, then Y, then Z for thexyz
method), interpreted using the method above (or with thexyz
method if theorientation_mode
is not specified). An example for three Euler angles would beorientation_mode = "zyx" orientation = 45deg 10deg 12deg
which describes the rotation of 45° around the Z axis, followed by a 10° rotation around the initial Y axis, and finally] a rotation of 12° around the initial X axis.
Note
All supported rotations are extrinsic active rotations, i.e. the vector itself is rotated, not the coordinate system. All angles in configuration files should be specified in the order they will be applied. 
A
type
parameter describing the detector model, for exampletimepix
ormimosa26
. These models define the geometry and parameters of the detector. Multiple detectors can share the same model, several of which are shipped readytouse with the framework. 
An
alignment_precision_position
optional parameter to specify the alignment precision along the three global axes as described in Section 3.3. 
An optional parameter
alignment_precision_orientation
for the alignment precision in the three rotation angles as described in Section 3.3. 
An optional electric or magnetic field in the sensitive device. These fields can be added to a detector by special modules as demonstrated in Section 3.7.
The detector configuration is provided in the detector configuration file as explained in Section 3.3.
Coordinate systems
Local coordinate systems for each detector and a global frame of reference for the full setup are defined. The global coordinate system is chosen as a righthanded Cartesian system, and the rotations of individual devices are performed around the geometric center of their sensor.
Local coordinate systems for the detectors are also righthanded Cartesian systems, with the x and yaxes defining the sensor plane. The origin of this coordinate system is the center of the lower left pixel in the grid, i.e. the pixel with indices (0,0), whereas the zaxis pointing towards the readout connected to the sensor. This simplifies calculations in the local coordinate system as all positions can either be stated in absolute numbers or in fractions of the pixel pitch.
A sketch of the actual coordinate transformations performed, including the order of transformations, is given below. The global coordinate system used for tracking of particles through the detector setup is shown on the left side, while the local coordinate system used to describe the individual sensors is located at the right. Both local and global coordinate systems are aligned by default. Therefore, without any rotation, the sensor backplane (opposite to the plane where the readout is performed) is turned to the negative side of the zaxis.
Coordinate transformations from global to local and reverse. The first row shows the detector positions in the respective
coordinate systems in top view, the second row in side view.
The global reference for time measurements is the beginning of the event, i.e. the start of the particle tracking through the setup. The local time reference is the time of entry of the first primary particle of the event into the sensor. This means that secondary particles created within the sensor inherit the local time reference from their parent particles in order to have a uniform time reference in the sensor. It should be noted that Monte Carlo particles that start the local time frame on different detectors do not necessarily have to belong to the same particle track.
Changing and accessing the geometry
The geometry is needed at an early stage because it determines the number of detector module instantiations as explained in Section 4.4. The procedure of finding and loading the appropriate detector models is explained in more detail in the next section.
The geometry is directly added from the detector configuration file described in
Section 3.3. The geometry manager parses this file on construction, and
the detector models are loaded and linked later during geometry closing as described above. It is also possible to add
additional models and detectors directly using addModel
and addDetector
(before the geometry is closed). Furthermore it
is possible to add additional points which should be part of the world geometry using addPoint
. This can for example be
used to add the beam source to the world geometry.
The detectors and models can be accessed by name and type through the geometry manager using getDetector
and getModel
,
respectively. All detectors can be fetched at once using the getDetectors
method. If the module is a detectorspecific
module its related detector can be accessed through the getDetector
method of the module base class instead (returns a null
pointer for unique modules) as follows:
void run(Event* event) {
// Returns the linked detector
std::shared_ptr<Detector> detector = this>getDetector();
}