API Reference

Classes

class AnnulusBounds : public Acts::DiscBounds

Class that implements a (potentially asymmetric) bounds with difference between surface bound center and surface coordinate center.

These bounds combine two different systems:

• module system : radial bounds centred on the moduleOrigin

• strip system : phi bounds centred on the stripOrigin

The measurement will be done in the strip system, with r/phi local coordinates.

Public Types

enum BoundValues

Enumeration for the different bound values.

Values:

enumerator eMinR

enumerator eMaxR

enumerator eMinPhiRel

enumerator eMaxPhiRel

enumerator eAveragePhi

enumerator eOriginX

enumerator eOriginY

enumerator eSize

Public Functions

explicit AnnulusBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor - from fixed size array.

Parameters:

values – The bound values stored in a fixed size array

inline explicit AnnulusBounds(double minR, double maxR, double minPhiRel, double maxPhiRel, const Vector2 &moduleOrigin = {0, 0}, double avgPhi = 0) noexcept(false)

Default constructor from parameters.

Note

For morigin you need to actually calculate the cartesian offset

Parameters:

• minR – The inner radius of the annulus

• maxR – The outer radius of the annulus

• minPhiRel – The minimum phi relative to average phi

• maxPhiRel – The maximum phi relative to average phi

• moduleOrigin – The origin of the module in the strip frame

• avgPhi – The average phi value

inline virtual double binningValuePhi() const final

Return a reference phi for binning.

Returns:

Average phi angle for binning purposes

inline virtual double binningValueR() const final

Return a reference radius for binning.

Returns:

Average radius for binning purposes

virtual SquareMatrix2 boundToCartesianJacobian(const Vector2 &lposition) const final

Computes the bound to cartesian jacobian at a given local position.

Parameters:

lposition – is the local position at which the jacobian is computed

Returns:

the bound to cartesian jacobian

virtual SquareMatrix2 boundToCartesianMetric(const Vector2 &lposition) const final

Computes the bound to cartesian metric at a given local position.

Parameters:

lposition – is the local position at which the metric is computed

Returns:

the bound to cartesian metric

virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Note

For AnnulusBounds: returns pre-calculated center from corner vertices in strip polar coordinates (r, phi), accounting for average phi rotation

Returns:

Vector2 representing the center position in local coordinates

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

std::vector<Vector2> corners() const

This method returns the four corners of the bounds in polar coordinates Starting from the upper right (max R, pos locX) and proceeding clock-wise i.e.

(max R; pos locX), (min R; pos locX), (min R; neg loc X), (max R: neg locX)

Returns:

Vector of corner points in polar coordinates

inline virtual bool coversFullAzimuth() const final

Returns true for full phi coverage.

Returns:

True if the annulus covers the full azimuthal range, false otherwise

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

The value of the specified bound parameter

virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

inline virtual bool insideRadialBounds(double R, double tolerance = 0.) const final

Checks if this is inside the radial coverage given the a tolerance.

Parameters:

• R – The radius value to check

• tolerance – The tolerance for the check

Returns:

True if the radius is within bounds (plus tolerance), false otherwise

inline virtual bool isCartesian() const final

Check if the bound coordinates are cartesian.

Returns:

true if the bound coordinates are cartesian

Vector2 moduleOrigin() const

Returns moduleOrigin, but rotated out, so averagePhi is already considered.

The module origin needs to consider the rotation introduced by averagePhi

Returns:

The origin of the local frame

inline double phiMax() const

Returns the left angular edge of the module.

Returns:

The left side angle

inline double phiMin() const

Returns the right angular edge of the module.

Returns:

The right side angle

inline virtual double rMax() const final

This method returns outer radius.

Returns:

Maximum radius of the annulus

inline virtual double rMin() const final

This method returns inner radius.

Returns:

Minimum radius of the annulus

virtual std::ostream &toStream(std::ostream &sl) const final

Outstream operator.

Parameters:

sl – is the ostream to be dumped into

Returns:

Reference to the output stream

inline virtual BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

the bounds type

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

virtual std::vector<Vector2> vertices(unsigned int quarterSegments = 2u) const override

This method returns the xy coordinates of the four corners of the bounds in module coordinates (in x/y), and if quarterSegments is bigger or equal to 0, the curved part of the segment is included and approximated by the corresponding number of segments.

Starting from the upper right (max R, pos locX) and proceeding clock-wise i.e. (max R; pos locX), (min R; pos locX), (min R; neg loc X), (max R: neg locX)

Parameters:

quarterSegments – the number of segments used to approximate a quarter of a circle

Returns:

vector for vertices in 2D

Warning

doxygenclass: Cannot find class “Acts::AnyCharge” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

class AtlasBetheHeitlerApprox : public Acts::BetheHeitlerApprox

This class approximates the Bethe-Heitler distribution as a gaussian mixture.

To enable an approximation for continuous input variables, the weights, means and variances are internally parametrized as a Nth order polynomial.

Public Types

using Data = std::vector<PolyData>

Type alias for array of polynomial data for all components.

Public Functions

inline AtlasBetheHeitlerApprox(const Data &lowData, const Data &highData, bool lowTransform, bool highTransform, double lowLimit, double highLimit, bool clampToRange, double noChangeLimit, double singleGaussianLimit)

Construct the Bethe-Heitler approximation description with two parameterizations, one for lower ranges, one for higher ranges.

Is it assumed that the lower limit of the high-x/x0 data is equal to the upper limit of the low-x/x0 data.

Parameters:

• lowData – data for the lower x/x0 range

• highData – data for the higher x/x0 range

• lowTransform – whether the low data need to be transformed

• highTransform – whether the high data need to be transformed

• lowLimit – the upper limit for the low data

• highLimit – the upper limit for the high data

• clampToRange – whether to clamp the input x/x0 to the allowed range

• noChangeLimit – limit below which no change is applied

• singleGaussianLimit – limit below which a single Gaussian is used

inline virtual std::size_t maxComponents() const override

Returns the number of components the returned mixture will have.

Returns:

Number of components in the mixture

virtual std::span<Component> mixture(double xOverX0, const std::span<Component> mixture) const override

Generates the mixture from the polynomials and reweights them, so that the sum of all weights is 1.

Parameters:

• xOverX0 – pathlength in terms of the radiation length

• mixture – preallocated array to store the result

Returns:

the potentially modified input span containing the mixture

inline virtual bool validXOverX0(const double xOverX0) const override

Checks if an input is valid for the parameterization.

Parameters:

xOverX0 – pathlength in terms of the radiation length

Returns:

True if x/x0 is within valid range for this parameterization

Public Static Functions

static AtlasBetheHeitlerApprox loadFromFiles(const std::string &low_parameters_path, const std::string &high_parameters_path, double lowLimit, double highLimit, bool clampToRange, double noChangeLimit, double singleGaussianLimit)

Loads a parameterization from a file according to the Atlas file description.

Parameters:

• low_parameters_path – Path to the foo.par file that stores the parameterization for low x/x0

• high_parameters_path – Path to the foo.par file that stores the parameterization for high x/x0

• lowLimit – the upper limit for the low x/x0-data

• highLimit – the upper limit for the high x/x0-data

• clampToRange – forwarded to constructor

• noChangeLimit – forwarded to constructor

• singleGaussianLimit – forwarded to constructor

Returns:

AtlasBetheHeitlerApprox instance loaded from parameter files

struct PolyData

Polynomial coefficient sets for a Gaussian mixture component.

Public Members

std::vector<double> meanCoeffs

Polynomial coefficients for component mean.

std::vector<double> varCoeffs

Polynomial coefficients for component variance.

std::vector<double> weightCoeffs

Polynomial coefficients for component weight.

class AtlasStepper

the AtlasStepper implementation for the

This is based original stepper code from the ATLAS RungeKuttaPropagator

Public Types

using BoundParameters = BoundTrackParameters

Type alias for bound track parameters.

using BoundState = std::tuple<BoundParameters, Jacobian, double>

Type alias for bound state (parameters, jacobian, path length)

using Covariance = BoundMatrix

Type alias for covariance matrix.

using Jacobian = BoundMatrix

Type alias for Jacobian matrix.

Public Functions

inline explicit AtlasStepper(const Config &config)

Construct AtlasStepper with configuration.

Parameters:

config – Configuration containing magnetic field provider and other settings

inline explicit AtlasStepper(std::shared_ptr<const MagneticFieldProvider> bField)

Construct AtlasStepper with magnetic field provider.

Parameters:

bField – Shared pointer to magnetic field provider

inline double absoluteMomentum(const State &state) const

Absolute momentum accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Absolute momentum magnitude

inline Result<BoundState> boundState(State &state, const Surface &surface, bool transportCov = true, const FreeToBoundCorrection &freeToBoundCorrection = FreeToBoundCorrection(false)) const

Create and return the bound state at the current position.

Parameters:

• state – [in] State that will be presented as BoundState

• surface – [in] The surface to which we bind the state

• transportCov – [in] Flag steering covariance transport

• freeToBoundCorrection – [in] Correction for non-linearity effect during transform from free to bound

Returns:

A bound state:

• the parameters at the surface

• the stepwise jacobian towards it

• and the path length (from start - for ordering)

inline double charge(const State &state) const

Charge access.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Electric charge of the particle

inline BoundState curvilinearState(State &state, bool transportCov = true) const

Create and return a curvilinear state at the current position.

Parameters:

• state – [in] State that will be presented as CurvilinearState

• transportCov – [in] Flag steering covariance transport

Returns:

A curvilinear state:

• the curvilinear parameters at given position

• the stepweise jacobian towards it

• and the path length (from start - for ordering)

inline Vector3 direction(const State &state) const

Get particle direction from stepper state.

Parameters:

state – Stepper state containing track information

Returns:

3D unit direction vector

inline Result<Vector3> getField(State &state, const Vector3 &pos) const

Get the field for the stepping It checks first if the access is still within the Cell, and updates the cell if necessary, then it takes the field from the cell.

Parameters:

• state – [inout] is the stepper state associated with the track the magnetic field cell is used (and potentially updated)

• pos – [in] is the field position

Returns:

Magnetic field vector at the given position or error

inline double getStepSize(const State &state, ConstrainedStep::Type stype) const

Get the step size.

Parameters:

• state – [in] The stepping state (thread-local cache)

• stype – [in] The step size type to be returned

Returns:

Current step size for the specified constraint type

inline void initialize(State &state, const BoundParameters &par) const

Initialize stepper state from bound track parameters.

Parameters:

• state – Stepper state to initialize

• par – Bound track parameters containing initial conditions

inline void initialize(State &state, const BoundVector &boundParams, const std::optional<BoundMatrix> &cov, ParticleHypothesis particleHypothesis, const Surface &surface) const

Initialize stepper state from individual parameters.

Parameters:

• state – Stepper state to initialize

• boundParams – Bound track parameter vector

• cov – Optional covariance matrix

• particleHypothesis – Particle hypothesis (mass, charge)

• surface – Reference surface for bound parameters

inline State makeState(const Options &options) const

Create stepper state with given options.

Parameters:

options – Stepper options including magnetic field context

Returns:

Stepper state initialized with options and magnetic field cache

inline Vector3 momentum(const State &state) const

Get 3D momentum vector from stepper state.

Parameters:

state – Stepper state containing track information

Returns:

3D momentum vector

inline std::string outputStepSize(const State &state) const

Output the Step Size - single component.

Parameters:

state – [inout] The stepping state (thread-local cache)

Returns:

String representation of the current step size

inline double overstepLimit(const State&) const

Overstep limit.

Returns:

Overstep limit for this stepper (negative value)

inline const ParticleHypothesis &particleHypothesis(const State &state) const

Particle hypothesis.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Reference to the particle hypothesis used

inline Vector3 position(const State &state) const

Get particle position from stepper state.

Parameters:

state – Stepper state containing track information

Returns:

3D position vector

inline bool prepareCurvilinearState(State &state) const

If necessary fill additional members needed for curvilinearState.

Compute path length derivatives in case they have not been computed yet, which is the case if no step has been executed yet.

Parameters:

state – [inout] The stepping state (thread-local cache)

Returns:

true if nothing is missing after this call, false otherwise.

inline double qOverP(const State &state) const

Get charge over momentum from stepper state.

Parameters:

state – Stepper state containing track information

Returns:

Charge over momentum (q/p)

inline void releaseStepSize(State &state, ConstrainedStep::Type stype) const

Release the Step size.

Parameters:

• state – [inout] The stepping state (thread-local cache)

• stype – [in] The step size type to be released

inline Result<double> step(State &state, Direction propDir, const IVolumeMaterial *material) const

Perform the actual step on the state.

Note

The state contains the desired step size. It can be negative during backwards track propagation, and since we’re using an adaptive algorithm, it can be modified by the stepper class during propagation.

Parameters:

• state – [inout] State of the stepper

• propDir – is the direction of propagation

• material – is the optional volume material we are stepping through.

Returns:

the result of the step

inline double time(const State &state) const

Time access.

Parameters:

state – The stepping state to get time from

Returns:

Current time coordinate

inline void transportCovarianceToBound(State &state, const Surface &surface, const FreeToBoundCorrection& = FreeToBoundCorrection(false)) const

Method for on-demand transport of the covariance to a new curvilinear frame at current position, or direction of the state.

Parameters:

• state – [inout] State of the stepper

• surface – [in] is the surface to which the covariance is forwarded to

inline void transportCovarianceToCurvilinear(State &state) const

Method for on-demand transport of the covariance to a new curvilinear frame at current position, or direction of the state.

Parameters:

state – [inout] State of the stepper

inline void update(State &state, const FreeVector &parameters, const BoundVector &boundParams, const Covariance &covariance, const Surface &surface) const

The state update method.

Parameters:

• state – [inout] The stepper state for

• parameters – [in] The new free track parameters at start

• boundParams – [in] Corresponding bound parameters

• covariance – [in] The updated covariance matrix

• surface – [in] The surface used to update the pVector

inline void update(State &state, const Vector3 &uposition, const Vector3 &udirection, double qop, double time) const

Method to update momentum, direction and p.

Parameters:

• state – The state object

• uposition – the updated position

• udirection – the updated direction

• qop – the updated momentum value

• time – the update time

inline void updateStepSize(State &state, const NavigationTarget &target, Direction direction, ConstrainedStep::Type stype) const

Update step size.

It checks the status to the reference surface & updates the step size accordingly

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• target – [in] The NavigationTarget

• direction – [in] The propagation direction

• stype – [in] The step size type to be set

inline void updateStepSize(State &state, double stepSize, ConstrainedStep::Type stype) const

Update step size - explicitly with a double.

Parameters:

• state – [inout] The stepping state (thread-local cache)

• stepSize – [in] The step size value

• stype – [in] The step size type to be set

inline IntersectionStatus updateSurfaceStatus(State &state, const Surface &surface, std::uint8_t index, Direction navDir, const BoundaryTolerance &boundaryTolerance, double surfaceTolerance, ConstrainedStep::Type stype, const Logger &logger = getDummyLogger()) const

Update surface status.

This method intersect the provided surface and update the navigation step estimation accordingly (hence it changes the state). It also returns the status of the intersection to trigger onSurface in case the surface is reached.

Parameters:

• state – [inout] The stepping state (thread-local cache)

• surface – [in] The surface provided

• index – [in] The surface intersection index

• navDir – [in] The navigation direction

• boundaryTolerance – [in] The boundary check for this status update

• surfaceTolerance – [in] Surface tolerance used for intersection

• stype – [in] The step size type to be set

• logger – [in] Logger instance to use

Returns:

IntersectionStatus indicating how the surface was encountered

struct Config

Configuration for constructing an AtlasStepper.

Public Members

std::shared_ptr<const MagneticFieldProvider> bField

Magnetic field provider.

struct Options : public Acts::StepperPlainOptions

Stepper options extending plain stepper settings.

Public Functions

inline Options(const GeometryContext &gctx, const MagneticFieldContext &mctx)

Constructor from context objects.

Parameters:

• gctx – Geometry context

• mctx – Magnetic field context

inline void setPlainOptions(const StepperPlainOptions &options)

Set plain options.

Parameters:

options – Plain stepper options to set

struct State

Nested State struct for the local caching.

Public Functions

inline State(const Options &optionsIn, MagneticFieldProvider::Cache fieldCacheIn)

Constructor.

Template Parameters:

Type – of TrackParameters

Parameters:

• optionsIn – [in] The options for the stepper

• fieldCacheIn – [in] The magnetic field cache

Public Members

Covariance cov = Covariance::Zero()

Local covariance matrix storage.

const Covariance *covariance = nullptr

Pointer to external covariance matrix.

bool covTransport = false

Flag indicating whether covariance transport is enabled.

bool debug = false

Debug output the string where debug messages are stored (optionally)

std::size_t debugMsgWidth = 50

Width for debug message formatting.

std::size_t debugPfxWidth = 30

buffer & formatting for consistent output

std::string debugString = ""

String buffer for debug output messages.

Vector3 field = Vector3::Zero()

Current magnetic field vector.

MagneticFieldProvider::Cache fieldCache

It caches the current magnetic field cell and stays (and interpolates) within as long as this is valid.

See step() code for details.

double jacobian[eBoundSize * eBoundSize] = {}

Jacobian matrix storage for parameter derivatives.

double maxPathLength = 0

Maximum path length for this propagation.

bool mcondition = false

Flag indicating magnetic field boundary conditions.

bool needgradient = false

Flag indicating whether magnetic field gradients are needed.

bool newfield = true

Flag indicating new magnetic field evaluation needed.

std::size_t nSteps = 0

Total number of performed steps.

std::size_t nStepTrials = 0

Totoal number of attempted steps.

Options options

Stepper options for this propagation.

double parameters[eBoundSize] = {0., 0., 0., 0., 0., 0.}

Storage pattern of pVector /dL0 /dL1 /dPhi /the /dCM /dT X ->P[0] dX / P[ 8] P[16] P[24] P[32] P[40] P[48] Y ->P[1] dY / P[ 9] P[17] P[25] P[33] P[41] P[49] Z ->P[2] dZ / P[10] P[18] P[26] P[34] P[42] P[50] T ->P[3] dT/ P[11] P[19] P[27] P[35] P[43] P[51] Ax ->P[4] dAx/ P[12] P[20] P[28] P[36] P[44] P[52] Ay ->P[5] dAy/ P[13] P[21] P[29] P[37] P[45] P[53] Az ->P[6] dAz/ P[14] P[22] P[30] P[38] P[46] P[54] CM ->P[7] dCM/ P[15] P[23] P[31] P[39] P[47] P[55] Cache: P[56] - P[59].

ParticleHypothesis particleHypothesis = ParticleHypothesis::pion()

Particle hypothesis used for energy loss calculations.

double pathAccumulated = 0.

Accumulated path length during propagation.

double previousStepSize = 0.

Previous step size for overstep estimation.

std::array<double, 60> pVector = {}

Parameter vector for track state and derivatives.

bool state_ready = false

Flag indicating whether the state is ready for stepping.

StepperStatistics statistics

The statistics of the stepper.

double step = 0

Current step size.

ConstrainedStep stepSize

Constrained step size for adaptive integration.

bool useJacobian = false

Flag indicating whether Jacobian calculation is enabled.

template<AxisType type, AxisBoundaryType bdt = AxisBoundaryType::Open>
class Axis

calculate bin indices from a given binning structure

This class provides some basic functionality for calculating bin indices for a given binning configuration. Both equidistant as well as variable binning structures are supported.

Bin intervals are defined such that the lower bound is closed and the upper bound is open.

Template Parameters:

equidistant – flag whether binning is equidistant (true) or not (false)

class BinUtility

The BinUtility class that translated global and local position into a bins of a BinnedArray, most performant is equidistant binning without a transform, however, optionally a transform can be provided, e.g.

for binning on shifted object, the transform is usually shared with the geometric object the Array is defined on, for performance reasons, also the inverse transform is stored.

Public Functions

inline BinUtility()

Constructor for equidistant.

BinUtility(BinUtility &&sbu) = default

Move constructor.

Parameters:

sbu – is the source bin utility

inline explicit BinUtility(const BinningData &bData, const Transform3 &tForm = Transform3::Identity())

Constructor from BinningData directly.

Parameters:

• bData – is the provided binning data

• tForm – is the (optional) transform

BinUtility(const BinUtility &sbu) = default

Copy constructor.

Parameters:

sbu – is the source bin utility

inline explicit BinUtility(const DirectedProtoAxis &dpAxis)

Create from a DirectedProtoAxis.

Parameters:

dpAxis – the DirectedProtoAxis to be used

inline explicit BinUtility(const std::vector<DirectedProtoAxis> &dpAxes)

Create from several DirectedProtoAxis objects.

Parameters:

dpAxes – the DirectedProtoAxis to be used with axis directions

inline explicit BinUtility(const Transform3 &tForm)

Constructor with only a Transform3.

Parameters:

tForm – is the local to global transform

inline BinUtility(std::size_t bins, float min, float max, BinningOption opt = open, AxisDirection value = AxisDirection::AxisX, const Transform3 &tForm = Transform3::Identity())

Constructor for equidistant.

Parameters:

• bins – is the number of bins

• min – in the minimal value

• max – is the maximal value

• opt – is the binning option : open, closed

• value – is the axis direction : AxisX, AxisY, AxisZ, etc.

• tForm – is the (optional) transform

inline explicit BinUtility(std::vector<float> &bValues, BinningOption opt = open, AxisDirection value = AxisDirection::AxisPhi, const Transform3 &tForm = Transform3::Identity())

Constructor for arbitrary.

Parameters:

• bValues – is the boundary values of the binning

• opt – is the binning option : open, closed

• value – is the axis direction : AxisX, AxisY, AxisZ, etc.

• tForm – is the (optional) transform

~BinUtility() = default

Virtual Destructor.

inline std::size_t bin(const Vector2 &lposition, std::size_t ba = 0) const

Bin from a 2D vector (following local parameters definitions)

• no optional transform applied

• USE WITH CARE !!

You need to make sure that the local position is actually in the binning frame of the BinUtility

Parameters:

• lposition – is the local position to be set

• ba – is the bin dimension

Returns:

bin calculated from local

inline std::size_t bin(const Vector3 &position, std::size_t ba = 0) const

Bin from a 3D vector (already in binning frame)

Parameters:

• position – is the 3D position to be evaluated

• ba – is the bin dimension

Returns:

is the bin value

inline const std::vector<BinningData> &binningData() const

Return the binning data vector.

Returns:

Reference to the vector of binning data

inline AxisDirection binningValue(std::size_t ba = 0) const

The type/value of the binning.

Parameters:

ba – is the binaccessor

Returns:

the binning value of the accessor entry

inline std::size_t bins() const

Return the total number of bins.

Returns:

Total number of bins across all dimensions

inline std::size_t bins(std::size_t ba) const

Number of bins.

Parameters:

ba – is the binaccessor

Returns:

std::size_t is the bins of the accessor entry

inline std::array<std::size_t, 3> binTriple(const Vector3 &position) const

Bin-triple fast access.

• calculate the bin triple with one transform

Parameters:

position – is the 3D position to be evaluated

Returns:

is the bin value in 3D

inline std::size_t dimensions() const

First bin maximal value.

Returns:

the dimension of the binning data

inline bool inside(const Vector3 &position) const

Check if bin is inside from Vector2 - optional transform applied.

Parameters:

position – is the global position to be evaluated

Returns:

is a boolean check

inline std::size_t max(std::size_t ba = 0) const

First bin maximal value.

Parameters:

ba – is the binaccessor

Returns:

std::size_t is the maximal bin of the accessor entry

inline int nextDirection(const Vector3 &position, const Vector3 &direction, std::size_t ba = 0) const

Return the other direction for fast interlinking.

Parameters:

• position – is the global position for the next search

• direction – is the global position for the next search

• ba – is the bin accessor

Returns:

the next bin

inline BinUtility &operator+=(const BinUtility &gbu)

Operator+= to make multidimensional BinUtility.

Parameters:

gbu – is the additional BinUtility to be chosen

Returns:

Reference to this BinUtility after addition

BinUtility &operator=(BinUtility&&) = default

Move assignment operator.

Returns:

Reference to this BinUtility after move assignment

inline BinUtility &operator=(const BinUtility &sbu)

Assignment operator.

Parameters:

sbu – is the source bin utility

Returns:

Reference to this BinUtility after assignment

inline bool operator==(const BinUtility &other) const

Equality operator.

Parameters:

other – The other BinUtility to compare with

Returns:

True if the BinUtilities are equal, false otherwise

inline std::size_t serialize(const std::array<std::size_t, 3> &bin) const

Serialize the bin triple.

• this creates a simple std::size_t from a triple object

Parameters:

bin – is the bin to be serialized

Returns:

Serialized bin index as a single std::size_t value

inline std::ostream &toStream(std::ostream &sl, const std::string &indent = "") const

Output Method for std::ostream, to be overloaded by child classes.

Parameters:

• sl – is the ostream to be dumped into

• indent – the current indentation

Returns:

the input stream

inline std::string toString(const std::string &indent = "") const

Output into a string.

Parameters:

indent – the current indentation

Returns:

a string with the stream information

inline const Transform3 &transform() const

Transform applied to global positions before lookup.

Returns:

Shared pointer to transform

Friends

inline friend std::ostream &operator<<(std::ostream &sl, const BinUtility &bgen)

Overload of << operator for std::ostream for debug output.

class BinnedSurfaceMaterial : public Acts::ISurfaceMaterial

It extends the ISurfaceMaterial base class and is an array pf MaterialSlab.

This is not memory optimised as every bin holds one material property object.

Public Functions

BinnedSurfaceMaterial() = delete

Default Constructor - deleted.

BinnedSurfaceMaterial(BinnedSurfaceMaterial &&bsm) = default

Copy Move Constructor.

Parameters:

bsm – is the source object to be copied

BinnedSurfaceMaterial(const BinnedSurfaceMaterial &bsm) = default

Copy Constructor.

Parameters:

bsm – is the source object to be copied

BinnedSurfaceMaterial(const BinUtility &binUtility, MaterialSlabMatrix fullProperties, double splitFactor = 0., MappingType mappingType = MappingType::Default)

Explicit constructor with only full MaterialSlab, for two-dimensional binning.

The split factors:

• 1. : oppositePre

• 0. : alongPre ===> 1 Dimensional array

Parameters:

• binUtility – defines the binning structure on the surface (copied)

• fullProperties – is the vector of properties as recorded (moved)

• splitFactor – is the pre/post splitting directive

• mappingType – is the type of surface mapping associated to the surface

BinnedSurfaceMaterial(const BinUtility &binUtility, MaterialSlabVector fullProperties, double splitFactor = 0., MappingType mappingType = MappingType::Default)

Explicit constructor with only full MaterialSlab, for one-dimensional binning.

The split factors:

• 1. : oppositePre

• 0. : alongPre ===> 1 Dimensional array

Parameters:

• binUtility – defines the binning structure on the surface (copied)

• fullProperties – is the vector of properties as recorded (moved)

• splitFactor – is the pre/post splitting directive

• mappingType – is the type of surface mapping associated to the surface

~BinnedSurfaceMaterial() override = default

Destructor.

inline const BinUtility &binUtility() const

Return the BinUtility.

Returns:

Reference to the bin utility used for material binning

inline const MaterialSlabMatrix &fullMaterial() const

Retrieve the entire material slab matrix.

Returns:

Reference to the complete matrix of material slabs

virtual const MaterialSlab &materialSlab(const Vector2 &lp) const final

Return method for full material description of the Surface.

• from local coordinate on the surface

Parameters:

lp – is the local position used for the (eventual) lookup

Returns:

const MaterialSlab

const MaterialSlab &materialSlab(const Vector2 &lp) const = 0

Return method for full material description of the Surface.

• from local coordinate on the surface

Parameters:

lp – is the local position used for the (eventual) lookup

Returns:

const MaterialSlab

MaterialSlab materialSlab(const Vector2 &lp, Direction pDir, MaterialUpdateMode mode) const

Return method for fully scaled material description of the Surface.

• from local coordinate on the surface

Parameters:

• lp – is the local position used for the (eventual) lookup

• pDir – is the positive direction through the surface

• mode – is the material update directive

Returns:

MaterialSlab

virtual const MaterialSlab &materialSlab(const Vector3 &gp) const final

Return method for full material description of the Surface.

• from the global coordinates

Parameters:

gp – is the global position used for the (eventual) lookup

Returns:

const MaterialSlab

const MaterialSlab &materialSlab(const Vector3 &gp) const = 0

Return method for full material description of the Surface.

• from the global coordinates

Parameters:

gp – is the global position used for the (eventual) lookup

Returns:

const MaterialSlab

MaterialSlab materialSlab(const Vector3 &gp, Direction pDir, MaterialUpdateMode mode) const

Return method for full material description of the Surface.

• from the global coordinates

Parameters:

• gp – is the global position used for the (eventual) lookup

• pDir – is the positive direction through the surface

• mode – is the material update directive

Returns:

MaterialSlab

BinnedSurfaceMaterial &operator=(BinnedSurfaceMaterial &&bsm) = default

Assignment Move operator.

Parameters:

bsm – The source object to move from

Returns:

Reference to this object after move assignment

BinnedSurfaceMaterial &operator=(const BinnedSurfaceMaterial &bsm) = default

Assignment operator.

Parameters:

bsm – The source object to copy from

Returns:

Reference to this object after copy assignment

virtual BinnedSurfaceMaterial &scale(double factor) final

Scale operation.

Parameters:

factor – is the scale factor for the full material

Returns:

Reference to this object after scaling

virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream, to be overloaded by child classes.

Parameters:

sl – The output stream to write to

Returns:

Reference to the output stream after writing

class BinningData

This class holds all the data necessary for the bin calculation.

phi has a very particular behaviour:

• there’s the change around +/- PI

• it can be multiplicative or additive multiplicative : each major bin has the same sub structure i.e. first binnning

structure is equidistant additive : sub structure replaces one bin (and one bin only)

Public Functions

BinningData() = default

inline BinningData(AxisDirection bValue, float bMin, float bMax)

Constructor for 0D binning.

Parameters:

• bValue – is the axis direction AxisX, AxisY, etc.

• bMin – is the minimum value

• bMax – is the maximum value

inline BinningData(BinningOption bOption, AxisDirection bValue, const std::vector<float> &bBoundaries, std::unique_ptr<const BinningData> sBinData = nullptr)

Constructor for non-equidistant binning.

Parameters:

• bOption – is the binning option : open / closed

• bValue – is the axis direction : AxisX, AxisY, etc.

• bBoundaries – are the bin boundaries

• sBinData – is (optional) sub structure

inline BinningData(BinningOption bOption, AxisDirection bValue, std::size_t bBins, float bMin, float bMax, std::unique_ptr<const BinningData> sBinData = nullptr, bool sBinAdditive = false)

Constructor for equidistant binning and optional sub structure can be multiplicative or additive.

Parameters:

• bOption – is the binning option : open, closed

• bValue – is the axis direction: Axis, AxisY, etc.

• bBins – is number of equidistant bins

• bMin – is the minimum value

• bMax – is the maximum value

• sBinData – is (optional) sub structure

• sBinAdditive – is the prescription for the sub structure

inline BinningData(const BinningData &bdata)

Copy constructor.

Parameters:

bdata – is the source object

inline explicit BinningData(const DirectedProtoAxis &dpAxis)

Constructor from DirectedProtoAxis.

Parameters:

dpAxis – is the ProtoAxis object

~BinningData() = default

inline std::size_t bins() const

Return the number of bins - including sub bins.

Returns:

Total number of bins including sub-bins

inline const std::vector<float> &boundaries() const

Return the boundaries - including sub boundaries.

Returns:

vector of floats indicating the boundary values

inline float center(std::size_t bin) const

Get the center value of a bin.

Parameters:

bin – is the bin for which the center value is requested

Returns:

float value according to the bin center

inline float centerValue(std::size_t bin) const

access to the center value this uses the bin boundary vector, it also works with sub structure

Parameters:

bin – is the bin for which the value is requested, if bin > nbins it is set to max

Returns:

the center value of the bin is given

inline bool inside(const Vector2 &lposition) const

Check if bin is inside from Vector2.

Parameters:

lposition – is the search position in global coordinated

Returns:

boolean if this is inside() method is true

inline bool inside(const Vector3 &position) const

Check if bin is inside from Vector3.

Parameters:

position – is the search position in global coordinated

Returns:

boolean if this is inside() method is true

inline int nextDirection(const Vector3 &position, const Vector3 &dir) const

Layer next direction is needed.

Parameters:

• position – is the start search position

• dir – is the direction

Returns:

integer that indicates which direction to move

inline BinningData &operator=(const BinningData &bdata)

Assignment operator.

Parameters:

bdata – is the source object

Returns:

Reference to this BinningData after assignment

inline bool operator==(const BinningData &bData) const

Equality operator.

Parameters:

bData – is the binning data to be checked against

Returns:

a boolean indicating if they are the same

inline std::size_t search(float value) const

Generic search - forwards to correct function pointer.

Parameters:

value – is the searchvalue as float

Returns:

bin according tot this

inline std::size_t searchGlobal(const Vector3 &position) const

Generic search from a 3D position &#8212; corresponds to global coordinate schema.

Parameters:

position – is the search position in global coordinated

Returns:

bin according tot this

inline std::size_t searchLocal(const Vector2 &lposition) const

Generic search from a 2D position &#8212; corresponds to local coordinate schema.

Parameters:

lposition – is the search position in local coordinated

Returns:

bin according tot this

inline std::size_t searchWithSubStructure(float value) const

Generic search with sub structure.

• forwards to correct function pointer

Parameters:

value – is the searchvalue as float

Returns:

bin according tot this

inline std::string toString(const std::string &indent = "") const

String screen output method.

Parameters:

indent – the current indentation

Returns:

a string containing the screen information

inline float value(const Vector2 &lposition) const

Take the right float value.

Parameters:

lposition – assumes the correct local position expression

Returns:

float value according to the binning setup

inline float value(const Vector3 &position) const

Take the right float value.

Parameters:

position – is the global position

Returns:

float value according to the binning setup

inline float width(std::size_t bin) const

Get the width of a bin.

Parameters:

bin – is the bin for which the width is requested

Returns:

float value of width

Public Members

AxisDirection binvalue = {}

axis direction: AxisX, AxisY, AxisZ, …

float max = {}

maximum value

float min = {}

minimum value

BinningOption option = {}

binning option: open, closed

float step = {}

binning step

bool subBinningAdditive = {}

sub structure: additive or multiplicative

std::unique_ptr<const BinningData> subBinningData

sub structure: describe some sub binning

BinningType type = {}

binning type: equidistant, arbitrary

bool zdim = {}

zero dimensional binning : direct access

class BoundaryTolerance

Variant-like type to capture different types of boundary tolerances.

Since our track hypothesis comes with uncertainties, we sometimes need to check if the track is not just within the boundary of the surface but also within a certain tolerance. This class captures different parameterizations of such tolerances. The surface class will then use these tolerances to check if a ray is within the boundary+tolerance of the surface.

Different types of boundary tolerances implemented:

• Infinite: Infinite tolerance i.e. no boundary check will be performed.

• None: No tolerance i.e. exact boundary check will be performed.

• AbsoluteEuclidean: Absolute tolerance in Euclidean distance. The tolerance is defined as a single absolute value for the Euclidean distance. The Euclidean distance can be calculated via the local bound Jacobian and the bound coordinate residual. If the distance is within the tolerance, the boundary check is considered as passed.

• Chi2Bound: Chi2 tolerance in bound coordinates. The tolerance is defined as a maximum chi2 value and a weight matrix, which is the inverse of the bound covariance matrix. The chi2 value is calculated from the bound coordinates residual and the weight matrix. If the chi2 value is below the maximum chi2 value, the boundary check is considered as passed.

• Chi2Cartesian: Chi2 tolerance in Cartesian coordinates. Similar to Chi2Bound, but the chi2 value is calculated in Cartesian coordinates.

The bound coordinates residual is defined as the difference between the point checked and the closest point on the boundary. The Jacobian is the derivative of the bound coordinates with respect to the Cartesian coordinates.

Public Types

enum class ToleranceMode

Enumeration defining how tolerance should be applied to boundaries.

Values:

enumerator Extend

enumerator None

enumerator Shrink

Public Functions

BoundaryTolerance(BoundaryTolerance &&other) noexcept = default

Move constructor.

Parameters:

other – The BoundaryTolerance object to move

BoundaryTolerance(const BoundaryTolerance &other) noexcept = default

Copy constructor.

Parameters:

other – The BoundaryTolerance object to copy

inline constexpr const AbsoluteEuclideanParams &asAbsoluteEuclidean() const

Get the tolerance as absolute Euclidean.

Returns:

Reference to the absolute Euclidean tolerance parameters

inline constexpr const Chi2BoundParams &asChi2Bound() const

Get the tolerance as chi2 bound.

Returns:

Reference to the chi2 bound tolerance parameters

inline constexpr const Chi2CartesianParams &asChi2Cartesian() const

Get the tolerance as chi2 Cartesian.

Returns:

Reference to the chi2 Cartesian tolerance parameters

inline constexpr bool hasAbsoluteEuclidean() const

Check if the tolerance is absolute with Euclidean distance.

Returns:

True if configured for absolute Euclidean tolerance, false otherwise

inline constexpr bool hasChi2Bound() const

Check if the tolerance is chi2 with bound coordinates.

Returns:

True if configured for chi2 tolerance in bound coordinates, false otherwise

inline constexpr bool hasChi2Cartesian() const

Check if the tolerance is chi2 with Cartesian coordinates.

Returns:

True if configured for chi2 tolerance in Cartesian coordinates, false otherwise

inline constexpr bool isInfinite() const

Check if the tolerance is infinite.

Returns:

True if configured for infinite tolerance, false otherwise

inline constexpr bool isNone() const

Check if the is no tolerance.

Returns:

True if configured for no tolerance (exact checking), false otherwise

bool isTolerated(const Vector2 &boundDelta, const SquareMatrix2 &boundToCartesian) const

Check if the bound position delta is tolerated.

Parameters:

• boundDelta – The delta in bound coordinates

• boundToCartesian – The transformation matrix from bound to Cartesian

Returns:

True if the delta is within tolerance, false otherwise

BoundaryTolerance &operator=(BoundaryTolerance &&other) noexcept = default

Move assignment operator.

Parameters:

other – The BoundaryTolerance object to move

Returns:

Reference to this BoundaryTolerance after moving

BoundaryTolerance &operator=(const BoundaryTolerance &other) noexcept = default

Copy assignment operator.

Parameters:

other – The BoundaryTolerance object to copy

Returns:

Reference to this BoundaryTolerance after copying

ToleranceMode toleranceMode() const

Get the tolerance mode.

Returns:

ToleranceMode indicating how the tolerance should be applied

Public Static Functions

static inline constexpr auto AbsoluteEuclidean(double tolerance) noexcept

Absolute tolerance in Euclidean distance.

Parameters:

tolerance – The tolerance value in Euclidean distance

Returns:

BoundaryTolerance configured for absolute Euclidean tolerance

static inline auto Chi2Bound(const SquareMatrix2 &weight, double maxChi2) noexcept

Chi2 tolerance in bound coordinates.

Parameters:

• weight – The weight matrix for the chi2 calculation

• maxChi2 – The maximum chi2 value allowed

Returns:

BoundaryTolerance configured for chi2 tolerance in bound coordinates

static inline auto Chi2Cartesian(const SquareMatrix2 &weight, double maxChi2) noexcept

Chi2 tolerance in Cartesian coordinates.

Parameters:

• weight – The weight matrix for the chi2 calculation

• maxChi2 – The maximum chi2 value allowed

Returns:

BoundaryTolerance configured for chi2 tolerance in Cartesian coordinates

static inline constexpr auto Infinite() noexcept

Infinite tolerance i.e.

no boundary check

Returns:

BoundaryTolerance configured for infinite tolerance

static inline constexpr auto None() noexcept

No tolerance i.e.

exact boundary check

Returns:

BoundaryTolerance configured for no tolerance (exact checking)

struct AbsoluteEuclideanParams

Parameters for absolute Euclidean boundary tolerance.

Public Members

double tolerance = {}

Tolerance value.

struct Chi2BoundParams

Parameters for chi2 boundary tolerance in bound coordinates.

Public Functions

inline Eigen::Map<SquareMatrix2> weightMatrix()

Get weight matrix as Eigen matrix.

Returns:

Mapped weight matrix

inline Eigen::Map<const SquareMatrix2> weightMatrix() const

Get weight matrix as const Eigen matrix.

Returns:

Mapped weight matrix

Public Members

double maxChi2 = {}

Maximum chi2 value.

std::array<double, 4> weight = {}

Weight matrix stored as flat array.

struct Chi2CartesianParams

Parameters for chi2 boundary tolerance in Cartesian coordinates.

Public Functions

inline Eigen::Map<SquareMatrix2> weightMatrix()

Get weight matrix as Eigen matrix.

Returns:

Mapped weight matrix

inline Eigen::Map<const SquareMatrix2> weightMatrix() const

Get weight matrix as const Eigen matrix.

Returns:

Mapped weight matrix

Public Members

double maxChi2 = {}

Maximum chi2 value.

std::array<double, 4> weight = {}

Weight matrix stored as flat array.

struct InfiniteParams

struct NoneParams

class CalibrationContext : public ContextType

This is the central definition of the Acts payload object regarding detector calibration.

It is propagated through the code to allow for event/thread dependent calibration

template<typename propagator_t, typename track_container_t>
class CombinatorialKalmanFilter

Combinatorial Kalman filter to find tracks.

The CombinatorialKalmanFilter contains an Actor and a Sequencer sub-class. The Sequencer has to be part of the Navigator of the Propagator in order to initialize and provide the measurement surfaces.

The Actor is part of the Propagation call and does the Kalman update. Updater and Calibrator are given to the Actor for further use:

• The Updater is the implemented kalman updater formalism, it runs via a visitor pattern through the measurements.

Measurements are not required to be ordered for the CombinatorialKalmanFilter, measurement ordering needs to be figured out by the navigation of the propagator.

The void components are provided mainly for unit testing.

Template Parameters:

propagator_t – Type of the propagator

Public Functions

CombinatorialKalmanFilter() = delete

Default constructor is deleted.

inline explicit CombinatorialKalmanFilter(propagator_t pPropagator, std::unique_ptr<const Logger> _logger = getDefaultLogger("CKF", Logging::INFO))

Constructor with propagator and logging level.

Parameters:

• pPropagator – The propagator used for the track finding

• _logger – The logger for messages

inline auto findTracks(const BoundTrackParameters &initialParameters, const CombinatorialKalmanFilterOptions<track_container_t> &tfOptions, track_container_t &trackContainer) const -> Result<std::vector<typename std::decay_t<decltype(trackContainer)>::TrackProxy>>

Combinatorial Kalman Filter implementation, calls the Kalman filter.

Note

The input measurements are given in the form of SourceLinks. It’s calibrator_t's job to turn them into calibrated measurements used in the track finding.

Parameters:

• initialParameters – The initial track parameters

• tfOptions – CombinatorialKalmanFilterOptions steering the track finding

• trackContainer – Track container in which to store the results

Returns:

a container of track finding result for all the initial track parameters

inline auto findTracks(const BoundTrackParameters &initialParameters, const CombinatorialKalmanFilterOptions<track_container_t> &tfOptions, track_container_t &trackContainer, typename track_container_t::TrackProxy rootBranch) const -> Result<std::vector<typename std::decay_t<decltype(trackContainer)>::TrackProxy>>

Combinatorial Kalman Filter implementation, calls the Kalman filter.

Note

The input measurements are given in the form of SourceLinks. It’s calibrator_t's job to turn them into calibrated measurements used in the track finding.

Parameters:

• initialParameters – The initial track parameters

• tfOptions – CombinatorialKalmanFilterOptions steering the track finding

• trackContainer – Track container in which to store the results

• rootBranch – The track to be used as the root branch

Returns:

a container of track finding result for all the initial track parameters

class ConeBounds : public Acts::SurfaceBounds

Bounds for a conical surface, the opening angle is stored in \( \tan(\alpha) \) and always positively defined.

The cone can open to both sides, steered by \( z_min \) and \( z_max \).

Public Types

enum BoundValues

Enumeration for the bound values.

Values:

enumerator eAlpha

enumerator eMinZ

enumerator eMaxZ

enumerator eHalfPhiSector

enumerator eAveragePhi

enumerator eSize

Public Functions

explicit ConeBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor - from parameters array.

Parameters:

values – The parameter array

ConeBounds(double alpha, bool symm, double halfphi = std::numbers::pi, double avphi = 0.) noexcept(false)

Constructor - open cone with alpha, by default a full cone but optionally can make a conical section.

Parameters:

• alpha – is the opening angle of the cone

• symm – is the boolean indicating if the cone is symmetric in +/- z

• halfphi – is the half opening angle (default is pi)

• avphi – is the phi value around which the bounds are opened (default=0)

ConeBounds(double alpha, double minz, double maxz, double halfphi = std::numbers::pi, double avphi = 0.) noexcept(false)

Constructor - open cone with alpha, minz and maxz, by default a full cone but can optionally make it a conical section.

Parameters:

• alpha – is the opening angle of the cone

• minz – cone expanding from minimal z

• maxz – cone expanding to maximal z

• halfphi – is the half opening angle (default is pi)

• avphi – is the phi value around which the bounds are opened (default=0)

inline virtual SquareMatrix2 boundToCartesianJacobian(const Vector2 &lposition) const final

Computes the bound to cartesian jacobian at a given local position.

Parameters:

lposition – is the local position at which the jacobian is computed

Returns:

the bound to cartesian jacobian

inline virtual SquareMatrix2 boundToCartesianMetric(const Vector2 &lposition) const final

Computes the bound to cartesian metric at a given local position.

Parameters:

lposition – is the local position at which the metric is computed

Returns:

the bound to cartesian metric

virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Note

For ConeBounds: returns (averagePhi, (minZ + maxZ)/2) in cone coordinates

Returns:

Vector2 representing the center position in local coordinates

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

Value of the specified bound parameter

virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

inline virtual bool isCartesian() const final

Check if the bound coordinates are cartesian.

Returns:

true if the bound coordinates are cartesian

inline double r(double z) const

Return the radius at a specific z values.

Parameters:

z – is the z value for which r is requested

Returns:

is the r value associated with z

inline double tanAlpha() const

Return tangent of alpha (pre-computed)

Returns:

Tangent of the cone half-angle

virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream.

Parameters:

sl – is the ostrea into which the dump is done

Returns:

is the input object

inline virtual BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

the bounds type

virtual std::vector<double> values() const final

Access method for bound values, this is a dynamically sized vector containing the parameters needed to describe these bounds.

Returns:

of the stored values for this SurfaceBounds object

class ConeLayer : public virtual Acts::ConeSurface, public Acts::Layer

Class to describe a conical detector layer for tracking, it inherits from both, Layer base class and ConeSurface class.

Public Functions

ConeLayer() = delete

ConeLayer(const ConeLayer &cla) = delete

~ConeLayer() override = default

ConeLayer &operator=(const ConeLayer&) = delete

virtual const ConeSurface &surfaceRepresentation() const override

Transforms the layer into a Surface representation for extrapolation.

Returns:

Const reference to the cone surface representing this layer

virtual ConeSurface &surfaceRepresentation() override

Non-const version of surface representation access.

Returns:

Mutable reference to the cone surface

Public Static Functions

static std::shared_ptr<ConeLayer> create(const Transform3 &transform, std::shared_ptr<const ConeBounds> cbounds, std::unique_ptr<SurfaceArray> surfaceArray, double thickness = 0., std::unique_ptr<ApproachDescriptor> ad = nullptr, LayerType laytyp = active)

Factory for shared layer.

Parameters:

• transform – is the 3D transform that positions the layer in 3D frame

• cbounds – is the conical bound description

• surfaceArray – is the array of sensitive surfaces

• thickness – is the layer thickness along the normal axis

• ad – is the approach descriptor for navigation towards the layer

• laytyp – is the layer type

Returns:

is a shared pointer to a layer

class ConeSurface : public Acts::RegularSurface

Class for a conical surface in the Tracking geometry.

It inherits from Surface.

The ConeSurface is special since no corresponding Track parameters exist since they’re numerical instable at the tip of the cone. Propagations to a cone surface will be returned in curvilinear coordinates.

Subclassed by Acts::ConeLayer

Public Functions

virtual AlignmentToPathMatrix alignmentToPathDerivative(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Calculate the derivative of path length at the geometry constraint or point-of-closest-approach w.r.t.

alignment parameters of the surface (i.e. local frame origin in global 3D Cartesian coordinates and its rotation represented with extrinsic Euler angles)

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Derivative of path length w.r.t. the alignment parameters

void assignSurfaceBounds(std::shared_ptr<const ConeBounds> newBounds)

Overwrite the existing surface bounds with new ones.

Parameters:

newBounds – Pointer to the new bounds

virtual const ConeBounds &bounds() const final

This method returns the ConeBounds by reference.

Returns:

Reference to the cone bounds

const std::shared_ptr<const ConeBounds> &boundsPtr() const

This method returns the shared_ptr to the ConeBounds.

Returns:

Shared pointer to the cone bounds

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final

Convert a global position to a local one this is the most generic interface, which is implemented by all surfaces.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be converted

• direction – is the direction of the local position (ignored for RegularSurface)

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const final

Global to local transformation.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be transformed

• tolerance – optional tolerance within which a point is considered valid on surface

Returns:

a Result<Vector2> which can be !ok() if the operation fails

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const = 0

Convert a global position to a local one.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be converted

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual MultiIntersection3D intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), double tolerance = s_onSurfaceTolerance) const final

Straight line intersection schema from position/direction.

If possible returns both solutions for the cylinder

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The position to start from

• direction – The direction at start

• boundaryTolerance – the Boundary Check

• tolerance – the tolerance used for the intersection

Returns:

MultiIntersection3D object (contains intersection & surface)

virtual Matrix<2, 3> localCartesianToBoundLocalDerivative(const GeometryContext &gctx, const Vector3 &position) const final

Calculate the derivative of bound track parameters local position w.r.t.

position in local 3D Cartesian coordinates

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The position of the parameters in global

Returns:

Derivative of bound local position w.r.t. position in local 3D cartesian coordinates

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const final

Local to global transformation.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is the local position to be transformed

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Local to global transformation.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const final

Local to global transformation.

This is the most generic interface, which is implemented by all surfaces.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

• direction – global 3D momentum direction (ignored for RegularSurface)

Returns:

The global position by value

virtual std::string name() const override

Return properly formatted class name for screen output.

Returns:

String representation of the class name

virtual Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const final

Return method for surface normal information.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is the local position at normal vector request

Returns:

Vector3 normal vector in global frame

Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Calculate the normal vector of the surface This overload requires an on-surface local position.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is the local position where the normal vector is constructed

Returns:

normal vector by value

Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const final

Calculate the normal vector of the surface This overload is fully generic, fulfills the Surface interface and accepts a global position and a direction.

For RegularSurface this is equivalent to the normal overload, ignoring the direction

Parameters:

• gctx – The current geometry context object, e.g. alignment

• pos – is the global position where the normal vector is constructed

• direction – is the direction of the normal vector (ignored for RegularSurface)

Returns:

Normal vector at the given position

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const final

Return method for surface normal information.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position as normal vector base

Returns:

Vector3 normal vector in global frame

Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const = 0

Calculate the normal vector of the surface This overload accepts a global position.

Parameters:

• position – is the global position where the normal vector is constructed

• gctx – The current geometry context object, e.g. alignment

Returns:

normal vector by value

ConeSurface &operator=(const ConeSurface &other)

Assignment operator.

Parameters:

other – is the source surface for the assignment

Returns:

Reference to this ConeSurface after assignment

virtual double pathCorrection(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

The pathCorrection for derived classes with thickness.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global potion at the correction point

• direction – is the momentum direction at the correction point

Returns:

is the path correction due to incident angle

virtual Polyhedron polyhedronRepresentation(const GeometryContext &gctx, unsigned int quarterSegments = 2u) const override

Return a Polyhedron for the surfaces.

Note

The phi extrema points at (-pi, -1/2 pi, 0, 1/2 pi) that fall within the surface will be inserted to guarantee an appropriate extent measurement in x and y

Parameters:

• gctx – The current geometry context object, e.g. alignment

• quarterSegments – Number of segments used to approximate a quarter

Returns:

A list of vertices and a face/facett description of it

virtual RotationMatrix3 referenceFrame(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Return the measurement frame - this is needed for alignment, in particular for StraightLine and Perigee Surface.

• the default implementation is the RotationMatrix3 of the transform

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position where the measurement frame is constructed

• direction – is the momentum direction used for the measurement frame construction

Returns:

matrix that indicates the measurement frame

virtual Vector3 referencePosition(const GeometryContext &gctx, AxisDirection aDir) const final

The binning position method - is overloaded for r-type binning.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• aDir – defines the direction of binning applied in the global frame

Returns:

The return type is a vector for positioning in the global frame

virtual Vector3 rotSymmetryAxis(const GeometryContext &gctx) const

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

The local z axis vector

virtual SurfaceType type() const override

Return the surface type.

Returns:

Surface type identifier

class ConeVolumeBounds : public Acts::VolumeBounds

Volume bound class for describing conical volumes either with cylindrical inlay or outer boundary, it also allows for a sectoral description.

Public Types

enum BoundValues

for readability

Values:

enumerator eInnerAlpha

enumerator eInnerOffsetZ

enumerator eOuterAlpha

enumerator eOuterOffsetZ

enumerator eHalfLengthZ

enumerator eAveragePhi

enumerator eHalfPhiSector

enumerator eSize

Public Functions

ConeVolumeBounds() = delete

ConeVolumeBounds(const ConeVolumeBounds &cobo) = default

Copy constructor.

Parameters:

cobo – Cone volume bounds to copy

inline explicit ConeVolumeBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor - from a fixed size array.

Parameters:

values – The bound values

ConeVolumeBounds(double cylinderR, double alpha, double offsetZ, double halflengthZ, double averagePhi, double halfPhiSector) noexcept(false)

Constructor - for general cylidner-cone setups.

Note

depending on cylinderR > coneR it is constructing a cone with cylindrical cutout or a cylinder with conical cutout

Parameters:

• cylinderR – The inner radius of the cylinder

• alpha – The opening angle of the cone (0 if no cone)

• offsetZ – The tip z position in of the cone, w.r.t center

• halflengthZ – The minimum z value of the inner and outer cones

• averagePhi – The phi orientation of the sector (defaulted to 0)

• halfPhiSector – The opening angle phi sector

ConeVolumeBounds(double innerAlpha, double innerOffsetZ, double outerAlpha, double outerOffsetZ, double halflengthZ, double averagePhi, double halfPhiSector) noexcept(false)

Constructor - for general cone-cone setups.

Parameters:

• innerAlpha – The opening angle of the inner cone (0 if no cone)

• innerOffsetZ – The tip z position in of the inner cone, w.r.t center

• outerAlpha – The opening angle of the outer cone (0 if no cone)

• outerOffsetZ – The tip z position in of the outer cone, w.r.t center

• halflengthZ – The minimum z value of the inner and outer cones

• averagePhi – The phi orientation of the sector

• halfPhiSector – The opening angle phi sector

~ConeVolumeBounds() override = default

virtual Volume::BoundingBox boundingBox(const Transform3 *trf = nullptr, const Vector3 &envelope = {0, 0, 0}, const Volume *entity = nullptr) const final

Construct bounding box for this shape.

Parameters:

• trf – Optional transform

• envelope – Optional envelope to add / subtract from min/max

• entity – Entity to associate this bounding box with

Returns:

Constructed bounding box

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

Value of the specified bound parameter

double innerRmax() const

Return the derived inner maximum radius.

Returns:

Inner maximum radius at the largest z position

double innerRmin() const

Return the derived inner minimum radius.

Returns:

Inner minimum radius at the smallest z position

double innerTanAlpha() const

Return the derived inner tangent of the cone opening angle.

Returns:

Tangent of the inner cone opening angle

virtual bool inside(const Vector3 &pos, double tol = 0.) const final

This method checks if position in the 3D volume frame is inside the cylinder.

Parameters:

• pos – is the position in volume frame to be checked

• tol – is the absolute tolerance to be applied

Returns:

True if the position is inside the cone volume bounds

ConeVolumeBounds &operator=(const ConeVolumeBounds &cobo) = default

Assignment operator.

Parameters:

cobo – Cone volume bounds to assign

Returns:

Reference to this object

virtual std::vector<OrientedSurface> orientedSurfaces(const Transform3 &transform = Transform3::Identity()) const final

Oriented surfaces, i.e.

the decomposed boundary surfaces and the according navigation direction into the volume given the normal vector on the surface

It will throw an exception if the orientation prescription is not adequate

Parameters:

transform – is the 3D transform to be applied to the boundary surfaces to position them in 3D space

Returns:

a vector of surfaces bounding this volume

double outerRmax() const

Return the derived outer maximum radius.

Returns:

Outer maximum radius at the largest z position

double outerRmin() const

Return the derived outer minimum radius.

Returns:

Outer minimum radius at the smallest z position

double outerTanAlpha() const

Return the derived outer tangent of the cone opening angle.

Returns:

Tangent of the outer cone opening angle

virtual std::ostream &toStream(std::ostream &os) const final

Output Method for std::ostream.

Parameters:

os – is ostream operator to be dumped into

Returns:

Reference to the output stream after writing

inline virtual VolumeBounds::BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

is a BoundsType enum

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

class ConstantBField : public Acts::MagneticFieldProvider

The simplest magnetic field implementation is a constant field, which returns the same field values at every queried location.

Public Functions

inline explicit ConstantBField(Vector3 B)

Construct constant magnetic field from field vector.

Parameters:

B – [in] magnetic field vector in global coordinate system

inline Vector3 getField() const

Get the B field at a position.

Returns:

The constant magnetic field vector

inline virtual Result<Vector3> getField(const Vector3 &position, MagneticFieldProvider::Cache &cache) const override

Retrieve magnetic field value at a given location.

Requires an instance of Acts::MagneticFieldProvider::Cache created through makeCache.

Note

The position is ignored and only kept as argument to provide a consistent interface with other magnetic field services.

Parameters:

• position – [in] global 3D position for the lookup

• cache – [inout] Field provider specific cache object

Returns:

magnetic field vector at given position

inline bool isInside(const Vector3&) const

check whether given 3D position is inside look-up domain

Returns:

Always true for constant magnetic field

inline virtual Acts::MagneticFieldProvider::Cache makeCache(const Acts::MagneticFieldContext &mctx) const override

Make an opaque cache for the magnetic field.

Instructs the specific implementation to generate a Acts::MagneticFieldProvider::Cache instance for magnetic field lookup.

Parameters:

mctx – The magnetic field context to generate cache for

Returns:

Cache The opaque cache object

inline void setField(const Vector3 &B)

update magnetic field vector

Parameters:

B – [in] magnetic field vector in global coordinate system

struct Cache

Cache object for constant magnetic field.

Public Functions

inline explicit Cache(const MagneticFieldContext&)

Constructor with context.

Note

For the constant field, the cache is empty.

class ConstrainedStep

A constrained step class for the steppers.

This class is symmetrical for forward and backward propagation. The sign of the propagation direction should not enter here but rather be applied the step is actually taken.

As simple as this class looks it hides a few very important details:

• Overstepping handling. The step size sign will flip if we happened to pass our target.

• Convergence handling. Smaller and smaller step sizes have to be used in order to converge on a target.

Because of the points mentioned above, the update function will always prefer negative step sizes. A side effect of this is that we will propagate in the opposite direction if the target is “behind us”.

The hierarchy is:

• Overstepping resolution / backpropagation

• Convergence

• Step into the void with std::numeric_limits<double>max()

Public Types

enum class Type : int

the types of constraints from navigator - this would be a navigation step from actor - this would be an actor condition from user - this is user given for what reason ever

Values:

enumerator Navigator

enumerator Actor

enumerator User

Public Functions

constexpr ConstrainedStep() = default

inline explicit constexpr ConstrainedStep(double v)

constructor

Parameters:

v – is the user given initial value

inline constexpr double accuracy() const

Access the accuracy value.

Returns:

The step size accuracy constraint

inline constexpr void release(Type type)

release a certain constraint value

Parameters:

type – is the constraint type to be released

inline constexpr void releaseAccuracy()

release accuracy

inline constexpr void setAccuracy(double v)

set accuracy

this will set only the accuracy, as this is the most exposed to the Propagator

Parameters:

v – is the new accuracy value

inline constexpr void setUser(double v)

set user

Parameters:

v – is the new user value

inline std::ostream &toStream(std::ostream &os) const

Stream the constrained step into an output stream.

Parameters:

os – Output stream to write to

Returns:

Reference to the output stream for chaining

inline std::string toString() const

Convert the constrained step to a string representation.

Returns:

String representation of the constrained step

inline constexpr void update(double v, Type type)

Update the step size of a certain type.

Only navigation and target abortion step size updates may change the sign due to overstepping

Parameters:

• v – is the new value to be updated

• type – is the constraint type

inline constexpr double value() const

returns the min step size

Returns:

The minimum constrained step size considering all constraints

inline constexpr double value(Type type) const

Access a specific value.

Parameters:

type – is the requested parameter type

Returns:

The step size for the specified constraint type

template<int N>
class ConvexPolygonBounds : public Acts::ConvexPolygonBoundsBase

This is the actual implementation of the bounds.

It is templated on the number of vertices, but there is a specialization for dynamic number of vertices, where the underlying storage is then a vector.

Template Parameters:

N – Number of vertices

Public Functions

explicit ConvexPolygonBounds(std::span<const double> values) noexcept(false)

Constructor from a fixed size array of parameters This will throw if the vertices do not form a convex polygon.

Parameters:

values – The values to build up the vertices

explicit ConvexPolygonBounds(std::span<const Vector2> vertices) noexcept(false)

Constructor from a vector of vertices, to facilitate construction.

This will throw if the vector size does not match num_vertices. This will throw if the vertices do not form a convex polygon.

Parameters:

vertices – The list of vertices.

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

virtual std::vector<Vector2> vertices(unsigned int ignoredSegments = 0u) const final

Return the vertices.

Note

the number of segments is ignored in this representation

Parameters:

ignoredSegments – the number of segments used to approximate and eventually curved line

Returns:

vector for vertices in 2D

Public Static Attributes

static constexpr std::size_t eSize = 2 * N

Expose number of parameters as a template parameter.

Note

The eSize name here emulates the size of the bound values in other bounds classes.

static constexpr std::size_t nVertices = N

Expose number of vertices given as template parameter.

class ConvexPolygonBoundsBase : public Acts::PlanarBounds

base class for convex polygon bounds

This class serves as a base class for the actual bounds class. The only deriving type is the templated ConvexPolygonBounds.

Subclassed by Acts::ConvexPolygonBounds< N >, Acts::ConvexPolygonBounds< PolygonDynamic >

Public Functions

virtual const RectangleBounds &boundingBox() const final

Return a rectangle bounds object that encloses this polygon.

Returns:

The rectangular bounds

virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Note

For ConvexPolygonBounds: returns average of all vertices (vertex centroid)

Returns:

Vector2 representing the center position in local coordinates

virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream.

Parameters:

sl – is the ostream to be written into

Returns:

Reference to the output stream after writing

inline virtual BoundsType type() const final

Return the bounds type of this bounds object.

Returns:

The bounds type

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

class CuboidVolumeBounds : public Acts::VolumeBounds

Bounds for a cubical Volume, the orientedSurfaces(…) method creates a vector of 6 surfaces:

BoundarySurfaceFace [index]:

• negativeFaceXY [0] : Rectangular Acts::PlaneSurface, parallel to \( xy \) plane at negative \( z \)

• positiveFaceXY [1] : Rectangular Acts::PlaneSurface, parallel to \( xy \) plane at positive \( z \)

• negativeFaceXY [2] : Rectangular Acts::PlaneSurface, attached to \( yz \) plane at negative \( x \)

• positiveFaceXY [3] : Rectangular Acts::PlaneSurface, attached to \( yz \) plane at negative \( x \)

• negativeFaceXY [4] : Rectangular Acts::PlaneSurface, parallel to \( zx \) plane at negative \( y \)

• positiveFaceXY [5] : Rectangular Acts::PlaneSurface, parallel to \( zx \) plane at positive \( y \)

Public Types

enum BoundValues

for streaming and access

Values:

enumerator eHalfLengthX

enumerator eHalfLengthY

enumerator eHalfLengthZ

enumerator eSize

enum class Face : unsigned int

Enum describing the possible faces of a cuboid volume.

Note

These values are synchronized with the BoundarySurfaceFace enum. Once Gen1 is removed, this can be changed.

Values:

enumerator NegativeZFace

enumerator PositiveZFace

enumerator NegativeXFace

enumerator PositiveXFace

enumerator NegativeYFace

enumerator PositiveYFace

Public Functions

CuboidVolumeBounds() = delete

CuboidVolumeBounds(const CuboidVolumeBounds &bobo) = default

Copy Constructor.

Parameters:

bobo – is the source volume bounds to be copied

explicit CuboidVolumeBounds(const std::array<double, eSize> &values)

Constructor - from a fixed size array.

Parameters:

values – iw the bound values

CuboidVolumeBounds(double halex, double haley, double halez) noexcept(false)

Constructor - the box boundaries.

Parameters:

• halex – is the half length of the cube in x

• haley – is the half length of the cube in y

• halez – is the half length of the cube in z

CuboidVolumeBounds(std::initializer_list<std::pair<BoundValues, double>> keyValues)

Constructor with initializer list of key-value pairs.

Parameters:

keyValues – List of bound value identifiers and their corresponding values

~CuboidVolumeBounds() override = default

virtual Volume::BoundingBox boundingBox(const Transform3 *trf = nullptr, const Vector3 &envelope = {0, 0, 0}, const Volume *entity = nullptr) const final

Construct bounding box for this shape.

Parameters:

• trf – Optional transform

• envelope – Optional envelope to add / subtract from min/max

• entity – Entity to associate this bounding box with

Returns:

Constructed bounding box

inline virtual std::vector<AxisDirection> canonicalAxes() const override

Get the canonical binning direction, i.e.

the binning directions for that fully describe the shape’s extent

Returns:

vector of canonical binning values

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

The requested bound value

virtual bool inside(const Vector3 &pos, double tol = 0.) const override

This method checks if position in the 3D volume frame is inside the cylinder.

Parameters:

• pos – is the position in volume frame to be checked

• tol – is the absolute tolerance to be applied

Returns:

True if the position is inside the cuboid bounds

CuboidVolumeBounds &operator=(const CuboidVolumeBounds &bobo) = default

Assignment operator.

Parameters:

bobo – is the source volume bounds to be assigned

Returns:

Reference to this object after assignment

virtual std::vector<OrientedSurface> orientedSurfaces(const Transform3 &transform = Transform3::Identity()) const override

Oriented surfaces, i.e.

the decomposed boundary surfaces and the according navigation direction into the volume given the normal vector on the surface

It will throw an exception if the orientation prescription is not adequate

Parameters:

transform – is the 3D transform to be applied to the boundary surfaces to position them in 3D space

Returns:

a vector of surfaces bounding this volume

virtual double referenceBorder(AxisDirection aDir) const final

Binning borders in double.

Parameters:

aDir – is the axis direction for which the reference border is requested

Returns:

float offset to be used for the binning

void set(BoundValues bValue, double value)

Set a bound value.

Parameters:

• bValue – the bound value identifier

• value – the value to be set

void set(std::initializer_list<std::pair<BoundValues, double>> keyValues)

Set a range of bound values.

Parameters:

keyValues – the initializer list of key value pairs

virtual std::ostream &toStream(std::ostream &os) const override

Output Method for std::ostream.

Parameters:

os – is ostream operator to be dumped into

Returns:

Reference to the output stream after writing

inline virtual VolumeBounds::BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

is a BoundsType enum

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

Public Static Functions

static BoundValues boundsFromAxisDirection(AxisDirection direction)

Convert axis direction to a corresponding bound value in local coordinate convention.

Parameters:

direction – the axis direction to convert

Returns:

The bound value corresponding to the axis direction

static std::tuple<Face, Face, std::array<Face, 4>> facesFromAxisDirection(AxisDirection direction)

Convert axis direction to a set of corresponding cuboid faces in local coordinate convention.

Parameters:

direction – the axis direction to convert

Returns:

A tuple of cuboid faces with the following ordering convention: (1) negative face orthogonal to the axis direction (2) positive face orthogonal to the axis direction (3) list of side faces parallel to the axis direction

class CuboidVolumeStack : public Acts::VolumeStack

This class implements a x-.

y-. z-aligned stack of cuboid volumes with synchronized bounds. Externally, it presents as a single volume. On construction, the input volumes are modified so that they are connected in x, y, z and have synchronized bounds. The way this is done can be configured using an attachment and a resize strategy. Depending on the configuration, the input volumes are either extended or gap volumes are created.

Note

The size adjustment convention is that volumes are never shrunk

Public Functions

CuboidVolumeStack(const GeometryContext &gctx, std::vector<Volume*> &volumes, AxisDirection direction, VolumeAttachmentStrategy strategy = VolumeAttachmentStrategy::Midpoint, VolumeResizeStrategy resizeStrategy = VolumeResizeStrategy::Expand, const Logger &logger = Acts::getDummyLogger())

Constructor from a vector of volumes and direction.

Note

resizeStrategy only affects resizing along direction. Resizing in the other direction is always delegated to the child volumes, which might in turn be CuboidVolumeStack

Note

Preconditions are checked on construction

Parameters:

• gctx – The current geometry context object, e.g. alignment

• volumes – is the vector of volumes

• direction – is the axis direction

• strategy – is the attachment strategy

• resizeStrategy – is the resize strategy

• logger – is the logger

Pre:

The volumes need to have a common coordinate system relative to direction. I.e. they need to be aligned in z and cannot have a rotation in x or y.

Pre:

The volumes all need to have CuboidVolumeBounds

virtual void update(const GeometryContext &gctx, std::shared_ptr<VolumeBounds> volbounds, std::optional<Transform3> transform = std::nullopt, const Logger &logger = getDummyLogger()) override

Update the volume bounds and transform.

This will update the bounds of all volumes in the stack to accommodate the new bounds and optionally create gap volumes according to the resize strategy set during construction.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• volbounds – is the new bounds

• transform – is the new transform

• logger – is the logger

Pre:

The volume bounds need to be of type CuboidVolumeBounds.

Public Static Functions

static std::size_t axisToIndex(AxisDirection direction)

Convert axis direction to an array index according to stack convention.

For example, AxisX –> 0

Parameters:

direction – is the axis direction to convert

Returns:

Array index corresponding to the axis direction

static std::pair<AxisDirection, AxisDirection> getOrthogonalAxes(AxisDirection direction)

Get axis directions orthogonal to the given one according to stack convention.

For example AxisX –> <AxisY, AxisZ>

Parameters:

direction – is the axis direction to find the orthogonal for

Returns:

Pair of orthogonal axis directions

class CutoutCylinderVolumeBounds : public Acts::VolumeBounds

Class which implements a cutout cylinder.

This shape is basically a cylinder, with another, smaller cylinder subtracted from the center. ——————&#8212; rmax | | | |——&#8212;| | rmed | | | | —&#8212; —&#8212; rmin &#8212; hlZc &#8212; ——&#8212; hlZ —-&#8212;

Public Types

enum BoundValues

for streaming and access

Values:

enumerator eMinR

enumerator eMedR

enumerator eMaxR

enumerator eHalfLengthZ

enumerator eHalfLengthZcutout

enumerator eSize

Public Functions

inline explicit CutoutCylinderVolumeBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor - from a fixed size array.

Parameters:

values – The bound values

inline CutoutCylinderVolumeBounds(double rmin, double rmed, double rmax, double hlZ, double hlZc) noexcept(false)

Constructor from defining parameters.

Parameters:

• rmin – Minimum radius at the “choke points”

• rmed – The medium radius (outer radius of the cutout)

• rmax – The outer radius of the overall shape

• hlZ – The longer halflength of the shape

• hlZc – The cutout halflength of the shape

virtual Volume::BoundingBox boundingBox(const Transform3 *trf = nullptr, const Vector3 &envelope = {0, 0, 0}, const Volume *entity = nullptr) const final

Construct bounding box for this shape.

Parameters:

• trf – Optional transform

• envelope – Optional envelope to add / subtract from min/max

• entity – Entity to associate this bounding box with

Returns:

Constructed bounding box

inline virtual std::vector<AxisDirection> canonicalAxes() const override

Get the canonical binning direction, i.e.

the axis values that fully describe the shape’s extent

Returns:

vector of canonical binning values

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

Value of the specified bound parameter

virtual bool inside(const Vector3 &gpos, double tol = 0) const override

Inside method to test whether a point is inside the shape.

Parameters:

• gpos – The point to test

• tol – The tolerance to test with

Returns:

Whether the point is inside or not.

virtual std::vector<OrientedSurface> orientedSurfaces(const Transform3 &transform = Transform3::Identity()) const override

Oriented surfaces, i.e.

the decomposed boundary surfaces and the according navigation direction into the volume given the normal vector on the surface

It will throw an exception if the orientation prescription is not adequate

Parameters:

transform – is the 3D transform to be applied to the boundary surfaces to position them in 3D space

Returns:

a vector of surfaces bounding this volume

virtual std::ostream &toStream(std::ostream &sl) const override

Write information about this instance to an outstream.

Parameters:

sl – The outstream

Returns:

The outstream

inline virtual VolumeBounds::BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

is a BoundsType enum

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

class CylinderBounds : public Acts::SurfaceBounds

Bounds for a cylindrical Surface.

These bounds may be used for a CylinderSurface In case of bounds for a StraightLineSurface the radius determines the radius within a localPosition is regarded as inside bounds.

CylinderBounds also enhance the possibility of a cylinder segment with an opening angle \( 2\cdot\phi_{half}\) around an average \( \phi \) angle \( \phi_{ave} \).

CylinderBounds also supports beveled sides defined by an angle. Different angles can be defined on both sides of the cylinder. A positive angle is defined as “extruding” from the defined Zlength, while a negative angle is “intruding” on the Zlength.

• - - +

  \ | / \ | / \ | / \ | / |/______________|/ 2 * ZhalfLength

Public Types

enum BoundValues

Enumeration for the bound values.

Values:

enumerator eR

enumerator eHalfLengthZ

enumerator eHalfPhiSector

enumerator eAveragePhi

enumerator eBevelMinZ

enumerator eBevelMaxZ

enumerator eSize

Public Functions

inline explicit CylinderBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor from array.

Parameters:

values – The bound values stored in an array

inline CylinderBounds(double r, double halfZ, double halfPhi = std::numbers::pi, double avgPhi = 0., double bevelMinZ = 0., double bevelMaxZ = 0.) noexcept(false)

Constructor - full cylinder.

Parameters:

• r – The radius of the cylinder

• halfZ – The half length in z

• halfPhi – The half opening angle

• avgPhi – (optional) The phi value from which the opening angle spans

• bevelMinZ – (optional) The bevel on the negative z side

• bevelMaxZ – (optional) The bevel on the positive z sid The bevel on the positive z side

inline virtual SquareMatrix2 boundToCartesianJacobian(const Vector2 &lposition) const final

Computes the bound to cartesian jacobian at a given local position.

Parameters:

lposition – is the local position at which the jacobian is computed

Returns:

the bound to cartesian jacobian

inline virtual SquareMatrix2 boundToCartesianMetric(const Vector2 &lposition) const final

Computes the bound to cartesian metric at a given local position.

Parameters:

lposition – is the local position at which the metric is computed

Returns:

the bound to cartesian metric

virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Note

For CylinderBounds: returns (averagePhi, 0) in local (rphi, z) coordinates

Returns:

Vector2 representing the center position in local coordinates

std::vector<Vector3> circleVertices(const Transform3 transform, unsigned int quarterSegments) const

Create the bow/circle vertices on either side of the cylinder.

Parameters:

• transform – is the global transform

• quarterSegments – is the number of segments to approximate a quarter of a circle. In order to symmetrize fully closed and sectoral cylinders, also in the first case the two end points are given (albeit they overlap) in -pi / pi

Returns:

a singlevector containing the vertices from one side and then from the other side consecutively

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

inline bool coversFullAzimuth() const

Returns true for full phi coverage.

Returns:

True if the cylinder covers full azimuthal range

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

Value of the specified bound parameter

virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

inline virtual bool isCartesian() const final

Check if the bound coordinates are cartesian.

Returns:

true if the bound coordinates are cartesian

virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream.

Parameters:

sl – The output stream to write to

Returns:

Reference to the output stream after writing

inline virtual BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

the bounds type

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

class CylinderLayer : public Acts::CylinderSurface, public Acts::Layer

Class to describe a cylindrical detector layer for tracking, it inherits from both, Layer base class and CylinderSurface class.

Public Functions

CylinderLayer() = delete

CylinderLayer(const CylinderLayer &cla) = delete

~CylinderLayer() override = default

CylinderLayer &operator=(const CylinderLayer&) = delete

virtual const CylinderSurface &surfaceRepresentation() const override

Transforms the layer into a Surface representation This is for positioning and extrapolation.

Returns:

Const reference to the cylinder surface representing this layer

virtual CylinderSurface &surfaceRepresentation() override

Non-const version of surface representation access.

Returns:

Mutable reference to the cylinder surface

Public Static Functions

static std::shared_ptr<CylinderLayer> create(const Transform3 &transform, const std::shared_ptr<const CylinderBounds> &cbounds, std::unique_ptr<SurfaceArray> surfaceArray, double thickness = 0., std::unique_ptr<ApproachDescriptor> ad = nullptr, LayerType laytyp = passive)

Factory for shared Layer pointer create a shared, fully deployed CylinderLayer.

Parameters:

• transform – is the 3D transform that places the layer in 3D space

• cbounds – are the cylindrical bounds of the layer

• surfaceArray – is the Binned Array that holds the sensitive surfaces

• thickness – is the layer thickness (along the normal)

• ad – is the approach descriptor for approaching the layer

• laytyp – is the layer type

Returns:

The return object is a shared pointer to the layer.

class CylinderSurface : public Acts::RegularSurface

Class for a CylinderSurface in the TrackingGeometry.

It inherits from Surface.

The cylinder surface has a special role in the TrackingGeometry, since it builds the surfaces of all TrackingVolumes at container level for a cylindrical tracking geometry.

Subclassed by Acts::CylinderLayer

Public Functions

virtual AlignmentToPathMatrix alignmentToPathDerivative(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Calculate the derivative of path length at the geometry constraint or point-of-closest-approach w.r.t.

alignment parameters of the surface (i.e. local frame origin in global 3D Cartesian coordinates and its rotation represented with extrinsic Euler angles)

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Derivative of path length w.r.t. the alignment parameters

void assignSurfaceBounds(std::shared_ptr<const CylinderBounds> newBounds)

Overwrite the existing surface bounds with new ones.

Parameters:

newBounds – Pointer to the new bounds

virtual const CylinderBounds &bounds() const final

This method returns the CylinderBounds by reference.

Returns:

Reference to the cylinder bounds

const std::shared_ptr<const CylinderBounds> &boundsPtr() const

This method returns the shared_ptr to the CylinderBounds.

Returns:

Shared pointer to the cylinder bounds

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final

Convert a global position to a local one this is the most generic interface, which is implemented by all surfaces.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be converted

• direction – is the direction of the local position (ignored for RegularSurface)

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const final

Global to local transformation.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be transformed

• tolerance – optional tolerance within which a point is considered valid on surface

Returns:

a Result<Vector2> which can be !ok() if the operation fails

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const = 0

Convert a global position to a local one.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be converted

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual MultiIntersection3D intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), double tolerance = s_onSurfaceTolerance) const final

Straight line intersection schema from position/direction.

If possible returns both solutions for the cylinder

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The position to start from

• direction – The direction at start

• boundaryTolerance – the Boundary Check Tolerance

• tolerance – the tolerance used for the intersection

Returns:

SurfaceIntersection object (contains intersection & surface)

virtual Matrix<2, 3> localCartesianToBoundLocalDerivative(const GeometryContext &gctx, const Vector3 &position) const final

Calculate the derivative of bound track parameters local position w.r.t.

position in local 3D Cartesian coordinates

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The position of the parameters in global

Returns:

Derivative of bound local position w.r.t. position in local 3D cartesian coordinates

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const final

Local to global transformation.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is the local position to be transformed

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Local to global transformation.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const final

Local to global transformation.

This is the most generic interface, which is implemented by all surfaces.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

• direction – global 3D momentum direction (ignored for RegularSurface)

Returns:

The global position by value

std::pair<std::shared_ptr<CylinderSurface>, bool> mergedWith(const CylinderSurface &other, AxisDirection direction, bool externalRotation, const Logger &logger = getDummyLogger()) const

Merge two cylinder surfaces into a single one.

Note

The surfaces need to be compatible, i.e. have cylinder bounds that align, and have the same radius

Note

The returned boolean is false if this is left or counter-clockwise of other, and true if not.

Parameters:

• other – The other cylinder surface to merge with

• direction – The axis direction: either AxisZ or AxisRPhi

• externalRotation – If true, any phi rotation is done in the transform

• logger – The logger to use

Returns:

The merged cylinder surface and a boolean indicating if surfaces are reversed

virtual std::string name() const override

Return method for properly formatted output string.

Returns:

String representation of the class name

virtual Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const final

Return method for surface normal information.

Note

for a Cylinder a local position is always required for the normal vector

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is the local position for which the normal vector is requested

Returns:

normal vector at the local position by value

Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Calculate the normal vector of the surface This overload requires an on-surface local position.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is the local position where the normal vector is constructed

Returns:

normal vector by value

Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const final

Calculate the normal vector of the surface This overload is fully generic, fulfills the Surface interface and accepts a global position and a direction.

For RegularSurface this is equivalent to the normal overload, ignoring the direction

Parameters:

• gctx – The current geometry context object, e.g. alignment

• pos – is the global position where the normal vector is constructed

• direction – is the direction of the normal vector (ignored for RegularSurface)

Returns:

Normal vector at the given position

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const final

Return method for surface normal information.

Note

for a Cylinder a local position is always required for the normal vector

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position for which the normal vector is requested

Returns:

normal vector at the global position by value

Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const = 0

Calculate the normal vector of the surface This overload accepts a global position.

Parameters:

• position – is the global position where the normal vector is constructed

• gctx – The current geometry context object, e.g. alignment

Returns:

normal vector by value

CylinderSurface &operator=(const CylinderSurface &other)

Assignment operator.

Parameters:

other – is the source cylinder for the copy

Returns:

Reference to this CylinderSurface after assignment

virtual double pathCorrection(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Path correction due to incident of the track.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position as a starting point

• direction – is the global momentum direction at the starting point

Returns:

is the correction factor due to incident

virtual Polyhedron polyhedronRepresentation(const GeometryContext &gctx, unsigned int quarterSegments = 2u) const override

Return a Polyhedron for a cylinder.

This method represents the cylinder as a polyhedron with a given number of segments to represent a quarter of a full circle. The polyedron will consist of the vertices of the cylinder on both sides, and faces between them, both as rectangular faces and as triangular faces.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• quarterSegments – The number of segments to approximate a quarter of the full circle; it’s chosen to be 1, only the extrema points (-pi, -0.5pi, 0., 0.5pi) are inserted to capture the correct extent in the x-y plane

Returns:

A list of vertices and a face/facett description of it

virtual RotationMatrix3 referenceFrame(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Return the measurement frame - this is needed for alignment, in particular The measurement frame of a cylinder is the tangential plane at a given position.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the position where the measurement frame is defined

• direction – is the momentum direction vector (ignored)

Returns:

rotation matrix that defines the measurement frame

virtual Vector3 referencePosition(const GeometryContext &gctx, AxisDirection aDir) const final

The binning position method - is overloaded for r-type binning.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• aDir – is the axis Direction of global binning to be done

Returns:

is the global position to be used for binning

virtual Vector3 rotSymmetryAxis(const GeometryContext &gctx) const

Return method for the rotational symmetry axis.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

the z-Axis of transform

virtual SurfaceType type() const override

Return the surface type.

Returns:

Surface type identifier

class CylinderVolumeBounds : public Acts::VolumeBounds

[0] and [1] at positive \( \phi \)

Bounds for a cylindrical Volume, the orientedSurfaces(..) method creates a vector of up to 6 surfaces:

case A) 3 Surfaces (full cylindrical tube): BoundarySurfaceFace [index]:

• negativeFaceXY [0] : Acts::DiscSurface with \( r_{inner}=0 \), parallel to \( xy \) plane at negative \( z\)

• positiveFaceXY [1] : Acts::DiscSurface with \( r_{inner}=0 \), parallel to \( xy \) plane at positive \( z\)

• cylinderCover [2] : Acts::CylinderSurface confining the Acts::Volume

case B) 4 Surfaces (tube with inner and outer radius): BoundarySurfaceFace [index]:

• negativeFaceXY [0] : Acts::DiscSurface with \( r_{inner}>0 \), parallel to \( xy \) plane at negative \( z\)

• positiveFaceXY [1] : Acts::DiscSurface with \( r_{inner}>0 \), parallel to \( xy \) plane at positive \( z\)

• tubeOuterCover [2] : Acts::CylinderSurface with \( r = r_{outer} \)

• tubeInnerCover [3] : Acts::CylinderSurface with \( r = r_{inner} \)

case C) 6 Surfaces (sectoral tube with inner and outer radius): BoundarySurfaceFace [index]:

• negativeFaceXY [0] : Acts::DiscSurface with \( r_{inner}>0\) and \( \phi < \pi \), parallel to \( xy \) plane at negative \(z\)

• positiveFaceXY [1] : Acts::DiscSurface with \( r_{inner}>0 \) and \( \phi < \pi \), parallel to \( xy \) plane at positive \(z\)

• tubeSectorOuterCover [2] : Acts::CylinderSurface with \( r = r_{outer}\)

• tubeSectorInnerCover [3] : Acts::CylinderSurface with \( r = r_{inner} \)

• tubeSectorNegativePhi [4] : Rectangular Acts::PlaneSurface attached to [0] and [1] at negative \( \phi \)

  • tubeSectorNegativePhi [5] :

Public Types

enum BoundValues

for streaming and access

Values:

enumerator eMinR

enumerator eMaxR

enumerator eHalfLengthZ

enumerator eHalfPhiSector

enumerator eAveragePhi

enumerator eBevelMinZ

enumerator eBevelMaxZ

enumerator eSize

enum class Face : unsigned int

Enum describing the possible faces of a cylinder volume.

Note

These values are synchronized with the BoundarySurfaceFace enum. Once Gen1 is removed, this can be changed.

Values:

enumerator PositiveDisc

enumerator NegativeDisc

enumerator OuterCylinder

enumerator InnerCylinder

enumerator NegativePhiPlane

enumerator PositivePhiPlane

Public Functions

CylinderVolumeBounds() = delete

CylinderVolumeBounds(const CylinderBounds &cBounds, double thickness)

Constructor - extruded from cylinder bounds and thickness.

Parameters:

• cBounds – the cylinder bounds

• thickness – of the extrusion

CylinderVolumeBounds(const CylinderVolumeBounds &cylbo)

Copy Constructor.

Parameters:

cylbo – is the source cylinder volume bounds for the copy

CylinderVolumeBounds(const RadialBounds &rBounds, double thickness)

Constructor - extruded from radial bounds and thickness.

Parameters:

• rBounds – the Radial bounds

• thickness –

explicit CylinderVolumeBounds(const std::array<double, eSize> &values)

Constructor - from a fixed size array.

Parameters:

values – The bound values

CylinderVolumeBounds(double rmin, double rmax, double halfz, double halfphi = std::numbers::pi, double avgphi = 0., double bevelMinZ = 0., double bevelMaxZ = 0.)

Constructor.

Parameters:

• rmin – The inner radius of the cylinder

• rmax – The outer radius of the cylinder

• halfz – The half length in z

• halfphi – The half lopening angle

• avgphi – The average phi value

• bevelMinZ – The bevel angle, in radians, for the negative side

• bevelMaxZ – The bevel angle, in radians, for the positive side

~CylinderVolumeBounds() override = default

virtual Volume::BoundingBox boundingBox(const Transform3 *trf = nullptr, const Vector3 &envelope = {0, 0, 0}, const Volume *entity = nullptr) const final

Construct bounding box for this shape.

Parameters:

• trf – Optional transform

• envelope – Optional envelope to add / subtract from min/max

• entity – Entity to associate this bounding box with

Returns:

Constructed bounding box

inline virtual std::vector<AxisDirection> canonicalAxes() const override

Get the canonical binning directions, i.e.

the axis directions that fully describe the shape’s extent

Returns:

vector of canonical binning values

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

The requested bound value

virtual bool inside(const Vector3 &pos, double tol = 0.) const override

This method checks if position in the 3D volume frame is inside the cylinder.

Parameters:

• pos – is a global position to be checked

• tol – is the tolerance for the check

Returns:

True if the position is inside the cylinder bounds

CylinderVolumeBounds &operator=(const CylinderVolumeBounds &cylbo) = default

Assignment operator.

Parameters:

cylbo – Source cylinder volume bounds to copy from

Returns:

Reference to this object after assignment

virtual std::vector<OrientedSurface> orientedSurfaces(const Transform3 &transform = Transform3::Identity()) const override

Oriented surfaces, i.e.

the decomposed boundary surfaces and the according navigation direction into the volume given the normal vector on the surface

It will throw an exception if the orientation prescription is not adequate

Parameters:

transform – is the 3D transform to be applied to the boundary surfaces to position them in 3D space

Returns:

a vector of surfaces bounding this volume

virtual double referenceBorder(AxisDirection aDir) const override

Binning borders in double.

Parameters:

aDir – is the axis direction used for the binning

Returns:

Reference border value for the given axis direction

virtual Vector3 referenceOffset(AxisDirection aDir) const override

Binning offset - overloaded for some R-binning types.

Parameters:

aDir – is the axis direction used for the binning

Returns:

Reference offset vector for the given axis direction

void set(BoundValues bValue, double value)

Set a bound value.

Parameters:

• bValue – the bound value identifier

• value – the value to be set

void set(std::initializer_list<std::pair<BoundValues, double>> keyValues)

Set a range of bound values.

Parameters:

keyValues – the initializer list of key value pairs

virtual std::ostream &toStream(std::ostream &os) const override

Output Method for std::ostream.

Parameters:

os – is the output stream

Returns:

Reference to the output stream after writing

inline virtual VolumeBounds::BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

is a BoundsType enum

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

class CylinderVolumeBuilder : public Acts::ITrackingVolumeBuilder

A volume builder to be used for building concentric cylinder volumes.

• a) configured volume

• b) wrapping around a cylindrical/disk layer config

All are optionally wrapped around a given volume which has to by a cylinder volume and which has to be center at z == 0

To receive the tracking volume it is possible to also hand over a triple of layers, which is a C++ tuple of three pointers to layer vectors (defined in the ITrackingVolumeBuilder). This functionality is needed for a possible translation of an geometry existing in another format. The first entry represents the layers of the negative endcap, the second the layers of the barrel and the third the layers of the positive endcap. If the one of these pointers is a nullptr no layers will be created for this volume

For the endcap region it is possible to check for a ring layout, in which case an attempt to split into individual ring volumes is done

Public Functions

explicit CylinderVolumeBuilder(const Config &cvbConfig, std::unique_ptr<const Logger> logger = getDefaultLogger("CylinderVolumeBuilder", Logging::INFO))

Constructor.

Parameters:

• cvbConfig – [in] is the configuration struct to steer the builder

• logger – [in] logging instance

~CylinderVolumeBuilder() override

Destructor.

VolumeConfig analyzeContent(const GeometryContext &gctx, const LayerVector &lVector, const MutableTrackingVolumeVector &mtvVector) const

Analyze the config to gather needed dimension.

Parameters:

• gctx – [in] the geometry context for this building

• lVector – [in] is the vector of layers that are parsed

• mtvVector – [in] Vector of mutable tracking volumes to analyze

Returns:

a VolumeConfig representing this layer

inline Config getConfiguration() const

Get configuration method.

Return the configuration object.

Returns:

a copy of the config object

void setConfiguration(const Config &cvbConfig)

Set configuration method.

Parameters:

cvbConfig – [in] is the new configuration to be set

void setLogger(std::unique_ptr<const Logger> newLogger)

set logging instance

Parameters:

newLogger – [in] is the logging instance to be set

virtual MutableTrackingVolumePtr trackingVolume(const GeometryContext &gctx, TrackingVolumePtr existingVolume = nullptr, std::shared_ptr<const VolumeBounds> externalBounds = nullptr) const override

CylinderVolumeBuilder main call method.

Parameters:

• gctx – [in] geometry context for which this cylinder volume is built

• existingVolume – [in] is an (optional) volume to be included

• externalBounds – [in] are (optional) external confinement constraints

Returns:

a mutable pointer to a new TrackingVolume which includes the optionally provided existingVolume consistently for further processing

struct Config

Nested configuration struct for this CylinderVolumeBuilder.

Public Members

std::array<std::shared_ptr<const ISurfaceMaterial>, 6> boundaryMaterial{nullptr, nullptr, nullptr, nullptr, nullptr, nullptr}

—————–&#8212; MB (outer [1]) ————&#8212; | MB [2] NEC MB [3] | B | MB [4] PEC MB [5] | —————–&#8212; MB (inner [0]) ————&#8212;

bool buildToRadiusZero = false

Build the volume to the beam line.

bool checkRingLayout = false

Check for endcap ring layout.

std::shared_ptr<const IConfinedTrackingVolumeBuilder> ctVolumeBuilder = nullptr

Builder to construct confined volumes within the volume.

std::shared_ptr<const ILayerBuilder> layerBuilder = nullptr

Builder to construct layers within the volume.

std::pair<double, double> layerEnvelopeR = {1. * UnitConstants::mm, 1. * UnitConstants::mm}

Additional envelope in R to create rMin, rMax.

double layerEnvelopeZ = 1. * UnitConstants::mm

the additional envelope in Z to create zMin, zMax

double ringTolerance = 0 * UnitConstants::mm

Tolerance for endcap ring association.

std::shared_ptr<const ITrackingVolumeHelper> trackingVolumeHelper = nullptr

The tracking volume helper for construction.

std::shared_ptr<const IVolumeMaterial> volumeMaterial = nullptr

The world material.

std::string volumeName = ""

The string based identification.

class CylinderVolumeStack : public Acts::VolumeStack

This class implements a z-aligned or r-aligned stack of cylinder volumes with synchronized bounds.

Externally, it presents as a single volume. On construction, the input volumes are modified so that they are connected in z and r and have synchronized bounds. The way this is done can be configured using an attachment and a resize strategy. Depending on the configuration, the input volumes are either extended or gap volumes are created.

Note

The volumes are never shrunk, because this would potentially result in overlaps of the resulting volumes bounds.

Public Functions

CylinderVolumeStack(const GeometryContext &gctx, std::vector<Volume*> &volumes, AxisDirection direction, VolumeAttachmentStrategy strategy, std::pair<VolumeResizeStrategy, VolumeResizeStrategy> resizeStrategies, const Logger &logger = Acts::getDummyLogger())

Constructor from a vector of volumes and direction.

Note

resizeStrategy only affects resizing along direction. Resizing in the other direction is always delegated to the child volumes, which might in turn be CylinderVolumeStack

Note

The first element of resizeStrategies is used for the low end and the second element is used for the high end of the stack

Note

Preconditions are checked on construction

Parameters:

• gctx – The current geometry context object, e.g. alignment

• volumes – is the vector of volumes

• direction – is the binning direction

• strategy – is the attachment strategy

• resizeStrategies – is the resize strategies

• logger – is the logger

Pre:

The volumes need to have a common coordinate system relative to direction. I.e. they need to be aligned in z and cannot have a rotation in x or y.

Pre:

The volumes all need to have CylinerVolumeBounds and cannot have a \(\phi\) sector or bevels.

CylinderVolumeStack(const GeometryContext &gctx, std::vector<Volume*> &volumes, AxisDirection direction, VolumeAttachmentStrategy strategy = VolumeAttachmentStrategy::Midpoint, VolumeResizeStrategy resizeStrategy = VolumeResizeStrategy::Expand, const Logger &logger = Acts::getDummyLogger())

Constructor from a vector of volumes and direction.

Note

resizeStrategy only affects resizing along direction. Resizing in the other direction is always delegated to the child volumes, which might in turn be CylinderVolumeStack

Note

resizeStrategy is used for both ends of the stack

Note

Preconditions are checked on construction

Parameters:

• gctx – The current geometry context object, e.g. alignment

• volumes – is the vector of volumes

• direction – is the binning direction

• strategy – is the attachment strategy

• resizeStrategy – is the resize strategy

• logger – is the logger

Pre:

The volumes need to have a common coordinate system relative to direction. I.e. they need to be aligned in z and cannot have a rotation in x or y.

Pre:

The volumes all need to have CylinerVolumeBounds and cannot have a \(\phi\) sector or bevels.

virtual void update(const GeometryContext &gctx, std::shared_ptr<VolumeBounds> volbounds, std::optional<Transform3> transform = std::nullopt, const Logger &logger = getDummyLogger()) override

Update the volume bounds and transform.

This will update the bounds of all volumes in the stack to accommodate the new bounds and optionally create gap volumes according to the resize strategy set during construction.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• volbounds – is the new bounds

• transform – is the new transform

• logger – is the logger

Pre:

The volume bounds need to be of type CylinderVolumeBounds.

template<typename, typename H = void, DelegateType = DelegateType::NonOwning>
class Delegate

Warning

doxygenclass: Cannot find class “Acts::DetectorElementBase” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

class DiamondBounds : public Acts::PlanarBounds

Bounds for a double trapezoidal (“diamond”), planar Surface.

Public Types

enum BoundValues

Enumeration for the bound values.

Values:

enumerator eHalfLengthXnegY

enumerator eHalfLengthXzeroY

enumerator eHalfLengthXposY

enumerator eHalfLengthYneg

enumerator eHalfLengthYpos

enumerator eSize

Public Functions

inline explicit DiamondBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor - from fixed size array.

Parameters:

values – The parameter values

inline DiamondBounds(double halfXnegY, double halfXzeroY, double halfXposY, double halfYneg, double halfYpos) noexcept(false)

Constructor for convex hexagon symmetric about the y axis.

Parameters:

• halfXnegY – is the halflength in x at minimal y

• halfXzeroY – is the halflength in x at y = 0

• halfXposY – is the halflength in x at maximal y

• halfYneg – is the halflength into y < 0

• halfYpos – is the halflength into y > 0

virtual const RectangleBounds &boundingBox() const final

Bounding box parameters.

Returns:

rectangle bounds for a bounding box

virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Note

For DiamondBounds: returns center of symmetry (0,0)

Returns:

Vector2 representing the center position in local coordinates

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

Value of the specified bound parameter

virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream.

Parameters:

sl – is the ostream in which it is dumped

Returns:

Reference to the output stream after writing

inline virtual BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

the bounds type

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

virtual std::vector<Vector2> vertices(unsigned int ignoredSegments = 0u) const final

Return the vertices that describe this shape.

Parameters:

ignoredSegments – is an ignored parameter only used for curved bound segments

Returns:

vector for vertices in 2D

class DiamondVolumeBounds : public Acts::VolumeBounds

Bounds for a polygonal prism shaped Volume, the orientedSurface(…) method creates a vector of 8 surfaces: 2 Diamond Shape Surfaces (see.

and 6 Rectangular Shape Surfaces.

BoundarySurfaceFace [index]:

• negativeFaceXY [0] : Diamond Acts::PlaneSurface, parallel to \( xy \) plane at negative \( z \)

• positiveFaceXY [1] : Diamond Acts::PlaneSurface, parallel to \( xy \) plane at positive \( z \)

• negativeXFaceYZ12 [2] : Rectangular Acts::PlaneSurface, parallel to \( yz \) plane at negative \( x \) attached at [-x1,-y1] and [-x2,0]

• positiveXFaceYZ12 [3] : Rectangular Acts::PlaneSurface, parallel to \( yz \) plane at positive \( x \) attached at [x1,-y1] and [x2,0]

• negativeXFaceYZ23 [4] : Rectangular Acts::PlaneSurface, parallel to \( yz \) plane at negative \( x \) attached at [-x2,0] and [-x3,y2]

• positiveXFaceYZ23 [5] : Rectangular Acts::PlaneSurface, parallel to \( yz \) plane at positive \( x \) attached at [x2,0] and [x3,y2]

• negativeYFaceZX [6] : Rectangular Acts::PlaneSurface, parallel to \( zx \) plane at negative \( y \)

• positiveYFaceZX [7] : Rectangular Acts::PlaneSurface, parallel to \( zx \) plane at positive \( y \)

Public Types

enum BoundValues

for access / streaming

Values:

enumerator eHalfLengthX1

half length in x at positive y1

enumerator eHalfLengthX2

half length in x at y=0

enumerator eHalfLengthX3

half length in x at negative y2

enumerator eLengthY1

length in positive y1

enumerator eLengthY2

length in negative y2

enumerator eHalfLengthZ

half length in z

enumerator eAlphaAngle

angle alpha between negYFaceZX and faceYZ12

enumerator eBetaAngle

angle beta between FaceYZ12 and FaceYZ23

enumerator eSize

length of the bounds vector

enum class Face : unsigned int

Enumeration of faces of the diamond volume.

Values:

enumerator NegativeZFaceXY

enumerator PositiveZFaceXY

enumerator NegativeXFaceYZ12

enumerator PositiveXFaceYZ12

enumerator NegativeXFaceYZ23

enumerator PositiveXFaceYZ23

enumerator NegativeYFaceZX

enumerator PositiveYFaceZX

Public Functions

DiamondVolumeBounds(const DiamondVolumeBounds &other) = default

Copy constructor.

Parameters:

other – The other DiamondVolumeBounds to copy from

explicit DiamondVolumeBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor - from a vector of bound values.

Parameters:

values – The bound values (eSize elements)

DiamondVolumeBounds(DiamondVolumeBounds &&other) = default

Move constructor.

Parameters:

other – The other DiamondVolumeBounds to move from

DiamondVolumeBounds(double x1, double x2, double x3, double y1, double y2, double halez) noexcept(false)

Constructor - the polygonal prism boundaries.

Parameters:

• x1 – is the half length in x at negative y1

• x2 – is the half length in x at y=0

• x3 – is the half length in x at positive y2

• y1 – is the positive y extent

• y2 – is the negative y extent

• halez – is the half length in z

~DiamondVolumeBounds() override = default

Default destructor.

virtual Volume::BoundingBox boundingBox(const Transform3 *trf = nullptr, const Vector3 &envelope = {0, 0, 0}, const Volume *entity = nullptr) const final

Construct bounding box for this shape.

Parameters:

• trf – Optional transform

• envelope – Optional envelope to add / subtract from min/max

• entity – Entity to associate this bounding box with

Returns:

Constructed bounding box

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

The bound value at the specified index

virtual bool inside(const Vector3 &pos, double tol = 0.) const final

This method checks if position in the 3D volume frame is inside the cylinder.

Parameters:

• pos – is the global position to be checked

• tol – is the tolerance applied

Returns:

boolean indicator if position is inside

DiamondVolumeBounds &operator=(const DiamondVolumeBounds &other) = default

Copy constructor assignment.

Parameters:

other – The other DiamondVolumeBounds to copy from

Returns:

Reference to this object

DiamondVolumeBounds &operator=(DiamondVolumeBounds &&other) = default

Move constructor assignment.

Parameters:

other – The other DiamondVolumeBounds to move from

Returns:

Reference to this object

virtual std::vector<OrientedSurface> orientedSurfaces(const Transform3 &transform = Transform3::Identity()) const final

Oriented surfaces, i.e.

the decomposed boundary surfaces and the according navigation direction into the volume given the normal vector on the surface

It will throw an exception if the orientation prescription is not adequate

Parameters:

transform – is the 3D transform to be applied to the boundary surfaces to position them in 3D space

Returns:

a vector of surfaces bounding this volume

virtual std::ostream &toStream(std::ostream &os) const override

Output Method for std::ostream.

Parameters:

os – is the output stream

Returns:

Modified ostream for chaining

inline virtual VolumeBounds::BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

is a BoundsType enum

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

class DirectNavigator

A fully guided navigator.

This is a fully guided navigator that progresses through a provided sequence of surfaces.

This can either be used as a validation tool, for truth tracking, or track refitting.

Public Functions

inline explicit DirectNavigator(std::unique_ptr<const Logger> _logger = getDefaultLogger("DirectNavigator", Logging::INFO))

Constructor with optional logger.

Parameters:

_logger – Logger instance for navigation messages

inline bool checkTargetValid(const State &state, const Vector3 &position, const Vector3 &direction) const

Check if the current target is still valid.

This function checks if the target is valid. For the direct navigator this is always true.

Parameters:

• state – The navigation state

• position – The current position

• direction – The current direction

Returns:

True if the target is valid

inline const Surface *currentSurface(const State &state) const

Get the current surface from the navigation state.

Parameters:

state – The navigation state

Returns:

Pointer to current surface, nullptr if none

inline const TrackingVolume *currentVolume(const State &state) const

Get the current tracking volume (not used by DirectNavigator)

Parameters:

state – The navigation state (unused)

Returns:

Always returns nullptr as DirectNavigator doesn’t use volumes

inline const IVolumeMaterial *currentVolumeMaterial(const State &state) const

Get the current volume material (not used by DirectNavigator)

Parameters:

state – The navigation state (unused)

Returns:

Always returns nullptr as DirectNavigator doesn’t use volume material

inline bool endOfWorldReached(State &state) const

Check if the end of world has been reached (not applicable for DirectNavigator)

Parameters:

state – The navigation state (unused)

Returns:

Always returns false as DirectNavigator operates on a surface sequence

inline void handleSurfaceReached(State &state, const Vector3 &position, const Vector3 &direction, const Surface &surface) const

Handle the surface reached.

This function handles the surface reached. For the direct navigator this effectively sets the current surface to the reached surface.

Parameters:

• state – The navigation state

• position – The current position

• direction – The current direction

• surface – The surface reached

inline Result<void> initialize(State &state, const Vector3 &position, const Vector3 &direction, Direction propagationDirection) const

Initialize the navigator.

This function initializes the navigator for a new propagation.

Parameters:

• state – The navigation state

• position – The start position

• direction – The start direction

• propagationDirection – The propagation direction

Returns:

Always returns success result as DirectNavigator initialization cannot fail

inline State makeState(const Options &options) const

Create a new navigation state from options.

Parameters:

options – The navigator options

Returns:

New state initialized with the provided options

inline bool navigationBreak(const State &state) const

Check if navigation should break/stop.

Parameters:

state – The navigation state

Returns:

True if navigation should break, false otherwise

inline NavigationTarget nextTarget(State &state, const Vector3 &position, const Vector3 &direction) const

Get the next target surface.

This function gets the next target surface for the propagation. For the direct navigator this is always the next surface in the sequence.

Parameters:

• state – The navigation state

• position – The current position

• direction – The current direction

Returns:

The next target surface

inline const Surface *startSurface(const State &state) const

Get the start surface from the navigation state.

Parameters:

state – The navigation state

Returns:

Pointer to start surface, nullptr if none

inline const Surface *targetSurface(const State &state) const

Get the target surface from the navigation state.

Parameters:

state – The navigation state

Returns:

Pointer to target surface, nullptr if none

struct Config

The nested configuration struct.

struct Options : public Acts::NavigatorPlainOptions

The nested options struct.

Public Functions

inline explicit Options(const GeometryContext &gctx)

Constructor from geometry context.

Parameters:

gctx – The geometry context

inline void setPlainOptions(const NavigatorPlainOptions &options)

Set the plain navigator options.

Parameters:

options – The plain navigator options to copy

Public Members

double farLimit = std::numeric_limits<double>::max()

The far limit to resolve surfaces.

double nearLimit = -100 * UnitConstants::um

Distance limit to discard intersections “behind us”.

Note

this is only necessary because some surfaces have more than one intersection

double surfaceTolerance = s_onSurfaceTolerance

The surface tolerance.

struct State

Nested State struct.

It acts as an internal state which is created for every propagation/extrapolation step and keep thread-local navigation information

Public Functions

inline explicit State(const Options &options_)

Constructor from options.

Parameters:

options_ – The navigator options

inline bool endOfSurfaces() const

Check if we have reached the end of the surface sequence.

Returns:

True if no more surfaces remain in the propagation direction

inline const Surface &navSurface() const

Get the current navigation surface.

Returns:

Reference to the surface at the current surface index

inline void nextSurface()

Move to the next surface in the sequence Increments or decrements surface index based on propagation direction.

inline int remainingSurfaces() const

Get the number of surfaces remaining in the sequence.

Returns:

Number of surfaces left to process in the propagation direction

inline void resetSurfaceIndex()

Reset the surface index to the initial position Sets index to before first surface (forward) or after last surface (backward)

Public Members

const Surface *currentSurface = nullptr

Navigation state - external interface: the current surface.

Direction direction = Direction::Forward()

Propagation direction (forward or backward)

bool navigationBreak = false

Navigation state - external interface: a break has been detected.

Options options

Configuration options for the direct navigator.

NavigatorStatistics statistics

Navigation statistics.

std::int32_t surfaceIndex = -1

Index of the next surface to try.

Note

-1 means before the first surface in the sequence and size() means after the last surface in the sequence

class Direction

The direction is always with respect to a given momentum, surface normal or other general axes.

Unnamed Group

inline friend constexpr friend int operator* (Direction dir, int value)

Arithmetic operators.

Multiply Direction with integer

Parameters:

• dir – Direction value

• value – Integer to multiply

Returns:

Signed integer result

inline friend constexpr friend float operator* (Direction dir, float value)

Multiply Direction with float.

Parameters:

• dir – Direction value

• value – Float to multiply

Returns:

Signed float result

inline friend constexpr friend double operator* (Direction dir, double value)

Multiply Direction with double.

Parameters:

• dir – Direction value

• value – Double to multiply

Returns:

Signed double result

inline friend Acts::Vector3 operator*(Direction dir, const Acts::Vector3 &value)

Multiply Direction with Vector3.

Parameters:

• dir – Direction value

• value – Vector3 to multiply

Returns:

Signed Vector3 result

inline friend constexpr friend int operator* (int value, Direction dir)

Multiply integer with Direction.

Parameters:

• value – Integer to multiply

• dir – Direction value

Returns:

Signed integer result

inline friend constexpr friend float operator* (float value, Direction dir)

Multiply float with Direction.

Parameters:

• value – Float to multiply

• dir – Direction value

Returns:

Signed float result

inline friend constexpr friend double operator* (double value, Direction dir)

Multiply double with Direction.

Parameters:

• value – Double to multiply

• dir – Direction value

Returns:

Signed double result

inline friend Acts::Vector3 operator*(const Acts::Vector3 &value, Direction dir)

Multiply Vector3 with Direction.

Parameters:

• value – Vector3 to multiply

• dir – Direction value

Returns:

Signed Vector3 result

inline friend constexpr friend int operator*= (int &value, Direction dir)

Multiply-assign integer with Direction.

Parameters:

• value – Integer reference to modify

• dir – Direction value

Returns:

Reference to modified integer

inline friend constexpr friend float operator*= (float &value, Direction dir)

Multiply-assign float with Direction.

Parameters:

• value – Float reference to modify

• dir – Direction value

Returns:

Reference to modified float

inline friend constexpr friend double operator*= (double &value, Direction dir)

Multiply-assign double with Direction.

Parameters:

• value – Double reference to modify

• dir – Direction value

Returns:

Reference to modified double

inline friend Acts::Vector3 &operator*=(Acts::Vector3 &value, Direction dir)

Multiply-assign Vector3 with Direction.

Parameters:

• value – Vector3 reference to modify

• dir – Direction value

Returns:

Reference to modified Vector3

Public Functions

inline constexpr std::size_t index() const

Convert dir to index [0,1] which allows to store direction dependent objects in std::array<T, 2u>

Returns:

either 0 or 1

inline constexpr Direction invert() const

Reverse the direction.

Returns:

an opposite direction

constexpr bool operator==(const Direction &rhs) const noexcept = default

Check if two directions are equal.

Parameters:

rhs – The Direction to compare to

Returns:

True if the two Directions are equal, false otherwise

inline constexpr int sign() const

Turns the direction into a signed value.

Returns:

a signed value

std::string toString() const

Convert direction to string representation.

Returns:

String representation of the direction (“positive” or “negative”)

Public Static Functions

static inline constexpr Direction AlongNormal()

Create direction along normal (positive)

Returns:

Direction with positive value, along surface normal

static inline constexpr Direction Backward()

Create backward direction (equivalent to negative)

Returns:

Direction with negative value for backward propagation

static inline constexpr Direction Forward()

Create forward direction (equivalent to positive)

Returns:

Direction with positive value for forward propagation

static inline constexpr Direction fromIndex(std::size_t index)

Convert and index [0,1] to a direction e.g.

for sorting in std::array<T, 2u>

Parameters:

index – is the direction at input

Returns:

Direction corresponding to the index (0->Negative, 1->Positive)

static inline constexpr Direction fromScalar(double scalar)

This turns a signed value into a direction.

Will assert on zero.

Parameters:

scalar – is the signed value

Returns:

a direction enum

static inline constexpr Direction fromScalarZeroAsPositive(double scalar)

This turns a signed value into a direction and 0 will be handled as a positive direction.

Only use this when you are convinced that the 0 case is properly handled downstream.

Parameters:

scalar – is the signed value

Returns:

a direction enum

static inline constexpr Direction Negative()

Create negative direction (-1)

Returns:

Direction with negative value

static inline constexpr Direction OppositeNormal()

Create direction opposite to normal (negative)

Returns:

Direction with negative value, opposite to surface normal

static inline constexpr Direction Positive()

Create positive direction (+1)

Returns:

Direction with positive value

Friends

inline friend std::ostream &operator<<(std::ostream &os, Direction dir)

Stream operator for Direction.

Parameters:

• os – Output stream

• dir – Direction to output

Returns:

Reference to output stream

class DiscBounds : public Acts::SurfaceBounds

common base class for all bounds that are in a r/phi frame

• simply introduced to avoid wrong bound assignments to surfaces

Subclassed by Acts::AnnulusBounds, Acts::DiscTrapezoidBounds, Acts::RadialBounds

Public Functions

virtual double binningValuePhi() const = 0

Returns a refererance phi for binning.

Returns:

Reference phi angle value used for binning purposes

virtual double binningValueR() const = 0

Returns a reference radius for binning.

Returns:

Reference radius value used for binning purposes

virtual bool coversFullAzimuth() const = 0

Returns true for full phi coverage.

Returns:

True if the bounds cover the full azimuthal range, false otherwise

virtual bool insideRadialBounds(double R, double tolerance = 0.) const = 0

Checks if it’s inside the radius.

Parameters:

• R – The radius value to check

• tolerance – The tolerance for the check

Returns:

True if the radius is within the bounds, false otherwise

virtual double rMax() const = 0

Return method for outer Radius.

Returns:

Maximum radius of the disc bounds

virtual double rMin() const = 0

Return method for inner Radius.

Returns:

Minimum radius of the disc bounds

virtual std::vector<Vector2> vertices(unsigned int quarterSegments = 2u) const = 0

Return the vertices.

Parameters:

quarterSegments – The number of segments used to describe a quarter of a circle, if it is 1, then only the extrema points in phi are inserted next to the segment corners

Returns:

vector for vertices in 2D

class DiscLayer : public virtual Acts::DiscSurface, public Acts::Layer

Class to describe a disc-like detector layer for tracking, it inherits from both, Layer base class and DiscSurface class.

Public Functions

DiscLayer() = delete

DiscLayer(const DiscLayer &cla) = delete

~DiscLayer() override = default

DiscLayer &operator=(const DiscLayer&) = delete

virtual const DiscSurface &surfaceRepresentation() const override

Transforms the layer into a Surface representation for extrapolation.

Returns:

This method returns a surface reference

virtual DiscSurface &surfaceRepresentation() override

Non-const version of surface representation access.

Returns:

Mutable reference to the disc surface

Public Static Functions

static std::shared_ptr<DiscLayer> create(const Transform3 &transform, const std::shared_ptr<const DiscBounds> &dbounds, std::unique_ptr<SurfaceArray> surfaceArray, double thickness = 0., std::unique_ptr<ApproachDescriptor> ad = nullptr, LayerType laytyp = passive)

Factory constructor with DiscSurface components.

Parameters:

• transform – is the transform to place the layer in the 3D frame

• dbounds – are the disc bounds that describe the layer dimensions

• surfaceArray – is the array of sensitive surfaces

• thickness – is the layer thickness (along the normal vector)

• ad – is the approach descriptor that provides the approach surface

• laytyp – is the layer type

Returns:

a sharted pointer to the new layer

class DiscSurface : public Acts::RegularSurface

Class for a disc surface (or a segment thereof)

The DiscSurface is defined by the local polar coordinates \( (r,phi) \).

The surface transform positions the disc such that the origin is at \( r=0 \), independent of the provided DiscBounds. The normal vector of the disc (i.e., the local \(z\)-axis) is given by \( \vec e_{z} = \vec e_{r} \times\vec e_{phi} \).

The disc surface The only surface type for which the covariance matrix is NOT given in the reference frame. A conversion from polar to cartesian coordinates needs to happen to transfer the local coordinates onto the cartesian reference frame coordinates.

Subclassed by Acts::DiscLayer

Public Functions

void assignSurfaceBounds(std::shared_ptr<const DiscBounds> newBounds)

Overwrite the existing surface bounds with new ones.

Parameters:

newBounds – Pointer to the new bounds

virtual const SurfaceBounds &bounds() const final

This method returns the bounds by reference.

Returns:

Reference to the surface bounds

const std::shared_ptr<const DiscBounds> &boundsPtr() const

This method returns the shared_ptr to the DiscBounds.

Returns:

Shared pointer to the disc bounds

virtual BoundToFreeMatrix boundToFreeJacobian(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Calculate the jacobian from local to global which the surface knows best, hence the calculation is done here.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Jacobian from local to global

virtual FreeToBoundMatrix freeToBoundJacobian(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Calculate the jacobian from global to local which the surface knows best, hence the calculation is done here.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Jacobian from global to local

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final

Convert a global position to a local one this is the most generic interface, which is implemented by all surfaces.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be converted

• direction – is the direction of the local position (ignored for RegularSurface)

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const final

Global to local transformation.

Note

the direction is ignored for Disc surfaces in this calculateion

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position - considered to be on surface but not inside bounds (check is done)

• tolerance – optional tolerance within which a point is considered valid on surface

Returns:

a Result<Vector2> which can be !ok() if the operation fails

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const = 0

Convert a global position to a local one.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be converted

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

Vector2 globalToLocalCartesian(const GeometryContext &gctx, const Vector3 &position, double tol = 0.) const

Special method for DiscSurface : global<->local from cartesian coordinates.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is a global cartesian 3D position

• tol – The absolute tolerance parameter

Returns:

value is a local polar

virtual MultiIntersection3D intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), double tolerance = s_onSurfaceTolerance) const final

Straight line intersection schema.

Mathematical motivation:

the equation of the plane is given by: \( \vec n \cdot \vec x = \vec n \cdot \vec p,\) where \( \vec n = (n_{x}, n_{y}, n_{z})\) denotes the normal vector of the plane, \( \vec p = (p_{x}, p_{y}, p_{z})\) one specific point on the plane and \( \vec x = (x,y,z) \)

all possible points on the plane.

Given a line with:

\( \vec l(u) = \vec l_{1} + u \cdot \vec v \)

,

the solution for

\( u \) can be written: \( u = \frac{\vec n (\vec p - \vec l_{1})}{\vec n \vec v}\) If the denominator is 0 then the line lies:

• either in the plane

• perpendicular to the normal of the plane

Note

expected to be normalized (no checking)

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The global position as a starting point

• direction – The global direction at the starting point

• boundaryTolerance – The boundary check prescription

• tolerance – the tolerance used for the intersection

Returns:

The MultiIntersection3D object

virtual Matrix<2, 3> localCartesianToBoundLocalDerivative(const GeometryContext &gctx, const Vector3 &position) const final

Calculate the derivative of bound track parameters local position w.r.t.

position in local 3D Cartesian coordinates

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The position of the parameters in global

Returns:

Derivative of bound local position w.r.t. position in local 3D cartesian coordinates

Vector3 localCartesianToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const

Special method for DiscSurface : local<->global transformation when provided cartesian coordinates.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is local 2D position in cartesian coordinates

Returns:

value is a global cartesian 3D position

Vector2 localCartesianToPolar(const Vector2 &lcart) const

Special method for Disc surface : local<->local transformations polar <-> cartesian.

Parameters:

lcart – is local 2D position in cartesian coordinates

Returns:

value is a local position in polar coordinates

Vector2 localPolarToCartesian(const Vector2 &lpolar) const

Special method for DiscSurface : local<->local transformations polar <-> cartesian.

Parameters:

lpolar – is a local position in polar coordinates

Returns:

values is local 2D position in cartesian coordinates

Vector2 localPolarToLocalCartesian(const Vector2 &locpol) const

Special method for DiscSurface : local<->local transformations polar <-> cartesian.

Parameters:

locpol – is a local position in polar coordinates

Returns:

values is local 2D position in cartesian coordinates

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const final

Local to global transformation For planar surfaces the momentum direction is ignored in the local to global transformation.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

Returns:

global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Local to global transformation.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const final

Local to global transformation.

This is the most generic interface, which is implemented by all surfaces.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

• direction – global 3D momentum direction (ignored for RegularSurface)

Returns:

The global position by value

std::pair<std::shared_ptr<DiscSurface>, bool> mergedWith(const DiscSurface &other, AxisDirection direction, bool externalRotation, const Logger &logger = getDummyLogger()) const

Merge two disc surfaces into a single one.

Note

The surfaces need to be compatible, i.e. have disc bounds that align

Note

The returned boolean is false if this is left or counter-clockwise of other, and true if not.

Parameters:

• other – The other disc surface to merge with

• direction – The binning direction: either AxisR or AxisPhi

• externalRotation – If true, any phi rotation is done in the transform

• logger – The logger to use

Returns:

The merged disc surface and a boolean indicating if surfaces are reversed

virtual std::string name() const override

Return properly formatted class name for screen output.

Returns:

String representation of the class name

Vector3 normal(const GeometryContext &gctx) const

Get the normal vector, independent of the location.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

The normal vector

virtual Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const final

Normal vector return.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – The local position is ignored

Returns:

a Vector3 by value

Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Calculate the normal vector of the surface This overload requires an on-surface local position.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is the local position where the normal vector is constructed

Returns:

normal vector by value

Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const final

Calculate the normal vector of the surface This overload is fully generic, fulfills the Surface interface and accepts a global position and a direction.

For RegularSurface this is equivalent to the normal overload, ignoring the direction

Parameters:

• gctx – The current geometry context object, e.g. alignment

• pos – is the global position where the normal vector is constructed

• direction – is the direction of the normal vector (ignored for RegularSurface)

Returns:

Normal vector at the given position

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const final

Get the normal vector of this surface at a given global position.

Note

The position is required to be on-surface.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global positiono (for DiscSurface this is ignored)

Returns:

The normal vector

Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const = 0

Calculate the normal vector of the surface This overload accepts a global position.

Parameters:

• position – is the global position where the normal vector is constructed

• gctx – The current geometry context object, e.g. alignment

Returns:

normal vector by value

DiscSurface &operator=(const DiscSurface &other)

Assignment operator.

Parameters:

other – The source sourface for the assignment

Returns:

Reference to this DiscSurface after assignment

virtual double pathCorrection(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Path correction due to incident of the track.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The global position as a starting point

• direction – The global momentum direction at the starting point

Returns:

The correction factor due to incident

virtual Polyhedron polyhedronRepresentation(const GeometryContext &gctx, unsigned int quarterSegments) const override

Return a Polyhedron for the surfaces.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• quarterSegments – Number of segments used to describe the quarter of a full circle

Returns:

A list of vertices and a face/facett description of it

RotationMatrix3 referenceFrame(const GeometryContext &gctx) const

Return method for the reference frame This is the frame in which the covariance matrix is defined (specialized by all surfaces)

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

RotationMatrix3 which defines the three axes of the measurement frame

RotationMatrix3 referenceFrame(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Return method for the reference frame This is the frame in which the covariance matrix is defined (specialized by all surfaces)

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position - considered to be on surface but not inside bounds (check is done)

• direction – global 3D momentum direction (optionally ignored)

Returns:

RotationMatrix3 which defines the three axes of the measurement frame

virtual Vector3 referencePosition(const GeometryContext &gctx, AxisDirection aDir) const final

A reference position for a given axis direction.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• aDir – The axis direction for the reference position request

Returns:

position that can beused for this binning

virtual double referencePositionValue(const GeometryContext &gctx, AxisDirection aDir) const final

A reference position value for a given axis direction.

Note

This calls the parent method except for AxisR

Parameters:

• gctx – The current geometry context object, e.g. alignment

• aDir – the value generated for the reference position

Returns:

float to be used for the binning schema

virtual SurfaceType type() const override

Return the surface type.

Returns:

Surface type identifier

class DiscTrapezoidBounds : public Acts::DiscBounds

Class to describe the bounds for a planar DiscSurface.

By providing an argument for hphisec, the bounds can be restricted to a phi-range around the center position.

Public Types

enum BoundValues

Enumeration for the bound values.

Values:

enumerator eHalfLengthXminR

enumerator eHalfLengthXmaxR

enumerator eMinR

enumerator eMaxR

enumerator eAveragePhi

enumerator eStereo

enumerator eSize

Public Functions

inline explicit DiscTrapezoidBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor - from fixed size array.

Parameters:

values – The parameter values

explicit DiscTrapezoidBounds(double halfXminR, double halfXmaxR, double minR, double maxR, double avgPhi = std::numbers::pi / 2., double stereo = 0.) noexcept(false)

Constructor for a symmetric Trapezoid giving min X length, max X length, Rmin and R max.

Parameters:

• halfXminR – half length in X at min radius

• halfXmaxR – half length in X at maximum radius

• minR – inner radius

• maxR – outer radius

• avgPhi – average phi value

• stereo – optional stereo angle applied

inline virtual double binningValuePhi() const final

Return a reference phi for binning.

Returns:

Average phi angle for binning purposes

inline virtual double binningValueR() const final

Return a reference radius for binning.

Returns:

Average radius for binning purposes

virtual SquareMatrix2 boundToCartesianJacobian(const Vector2 &lposition) const final

Computes the bound to cartesian jacobian at a given local position.

Parameters:

lposition – is the local position at which the jacobian is computed

Returns:

the bound to cartesian jacobian

virtual SquareMatrix2 boundToCartesianMetric(const Vector2 &lposition) const final

Computes the bound to cartesian metric at a given local position.

Parameters:

lposition – is the local position at which the metric is computed

Returns:

the bound to cartesian metric

virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Returns:

Vector2 representing the center position in local coordinates

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

inline virtual bool coversFullAzimuth() const final

Returns true for full phi coverage - obviously false here.

Returns:

Always false since disc trapezoids have limited phi coverage

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

The value of the specified bound parameter

inline double halfLengthY() const

This method returns the half length in Y (this is Rmax -Rmin)

Returns:

Half length in Y direction calculated from radial bounds

inline double halfPhiSector() const

This method returns the halfPhiSector which is covered by the disc.

Returns:

Half phi sector angle covered by the disc trapezoid

virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

inline virtual bool insideRadialBounds(double R, double tolerance = 0.) const final

Checks if this is inside the radial coverage given the a tolerance.

Parameters:

• R – The radius value to check

• tolerance – The tolerance for the check

Returns:

True if radius is within bounds (plus tolerance), false otherwise

inline virtual bool isCartesian() const final

Check if the bound coordinates are cartesian.

Returns:

true if the bound coordinates are cartesian

inline double rCenter() const

This method returns the center radius.

Returns:

Center radius calculated from inner and outer bounds

inline virtual double rMax() const final

This method returns outer radius.

Returns:

Maximum radius of the disc trapezoid

inline virtual double rMin() const final

This method returns inner radius.

Returns:

Minimum radius of the disc trapezoid

inline double stereo() const

This method returns the stereo angle.

Returns:

Stereo angle of the disc trapezoid

virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream.

Parameters:

sl – The output stream to write to

Returns:

Reference to the output stream after writing

inline virtual BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

the bounds type

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

virtual std::vector<Vector2> vertices(unsigned int ignoredSegments = 0u) const final

This method returns the xy coordinates of the four corners of the bounds in module coorindates (in xy)

Parameters:

ignoredSegments – is an ignored parameter only used for curved bound segments

Returns:

vector for vertices in 2D

template<typename extension_t = EigenStepperDefaultExtension>
class EigenStepper

Runge-Kutta-Nystroem stepper based on Eigen implementation for the following ODE:

r = (x,y,z) … global position T = (Ax,Ay,Az) … momentum direction (normalized)

dr/ds = T dT/ds = q/p * (T x B)

with s being the arc length of the track, q the charge of the particle, p the momentum magnitude and B the magnetic field

Public Types

using BoundParameters = BoundTrackParameters

Type alias for bound track parameters.

using BoundState = std::tuple<BoundParameters, Jacobian, double>

Bound state tuple containing parameters, Jacobian, and path length.

using Covariance = BoundMatrix

Type alias for covariance matrix.

using Jacobian = BoundMatrix

Type alias for jacobian matrix.

Public Functions

inline explicit EigenStepper(const Config &config)

Constructor with configuration.

Parameters:

config – [in] The configuration of the stepper

explicit EigenStepper(std::shared_ptr<const MagneticFieldProvider> bField)

Constructor requires knowledge of the detector’s magnetic field.

Parameters:

bField – The magnetic field provider

inline double absoluteMomentum(const State &state) const

Absolute momentum accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Absolute momentum magnitude

Result<BoundState> boundState(State &state, const Surface &surface, bool transportCov = true, const FreeToBoundCorrection &freeToBoundCorrection = FreeToBoundCorrection(false)) const

Create and return the bound state at the current position.

This transports (if necessary) the covariance to the surface and creates a bound state. It does not check if the transported state is at the surface, this needs to be guaranteed by the propagator

Parameters:

• state – [in] State that will be presented as BoundState

• surface – [in] The surface to which we bind the state

• transportCov – [in] Flag steering covariance transport

• freeToBoundCorrection – [in] Correction for non-linearity effect during transform from free to bound

Returns:

A bound state:

• the parameters at the surface

• the stepwise jacobian towards it (from last bound)

• and the path length (from start - for ordering)

inline double charge(const State &state) const

Charge access.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Electric charge of the particle

BoundState curvilinearState(State &state, bool transportCov = true) const

Create and return a curvilinear state at the current position.

This transports (if necessary) the covariance to the current position and creates a curvilinear state.

Parameters:

• state – [in] State that will be presented as CurvilinearState

• transportCov – [in] Flag steering covariance transport

Returns:

A curvilinear state:

• the curvilinear parameters at given position

• the stepweise jacobian towards it (from last bound)

• and the path length (from start - for ordering)

inline Vector3 direction(const State &state) const

Momentum direction accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Current normalized direction vector

inline Result<Vector3> getField(State &state, const Vector3 &pos) const

Get the field for the stepping, it checks first if the access is still within the Cell, and updates the cell if necessary.

Parameters:

• state – [inout] is the propagation state associated with the track the magnetic field cell is used (and potentially updated)

• pos – [in] is the field position

Returns:

Magnetic field vector at the given position or error

inline double getStepSize(const State &state, ConstrainedStep::Type stype) const

Get the step size.

Parameters:

• state – [in] The stepping state (thread-local cache)

• stype – [in] The step size type to be returned

Returns:

Current step size for the specified constraint type

void initialize(State &state, const BoundParameters &par) const

Initialize the stepper state from bound track parameters.

Parameters:

• state – Stepper state to initialize

• par – Bound track parameters to initialize from

void initialize(State &state, const BoundVector &boundParams, const std::optional<BoundMatrix> &cov, ParticleHypothesis particleHypothesis, const Surface &surface) const

Initialize the stepper state from bound parameters and surface.

Parameters:

• state – Stepper state to initialize

• boundParams – Vector of bound track parameters

• cov – Optional covariance matrix

• particleHypothesis – Particle hypothesis for the track

• surface – Surface associated with the parameters

State makeState(const Options &options) const

Create a stepper state from given options.

Parameters:

options – Configuration options for the stepper state

Returns:

Initialized stepper state object

inline Vector3 momentum(const State &state) const

Momentum accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Current momentum vector

inline std::string outputStepSize(const State &state) const

Output the Step Size - single component.

Parameters:

state – [in,out] The stepping state (thread-local cache)

Returns:

String representation of the current step size

inline const ParticleHypothesis &particleHypothesis(const State &state) const

Particle hypothesis.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Reference to the particle hypothesis used

inline Vector3 position(const State &state) const

Global particle position accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Current global position vector

bool prepareCurvilinearState(State &state) const

If necessary fill additional members needed for curvilinearState.

Compute path length derivatives in case they have not been computed yet, which is the case if no step has been executed yet.

Parameters:

state – [inout] The state of the stepper

Returns:

true if nothing is missing after this call, false otherwise.

inline double qOverP(const State &state) const

QoP direction accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Charge over momentum (q/p) value

inline void releaseStepSize(State &state, ConstrainedStep::Type stype) const

Release the Step size.

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• stype – [in] The step size type to be released

Result<double> step(State &state, Direction propDir, const IVolumeMaterial *material) const

Perform a Runge-Kutta track parameter propagation step.

Note

The state contains the desired step size. It can be negative during backwards track propagation, and since we’re using an adaptive algorithm, it can be modified by the stepper class during propagation.

Parameters:

• state – [inout] State of the stepper

• propDir – is the direction of propagation

• material – is the optional volume material we are stepping through.

Returns:

the result of the step

inline double time(const State &state) const

Time access.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

The time coordinate from the free parameters vector

void transportCovarianceToBound(State &state, const Surface &surface, const FreeToBoundCorrection &freeToBoundCorrection = FreeToBoundCorrection(false)) const

Method for on-demand transport of the covariance to a new curvilinear frame at current position, or direction of the state.

Note

no check is done if the position is actually on the surface

Template Parameters:

surface_t – the Surface type

Parameters:

• state – [inout] State of the stepper

• surface – [in] is the surface to which the covariance is forwarded to

• freeToBoundCorrection – [in] Correction for non-linearity effect during transform from free to bound

void transportCovarianceToCurvilinear(State &state) const

Method for on-demand transport of the covariance to a new curvilinear frame at current position, or direction of the state.

Parameters:

state – [inout] State of the stepper

void update(State &state, const FreeVector &freeParams, const BoundVector &boundParams, const Covariance &covariance, const Surface &surface) const

Method to update a stepper state to the some parameters.

Parameters:

• state – [inout] State object that will be updated

• freeParams – [in] Free parameters that will be written into state

• boundParams – [in] Corresponding bound parameters used to update jacToGlobal in state

• covariance – [in] The covariance that will be written into state

• surface – [in] The surface used to update the jacToGlobal

void update(State &state, const Vector3 &uposition, const Vector3 &udirection, double qOverP, double time) const

Method to update the stepper state.

Parameters:

• state – [inout] State object that will be updated

• uposition – [in] the updated position

• udirection – [in] the updated direction

• qOverP – [in] the updated qOverP value

• time – [in] the updated time value

inline void updateStepSize(State &state, const NavigationTarget &target, Direction direction, ConstrainedStep::Type stype) const

Update step size.

This method intersects the provided surface and update the navigation step estimation accordingly (hence it changes the state). It also returns the status of the intersection to trigger onSurface in case the surface is reached.

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• target – [in] The NavigationTarget

• direction – [in] The propagation direction

• stype – [in] The step size type to be set

inline void updateStepSize(State &state, double stepSize, ConstrainedStep::Type stype) const

Update step size - explicitly with a double.

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• stepSize – [in] The step size value

• stype – [in] The step size type to be set

inline IntersectionStatus updateSurfaceStatus(State &state, const Surface &surface, std::uint8_t index, Direction propDir, const BoundaryTolerance &boundaryTolerance, double surfaceTolerance, ConstrainedStep::Type stype, const Logger &logger = getDummyLogger()) const

Update surface status.

It checks the status to the reference surface & updates the step size accordingly

Parameters:

• state – [inout] The stepping state (thread-local cache)

• surface – [in] The surface provided

• index – [in] The surface intersection index

• propDir – [in] The propagation direction

• boundaryTolerance – [in] The boundary check for this status update

• surfaceTolerance – [in] Surface tolerance used for intersection

• stype – [in] The step size type to be set

• logger – [in] A Logger instance

Returns:

Status of the intersection indicating whether surface was reached

struct Config

Configuration for the Eigen stepper.

Public Members

std::shared_ptr<const MagneticFieldProvider> bField

Magnetic field provider.

struct Options : public Acts::StepperPlainOptions

Stepper options including geometry and magnetic field contexts.

Public Functions

inline Options(const GeometryContext &gctx, const MagneticFieldContext &mctx)

Constructor from geometry and magnetic field contexts.

Parameters:

• gctx – The geometry context

• mctx – The magnetic field context

inline void setPlainOptions(const StepperPlainOptions &options)

Set plain options.

Parameters:

options – The plain options to set

struct State

State for track parameter propagation.

It contains the stepping information and is provided thread local by the propagator

Public Functions

inline State(const Options &optionsIn, MagneticFieldProvider::Cache fieldCacheIn)

Constructor from the initial bound track parameters.

Note

the covariance matrix is copied when needed

Parameters:

• optionsIn – [in] is the options object for the stepper

• fieldCacheIn – [in] is the cache object for the magnetic field

Public Members

Vector3 B_first = {}

Magnetic field evaluations.

Vector3 B_last = {}

Vector3 B_middle = {}

Covariance cov = Covariance::Zero()

Covariance matrix for track parameter uncertainties.

bool covTransport = false

Covariance matrix (and indicator) associated with the initial error on track parameters.

FreeVector derivative = FreeVector::Zero()

The propagation derivative.

extension_t extension

Algorithmic extension.

MagneticFieldProvider::Cache fieldCache

This caches the current magnetic field cell and stays (and interpolates) within it as long as this is valid.

See step() code for details.

Jacobian jacobian = Jacobian::Identity()

The full jacobian of the transport entire transport.

BoundToFreeMatrix jacToGlobal = BoundToFreeMatrix::Zero()

Jacobian from local to the global frame.

FreeMatrix jacTransport = FreeMatrix::Identity()

Pure transport jacobian part from runge kutta integration.

Vector3 k1 = {}

k_i of the RKN4 algorithm

Vector3 k2 = {}

Vector3 k3 = {}

Vector3 k4 = {}

std::array<double, 4> kQoP = {}

k_i elements of the momenta

std::size_t nSteps = 0

Total number of performed steps.

std::size_t nStepTrials = 0

Totoal number of attempted steps.

Options options

Configuration options for the Eigen stepper.

FreeVector pars = FreeVector::Zero()

Internal free vector parameters.

ParticleHypothesis particleHypothesis = ParticleHypothesis::pion()

Particle hypothesis.

double pathAccumulated = 0.

Accumulated path length state.

double previousStepSize = 0.

Last performed step (for overstep limit calculation)

StepperStatistics statistics

Statistics of the stepper.

struct Acts::EigenStepper::State::[anonymous] stepData

Storage of magnetic field and the sub steps during a RKN4 step.

ConstrainedStep stepSize

Adaptive step size of the runge-kutta integration.

class EllipseBounds : public Acts::PlanarBounds

Class to describe the bounds for a planar ellispoid surface.

By providing an argument for hphisec, the bounds can be restricted to a phi-range around the center position.

Public Types

enum BoundValues

Enumeration for the bound values.

Values:

enumerator eInnerRx

enumerator eInnerRy

enumerator eOuterRx

enumerator eOuterRy

enumerator eHalfPhiSector

enumerator eAveragePhi

enumerator eSize

Public Functions

inline explicit EllipseBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor - from fixed size array.

Parameters:

values – The parameter values

inline explicit EllipseBounds(double innerRx, double innerRy, double outerRx, double outerRy, double halfPhi = std::numbers::pi, double averagePhi = 0.) noexcept(false)

Constructor for full of an ellipsoid ring.

Parameters:

• innerRx – The inner ellipse radius in x

• innerRy – The inner ellipse radius in y

• outerRx – The outer ellipse radius in x

• outerRy – The outer ellipse radius in y

• halfPhi – spanning phi sector (is set to pi as default)

• averagePhi – average phi (is set to 0. as default)

virtual const RectangleBounds &boundingBox() const final

Bounding box parameters.

Returns:

rectangle bounds for a bounding box

virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Returns:

Vector2 representing the center position in local coordinates

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

Value of the specified bound parameter

virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream.

Parameters:

sl – The output stream to write to

Returns:

Reference to the output stream after writing

inline virtual BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

the bounds type

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

virtual std::vector<Vector2> vertices(unsigned int quarterSegments) const final

Return the vertices.

Parameters:

quarterSegments – is the number of segments to approximate a quarter of a circle. In order to symmetrize fully closed and sectoral cylinders, also in the first case the two end points are given (albeit they overlap) in -pi / pi

Returns:

vector for vertices in 2D

class GainMatrixSmoother

Kalman trajectory smoother based on gain matrix formalism.

This implements not a single smoothing step, but the full backwards smoothing procedure for a filtered, forward trajectory using the stored linearization.

Public Types

using GetCovariance = Acts::Delegate<TrackStateTraits<kMeasurementSizeMax, false>::Covariance(void*)>

Type alias for delegate to get track state covariance matrix.

using GetParameters = Acts::Delegate<TrackStateTraits<kMeasurementSizeMax, false>::Parameters(void*)>

Type alias for delegate to get track state parameters.

Public Functions

Result<void> calculate(AnyMutableTrackStateProxy ts, AnyConstTrackStateProxy prev_ts, const Logger &logger) const

Calculate smoothed parameters for a single track state using gain matrix formalism.

Parameters:

• ts – Current track state to be smoothed

• prev_ts – Previous track state (in forward direction)

• logger – Logger for verbose output

Returns:

Success or failure of the smoothing calculation

template<typename traj_t>
inline Result<void> operator()(const GeometryContext &gctx, traj_t &trajectory, std::size_t entryIndex, const Logger &logger = getDummyLogger()) const

Run the Kalman smoothing for one trajectory.

Parameters:

• gctx – [in] The geometry context to be used

• trajectory – [inout] The trajectory to be smoothed

• entryIndex – [in] The index of state to start the smoothing

• logger – [in] Where to write logging information to

Returns:

Success or failure of the smoothing procedure

Public Members

bool doCovCheckAndAttemptFix = false

Whether to check the covariance matrices if they are semi-positive and if not attempt to correct them.

class GainMatrixUpdater

Kalman update step using the gain matrix formalism.

Public Functions

GainMatrixUpdater() = default

inline explicit GainMatrixUpdater(bool useJosephFormulation)

Parameters:

useJosephFormulation – Whether to use the Joseph formulation for the covariance update, which is more numerically stable at the cost of additional computations.

template<typename traj_t>
inline Result<void> operator()(const GeometryContext&, typename traj_t::TrackStateProxy trackState, const Logger &logger = getDummyLogger()) const

Run the Kalman update step for a single trajectory state.

Template Parameters:

kMeasurementSizeMax –

Parameters:

• trackState – [inout] The track state

• logger – [in] Where to write logging information to

Returns:

Success or failure of the update procedure

class GenericCuboidVolumeBounds : public Acts::VolumeBounds

Volume bounds described by eight arbitrary cuboid vertices.

Public Functions

GenericCuboidVolumeBounds() = delete

explicit GenericCuboidVolumeBounds(const std::array<Acts::Vector3, 8> &vertices) noexcept(false)

Constructor from a set of vertices.

The ordering is considered to be:

• the first 4 vertices are the “top” face

• the second 4 vertices are the “bottom” face

• both faces are given in counter clock wise order

Parameters:

vertices – The set of input vertices

explicit GenericCuboidVolumeBounds(const std::array<double, BoundValues::eSize> &values) noexcept(false)

Constructor from a fixed size array.

Parameters:

values – The input values

~GenericCuboidVolumeBounds() override = default

virtual Volume::BoundingBox boundingBox(const Transform3 *trf = nullptr, const Vector3 &envelope = {0, 0, 0}, const Volume *entity = nullptr) const final

Construct bounding box for this shape.

Parameters:

• trf – Optional transform

• envelope – Optional envelope to add / subtract from min/max

• entity – Entity to associate this bounding box with

Returns:

Constructed bounding box

inline virtual std::vector<AxisDirection> canonicalAxes() const override

Get the canonical direction values, i.e.

the axis directions that fully describe the shape’s extent

Returns:

vector of canonical binning values

void draw(IVisualization3D &helper, const Transform3 &transform = Transform3::Identity()) const

Draw this shape using a visualization helper.

Parameters:

• helper – The visualizatin helper

• transform – Optional transformation matrix

virtual bool inside(const Vector3 &gpos, double tol = 0.) const override

Checking if position given in volume frame is inside.

Parameters:

• gpos – is the global position to be checked

• tol – is the tolerance applied for the inside check

Returns:

boolean indicating if the position is inside

virtual std::vector<OrientedSurface> orientedSurfaces(const Transform3 &transform = Transform3::Identity()) const override

Oriented surfaces, i.e.

the decomposed boundary surfaces and the according navigation direction into the volume given the normal vector on the surface

It will throw an exception if the orientation prescription is not adequate

Parameters:

transform – is the 3D transform to be applied to the boundary surfaces to position them in 3D space

Returns:

a vector of surfaces bounding this volume

virtual std::ostream &toStream(std::ostream &sl) const override

Parameters:

sl – is the output stream to be written into

Returns:

The output stream

inline virtual VolumeBounds::BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

is a BoundsType enum

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

struct BoundValues

This struct helps to symmetrize with the the other volume bounds classes.

Public Static Attributes

static constexpr std::size_t eSize = 24

Number of boundary values for cuboid volume bounds.

class GeometryContext : public ContextType

This is the central definition of the Acts payload object regarding detector geometry status (e.g.

alignment)

It is propagated through the code to allow for event/thread dependent geometry changes.

Public Functions

GeometryContext() = default

Default constructor.

Deprecated:

Use GeometryContext::dangerouslyDefaultConstruct() instead to make empty context construction explicit

template<typename T> inline  requires (!std::is_same_v< std::decay_t< T >, GeometryContext > &&!std::is_base_of_v< ContextType, std::decay_t< T > >) explicit GeometryContext(const T &value)

Copy construct from arbitrary type (inherited from ContextType)

Template Parameters:

T – The type of the value to construct from

Parameters:

value – The value to construct from

template<typename T> inline  requires (!std::is_same_v< std::decay_t< T >, GeometryContext > &&!std::is_base_of_v< ContextType, std::decay_t< T > >) explicit GeometryContext(T &&value)

Move construct from arbitrary type (inherited from ContextType)

Template Parameters:

T – The type of the value to construct from

Parameters:

value – The value to construct from

Public Static Functions

static inline GeometryContext dangerouslyDefaultConstruct()

Static factory method for default construction.

Note

Use this when you need a default context for testing or simple applications without alignment/conditions data

Returns:

A default-constructed GeometryContext

template<typename value_t>
class GeometryHierarchyMap

Store values mapped into the geometry hierarchy.

The core functionality is to find an equivalent element, i.e. an identifier-value pair, for a given geometry identifier via

auto it = container.find(GeometryIdentifier(...));
if (it != container.end()) {
    ...
}

Trailing zero levels of stored geometry identifiers are used as broadcast values to refer to higher-level objects within the geometry, e.g. a geometry identifier with vanishing approach and sensitive index identifies a layer. An entry will all geometry identifier levels set to zero acts as the global default value.

The container also supports range-based iteration over all stored elements

for (const auto& element : container) {
    ...
}

and index-based access to stored elements and associated geometry identifiers

GeometryIdentifier id3 = container.idAt(3);
const auto& element4 = container.valueAt(4);

Adding elements is potentially expensive as the internal lookup structure must be updated. In addition, modifying an element in-place could change its identifier which would also break the lookup. Thus, the container can not be modified after construction to prevent misuse.

Note

No guarantees are given for the element order when using range-based or index-based access. Any apparent ordering must be considered an implementation detail and might change.

Template Parameters:

value_t – stored value type

Public Types

using InputElement = typename std::pair<GeometryIdentifier, value_t>

Combined geometry identifier and value element. Only used for input.

using Iterator = typename std::vector<value_t>::const_iterator

Type alias for const iterator over stored values.

using Value = value_t

Type alias for stored value type.

Public Functions

GeometryHierarchyMap() = default

GeometryHierarchyMap(const GeometryHierarchyMap&) = default

Copy constructor.

GeometryHierarchyMap(GeometryHierarchyMap&&) noexcept = default

Move constructor.

inline GeometryHierarchyMap(std::initializer_list<InputElement> elements)

Construct the container from an initializer list.

Parameters:

elements – input initializer list

inline explicit GeometryHierarchyMap(std::vector<InputElement> elements)

Construct the container from the given elements.

Parameters:

elements – input elements (must be unique with respect to identifier)

~GeometryHierarchyMap() = default

inline Iterator begin() const

Return an iterator pointing to the beginning of the stored values.

Returns:

Iterator to the first element

inline bool contains(const GeometryIdentifier &id) const

Check if the most specific value exists for a given geometry identifier.

This function checks if there is an element matching exactly the given geometry id, or from the element for the next available higher level within the geometry hierarchy.

Parameters:

id – geometry identifier for which existence is being checked

Return values:

• <tt>true</tt> – if a matching element exists

• <tt>false</tt> – if no matching element exists

inline bool empty() const

Check if any elements are stored.

Returns:

True if the container is empty, false otherwise

inline Iterator end() const

Return an iterator pointing to the end of the stored values.

Returns:

Iterator past the last element

inline Iterator find(const GeometryIdentifier &id) const

Find the most specific value for a given geometry identifier.

This can be either from the element matching exactly to the given geometry id, if it exists, or from the element for the next available higher level within the geometry hierarchy.

Parameters:

id – geometry identifier for which information is requested

Return values:

• iterator – to an existing value

• <tt>.end()</tt> – iterator if no matching element exists

inline GeometryIdentifier idAt(std::size_t index) const

Access the geometry identifier for the i-th element with bounds check.

Parameters:

index – The index of the element to access

Throws:

std::out_of_range – for invalid indices

Returns:

The geometry identifier at the specified index

GeometryHierarchyMap &operator=(const GeometryHierarchyMap&) = default

Copy assignment operator.

Returns:

Reference to this object for chaining

GeometryHierarchyMap &operator=(GeometryHierarchyMap&&) noexcept = default

Move assignment operator.

Returns:

Reference to this object for chaining

inline std::size_t size() const

Return the number of stored elements.

Returns:

Number of elements in the container

inline const Value &valueAt(std::size_t index) const

Access the value of the i-th element in the container with bounds check.

Parameters:

index – The index of the element to access

Throws:

std::out_of_range – for invalid indices

Returns:

Reference to the value at the specified index

class GeometryIdentifier

Identifier for geometry nodes within the geometry hierarchy.

An identifier can be split into the following components. They define a hierarchy of objects starting from the high-level volumes:

• Volume

• Boundary surfaces (for a volume)

• Layers (confined within a volume)

• Approach surfaces (for a layer)

• Sensitive surfaces (confined to a layer, also called modules)

Public Types

using Value = std::uint64_t

Type alias for underlying value type (64-bit unsigned integer)

Public Functions

GeometryIdentifier() = default

Construct default GeometryIdentifier with all values set to zero.

GeometryIdentifier(const GeometryIdentifier&) = default

Copy constructor.

GeometryIdentifier(GeometryIdentifier&&) = default

Move constructor.

inline explicit constexpr GeometryIdentifier(Value encoded)

Construct from an already encoded value.

Parameters:

encoded – The encoded geometry identifier value

~GeometryIdentifier() = default

inline constexpr Value approach() const

Return the approach identifier.

Returns:

The approach identifier component

inline constexpr Value boundary() const

Return the boundary identifier.

Returns:

The boundary identifier component

inline constexpr Value extra() const

Return the extra identifier Usage can be experiment-specific, like tagging which kind of detector a surface object corresponds to, or which subsystem it belongs to.

Returns:

The extra identifier component for experiment-specific use

inline constexpr Value layer() const

Return the layer identifier.

Returns:

The layer identifier component

GeometryIdentifier &operator=(const GeometryIdentifier&) = default

Copy assignment operator.

Returns:

Reference to this GeometryIdentifier after copying

GeometryIdentifier &operator=(GeometryIdentifier&&) = default

Move assignment operator.

Returns:

Reference to this GeometryIdentifier after moving

inline constexpr Value passive() const

Return the passive identifier.

Returns:

The passive identifier component (shares bit field with approach)

inline constexpr Value sensitive() const

Return the sensitive identifier.

Returns:

The sensitive identifier component

inline constexpr Value value() const

Return the encoded value.

Returns:

The full encoded 64-bit geometry identifier value

inline constexpr Value volume() const

Return the volume identifier.

Returns:

The volume identifier component

inline constexpr GeometryIdentifier withApproach(Value approach) const

Return a new identifier with the approach set to approach.

Parameters:

approach – the new approach identifier

Returns:

a new identifier with the approach set to approach

inline constexpr GeometryIdentifier withBoundary(Value boundary) const

Return a new identifier with the boundary set to boundary.

Parameters:

boundary – the new boundary identifier

Returns:

a new identifier with the boundary set to boundary

inline constexpr GeometryIdentifier withExtra(Value extra) const

Return a new identifier with the extra set to extra.

Parameters:

extra – the new extra identifier

Returns:

a new identifier with the extra set to extra

inline constexpr GeometryIdentifier withLayer(Value layer) const

Return a new identifier with the layer set to layer.

Parameters:

layer – the new layer identifier

Returns:

a new identifier with the layer set to layer

inline constexpr GeometryIdentifier withPassive(Value passive) const

Return a new identifier with the passive set to passive.

Parameters:

passive – the new passive identifier

Returns:

a new identifier with the passive set to passive

inline constexpr GeometryIdentifier withSensitive(Value sensitive) const

Return a new identifier with the sensitive set to sensitive.

Parameters:

sensitive – the new sensitive identifier

Returns:

a new identifier with the sensitive set to sensitive

inline constexpr GeometryIdentifier withVolume(Value volume) const

Return a new identifier with the volume set to volume.

Parameters:

volume – the new volume identifier

Returns:

a new identifier with the volume set to volume

Public Static Functions

static inline constexpr Value getMaxApproach()

Get the maximum value for the approach identifier.

Returns:

the maximum value for the approach identifier

static inline constexpr Value getMaxBoundary()

Get the maximum value for the boundary identifier.

Returns:

the maximum value for the boundary identifier

static inline constexpr Value getMaxExtra()

Get the maximum value for the extra identifier.

Returns:

the maximum value for the extra identifier

static inline constexpr Value getMaxLayer()

Get the maximum value for the layer identifier.

Returns:

the maximum value for the layer identifier

static inline constexpr Value getMaxSensitive()

Get the maximum value for the sensitive identifier.

Returns:

the maximum value for the sensitive identifier

static inline constexpr Value getMaxVolume()

Get the maximum value for the volume identifier.

Returns:

the maximum value for the volume identifier

class GeometryObject

Base class to provide GeometryIdentifier interface:

• simple set and get

It also provides the referencePosition method for Geometry geometrical object to be binned in BinnedArrays

Subclassed by Acts::Layer, Acts::Surface, Acts::Volume

Public Functions

GeometryObject() = default

Defaulted constructor.

inline explicit GeometryObject(const GeometryIdentifier &geometryId)

Constructor from a value.

Parameters:

geometryId – the geometry identifier of the object

GeometryObject(const GeometryObject&) = default

Defaulted copy constructor.

virtual ~GeometryObject() noexcept = default

inline void assignGeometryId(const GeometryIdentifier &geometryId)

Set the value.

Parameters:

geometryId – the geometry identifier to be assigned

inline GeometryIdentifier geometryId() const

Returns:

the geometry id by reference

virtual Vector3 referencePosition(const GeometryContext &gctx, AxisDirection aDir) const = 0

Force a binning position method.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• aDir – is the value for which the reference position is requested

Returns:

vector 3D used for the binning schema

inline virtual double referencePositionValue(const GeometryContext &gctx, AxisDirection aDir) const

Implement the binningValue.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• aDir – is the dobule in which you want to bin

Returns:

float to be used for the binning schema

Warning

doxygenclass: Cannot find class “Acts::Grid” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

class HomogeneousSurfaceMaterial : public Acts::ISurfaceMaterial

It extends the ISurfaceMaterial virtual base class to describe a simple homogeneous material on a surface.

Public Functions

HomogeneousSurfaceMaterial() = default

Default Constructor - defaulted.

HomogeneousSurfaceMaterial(const HomogeneousSurfaceMaterial &hsm) = default

Copy Constructor.

Parameters:

hsm – is the source material

explicit HomogeneousSurfaceMaterial(const MaterialSlab &full, double splitFactor = 1., MappingType mappingType = MappingType::Default)

Explicit constructor.

Parameters:

• full – are the full material properties

• splitFactor – is the split for pre/post update

• mappingType – is the type of surface mapping associated to the surface

HomogeneousSurfaceMaterial(HomogeneousSurfaceMaterial &&hsm) = default

Copy Move Constructor.

Parameters:

hsm – is the source material

~HomogeneousSurfaceMaterial() override = default

Destructor.

double factor(Direction pDir, MaterialUpdateMode mode) const

The inherited methods - for scale access.

Parameters:

• pDir – Direction through the surface

• mode – Material update directive

Returns:

The scaling factor for the material

virtual const MaterialSlab &materialSlab(const Vector2 &lp) const final

Return method for full material description of the Surface.

• from local coordinate on the surface

Note

the input parameter is ignored

Parameters:

lp – is the local position used for the (eventual) lookup

Returns:

const MaterialSlab

const MaterialSlab &materialSlab(const Vector2 &lp) const = 0

Return method for full material description of the Surface.

• from local coordinate on the surface

Parameters:

lp – is the local position used for the (eventual) lookup

Returns:

const MaterialSlab

MaterialSlab materialSlab(const Vector2 &lp, Direction pDir, MaterialUpdateMode mode) const

Return method for fully scaled material description of the Surface.

• from local coordinate on the surface

Parameters:

• lp – is the local position used for the (eventual) lookup

• pDir – is the positive direction through the surface

• mode – is the material update directive

Returns:

MaterialSlab

const MaterialSlab &materialSlab(const Vector3 &gp) const = 0

Return method for full material description of the Surface.

• from the global coordinates

Parameters:

gp – is the global position used for the (eventual) lookup

Returns:

const MaterialSlab

MaterialSlab materialSlab(const Vector3 &gp, Direction pDir, MaterialUpdateMode mode) const

Return method for full material description of the Surface.

• from the global coordinates

Parameters:

• gp – is the global position used for the (eventual) lookup

• pDir – is the positive direction through the surface

• mode – is the material update directive

Returns:

MaterialSlab

virtual const MaterialSlab &materialSlab(const Vector3 &gp = Vector3{0., 0., 0.}) const final

Return method for full material description of the Surface.

• from the global coordinates

Note

the input parameter is ignored

Parameters:

gp – is the global position used for the (eventual) lookup

Returns:

const MaterialSlab

HomogeneousSurfaceMaterial &operator=(const HomogeneousSurfaceMaterial &hsm) = default

Assignment operator.

Parameters:

hsm – is the source material

Returns:

Reference to this material after assignment

HomogeneousSurfaceMaterial &operator=(HomogeneousSurfaceMaterial &&hsm) = default

Assignment Move operator.

Parameters:

hsm – is the source material

Returns:

Reference to this material after move assignment

virtual HomogeneousSurfaceMaterial &scale(double factor) final

Scale operator.

• it is effectively a thickness scaling

Parameters:

factor – is the scale factor

Returns:

Reference to this scaled material

virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream.

Parameters:

sl – The outoput stream

Returns:

Reference to the output stream for chaining

class IAxis

Common base class for all Axis instance.

This allows generice handling such as for inspection.

Subclassed by Acts::Axis< AxisType::Equidistant, bdt >, Acts::Axis< AxisType::Variable, bdt >

Public Functions

virtual ~IAxis() = default

Virtual destructor.

virtual std::size_t getBin(double x) const = 0

get corresponding bin index for given coordinate

Note

Bin indices start at 1. The underflow bin has the index 0 while the index nBins + 1 indicates the overflow bin .

Parameters:

x – [in] input coordinate

Returns:

index of bin containing the given value

virtual std::vector<double> getBinEdges() const = 0

Return a vector of bin edges.

Returns:

Vector which contains the bin edges

virtual AxisBoundaryType getBoundaryType() const = 0

returns the boundary type set in the template param

Returns:

AxisBoundaryType of this axis

virtual double getMax() const = 0

get maximum of binning range

Returns:

maximum of binning range

virtual double getMin() const = 0

get minimum of binning range

Returns:

minimum of binning range

virtual std::size_t getNBins() const = 0

get total number of bins

Returns:

total number of bins (excluding under-/overflow bins)

virtual AxisType getType() const = 0

returns the type of the axis

Returns:

AxisType of this axis

virtual bool isEquidistant() const = 0

returns whether the axis is equidistant

Returns:

bool is equidistant

virtual bool isVariable() const = 0

returns whether the axis is variable

Returns:

bool is variable

template<typename callable_t>
inline decltype(auto) visit(const callable_t &callable) const

Helper function that dispatches from the IAxis base class to a concrete axis type.

It will call the provided callable with a const reference to the concrete axis type.

Template Parameters:

callable_t – the callable type

Parameters:

callable – the callable object

Returns:

the value returned by the callable

Public Static Functions

static std::unique_ptr<IAxis> createEquidistant(AxisBoundaryType aBoundaryType, double min, double max, std::size_t nbins)

Centralized axis factory for equidistant binning.

Parameters:

• aBoundaryType – the axis boundary type

• min – the minimum edge of the axis

• max – the maximum edge of the axis

• nbins – the number of bins

Throws:

std::invalid_argument – if min >= max or nbins == 0

Returns:

a unique pointer to the axis

static std::unique_ptr<IAxis> createVariable(AxisBoundaryType aBoundaryType, const std::vector<double> &edges)

Centralized axis factory for variable binning.

Parameters:

• aBoundaryType – the axis boundary type

• edges – are the bin edges

Throws:

std::invalid_argument – if edges is empty or not strictly increasing

Returns:

a unique pointer to the axis

Friends

inline friend std::ostream &operator<<(std::ostream &os, const IAxis &axis)

Output stream operator.

Parameters:

• os – output stream

• axis – the axis to be printed

Returns:

the output stream

inline friend bool operator==(const IAxis &lhs, const IAxis &rhs)

Check if two axes are equal.

Parameters:

• lhs – first axis

• rhs – second axis

Returns:

true if the axes are equal

class ISurfaceMaterial

Base class of all surface-based material description.

The class supplies references to MaterialSlab that are associated to a surface, extended by certain special representations (binned, homogeneous). The concrete MaterialSlab can depend on the local position on the surface.

Subclassed by Acts::BinnedSurfaceMaterial, Acts::HomogeneousSurfaceMaterial, Acts::IGridSurfaceMaterialBase, Acts::ProtoSurfaceMaterialT< BinningType >

Public Functions

ISurfaceMaterial() = default

Constructor.

inline explicit ISurfaceMaterial(double splitFactor)

Constructor.

Parameters:

splitFactor – is the splitting ratio between pre/post update

inline explicit ISurfaceMaterial(double splitFactor, MappingType mappingType)

Constructor.

Parameters:

• splitFactor – is the splitting ratio between pre/post update

• mappingType – is the type of surface mapping associated to the surface

virtual ~ISurfaceMaterial() = default

Destructor.

double factor(Direction pDir, MaterialUpdateMode mode) const

Update pre factor.

Parameters:

• pDir – is the positive direction through the surface

• mode – is the material update directive

Returns:

Factor for material scaling based on direction and update mode

inline MappingType mappingType() const

Return the type of surface material mapping.

Returns:

The mapping type indicating how material is associated with the surface

virtual const MaterialSlab &materialSlab(const Vector2 &lp) const = 0

Return method for full material description of the Surface.

• from local coordinate on the surface

Parameters:

lp – is the local position used for the (eventual) lookup

Returns:

const MaterialSlab

virtual MaterialSlab materialSlab(const Vector2 &lp, Direction pDir, MaterialUpdateMode mode) const

Return method for fully scaled material description of the Surface.

• from local coordinate on the surface

Parameters:

• lp – is the local position used for the (eventual) lookup

• pDir – is the positive direction through the surface

• mode – is the material update directive

Returns:

MaterialSlab

virtual const MaterialSlab &materialSlab(const Vector3 &gp) const = 0

Return method for full material description of the Surface.

• from the global coordinates

Parameters:

gp – is the global position used for the (eventual) lookup

Returns:

const MaterialSlab

virtual MaterialSlab materialSlab(const Vector3 &gp, Direction pDir, MaterialUpdateMode mode) const

Return method for full material description of the Surface.

• from the global coordinates

Parameters:

• gp – is the global position used for the (eventual) lookup

• pDir – is the positive direction through the surface

• mode – is the material update directive

Returns:

MaterialSlab

virtual ISurfaceMaterial &scale(double factor) = 0

Scale material.

Parameters:

factor – is the scale factor applied

Returns:

Reference to this material object for chaining

virtual std::ostream &toStream(std::ostream &sl) const = 0

Output Method for std::ostream, to be overloaded by child classes.

Parameters:

sl – Output stream to write to

Returns:

Reference to the output stream for chaining

inline std::string toString() const

output into a string

Returns:

the string representation

Friends

inline friend std::ostream &operator<<(std::ostream &out, const ISurfaceMaterial &sm)

output stream operator

Prints information about this object to the output stream using the virtual ISurfaceMaterial::toStream method

Returns:

modified output stream object

class InfiniteBounds : public Acts::SurfaceBounds

templated boundless extension to forward the interface Returns all inside checks to true and can templated for all bounds

Public Functions

inline virtual SquareMatrix2 boundToCartesianJacobian(const Vector2 &lposition) const final

Computes the bound to cartesian jacobian at a given local position.

Parameters:

lposition – is the local position at which the jacobian is computed

Returns:

the bound to cartesian jacobian

inline virtual SquareMatrix2 boundToCartesianMetric(const Vector2 &lposition) const final

Computes the bound to cartesian metric at a given local position.

Parameters:

lposition – is the local position at which the metric is computed

Returns:

the bound to cartesian metric

inline virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Returns:

Vector2 representing the center position in local coordinates

inline virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

inline virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

inline virtual bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const final

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

inline virtual bool isCartesian() const final

Check if the bound coordinates are cartesian.

Returns:

true if the bound coordinates are cartesian

inline virtual std::ostream &toStream(std::ostream &os) const final

Output Method for std::ostream.

Parameters:

os – Output stream to write to

Returns:

Reference to the output stream for method chaining

inline virtual SurfaceBounds::BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

the bounds type

inline virtual std::vector<double> values() const final

Access method for bound values, this is a dynamically sized vector containing the parameters needed to describe these bounds.

Returns:

of the stored values for this SurfaceBounds object

template<typename grid_t>
class InterpolatedBFieldMap : public Acts::InterpolatedMagneticField

Interpolates magnetic field value from field values on a given grid.

This class implements a magnetic field service which is initialized by a field map defined by:

• a list of field values on a regular grid in some n-dimensional space,

• a transformation of global 3D coordinates onto this n-dimensional space.

• a transformation of local n-Dimensional magnetic field coordinates into global (cartesian) 3D coordinates

The magnetic field value for a given global position is then determined by:

• mapping the position onto the grid,

• looking up the magnetic field values on the closest grid points,

• doing a linear interpolation of these magnetic field values.

Internally, this class uses a field interpolation cell to speed up lookups. This cell contains the interpolation points so the grid does not have to be consulted for each lookup. Explicit methods to create such a field cell are provided, but field cell creation is automatically handled by Acts::InterpolatedBFieldMap::makeCache, opaque to the client.

This class can leverage spatial symmetries in the magnetic field distribution. For cylindrically symmetric fields (e.g., solenoids, toroids), a 2D rz map can be used instead of a full 3D xyz map, significantly reducing memory requirements and improving performance. Helper functions Acts::fieldMapRZ and Acts::fieldMapXYZ are provided to construct field maps with the appropriate symmetries.

Template Parameters:

grid_t – The Grid type which provides the field storage and interpolation

Public Types

using FieldType = typename Grid::value_type

Type alias for magnetic field vector type.

using Grid = grid_t

Type alias for magnetic field grid.

Public Functions

inline explicit InterpolatedBFieldMap(Config cfg)

default constructor

Parameters:

cfg – Configuration containing grid and scaling factor

inline Result<Vector3> getField(const Vector3 &position) const

retrieve field at given position

Parameters:

position – [in] global 3D position

Returns:

magnetic field value at the given position

Pre:

The given position must lie within the range of the underlying magnetic field map.

inline virtual Result<Vector3> getField(const Vector3 &position, MagneticFieldProvider::Cache &cache) const final

Retrieve magnetic field value at a given location.

Requires an instance of Acts::MagneticFieldProvider::Cache created through makeCache.

Parameters:

• position – [in] global 3D position for the lookup

• cache – [inout] Field provider specific cache object

Returns:

magnetic field vector at given position

inline Result<FieldCell> getFieldCell(const Vector3 &position) const

retrieve field cell for given position

Parameters:

position – [in] global 3D position

Returns:

field cell containing the given global position

Pre:

The given position must lie within the range of the underlying magnetic field map.

inline virtual Vector3 getFieldUnchecked(const Vector3 &position) const final

Get magnetic field value without bounds checking (faster).

Warning

No bounds checking is performed. The caller must ensure the position is within the valid range of the field map.

Parameters:

position – Global 3D position for the lookup

Returns:

Magnetic field value at the given position

inline const Grid &getGrid() const

Get a const reference on the underlying grid structure.

Returns:

grid reference

inline virtual std::vector<double> getMax() const final

get the maximum value of all axes of the field map

Returns:

vector returning the maxima of all field map axes

inline virtual std::vector<double> getMin() const final

get the minimum value of all axes of the field map

Returns:

vector returning the minima of all field map axes

inline virtual std::vector<std::size_t> getNBins() const final

get the number of bins for all axes of the field map

Returns:

vector returning number of bins for all field map axes

inline virtual bool isInside(const Vector3 &position) const final

check whether given 3D position is inside look-up domain

Parameters:

position – [in] global 3D position

Returns:

true if position is inside the defined look-up grid, otherwise false

inline bool isInsideLocal(const Vector<DIM_POS> &gridPosition) const

check whether given 3D position is inside look-up domain

Parameters:

gridPosition – [in] local N-D position

Returns:

true if position is inside the defined look-up grid, otherwise false

inline virtual MagneticFieldProvider::Cache makeCache(const MagneticFieldContext &mctx) const final

Make an opaque cache for the magnetic field.

Instructs the specific implementation to generate a Acts::MagneticFieldProvider::Cache instance for magnetic field lookup.

Parameters:

mctx – The magnetic field context to generate cache for

Returns:

Cache The opaque cache object

Public Static Attributes

static constexpr std::size_t DIM_POS = Grid::DIM

Dimensionality of the position space for field interpolation.

struct Cache

Cache for field cell to improve performance of field lookups.

This cache stores the current field cell which contains the interpolation data for a confined region of space. By caching the cell, subsequent lookups at nearby positions (e.g., during track propagation) can avoid expensive grid queries. The cache automatically updates when a position outside the current cell is queried.

Public Functions

inline explicit Cache(const MagneticFieldContext&)

Constructor with magnetic field context.

Public Members

std::optional<FieldCell> fieldCell

Stored field cell containing interpolation data.

bool initialized = false

Flag indicating if the cache has been initialized.

struct Config

Config structure for the interpolated B field map.

Public Members

Grid grid

grid storing magnetic field values

double scale = 1.

global B-field scaling factor

Note

Negative values for scale are accepted and will invert the direction of the magnetic field.

std::function<Vector3(const FieldType&, const Vector3&)> transformBField

calculating the global 3D coordinates (cartesian) of the magnetic field with the local n dimensional field and the global 3D position as input

std::function< Vector< DIM_POS >const Vector3 &)> transformPos

mapping of global 3D coordinates (cartesian) onto grid space

struct FieldCell

struct representing smallest grid unit in magnetic field grid

This type encapsulates all required information to perform linear interpolation of magnetic field values within a confined spatial region (hyper-box). The cell stores field values at all corner points and performs interpolation for any position within the cell boundaries. This allows for efficient repeated lookups within the same grid cell without consulting the full grid structure.

Public Functions

inline FieldCell(std::array<double, DIM_POS> lowerLeft, std::array<double, DIM_POS> upperRight, std::array<Vector3, N> fieldValues)

default constructor

Parameters:

• lowerLeft – [in] generalized lower-left corner of hyper box (containing the minima of the hyper box along each Dimension)

• upperRight – [in] generalized upper-right corner of hyper box (containing the maxima of the hyper box along each Dimension)

• fieldValues – [in] field values at the hyper box corners sorted in the canonical order defined in Acts::interpolate

inline Vector3 getField(const Vector<DIM_POS> &position) const

retrieve field at given position

Parameters:

position – [in] global 3D position

Returns:

magnetic field value at the given position

Pre:

The given position must lie within the current field cell.

inline bool isInside(const Vector<DIM_POS> &position) const

check whether given 3D position is inside this field cell

Parameters:

position – [in] global 3D position

Returns:

true if position is inside the current field cell, otherwise false

Public Static Attributes

static constexpr unsigned int N = 1 << DIM_POS

number of corner points defining the confining hyper-box

class InterpolatedMagneticField : public Acts::MagneticFieldProvider

Base class for interpolated magnetic field providers.

This class can be used for non-trivial magnetic field implementations.

The key idea here is to calculate an interpolated value of the magnetic field from a grid of known field values. In 3D, this means the interpolation is done from the 8 corner points of a field cell. The field cell can be retrieved for any given position. Since during typical access patterns, e.g. the propagation, subsequent steps are relatively likely to not cross the field cell boundary, the field cell can be cached.

Subclassed by Acts::InterpolatedBFieldMap< grid_t >

Public Functions

virtual Vector3 getFieldUnchecked(const Vector3 &position) const = 0

Get a field value without checking if the lookup position is within the interpolation domain.

Parameters:

position – The lookup position in 3D

Returns:

The field value at position

virtual std::vector<double> getMax() const = 0

get the maximum value of all axes of the field map

Returns:

vector returning the maxima of all field map axes

virtual std::vector<double> getMin() const = 0

get the minimum value of all axes of the field map

Returns:

vector returning the minima of all field map axes

virtual std::vector<std::size_t> getNBins() const = 0

get the number of bins for all axes of the field map

Returns:

vector returning number of bins for all field map axes

virtual bool isInside(const Vector3 &position) const = 0

check whether given 3D position is inside look-up domain

Parameters:

position – [in] global 3D position

Returns:

true if position is inside the defined look-up grid, otherwise false

class JsonDetectorElement : public Acts::SurfacePlacementBase

A implementation of a detector element, that is constructed from a JSON description of a surface.

The idea behind this is that it helps importing whole tracking geometries from JSON files. In some parts of the codebase, the existence of a detector element associated to a surface has a specific meaning (e.g., flags surfaces as sensitive).

Public Functions

JsonDetectorElement(const nlohmann::json &jSurface, double thickness)

Constructor from JSON surface description.

Parameters:

• jSurface – JSON object describing the surface

• thickness – Thickness of the detector element

inline virtual bool isSensitive() const override

Returns whether the placement corresponds to a surface on which the measurements from the experiment are represented, i.e.

it is

Returns:

True if this is a sensitive surface

virtual const Transform3 &localToGlobalTransform(const GeometryContext &gctx) const override

Return the transform for this detector element.

Parameters:

gctx – Geometry context (unused for this implementation)

Returns:

Transform matrix for this detector element

virtual const Surface &surface() const override

Return const reference to the surface.

Returns:

Const reference to the associated surface

virtual Surface &surface() override

Return mutable reference to the surface.

Returns:

Mutable reference to the associated surface

double thickness() const

Return the thickness of the detector element.

Returns:

Thickness value

template<typename propagator_t, typename traj_t>
class KalmanFitter

Kalman fitter implementation.

The Kalman filter contains an Actor and a Sequencer sub-class. The Sequencer has to be part of the Navigator of the Propagator in order to initialize and provide the measurement surfaces.

The Actor is part of the Propagation call and does the Kalman update and eventually the smoothing. Updater, Smoother and Calibrator are given to the Actor for further use:

• The Updater is the implemented kalman updater formalism, it runs via a visitor pattern through the measurements.

• The Smoother is called at the end of the filtering by the Actor.

Measurements are not required to be ordered for the KalmanFilter, measurement ordering needs to be figured out by the navigation of the propagator.

The void components are provided mainly for unit testing.

Template Parameters:

propagator_t – Type of the propagation class, usually an instance of Acts::Propagator

Public Functions

inline explicit KalmanFitter(propagator_t pPropagator, std::unique_ptr<const Logger> _logger = getDefaultLogger("KalmanFitter", Logging::INFO))

Constructor with propagator and logger.

Parameters:

• pPropagator – Propagator instance for track propagation

• _logger – Logger for diagnostic output

template<typename source_link_iterator_t, TrackContainerFrontend track_container_t>
inline Result<typename track_container_t::TrackProxy> fit(source_link_iterator_t it, source_link_iterator_t end, const BoundTrackParameters &sParameters, const KalmanFitterOptions<traj_t> &kfOptions, const std::vector<const Surface*> &sSequence, track_container_t &trackContainer) const
requires (isDirectNavigator)

Fit implementation of the forward filter, calls the the filter and smoother/reversed filter.

Note

The input measurements are given in the form of SourceLinks. It’s calibrator_t's job to turn them into calibrated measurements used in the fit.

Template Parameters:

• source_link_iterator_t – Iterator type used to pass source links

• track_container_t – Type of the track container

Parameters:

• it – Begin iterator for the fittable uncalibrated measurements

• end – End iterator for the fittable uncalibrated measurements

• sParameters – The initial track parameters

• kfOptions – KalmanOptions steering the fit

• sSequence – surface sequence used to initialize a DirectNavigator

• trackContainer – Input track container storage to append into

Returns:

the output as an output track

template<typename source_link_iterator_t, TrackContainerFrontend track_container_t>
inline Result<typename track_container_t::TrackProxy> fit(source_link_iterator_t it, source_link_iterator_t end, const BoundTrackParameters &sParameters, const KalmanFitterOptions<traj_t> &kfOptions, track_container_t &trackContainer) const

Fit implementation of the forward filter, calls the the filter and smoother/reversed filter.

Note

The input measurements are given in the form of SourceLink s. It’s the calibrators job to turn them into calibrated measurements used in the fit.

Template Parameters:

• source_link_iterator_t – Iterator type used to pass source links

• track_container_t – Type of the track container

Parameters:

• it – Begin iterator for the fittable uncalibrated measurements

• end – End iterator for the fittable uncalibrated measurements

• sParameters – The initial track parameters

• kfOptions – KalmanOptions steering the fit

• trackContainer – Input track container storage to append into

Returns:

the output as an output track

class Layer : public virtual Acts::GeometryObject

Base Class for a Detector Layer in the Tracking Geometry.

An actual implemented Detector Layer inheriting from this base class has to inherit from a specific type of Surface as well. In addition, a Layer can carry:

A SurfaceArray of Surfaces holding the actual detector elements or subSurfaces. A pointer to the TrackingVolume (can only be set by such) An active/passive code : 0 - active 1 - passive [….] - other

The search type for compatible surfaces on a layer is [ the higher the number, the faster ]: ——&#8212; Layer internal ———————————————&#8212; -1 - provide all intersection tested without boundary check 0 - provide all intersection tested with boundary check 1 - provide overlap descriptor based without boundary check 2 - provide overlap descriptor based with boundary check

A layer can have substructure regarding:

• m_ssRepresentingSurface -> always exists (1), can have material (2)

• m_ssSensitiveSurfaces -> can or not exist (0,1), can have material (2)

• m_ssApproachSurfaces -> can or not exist (0,1) cam have material (2)

Subclassed by Acts::ConeLayer, Acts::CylinderLayer, Acts::DiscLayer, Acts::NavigationLayer, Acts::PlaneLayer

Public Functions

~Layer() noexcept override

Destructor.

ApproachDescriptor *approachDescriptor()

Non-const version of the approach descriptor.

Returns:

Mutable pointer to the approach descriptor

const ApproachDescriptor *approachDescriptor() const

Return method for the approach descriptor, can be nullptr.

Returns:

Pointer to the approach descriptor, or nullptr if not set

boost::container::small_vector<NavigationTarget, 10> compatibleSurfaces(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const NavigationOptions<Surface> &options) const

Decompose Layer into (compatible) surfaces.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – Position parameter for searching

• direction – Direction of the parameters for searching

• options – The navigation options

Returns:

list of intersection of surfaces on the layer

virtual bool isOnLayer(const GeometryContext &gctx, const Vector3 &position, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::None()) const

geometrical isOnLayer() method

Note

using isOnSurface() with Layer specific tolerance

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be checked

• boundaryTolerance – is the boundary check directive

Returns:

boolean that indicates success of the operation

double layerThickness() const

Return the Thickness of the Layer this is by definition along the normal vector of the surfaceRepresentation.

Returns:

The layer thickness value

LayerType layerType() const

return the LayerType

Returns:

The layer type (active, passive, or navigation)

const Layer *nextLayer(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Fast navigation to next layer.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the start position for the search

• direction – is the direction for the search

Returns:

the pointer to the next layer

const Volume *representingVolume() const

Return the abstract volume that represents the layer.

Returns:

the representing volume of the layer

virtual bool resolve(bool resolveSensitive, bool resolveMaterial, bool resolvePassive) const

Accept layer according to the following collection directives.

Parameters:

• resolveSensitive – is the prescription to find the sensitive surfaces

• resolveMaterial – is the precription to find material surfaces

• resolvePassive – is the prescription to find all passive surfaces

Returns:

a boolean whether the layer is accepted for processing

template<typename options_t>
inline bool resolve(const options_t &options) const

Accept layer according to the following collection directives.

Template Parameters:

options_t – Type of the options for navigation

Parameters:

options – Navigation options containing resolution settings

Returns:

a boolean whether the layer is accepted for processing

SurfaceArray *surfaceArray()

Non-const version.

Returns:

Mutable pointer to the surface array

const SurfaceArray *surfaceArray() const

Return the entire SurfaceArray, returns a nullptr if no SurfaceArray.

Returns:

Pointer to the surface array, or nullptr if not set

NavigationTarget surfaceOnApproach(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const NavigationOptions<Layer> &options) const

Surface seen on approach for layers without sub structure, this is the surfaceRepresentation for layers with sub structure, this is the approachSurface.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – Position for searching

• direction – Direction for searching

• options – The navigation options

Returns:

the Surface intersection of the approach surface

virtual const Surface &surfaceRepresentation() const = 0

Transforms the layer into a Surface representation for extrapolation.

Note

the layer can be hosting many surfaces, but this is the global one to which one can extrapolate

Returns:

Reference to the layer’s surface representation

virtual Surface &surfaceRepresentation() = 0

Non-const version of surface representation access.

Returns:

Mutable reference to the layer surface

const TrackingVolume *trackingVolume() const

Get the confining TrackingVolume.

Returns:

the pointer to the enclosing volume

class LineBounds : public Acts::SurfaceBounds

Bounds for a LineSurface.

Public Types

enum BoundValues

Enumeration for the bound values.

Values:

enumerator eR

enumerator eHalfLengthZ

enumerator eSize

Public Functions

inline explicit LineBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor - from fixed size array.

Parameters:

values – The bound values stored in a fixed size array

inline explicit LineBounds(double r, double halfZ) noexcept(false)

Constructor.

Parameters:

• r – The radius of the line

• halfZ – The half length in z

inline virtual SquareMatrix2 boundToCartesianJacobian(const Vector2 &lposition) const final

Computes the bound to cartesian jacobian at a given local position.

Parameters:

lposition – is the local position at which the jacobian is computed

Returns:

the bound to cartesian jacobian

inline virtual SquareMatrix2 boundToCartesianMetric(const Vector2 &lposition) const final

Computes the bound to cartesian metric at a given local position.

Parameters:

lposition – is the local position at which the metric is computed

Returns:

the bound to cartesian metric

virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Note

For LineBounds: returns (0,0) since bounds are symmetric around origin

Returns:

Vector2 representing the center position in local coordinates

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

The bound value for the specified parameter

virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

inline virtual bool isCartesian() const final

Check if the bound coordinates are cartesian.

Returns:

true if the bound coordinates are cartesian

virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream.

Parameters:

sl – is the ostream to be dumped into

Returns:

Reference to the output stream for method chaining

inline virtual BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

the bounds type

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

class LineSurface : public Acts::Surface

Base class for a linear surfaces in the TrackingGeometry to describe dirft tube, straw like detectors or the Perigee It inherits from Surface.

Note

It leaves the type() method virtual, so it can not be instantiated

Subclassed by Acts::PerigeeSurface, Acts::StrawSurface

Public Functions

virtual AlignmentToPathMatrix alignmentToPathDerivative(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Calculate the derivative of path length at the geometry constraint or point-of-closest-approach w.r.t.

alignment parameters of the surface (i.e. local frame origin in global 3D Cartesian coordinates and its rotation represented with extrinsic Euler angles)

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Derivative of path length w.r.t. the alignment parameters

void assignSurfaceBounds(std::shared_ptr<const LineBounds> newBounds)

Overwrite the existing surface bounds with new ones.

Parameters:

newBounds – Pointer to the new bounds

virtual const SurfaceBounds &bounds() const final

This method returns the bounds of the surface by reference.

Returns:

Reference to the surface bounds

const std::shared_ptr<const LineBounds> &boundsPtr() const

This method returns the shared_ptr to the LineBounds.

Returns:

Shared pointer to the line bounds

virtual BoundToFreeMatrix boundToFreeJacobian(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Calculate the jacobian from local to global which the surface knows best, hence the calculation is done here.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Jacobian from local to global

virtual FreeToPathMatrix freeToPathDerivative(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Calculate the derivative of path length at the geometry constraint or point-of-closest-approach w.r.t.

free parameters

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Derivative of path length w.r.t. free parameters

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final

Specified for LineSurface: global to local method without dynamic memory allocation.

This method is the true global -> local transformation. It makes use of globalToLocal and indicates the sign of the Acts::eBoundLoc0 by the given momentum direction.

The calculation of the sign of the radius (or \( d_0 \)) can be done as follows: May \( \vec d = \vec m - \vec c \) denote the difference between the center of the line and the global position of the measurement/predicted state. Then, \( \vec d \) lies in the so-called measurement plane. The latter is determined by the two orthogonal vectors \( \vec{\texttt{measY}} = \vec{e}_z \) and \( \vec{\texttt{measX}} = \vec{\texttt{measY}} \times \frac{\vec{p}}{|\vec{p}|} \).

The sign of the radius (or \( d_{0} \) ) is then defined by the projection of \( \vec{d} \) on \( \vec{measX} \):\( sign = -sign(\vec{d} \cdot \vec{measX}) \)

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position - considered to be on surface but not inside bounds (check is done)

• direction – global 3D momentum direction (optionally ignored)

• tolerance – (unused)

Returns:

A Result<Vector2>, which is set to !ok() if the position is not the point of closest approach to the line surface.

virtual MultiIntersection3D intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), double tolerance = s_onSurfaceTolerance) const final

Calculate the straight-line intersection with the line surface.

Mathematical motivation:

Given two lines in parametric form:

\( \vec l_{a}(u) = \vec m_a + u \cdot \vec e_{a} \)

\( \vec l_{b}(\mu) = \vec m_b + \mu \cdot \vec e_{b} \)

The vector between any two points on the two lines is given by:

\( \vec s(u, \mu) = \vec l_{b} - l_{a} = \vec m_{ab} + \mu \cdot \vec e_{b} - u \cdot \vec e_{a} \),

where \( \vec m_{ab} = \vec m_{b} - \vec m_{a} \).

\( \vec s(u_0, \mu_0) \) denotes the vector between the two closest points

\( \vec l_{a,0} = l_{a}(u_0) \) and \( \vec l_{b,0} = l_{b}(\mu_0) \)

and is perpendicular to both, \( \vec e_{a} \) and \( \vec e_{b} \).

This results in a system of two linear equations:

• (i) \( 0 = \vec s(u_0, \mu_0) \cdot \vec e_a = \vec m_{ab} \cdot \vec e_a + \mu_0 \vec e_a \cdot \vec e_b - u_0 \)

• (ii) \( 0 = \vec s(u_0, \mu_0) \cdot \vec e_b = \vec m_{ab} \cdot \vec e_b + \mu_0 - u_0 \vec e_b \cdot \vec e_a \)

Solving (i) and (ii) for \( u \) and \( \mu_0 \) yields:

• \( u_0 = \frac{(\vec m_{ab} \cdot \vec e_a)-(\vec m_{ab} \cdot \vec e_b)(\vec e_a \cdot \vec e_b)}{1-(\vec e_a \cdot \vec e_b)^2} \)

• \( \mu_0 = - \frac{(\vec m_{ab} \cdot \vec e_b)-(\vec m_{ab} \cdot \vec e_a)(\vec e_a \cdot \vec e_b)}{1-(\vec e_a \cdot \vec e_b)^2} \)

The function checks if \( u_0 \simeq 0\) to check if the current position is at the point of closest approach, i.e. the intersection point, in which case it will return an onSurace intersection result. Otherwise, the path length from position to the point of closest approach ( \( u_0 \)) is returned in a reachable intersection.

Note

expected to be normalized

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The global position as a starting point

• direction – The global direction at the starting point

• boundaryTolerance – The boundary check directive for the estimate

• tolerance – the tolerance used for the intersection

Returns:

is the intersection object

Vector3 lineDirection(const GeometryContext &gctx) const

Get the line direction in global coordinates.

Parameters:

gctx – The geometry context

Returns:

The direction vector of the line surface

virtual Matrix<2, 3> localCartesianToBoundLocalDerivative(const GeometryContext &gctx, const Vector3 &position) const final

Calculate the derivative of bound track parameters local position w.r.t.

position in local 3D Cartesian coordinates

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The position of the parameters in global

Returns:

Derivative of bound local position w.r.t. position in local 3D cartesian coordinates

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const final

Local to global transformation.

Note

for line surfaces the momentum direction is used in order to interpret the drift radius

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is the local position to be transformed

• direction – is the global momentum direction (used to sign the closest approach)

Returns:

global position by value

virtual std::string name() const override

Return properly formatted class name for screen output.

Returns:

String representation of the class name

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const override

Return the surface normal at a given position and direction.

This method is fully generic, and valid for all surface types.

Note

For some surface types, the direction is ignored, but it is not safe to pass in a zero vector!

Parameters:

• gctx – The current geometry context object, e.g. alignment

• pos – The position at which to calculate the normal

• direction – The direction at which to calculate the normal

Returns:

The normal vector at the given position and direction

LineSurface &operator=(const LineSurface &other)

Assignment operator.

Parameters:

other – is the source surface dor copying

Returns:

Reference to this LineSurface after assignment

virtual double pathCorrection(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const override

the pathCorrection for derived classes with thickness is by definition 1 for LineSurfaces

Note

input parameters are ignored

Note

there’s no material associated to the line surface

Parameters:

• gctx – Geometry context (ignored)

• position – Position parameter (ignored)

• direction – Direction parameter (ignored)

Returns:

Always returns 1.0 for line surfaces

virtual RotationMatrix3 referenceFrame(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Return the measurement frame - this is needed for alignment, in particular.

for StraightLine and Perigee Surface

• the default implementation is the RotationMatrix3 of the transform

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position where the measurement frame is constructed

• direction – is the momentum direction used for the measurement frame construction

Returns:

is a rotation matrix that indicates the measurement frame

virtual Vector3 referencePosition(const GeometryContext &gctx, AxisDirection aDir) const final

The binning position is the position calculated for a certain binning type.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• aDir – is the axis direction for the reference position request

Returns:

position that can beused for this binning

class Logger

class for printing debug output

This class provides the user interface for printing debug messages with different levels of severity.

Public Functions

inline Logger(std::unique_ptr<Logging::OutputPrintPolicy> pPrint, std::unique_ptr<Logging::OutputFilterPolicy> pFilter)

construct from output print and filter policy

Parameters:

• pPrint – [in] policy for printing debug messages

• pFilter – [in] policy for filtering debug messages

inline std::unique_ptr<Logger> clone(const std::optional<std::string> &_name = std::nullopt, const std::optional<Logging::Level> &_level = std::nullopt) const

Make a copy of this logger, optionally changing the name or the level.

Parameters:

• _name – the optional new name

• _level – the optional new level

Returns:

Unique pointer to a cloned logger

inline std::unique_ptr<Logger> clone(Logging::Level _level) const

Make a copy of the logger, with a new level.

Convenience function for if you only want to change the level but not the name.

Parameters:

_level – the new level

Returns:

the new logger

inline std::unique_ptr<Logger> cloneWithSuffix(const std::string &suffix, std::optional<Logging::Level> _level = std::nullopt) const

Make a copy of the logger, with a suffix added to the end of it’s name.

You can also optionally supply a new level

Parameters:

• suffix – the suffix to add to the end of the name

• _level – the optional new level

Returns:

Unique pointer to a cloned logger with modified name

inline bool doPrint(const Logging::Level &lvl) const

decide whether a message with a given debug level has to be printed

Parameters:

lvl – [in] debug level of debug message

Returns:

true if debug message should be printed, otherwise false

inline const Logging::OutputFilterPolicy &filterPolicy() const

Return the filter policy for this logger.

Returns:

the filter policy

inline Logging::Level level() const

Return the level of the filter policy of this logger.

Returns:

the level

inline void log(const Logging::Level &lvl, const std::string &input) const

log a debug message

Parameters:

• lvl – [in] debug level of debug message

• input – [in] text of debug message

inline const std::string &name() const

Return the name of the print policy of this logger.

Returns:

the name

inline const Logger &operator()() const

Helper function so a logger reference can be used as is with the logging macros.

Returns:

Reference to this logger

inline const Logging::OutputPrintPolicy &printPolicy() const

Return the print policy for this logger.

Returns:

the print policy

class DefaultFilterPolicy : public Acts::Logging::OutputFilterPolicy

default filter policy for debug messages

All debug messages with a debug level equal or larger to the specified threshold level are processed.

Public Functions

inline explicit DefaultFilterPolicy(Level lvl)

constructor

Parameters:

lvl – [in] threshold debug level

~DefaultFilterPolicy() override = default

virtual default destructor

inline virtual std::unique_ptr<OutputFilterPolicy> clone(Level level) const override

Make a copy of this filter policy with a new level.

Parameters:

level – the new level

Returns:

the new copy

inline virtual bool doPrint(const Level &lvl) const override

decide whether a debug message should be processed

Parameters:

lvl – [in] debug level of debug message

Returns:

true if lvl >= m_level, otherwise false

inline virtual Level level() const override

Get the level of this filter policy.

Returns:

the levele

class DefaultPrintPolicy : public Acts::Logging::OutputPrintPolicy

default print policy for debug messages

This class allows to print debug messages without further modifications to a specified output stream.

Public Functions

inline explicit DefaultPrintPolicy(std::ostream *out = &std::cout)

constructor

Parameters:

out – [in] pointer to output stream object

Pre:

out is non-zero

inline virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string&) const override

Make a copy of this print policy with a new name.

Returns:

the copy

inline virtual void flush(const Level &lvl, const std::string &input) final

flush the debug message to the destination stream

Parameters:

• lvl – [in] debug level of debug message

• input – [in] text of debug message

inline virtual const std::string &name() const override

Fulfill OutputPrintPolicy interface.

This policy doesn’t actually have a name, so the assumption is that somewhere in the decorator hierarchy, there is something that returns a name without delegating to a wrappee, before reaching this overload.

Note

This method will throw an exception

Returns:

the name, but it never returns

class LevelOutputDecorator : public Acts::Logging::OutputDecorator

decorate debug message with its debug level

The debug message is complemented with its debug level.

Public Functions

inline explicit LevelOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee)

constructor

Parameters:

wrappee – [in] output print policy object to be wrapped

inline virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string &name) const override

Make a copy of this print policy with a new name.

Parameters:

name – the new name

Returns:

the copy

inline virtual void flush(const Level &lvl, const std::string &input) override

flush the debug message to the destination stream

This function prepends the debug level to the debug message and then delegates the flushing of the whole message to its wrapped object.

Parameters:

• lvl – [in] debug level of debug message

• input – [in] text of debug message

class NamedOutputDecorator : public Acts::Logging::OutputDecorator

decorate debug message with a name

The debug message is complemented with a name.

Public Functions

inline NamedOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee, const std::string &name, unsigned int maxWidth = 15)

constructor

Parameters:

• wrappee – [in] output print policy object to be wrapped

• name – [in] name to be added to debug message

• maxWidth – [in] maximum width of field used for name

inline virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string &name) const override

Make a copy of this print policy with a new name.

Parameters:

name – the new name

Returns:

the copy

inline virtual void flush(const Level &lvl, const std::string &input) override

flush the debug message to the destination stream

This function prepends the given name to the debug message and then delegates the flushing of the whole message to its wrapped object.

Parameters:

• lvl – [in] debug level of debug message

• input – [in] text of debug message

inline virtual const std::string &name() const override

Get this named output decorators name.

Returns:

the name

class OutputDecorator : public Acts::Logging::OutputPrintPolicy

base class for decorating the debug output

Derived classes may augment the debug message with additional information. Chaining different decorators is possible to customize the output to your needs.

Subclassed by Acts::Logging::LevelOutputDecorator, Acts::Logging::NamedOutputDecorator, Acts::Logging::ThreadOutputDecorator, Acts::Logging::TimedOutputDecorator

Public Functions

inline explicit OutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee)

constructor wrapping actual output print policy

Parameters:

wrappee – [in] output print policy object which is wrapped by this decorator object

inline virtual void flush(const Level &lvl, const std::string &input) override

flush the debug message to the destination stream

This function delegates the flushing of the debug message to its wrapped object.

Parameters:

• lvl – [in] debug level of debug message

• input – [in] text of debug message

inline virtual const std::string &name() const override

Return the name of the output decorator (forwards to wrappee)

Returns:

the name

class OutputFilterPolicy

abstract base class for filtering debug output

Implementations of this interface need to define whether a debug message with a certain debug level is processed or filtered out.

Subclassed by Acts::Logging::DefaultFilterPolicy

Public Functions

virtual ~OutputFilterPolicy() = default

virtual default destructor

virtual std::unique_ptr<OutputFilterPolicy> clone(Level level) const = 0

Make a copy of this filter policy with a new level.

Parameters:

level – the new level

Returns:

the new copy

virtual bool doPrint(const Level &lvl) const = 0

decide whether a debug message should be processed

Parameters:

lvl – [in] debug level of debug message

Returns:

true of debug message should be processed, false if debug message should be skipped

virtual Level level() const = 0

Get the level of this filter policy.

Returns:

the levele

class OutputPrintPolicy

abstract base class for printing debug output

Implementations of this interface need to define how and where to print debug messages (e.g. to a file, to a stream into a database etc).

Subclassed by Acts::Logging::DefaultPrintPolicy, Acts::Logging::OutputDecorator

Public Functions

virtual ~OutputPrintPolicy() = default

virtual default destructor

virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string &name) const = 0

Make a copy of this print policy with a new name.

Parameters:

name – the new name

Returns:

the copy

virtual void flush(const Level &lvl, const std::string &input) = 0

handle output of debug message

Parameters:

• lvl – [in] debug output level of message

• input – [in] text of debug message

virtual const std::string &name() const = 0

Return the name of the print policy.

Returns:

the name

class ThreadOutputDecorator : public Acts::Logging::OutputDecorator

decorate debug message with a thread ID

The debug message is complemented with a thread ID.

Public Functions

inline explicit ThreadOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee)

constructor

Parameters:

wrappee – [in] output print policy object to be wrapped

inline virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string &name) const override

Make a copy of this print policy with a new name.

Parameters:

name – the new name

Returns:

the copy

inline virtual void flush(const Level &lvl, const std::string &input) override

flush the debug message to the destination stream

This function prepends the thread ID to the debug message and then delegates the flushing of the whole message to its wrapped object.

Parameters:

• lvl – [in] debug level of debug message

• input – [in] text of debug message

class ThresholdFailure : public std::runtime_error

Custom exception class so threshold failures can be caught.

class TimedOutputDecorator : public Acts::Logging::OutputDecorator

decorate debug message with a time stamp

The debug message is complemented with a time stamp.

Public Functions

inline explicit TimedOutputDecorator(std::unique_ptr<OutputPrintPolicy> wrappee, const std::string &format = "%X")

constructor

Parameters:

• wrappee – [in] output print policy object to be wrapped

• format – [in] format of time stamp (see std::strftime)

inline virtual std::unique_ptr<OutputPrintPolicy> clone(const std::string &name) const override

Make a copy of this print policy with a new name.

Parameters:

name – the new name

Returns:

the copy

inline virtual void flush(const Level &lvl, const std::string &input) override

flush the debug message to the destination stream

This function prepends a time stamp to the debug message and then delegates the flushing of the whole message to its wrapped object.

Parameters:

• lvl – [in] debug level of debug message

• input – [in] text of debug message

class MagneticFieldContext : public ContextType

Context object for lookup of magnetic field values.

The magnetic field context is an opaque type which contains experiment specific event context information. This can be used to supply event dependent data to the magnetic field instance, in case it is needed to provide correct field values. The library itself does not make any assumptions on the content of this context type (it is implemented using std::any), but passes a reference through the call-chain to the field implementation. An experiment specific field implementation is then expected to performa cast to the concrete type, and use the contents.

An example use case of the context could be to look up conditions data / records for the value of the magnetic field at the time of the event.

class MagneticFieldProvider

Base class for all magnetic field providers.

All magnetic field implementations inherit and implement from this interface.

It provides a generic interface over different implementations. To speed up magnetic field lookup, each implementation can have a cache object. The cache object can for example be used to store a local interpolation domain, to speed up nearby field lookups. The client is expected to pass into lookup calls an instance of Acts::MagneticFieldProvider::Cache.

The implementation is then free to use and update this cache instance as needed. Before a client can issue field lookup calls, it needs to obtain an initialized instance of this cache object. This can be achieved generically for all implementations by using Acts::MagneticFieldProvider::makeCache. This function accepts an instance of Acts::MagneticFieldContext.

The main lookup method of Acts::MagneticFieldProvider is Acts::MagneticFieldProvider::getField

Aside from the lookup position as a global position vector, it accepts an instance of the opaque cache object mentioned before. The return value is a Acts::Result object. It either contains the field value at the requested location, or an Acts::MagneticFieldError in case of a lookup failure, like an out-of-bounds lookup position.

Below is an example of how a client can interact with an instance of Acts::MagneticFieldProvider.

// In event context
auto fieldContext = getExperimentFieldContext();
const Acts::MagneticFieldProvider& fieldProvider = getFieldProvider();
// Make an opaque cache for field lookups
auto cache = fieldProvider.makeCache(fieldContext);

auto lookupResult = fieldProvider.getField(Acts::Vector3{10, 10, 10},
                                  cache);
if(!lookupResult.ok()) {
   throw std::runtime_error{"Field lookup failure"};
}

Acts::Vector3 fieldValue = *lookupResult;

Subclassed by Acts::ConstantBField, Acts::InterpolatedMagneticField, Acts::MultiRangeBField, Acts::NullBField, Acts::SolenoidBField, Acts::ToroidField, ActsPlugins::DD4hepFieldAdapter

Public Types

using Cache = Acts::AnyBase<sizeof(char) * 512>

Opaque cache type that can store arbitrary implementation specific cache data.

Examples are an interpolation cell, or an experiment specific conditions data handle.

The cache is always creaded through makeCache.

Public Functions

virtual ~MagneticFieldProvider() = default

virtual Result<Vector3> getField(const Vector3 &position, Cache &cache) const = 0

Retrieve magnetic field value at a given location.

Requires an instance of Acts::MagneticFieldProvider::Cache created through makeCache.

Parameters:

• position – [in] global 3D position for the lookup

• cache – [inout] Field provider specific cache object

Returns:

magnetic field vector at given position

virtual Cache makeCache(const MagneticFieldContext &mctx) const = 0

Make an opaque cache for the magnetic field.

Instructs the specific implementation to generate a Acts::MagneticFieldProvider::Cache instance for magnetic field lookup.

Parameters:

mctx – The magnetic field context to generate cache for

Returns:

Cache The opaque cache object

class Material

Material description for interactions with matter.

The following parameters are used to specify the material and its interactions with traversing particles:

• radiation length X0 (native length units)

• nuclear interaction length L0 (native length units)

• relative atomic mass Ar (unitless number)

• nuclear charge number Z (elementary charge e)

• molar density (native amount-of-substance unit / (native length unit)³)

The parameters can be effective or average parameters e.g. when a mixture of materials is described.

Note

Always use the opaque parameters vector to serialize/deserialize the material information. Since the internal storage might be different from the external accessors, this ensures that always the numerically optimal parameters are stored. Use the ParametersVector type and do not assume any particular size since we might consider to store more parameters in the future.

Public Types

using ParametersVector = Eigen::Matrix<float, 5, 1>

Opaque parameters vector for serialization.

Public Functions

explicit Material(const ParametersVector &parameters)

Construct from an encoded parameters vector.

Parameters:

parameters – Encoded material parameters

inline constexpr float Ar() const

Return the relative atomic mass.

Returns:

Relative atomic mass

inline bool isVacuum() const

Check if the material is vacuum.

Returns:

True if the material is vacuum

inline constexpr float L0() const

Return the nuclear interaction length.

Infinity in case of vacuum.

Returns:

Nuclear interaction length

float massDensity() const

Return the mass density.

Returns:

Mass density

inline constexpr float meanExcitationEnergy() const

Return the mean electron excitation energy.

Returns:

Mean electron excitation energy

inline constexpr float molarDensity() const

Return the molar density.

Returns:

Molar density

inline constexpr float molarElectronDensity() const

Return the molar electron density.

Returns:

Molar electron density

ParametersVector parameters() const

Encode the properties into an opaque parameters vector.

Returns:

Encoded parameters vector

inline constexpr float X0() const

Return the radiation length.

Infinity in case of vacuum.

Returns:

Radiation length

inline constexpr float Z() const

Return the nuclear charge number.

Returns:

Nuclear charge number

Public Static Functions

static Material fromMassDensity(float x0, float l0, float ar, float z, float massRho)

Construct from material parameters using the mass density.

Warning

Due to the choice of native mass units, using the mass density can lead to numerical problems. Typical mass densities lead to computations with values differing by 20+ orders of magnitude.

Parameters:

• x0 – is the radiation length

• l0 – is the nuclear interaction length

• ar – is the relative atomic mass

• z – is the nuclear charge number

• massRho – is the mass density

Returns:

Material instance constructed from the given parameters

static Material fromMolarDensity(float x0, float l0, float ar, float z, float molarRho)

Construct from material parameters using the molar density.

Parameters:

• x0 – is the radiation length

• l0 – is the nuclear interaction length

• ar – is the relative atomic mass

• z – is the nuclear charge number

• molarRho – is the molar density

Returns:

Material instance constructed from the given parameters

static Material fromMolarDensity(float x0, float l0, float ar, float z, float molarRho, float molarElectronRho, std::optional<float> meanExcitationEnergy)

Construct from material parameters using the molar density.

Parameters:

• x0 – is the radiation length

• l0 – is the nuclear interaction length

• ar – is the relative atomic mass

• z – is the nuclear charge number

• molarRho – is the molar density

• molarElectronRho – is the molar electron density

• meanExcitationEnergy – is the mean electron excitation energy. If not provided it will be approximated.

Returns:

Material instance constructed from the given parameters

static inline constexpr Material Vacuum()

Create a vacuum material.

Returns:

Vacuum material

class MaterialSlab

Material description for an object with defined thickness.

This is intended to describe concrete surface materials.

See also

Material for a description of the available parameters.

Public Functions

inline constexpr MaterialSlab()

Default constructor.

TODO consider removing. currently needed for default construction in grids

MaterialSlab(const Material &material, float thickness)

Construct from material description.

Parameters:

• material – is the material description

• thickness – is the thickness of the material

inline bool isVacuum() const

Check if the material is vacuum.

Returns:

True if the material is vacuum or thickness is zero/negative

inline constexpr const Material &material() const

Access the (average) material parameters.

Returns:

Reference to the material properties

void scaleThickness(float scale)

Scale the material thickness by the given factor.

Parameters:

scale – Factor by which to scale the thickness

inline constexpr float thickness() const

Return the thickness.

Returns:

Material thickness in millimeters

inline constexpr float thicknessInL0() const

Return the nuclear interaction length fraction.

Returns:

Thickness as a fraction of nuclear interaction length

inline constexpr float thicknessInX0() const

Return the radiation length fraction.

Returns:

Thickness as a fraction of radiation length

Public Static Functions

static MaterialSlab combine(const MaterialSlab &slab1, const Material &material2, float thickness2)

Compute the average properties for a combined slab of two materials.

The averaged material slab has the combined thickness of the two input slabs and assumes the two input materials are homogeneously and continuously mixed throughout the slab.

Parameters:

• slab1 – Properties of the first material slab

• material2 – Properties of the second material

• thickness2 – Thickness of the second material slab. Can be negative to subtract the second material from the first slab.

Returns:

Material slab with the combined thickness and average parameters

static MaterialSlab combineLayers(const MaterialSlab &layerA, const MaterialSlab &layerB)

Combine material properties of two layers by averaging them.

Parameters:

• layerA – Input layer A to average over.

• layerB – Input layer B to average over.

Returns:

The resulting object has the combined thickness of all layers but just one set of appropriately averaged material constants.

static MaterialSlab combineLayers(const std::vector<MaterialSlab> &layers)

Combine material properties of multiple layers by averaging them.

Parameters:

layers – Input layers to average over.

Returns:

The resulting object has the combined thickness of all layers but just one set of appropriately averaged material constants.

static inline constexpr MaterialSlab Nothing()

Create a material slab with no material content.

Returns:

Empty material slab with zero thickness and no material

static inline constexpr MaterialSlab Vacuum(float thickness)

Create a vacuum material slab with specified thickness.

Parameters:

thickness – The thickness of the vacuum region

Returns:

Vacuum material slab with the given thickness

class MeasurementSelector

Measurement selection struct selecting those measurements compatible with the given track parameter against provided criteria on one surface.

The selection criteria could be allowed maximum chi2 and allowed maximum number of measurements on one surface

If there is no compatible measurement, the measurement with the minimum chi2 will be selected and the status will be tagged as an outlier

Public Types

using Config = Acts::GeometryHierarchyMap<MeasurementSelectorCuts>

Geometry-dependent cut configuration.

Different components on the geometry can require different cut settings. The configuration must either contain explicit settings for all geometry components that are used or contain a global default.

Public Functions

MeasurementSelector()

Default constructor.

This will use the default configuration for the cuts.

explicit MeasurementSelector(const Config &config)

Constructor with config.

Parameters:

config – a config instance

explicit MeasurementSelector(const MeasurementSelectorCuts &cuts)

Constructor with cuts.

Parameters:

cuts – The cuts to use

template<typename traj_t>
Result<std::pair<typename std::vector<typename traj_t::TrackStateProxy>::iterator, typename std::vector<typename traj_t::TrackStateProxy>::iterator>> select(std::vector<typename traj_t::TrackStateProxy> &candidates, bool &isOutlier, const Logger &logger) const

Function that select the measurements compatible with the given track parameter on a surface.

Parameters:

• candidates – The track state candidates which already contain predicted parameters

• isOutlier – The indicator for outlier or not

• logger – The logger wrapper

Returns:

Pair of iterators into candidates marking the range of selected candidates

template<Concepts::SingleStepper single_stepper_t, typename component_reducer_t = MaxWeightReducerLoop>
class MultiStepperLoop

Stepper based on a single-component stepper, but can handle Multi-Component Tracks (e.g., for the GSF).

Internally, this only manages a vector of states of the single stepper. This simplifies implementation, but has several drawbacks:

• There are certain redundancies between the global State and the component states

• The components do not share a single magnetic-field-cache

Template Parameters:

• sstepper_t – The single-component stepper type to use

• component_reducer_t – How to map the multi-component state to a single component

Public Types

using BoundParameters = MultiComponentBoundTrackParameters

Type alias for bound track parameters.

using BoundState = std::tuple<BoundParameters, Jacobian, double>

Bound state tuple containing parameters, Jacobian, and path length.

using ComponentProxy = detail::LoopComponentProxy<typename State::Component, MultiStepperLoop>

A proxy struct which allows access to a single component of the multi-component state.

It has the semantics of a mutable reference, i.e. it requires a mutable reference of the single-component state it represents

using ConstComponentProxy = detail::LoopComponentProxyBase<const typename State::Component, MultiStepperLoop>

A proxy struct which allows access to a single component of the multi-component state.

It has the semantics of a const reference, i.e. it requires a const reference of the single-component state it represents

using Covariance = BoundMatrix

Type alias for covariance matrix.

using Jacobian = BoundMatrix

Type alias for jacobian matrix.

using Reducer = component_reducer_t

The reducer type.

using SingleConfig = typename SingleStepper::Config

Typedef to the Config of the single component Stepper.

using SingleOptions = typename SingleStepper::Options

Typedef to the Single-Component Stepper Options.

using SingleState = typename SingleStepper::State

Typedef to the State of the single component Stepper.

using SingleStepper = single_stepper_t

Typedef to the Single-Component Eigen Stepper.

Public Functions

inline explicit MultiStepperLoop(const Config &config, std::unique_ptr<const Logger> logger = getDefaultLogger("MultiStepperLoop", Logging::INFO))

Constructor from a configuration and optionally provided Logger.

Parameters:

• config – Configuration object containing stepper settings

• logger – Logger instance for debugging output

inline explicit MultiStepperLoop(std::shared_ptr<const MagneticFieldProvider> bField, std::unique_ptr<const Logger> logger = getDefaultLogger("GSF", Logging::INFO))

Constructor from a magnetic field and a optionally provided Logger TODO this requires that every stepper can be constructed like this…

Parameters:

• bField – Magnetic field provider to use for propagation

• logger – Logger instance for debugging output

inline double absoluteMomentum(const State &state) const

Absolute momentum accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Absolute momentum magnitude from the reduced component state

inline Result<ComponentProxy> addComponent(State &state, const BoundTrackParameters &pars, double weight) const

Add a component to the Multistepper.

Note

: It is not ensured that the weights are normalized afterwards

Note

This function makes no garantuees about how new components are initialized, it is up to the caller to ensure that all components are valid in the end.

Note

The returned component-proxy is only garantueed to be valid until the component number is again modified

Parameters:

• state – [inout] The stepping state (thread-local cache)

• pars – [in] Parameters of the component to add

• weight – [in] Weight of the component to add

Returns:

ComponentProxy for the newly added component or error

Result<BoundState> boundState(State &state, const Surface &surface, bool transportCov = true, const FreeToBoundCorrection &freeToBoundCorrection = FreeToBoundCorrection(false)) const

Create and return the bound state at the current position.

This transports (if necessary) the covariance to the surface and creates a bound state. It does not check if the transported state is at the surface, this needs to be guaranteed by the propagator.

Note

This is done by combining the gaussian mixture on the specified surface. If the conversion to bound states of some components fails, these components are ignored unless all components fail. In this case an error code is returned.

Parameters:

• state – [in] State that will be presented as BoundState

• surface – [in] The surface to which we bind the state

• transportCov – [in] Flag steering covariance transport

• freeToBoundCorrection – [in] Flag steering non-linear correction during global to local correction

Returns:

A bound state:

• the parameters at the surface

• the stepwise jacobian towards it (from last bound)

• and the path length (from start - for ordering)

inline double charge(const State &state) const

Charge access.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Electric charge value from the reduced component state

inline void clearComponents(State &state) const

Reset the number of components.

Parameters:

state – [inout] The stepping state (thread-local cache)

inline auto componentIterable(State &state) const

Creates an iterable which can be plugged into a range-based for-loop to iterate over components.

Note

Use a for-loop with by-value semantics, since the Iterable returns a proxy internally holding a reference

Parameters:

state – Multi-component stepper state to iterate over

Returns:

Iterable range object that can be used in range-based for-loops

inline auto constComponentIterable(const State &state) const

Creates an constant iterable which can be plugged into a range-based for-loop to iterate over components.

Note

Use a for-loop with by-value semantics, since the Iterable returns a proxy internally holding a reference

Parameters:

state – Multi-component stepper state to iterate over (const)

Returns:

Const iterable range object for read-only iteration over components

BoundState curvilinearState(State &state, bool transportCov = true) const

Create and return a curvilinear state at the current position.

This transports (if necessary) the covariance to the current position and creates a curvilinear state.

Note

This is done as a simple average over the free representation and covariance of the components.

Parameters:

• state – [in] State that will be presented as CurvilinearState

• transportCov – [in] Flag steering covariance transport

Returns:

A curvilinear state:

• the curvilinear parameters at given position

• the stepweise jacobian towards it (from last bound)

• and the path length (from start - for ordering)

inline Vector3 direction(const State &state) const

Momentum direction accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Normalized momentum direction vector from the reduced component state

inline Result<Vector3> getField(State &state, const Vector3 &pos) const

Get the field for the stepping, it checks first if the access is still within the Cell, and updates the cell if necessary.

Note

This uses the cache of the first component stored in the state

Parameters:

• state – [inout] is the propagation state associated with the track the magnetic field cell is used (and potentially updated)

• pos – [in] is the field position

Returns:

Magnetic field vector at the given position or error

inline double getStepSize(const State &state, ConstrainedStep::Type stype) const

Get the step size.

Note

This returns the smallest step size of all components. It uses std::abs for comparison to handle backward propagation and negative step sizes correctly.

Parameters:

• state – [in] The stepping state (thread-local cache)

• stype – [in] The step size type to be returned

Returns:

Smallest step size among all components for the requested type

inline void initialize(State &state, const BoundParameters &par) const

Initialize the stepper state from multi-component bound track parameters.

Parameters:

• state – The stepper state to initialize

• par – The multi-component bound track parameters

inline State makeState(const Options &options) const

Create a state object for multi-stepping.

Parameters:

options – The propagation options

Returns:

Initialized state object for multi-stepper

inline Vector3 momentum(const State &state) const

Momentum accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Momentum vector from the reduced component state

inline std::size_t numberComponents(const State &state) const

Get the number of components.

Parameters:

state – [in,out] The stepping state (thread-local cache)

Returns:

Number of components in the multi-component state

inline std::string outputStepSize(const State &state) const

Output the Step Size of all components into one std::string.

Parameters:

state – [in,out] The stepping state (thread-local cache)

Returns:

String representation of all component step sizes concatenated

inline ParticleHypothesis particleHypothesis(const State &state) const

Particle hypothesis.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Particle hypothesis used for this multi-component state

inline Vector3 position(const State &state) const

Global particle position accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Global position vector from the reduced component state

inline bool prepareCurvilinearState(State &state) const

If necessary fill additional members needed for curvilinearState.

Compute path length derivatives in case they have not been computed yet, which is the case if no step has been executed yet.

Parameters:

state – [inout] The stepping state (thread-local cache)

Returns:

true if nothing is missing after this call, false otherwise.

inline double qOverP(const State &state) const

QoP access.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Charge over momentum (q/p) value from the reduced component state

inline void releaseStepSize(State &state, ConstrainedStep::Type stype) const

Release the step-size for all components.

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• stype – [in] The step size type to be released

inline void removeMissedComponents(State &state) const

Remove missed components from the component state.

Parameters:

state – [in,out] The stepping state (thread-local cache)

inline void reweightComponents(State &state) const

Reweight the components.

Parameters:

state – [inout] The stepping state (thread-local cache)

inline const SingleStepper &singleStepper() const

Get the single stepper instance.

Returns:

Reference to the single stepper instance used internally

Result<double> step(State &state, Direction propDir, const IVolumeMaterial *material) const

Perform a Runge-Kutta track parameter propagation step.

The state contains the desired step size. It can be negative during backwards track propagation, and since we’re using an adaptive algorithm, it can be modified by the stepper class during propagation.

Parameters:

• state – [inout] The state of the stepper

• propDir – is the direction of propagation

• material – is the material properties

Returns:

the result of the step

inline double time(const State &state) const

Time access.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Time coordinate from the reduced component state

inline void transportCovarianceToBound(State &state, const Surface &surface, const FreeToBoundCorrection &freeToBoundCorrection = FreeToBoundCorrection(false)) const

Method for on-demand transport of the covariance to a new curvilinear frame at current position, or direction of the state.

Note

no check is done if the position is actually on the surface

Template Parameters:

surface_t – the Surface type

Parameters:

• state – [inout] State of the stepper

• surface – [in] is the surface to which the covariance is forwarded

• freeToBoundCorrection – [in] Flag steering non-linear correction during global to local correction to

inline void transportCovarianceToCurvilinear(State &state) const

Method for on-demand transport of the covariance to a new curvilinear frame at current position, or direction of the state.

Parameters:

state – [inout] State of the stepper

template<typename object_intersection_t>
inline void updateStepSize(State &state, const object_intersection_t &oIntersection, Direction direction, ConstrainedStep::Type stype) const

Update step size.

This method intersects the provided surface and update the navigation step estimation accordingly (hence it changes the state). It also returns the status of the intersection to trigger onSurface in case the surface is reached.

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• oIntersection – [in] The ObjectIntersection to layer, boundary, etc

• direction – [in] The propagation direction

• stype – [in] The step size type to be set

inline void updateStepSize(State &state, double stepSize, ConstrainedStep::Type stype) const

Update step size - explicitly with a double.

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• stepSize – [in] The step size value

• stype – [in] The step size type to be set

inline IntersectionStatus updateSurfaceStatus(State &state, const Surface &surface, std::uint8_t index, Direction navDir, const BoundaryTolerance &boundaryTolerance, double surfaceTolerance, ConstrainedStep::Type stype, const Logger &logger = getDummyLogger()) const

Update surface status.

It checks the status to the reference surface & updates the step size accordingly

Parameters:

• state – [inout] The stepping state (thread-local cache)

• surface – [in] The surface provided

• index – [in] The surface intersection index

• navDir – [in] The navigation direction

• boundaryTolerance – [in] The boundary check for this status update

• surfaceTolerance – [in] Surface tolerance used for intersection

• stype – [in] The step size type to be set

• logger – [in] A Logger instance

Returns:

IntersectionStatus indicating the overall status of all components relative to the surface

Public Static Attributes

static constexpr int maxComponents = std::numeric_limits<int>::max()

How many components can this stepper manage?

struct Config : public SingleStepper::Config

Configuration for the multi-stepper loop.

Public Members

std::size_t stepLimitAfterFirstComponentOnSurface = 50

Limits the number of steps after at least one component reached the surface.

struct Options : public SingleOptions

struct State

State container for multi-component stepping.

Public Functions

inline explicit State(const Options &optionsIn)

Constructor from the initial bound track parameters.

Note

the covariance matrix is copied when needed

Parameters:

optionsIn – [in] is the options object for the stepper

Public Members

SmallVector<Component> components

The components of which the state consists.

bool covTransport = false

Whether to transport covariance.

Options options

Options for the propagation.

ParticleHypothesis particleHypothesis = ParticleHypothesis::pion()

Particle hypothesis.

double pathAccumulated = 0.

Accumulated path length.

StepperStatistics statistics

The stepper statistics.

std::optional<std::size_t> stepCounterAfterFirstComponentOnSurface

Step-limit counter which limits the number of steps when one component reached a surface.

std::size_t steps = 0

Number of steps taken.

struct Component

The struct that stores the individual components.

Public Functions

inline Component(SingleState state_, double weight_, IntersectionStatus status_)

Constructor for a multi-stepper component.

Parameters:

• state_ – The single state for this component

• weight_ – The weight of this component

• status_ – The intersection status of this component

Public Members

SingleState state

Individual component state for propagation.

IntersectionStatus status

Intersection status of this component.

double weight

Statistical weight of this component.

template<typename derived_t>
class MultiTrajectory

Store a trajectory of track states with multiple components.

This container supports both simple, sequential trajectories as well as combinatorial or multi-component trajectories. Each point can store a parent point such that the trajectory forms a directed, acyclic graph of sub-trajectories. From a set of endpoints, all possible sub-components can be easily identified. Some functionality is provided to simplify iterating over specific sub-components.

MultiTrajectory track state iteration

template<typename F> void visitBackwards(IndexType iendpoint, F &&callable) const requires detail_lt void applyBackwards (IndexType iendpoint, F &&callable) requires(!ReadOnly) &&detail_lt

Visit all previous states starting at a given endpoint.

Note

Only available if the MultiTrajectory is not read-only Range for the track states from iendpoint to the trajectory start

Note

Const version Range for the track states from iendpoint to the trajectory start, i.e from the outside in.

Note

Only available if the MultiTrajectory is not read-only

Note

Mutable version

Warning

If the trajectory contains multiple components with common points, this can have an impact on the other components.

Param iendpoint:

index of the last state

Param callable:

non-modifying functor to be called with each point Apply a function to all previous states starting at a given endpoint.

Param iendpoint:

index of the last state

Param callable:

modifying functor to be called with each point

Param iendpoint:

Trajectory entry point to start from

Param iendpoint:

Trajectory entry point to start from

Return:

Iterator pair to iterate over

Return:

Iterator pair to iterate over

inline auto forwardTrackStateRange(IndexType istartpoint) const

Range for the track states from istartpoint to the trajectory end, i.e from inside out.

Note

Const version

Parameters:

istartpoint – Trajectory state index for the innermost track state to start from

Returns:

Iterator pair to iterate over

inline auto forwardTrackStateRange(IndexType istartpoint)
requires (!ReadOnly)

Range for the track states from istartpoint to the trajectory end, i.e from inside out.

Note

Only available if the MultiTrajectory is not read-only

Parameters:

istartpoint – Trajectory state index for the innermost track state to start from

Returns:

Iterator pair to iterate over

MultiTrajectory track state (proxy) access and manipulation

These methods allow accessing track states, i.e. adding or retrieving a track state proxy that points at a specific track state in the container.

inline ConstTrackStateProxy getTrackState(IndexType istate) const

Access a read-only point on the trajectory by index.

Note

Only available if the MultiTrajectory is not read-only

Parameters:

istate – The index to access

Returns:

Read only proxy to the stored track state

inline TrackStateProxy getTrackState(IndexType istate)
requires (!ReadOnly)

Access a writable point on the trajectory by index.

Note

Only available if the MultiTrajectory is not read-only

Parameters:

istate – The index to access

Returns:

Read-write proxy to the stored track state

inline IndexType addTrackState(TrackStatePropMask mask = TrackStatePropMask::All, IndexType iprevious = kInvalid)
requires (!ReadOnly)

Add a track state without providing explicit information.

Which components of the track state are initialized/allocated can be controlled via mask

Note

Only available if the MultiTrajectory is not read-only

Parameters:

• mask – The bitmask that instructs which components to allocate and which to leave invalid

• iprevious – index of the previous state, kInvalid if first

Returns:

Index of the newly added track state

inline TrackStateProxy makeTrackState(TrackStatePropMask mask = TrackStatePropMask::All, IndexType iprevious = kInvalid)
requires (!ReadOnly)

Add a track state to the container and return a track state proxy to it This effectively calls addTrackState and getTrackState.

Note

Only available if the track state container is not read-only

Parameters:

• mask – Mask indicating which track state components to allocate

• iprevious – Index of the previous track state for linking

Returns:

a track state proxy to the newly added track state

MultiTrajectory column management

MultiTrajectory can manage a set of common static columns, and dynamic columns that can be added at runtime.

This set of methods allows you to manage the dynamic columns.

template<typename T>
inline void addColumn(std::string_view key)
requires (!ReadOnly)

Add a column to the MultiTrajectory.

Note

This takes a string argument rather than a hashed string to maintain compatibility with backends.

Note

Only available if the MultiTrajectory is not read-only

Template Parameters:

T – Type of the column values to add

Parameters:

key – the name of the column to be added

inline bool hasColumn(HashedString key) const

Check if a column with a key key exists.

Parameters:

key – Key to check for a column with

Returns:

True if the column exists, false if not.

Public Types

using ConstTrackStateProxy = Acts::TrackStateProxy<Derived, MeasurementSizeMax, true>

Alias for the const version of a track state proxy, with the same backends as this container.

using Derived = derived_t

Type alias for derived multi-trajectory implementation.

using IndexType = TrackIndexType

The index type of the track state container.

using TrackStateProxy = Acts::TrackStateProxy<Derived, MeasurementSizeMax, false>

Alias for the mutable version of a track state proxy, with the same backends as this container.

Public Functions

inline void clear()
requires (!ReadOnly)

Clear the MultiTrajectory.

Leaves the underlying storage untouched

Note

Only available if the MultiTrajectory is not read-only

inline IndexType size() const

Returns the number of track states contained.

Returns:

The number of track states

Public Static Attributes

static constexpr IndexType kInvalid = kTrackIndexInvalid

Sentinel value that indicates an invalid index.

static constexpr unsigned int MeasurementSizeMax = kMeasurementSizeMax

Maximum number of measurement dimensions supported by this trajectory.

static constexpr bool ReadOnly = IsReadOnlyMultiTrajectory<Derived>::value

Flag indicating whether this multi-trajectory is read-only.

Friends

friend class MultiTrajectory

friend class AnyTrackStateProxy

friend class detail_anytstate::TrackStateHandler

friend class TrackStateProxy< Derived, MeasurementSizeMax, false >

friend class TrackStateProxy< Derived, MeasurementSizeMax, true >

class NavigationLayer : public Acts::Layer

Class to be used for gaps in Volumes as a navigational link.

Navigation Layers have a surface representation, but should usually never be propagated to.

Public Functions

NavigationLayer() = delete

Default Constructor - deleted.

NavigationLayer(const NavigationLayer&) = delete

Copy Constructor - deleted.

~NavigationLayer() override

Destructor.

inline virtual bool isOnLayer(const GeometryContext &gctx, const Vector3 &gp, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::None()) const final

Geometric isOnLayer() method using isOnSurface() with Layer specific tolerance.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• gp – is the global position for the check

• boundaryTolerance – is the boundary check directive

Returns:

boolean that indicates if the position is on surface

NavigationLayer &operator=(const NavigationLayer&) = delete

Assignment operator - deleted.

inline virtual Vector3 referencePosition(const GeometryContext &gctx, AxisDirection aDir) const final

The binning position method.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• aDir – is the axis direction for which the reference position is requested

  • as default the center is given, but may be overloaded

Returns:

The return vector can be used for binning in a TrackingVolume

inline virtual bool resolve(bool resolveSensitive, bool resolveMaterial, bool resolvePassive) const final

Accept layer according to the following collection directives.

Note

navigation layers are never accepted

Parameters:

• resolveSensitive – is the prescription to find the sensitive surfaces

• resolveMaterial – is the precription to find material surfaces

• resolvePassive – is the prescription to find all passive surfaces

Returns:

a boolean whether the layer is accepted for processing

inline virtual const Surface &surfaceRepresentation() const final

Transforms the layer into a Surface representation for extrapolation In general, extrapolation to a surface should be avoided.

Returns:

Const reference to the navigation surface

inline virtual Surface &surfaceRepresentation() final

Non-const version of surface representation access.

Returns:

Mutable reference to the navigation surface

Public Static Functions

static inline LayerPtr create(std::shared_ptr<const Surface> sRepresentation, double thickness = 0.)

Factory Constructor - the surface representation is given by pointer (ownership passed)

Parameters:

• sRepresentation – is the representation for extrapolation

• thickness – is the thickness for the binning

Returns:

Shared pointer to the created navigation layer

class Navigator

Steers the propagation through the geometry by providing the next surface to be targeted.

The Navigator is part of the propagation and responsible for steering the surface sequence to encounter all the relevant surfaces which are intersected by the trajectory.

The current navigation stage is cached in the state struct and updated when necessary. If any surface in the extrapolation flow is hit, it is set to the navigation state, such that other actors can deal with it.

The current target surface is referenced by an index which points into the navigation candidates. The navigation candidates are ordered by the path length to the surface. If a surface is hit, the state.currentSurface pointer is set. This actors to observe that we are on a surface.

Public Types

using GeometryVersion = TrackingGeometry::GeometryVersion

Type alias for geometry version enumeration.

using NavigationBoundaries = boost::container::small_vector<NavigationTarget, 4>

Type alias for navigation boundary candidates container.

using NavigationCandidates = boost::container::small_vector<NavigationTarget, 10>

Type alias for generic navigation candidates container.

using NavigationLayers = boost::container::small_vector<NavigationTarget, 10>

Type alias for navigation layer candidates container.

using NavigationSurfaces = boost::container::small_vector<NavigationTarget, 10>

Type alias for navigation surface candidates container.

enum class Stage : int

The navigation stage.

Values:

enumerator initial

enumerator surfaceTarget

enumerator layerTarget

enumerator boundaryTarget

Public Functions

explicit Navigator(Config cfg, std::shared_ptr<const Logger> _logger = getDefaultLogger("Navigator", Logging::Level::INFO))

Constructor with configuration object.

Parameters:

• cfg – The navigator configuration

• _logger – a logger instance

bool checkTargetValid(State &state, const Vector3 &position, const Vector3 &direction) const

Check if the current target is still valid.

This function checks if the target is valid.

Parameters:

• state – The navigation state

• position – The current position

• direction – The current direction

Returns:

True if the target is valid

const Surface *currentSurface(const State &state) const

Get the current surface from navigation state.

Parameters:

state – The navigation state

Returns:

Pointer to current surface, or nullptr if none

const TrackingVolume *currentVolume(const State &state) const

Get the current volume from navigation state.

Parameters:

state – The navigation state

Returns:

Pointer to current volume, or nullptr if none

const IVolumeMaterial *currentVolumeMaterial(const State &state) const

Get material properties of the current volume.

Parameters:

state – The navigation state

Returns:

Pointer to volume material, or nullptr if no volume or material

bool endOfWorldReached(const State &state) const

Check if navigation has reached the end of the world (no current volume)

Parameters:

state – The navigation state

Returns:

True if end of world is reached

void handleSurfaceReached(State &state, const Vector3 &position, const Vector3 &direction, const Surface &surface) const

Handle the surface reached.

This function handles the surface reached.

Parameters:

• state – The navigation state

• position – The current position

• direction – The current direction

• surface – The surface reached

Result<void> initialize(State &state, const Vector3 &position, const Vector3 &direction, Direction propagationDirection) const

Initialize the navigator state.

This function initializes the navigator state for a new propagation.

Parameters:

• state – The navigation state

• position – The start position

• direction – The start direction

• propagationDirection – The propagation direction

Returns:

Indication if the initialization was successful

State makeState(const Options &options) const

Create a navigation state from options.

Parameters:

options – The navigation options

Returns:

A new navigation state

bool navigationBreak(const State &state) const

Check if navigation should be interrupted.

Parameters:

state – The navigation state

Returns:

True if navigation break flag is set

NavigationTarget nextTarget(State &state, const Vector3 &position, const Vector3 &direction) const

Get the next target surface.

This function gets the next target surface for the propagation.

Parameters:

• state – The navigation state

• position – The current position

• direction – The current direction

Returns:

The next target surface

const Surface *startSurface(const State &state) const

Get the starting surface from navigation state.

Parameters:

state – The navigation state

Returns:

Pointer to start surface, or nullptr if none

const Surface *targetSurface(const State &state) const

Get the target surface from navigation state.

Parameters:

state – The navigation state

Returns:

Pointer to target surface, or nullptr if none

struct Config

The navigator configuration.

Public Members

bool resolveMaterial = true

stop at every material surface (whether it is passive or not)

bool resolvePassive = false

stop at every surface regardless what it is

bool resolveSensitive = true

stop at every sensitive surface (whether it has material or not)

std::shared_ptr<const TrackingGeometry> trackingGeometry = {nullptr}

Tracking Geometry for this Navigator.

struct Options : public Acts::NavigatorPlainOptions

The navigator options.

Public Functions

inline explicit Options(const GeometryContext &gctx)

Constructor with geometry context.

Parameters:

gctx – The geometry context for the navigation

inline void setPlainOptions(const NavigatorPlainOptions &options)

Set the plain navigation options.

Parameters:

options – The plain navigator options to set

struct State

Nested State struct.

It acts as an internal state which is created for every propagation and meant to keep thread-local navigation information.

Public Functions

inline explicit State(const Options &options_)

Constructor with navigation options.

Parameters:

options_ – The navigation options for this state

inline NavigationTarget &navBoundary()

Get reference to current navigation boundary.

Returns:

Reference to current boundary intersection

inline NavigationTarget &navCandidate()

Get reference to current navigation candidate.

Returns:

Reference to current boundary intersection

inline NavigationTarget &navLayer()

Get reference to current navigation layer.

Returns:

Reference to current layer intersection

inline NavigationTarget &navSurface()

Get reference to current navigation surface.

Returns:

Reference to current navigation target

inline void resetAfterLayerSwitch()

Reset navigation state after switching layers.

inline void resetAfterVolumeSwitch()

Reset navigation state after switching volumes.

inline void resetForRenavigation()

Completely reset navigation state to initial conditions.

Public Members

const Layer *currentLayer = nullptr

Current layer during navigation.

const Surface *currentSurface = nullptr

Current surface during navigation.

const TrackingVolume *currentVolume = nullptr

Current volume during navigation.

std::vector<std::pair<const Surface*, bool>> freeCandidates = {}

Free candidates not part of the tracking geometry.

and a boolean indicating whether the surface has already been reached during propagation

std::vector<const Surface*> freeSurfaces

Surfaces that are not part of the tracking geometry.

NavigationBoundaries navBoundaries = {}

the vector of boundary surfaces to work through

std::optional<std::size_t> navBoundaryIndex

the current boundary index of the navigation state

std::optional<std::size_t> navCandidateIndex

the current candidate index of the navigation state

NavigationCandidates navCandidates = {}

the vector of navigation candidates to work through

bool navigationBreak = false

Flag to break navigation loop.

Stage navigationStage = Stage::initial

Current navigation stage in the state machine.

std::optional<std::size_t> navLayerIndex

the current layer index of the navigation state

NavigationLayers navLayers = {}

the vector of navigation layers to work through

std::optional<std::size_t> navSurfaceIndex

the current surface index of the navigation state

NavigationSurfaces navSurfaces = {}

the vector of navigation surfaces to work through

Options options

Navigation options configuration.

NavigationPolicyStateManager policyStateManager

Management of policy state allocation and deallocation.

const Layer *startLayer = nullptr

Layer where the navigation started.

const Surface *startSurface = nullptr

Surface where the navigation started.

const TrackingVolume *startVolume = nullptr

Volume where the navigation started.

NavigatorStatistics statistics

Statistics collection for navigation performance.

NavigationStream stream

Stream for navigation debugging and monitoring.

const Surface *targetSurface = nullptr

Target surface for navigation.

Warning

doxygenclass: Cannot find class “Acts::NeutralParticleHypothesis” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

Warning

doxygenclass: Cannot find class “Acts::NonNeutralCharge” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

Warning

doxygenclass: Cannot find class “Acts::NonNeutralChargedParticleHypothesis” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

class NullBField : public Acts::MagneticFieldProvider

Null bfield which returns 0 always.

Public Functions

NullBField() = default

Default constructor.

inline virtual Result<Vector3> getField(const Vector3 &position, MagneticFieldProvider::Cache &cache) const override

Retrieve magnetic field value at a given location.

Requires an instance of Acts::MagneticFieldProvider::Cache created through makeCache.

Note

The position is ignored and only kept as argument to provide a consistent interface with other magnetic field services.

Parameters:

• position – [in] global 3D position for the lookup

• cache – [inout] Field provider specific cache object

Returns:

magnetic field vector at given position

inline bool isInside(const Vector3&) const

check whether given 3D position is inside look-up domain

Note

The method will always return true for the null B-Field

Returns:

true if position is inside the defined look-up grid, otherwise false

inline virtual Acts::MagneticFieldProvider::Cache makeCache(const Acts::MagneticFieldContext &mctx) const override

Make an opaque cache for the magnetic field.

Instructs the specific implementation to generate a Acts::MagneticFieldProvider::Cache instance for magnetic field lookup.

Parameters:

mctx – The magnetic field context to generate cache for

Returns:

Cache The opaque cache object

struct Cache

Cache object for the null magnetic field provider.

Public Functions

inline explicit Cache(const MagneticFieldContext&)

constructor with context

class ParticleHypothesis

Particle hypothesis used in reconstruction.

The reconstruction hypothesis consists of absolute PDG code, mass and absolute charge.

Public Functions

inline explicit ParticleHypothesis(PdgParticle absPdg)

Creates a particle hypothesis using the absolute PDG.

The mass and charge is looked up using findMass and findCharge. If the lookup fails an exception is thrown.

Parameters:

absPdg – the absolute PDG

inline constexpr ParticleHypothesis(PdgParticle absPdg, float mass, ChargeHypothesis charge)

Creates a particle hypothesis using absolute PDG, mass and the charge type.

Parameters:

• absPdg – the absolute PDG

• mass – the particle mass

• charge – the charge type

inline constexpr ParticleHypothesis(PdgParticle absPdg, float mass, float absCharge)

Creates a particle hypothesis using absolute PDG, mass and the charge type.

Parameters:

• absPdg – the absolute PDG

• mass – the particle mass

• absCharge – the absolute charge

inline float absoluteCharge() const noexcept

Get the hypothesized absolute charge.

Returns:

The absolute charge magnitude

inline constexpr PdgParticle absolutePdg() const noexcept

Get the hypothesized absolute PDG.

Returns:

The absolute PDG particle identifier

inline constexpr const ChargeHypothesis &charge() const noexcept

Get the hypothesized charge.

Returns:

Reference to the charge type object

inline constexpr float extractCharge(double qOverP) const noexcept

Extracts the signed charge from the q over p track parameter using the charge hypothesis.

Parameters:

qOverP – the q over p track parameter.

Returns:

The extracted signed charge

inline constexpr double extractMomentum(double qOverP) const noexcept

Extracts the particle momentum from the q over p track parameter using the charge hypothesis.

Parameters:

qOverP – the q over p track parameter.

Returns:

The extracted absolute momentum

inline constexpr float mass() const noexcept

Get the hypothesized mass.

Returns:

The particle mass in natural units

inline constexpr double qOverP(double momentum, float signedQ) const noexcept

Calculate the q over p track parameter with the given absolute momentum and charge.

Parameters:

• momentum – the absolute momentum.

• signedQ – the signed charge.

Returns:

The calculated charge over momentum ratio

inline std::ostream &toStream(std::ostream &os) const

Output stream representation of the particle hypothesis.

Parameters:

os – Output stream to write to

Returns:

Modified output stream for chaining

Public Static Functions

static inline ParticleHypothesis chargedGeantino()

Create a charged geantino particle hypothesis with unit charge.

Returns:

Charged geantino particle hypothesis with any charge type

static inline ParticleHypothesis chargedGeantino(float absoluteCharge)

Create a charged geantino particle hypothesis with custom charge.

Parameters:

absoluteCharge – The absolute charge value

Returns:

Charged geantino particle hypothesis with any charge type

static inline ParticleHypothesis electron()

Create an electron particle hypothesis.

Returns:

Electron particle hypothesis with any charge type

static inline ParticleHypothesis geantino()

Create a neutral geantino particle hypothesis (massless neutral particle)

Returns:

Neutral geantino particle hypothesis with any charge type

static inline ParticleHypothesis kaon()

Create a charged kaon particle hypothesis.

Returns:

Charged kaon particle hypothesis with any charge type

static inline ParticleHypothesis muon()

Create a muon particle hypothesis.

Returns:

Muon particle hypothesis with any charge type

static inline ParticleHypothesis photon()

Create a photon particle hypothesis.

Returns:

Photon particle hypothesis with any charge type

static inline ParticleHypothesis pion()

Create a charged pion particle hypothesis.

Returns:

Charged pion particle hypothesis with any charge type

static inline ParticleHypothesis pion0()

Create a neutral pion particle hypothesis.

Returns:

Neutral pion particle hypothesis with any charge type

static inline ParticleHypothesis pionLike(float absoluteCharge)

Create a pion-like particle hypothesis with custom charge.

Parameters:

absoluteCharge – The absolute charge value

Returns:

Pion-like particle hypothesis with any charge type

static inline ParticleHypothesis proton()

Create a proton particle hypothesis.

Returns:

Proton particle hypothesis with any charge type

Friends

inline friend std::ostream &operator<<(std::ostream &os, const ParticleHypothesis &particleHypothesis)

Output stream operator for particle hypothesis.

Parameters:

• os – Output stream to write to

• particleHypothesis – The particle hypothesis to output

Returns:

Reference to output stream for chaining

class PerigeeSurface : public Acts::LineSurface

Class describing the Line to which the Perigee refers to.

The Surface axis is fixed to be the z-axis of the Tracking frame. It inherits from StraingLineSurface.

Public Functions

virtual std::string name() const final

Return properly formatted class name for screen output */.

Returns:

String representation of the surface type name

PerigeeSurface &operator=(const PerigeeSurface &other)

Assignment operator.

Parameters:

other – is the source surface to be assigned

Returns:

Reference to this surface for assignment chaining

virtual Polyhedron polyhedronRepresentation(const GeometryContext &gctx, unsigned int ingoreSegments) const final

Return a Polyhedron for the surfaces.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• ingoreSegments – is an ignored parameter

Returns:

A list of vertices and a face/facett description of it

virtual SurfaceType type() const final

Return the surface type.

Returns:

Surface type identifier for perigee surfaces

class PlanarBounds : public Acts::SurfaceBounds

common base class for all bounds that are in a local x/y cartesian frame

• simply introduced to avoid wrong bound assignments to surfaces

Subclassed by Acts::ConvexPolygonBoundsBase, Acts::DiamondBounds, Acts::EllipseBounds, Acts::RectangleBounds, Acts::TrapezoidBounds

Public Functions

virtual const RectangleBounds &boundingBox() const = 0

Bounding box parameters.

Returns:

rectangle bounds for a bounding box

inline virtual SquareMatrix2 boundToCartesianJacobian(const Vector2 &lposition) const final

Computes the bound to cartesian jacobian at a given local position.

Parameters:

lposition – is the local position at which the jacobian is computed

Returns:

the bound to cartesian jacobian

inline virtual SquareMatrix2 boundToCartesianMetric(const Vector2 &lposition) const final

Computes the bound to cartesian metric at a given local position.

Parameters:

lposition – is the local position at which the metric is computed

Returns:

the bound to cartesian metric

inline virtual bool isCartesian() const final

Check if the bound coordinates are cartesian.

Returns:

true if the bound coordinates are cartesian

virtual std::vector<Vector2> vertices(unsigned int quarterSegments = 2u) const = 0

Return the vertices.

Note

for planar bounds without curved segments quarterSegments is ignored

Parameters:

quarterSegments – is the number of segments used to describe curved segments in a quarter of the phi range. If it is 1, then only the extrema points in phi are inserted next to the segment corners.

Returns:

vector for vertices in 2D

class PlaneLayer : public virtual Acts::PlaneSurface, public Acts::Layer

Class to describe a planar detector layer for tracking, it inherits from both, Layer base class and PlaneSurface class.

Public Functions

PlaneLayer() = delete

PlaneLayer(const PlaneLayer &pla) = delete

~PlaneLayer() override = default

PlaneLayer &operator=(const PlaneLayer&) = delete

virtual const PlaneSurface &surfaceRepresentation() const override

Transforms the layer into a Surface representation for extrapolation.

Returns:

returns a reference to a PlaneSurface

virtual PlaneSurface &surfaceRepresentation() override

Non-const version of surface representation access.

Returns:

Mutable reference to the plane surface

Public Static Functions

static std::shared_ptr<PlaneLayer> create(const Transform3 &transform, std::shared_ptr<const PlanarBounds> pbounds, std::unique_ptr<SurfaceArray> surfaceArray, double thickness = 0., std::unique_ptr<ApproachDescriptor> ad = nullptr, LayerType laytyp = active)

Factory for a shared plane layer.

Parameters:

• transform – which places the layer in the global frame

• pbounds – the planar bounds that define the layer dimensions

• surfaceArray – is the surface array that holds the sensitive surfaces

• thickness – is the thickness of the layer (normal direction to plane)

• ad – is the approach descriptor for describing the approach surface

• laytyp – is the layer type

Returns:

shared pointer to a PlaneLayer

class PlaneSurface : public Acts::RegularSurface

Class for a planaer in the TrackingGeometry.

The PlaneSurface extends the Surface class with the possibility to convert local to global positions (vice versa).

Subclassed by Acts::PlaneLayer

Public Functions

void assignSurfaceBounds(std::shared_ptr<const PlanarBounds> newBounds)

Overwrite the existing surface bounds with new ones.

Parameters:

newBounds – Pointer to the new bounds

virtual const SurfaceBounds &bounds() const override

Return method for bounds object of this surfrace.

Returns:

Reference to the surface bounds

const std::shared_ptr<const PlanarBounds> &boundsPtr() const

This method returns the shared_ptr to the DiscBounds.

Returns:

Shared pointer to the planar bounds

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final

Convert a global position to a local one this is the most generic interface, which is implemented by all surfaces.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be converted

• direction – is the direction of the local position (ignored for RegularSurface)

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const override

Global to local transformation.

Note

For planar surfaces the momentum direction is ignored in the global to local transformation

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position - considered to be on surface but not inside bounds (check is done)

• tolerance – optional tolerance within which a point is considered valid on surface

Returns:

a Result<Vector2> which can be !ok() if the operation fails

Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const = 0

Convert a global position to a local one.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be converted

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual MultiIntersection3D intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), double tolerance = s_onSurfaceTolerance) const final

Straight line intersection.

mathematical motivation:

the equation of the plane is given by: \( \vec n \cdot \vec x = \vec n \cdot \vec p,\) where \( \vec n = (n_{x}, n_{y}, n_{z})\) denotes the normal vector of the plane, \( \vec p = (p_{x}, p_{y}, p_{z})\) one specific point on the plane and \( \vec x = (x,y,z) \) all possible points on the plane.

Given a line with:\( \vec l(u) = \vec l_{1} + u \cdot \vec v \)

,

the solution for

\( u \) can be written: \( u = \frac{\vec n (\vec p - \vec l_{1})}{\vec n \vec v}\) If the denominator is 0 then the line lies:

• either in the plane

• perpendicular to the normal of the plane

Note

expected to be normalized)

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The start position of the intersection attempt

• direction – The direction of the intersection attempt, (

• boundaryTolerance – The boundary check directive

• tolerance – the tolerance used for the intersection

Returns:

the MultiIntersection3D object

virtual Matrix<2, 3> localCartesianToBoundLocalDerivative(const GeometryContext &gctx, const Vector3 &position) const final

Calculate the derivative of bound track parameters local position w.r.t.

position in local 3D Cartesian coordinates

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The position of the parameters in global

Returns:

Derivative of bound local position w.r.t. position in local 3D cartesian coordinates

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const override

Local to global transformation.

Note

For planar surfaces the momentum direction is ignored in the local to global transformation

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

Returns:

the global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Local to global transformation.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

Returns:

The global position by value

Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const final

Local to global transformation.

This is the most generic interface, which is implemented by all surfaces.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

• direction – global 3D momentum direction (ignored for RegularSurface)

Returns:

The global position by value

std::pair<std::shared_ptr<PlaneSurface>, bool> mergedWith(const PlaneSurface &other, AxisDirection direction, const Logger &logger = getDummyLogger()) const

Merge two plane surfaces into a single one.

Note

The surfaces need to be compatible, i.e. have bounds that align along merging direction, and have the same bound size along the non-merging direction

Note

The returned boolean is false if this is left or counter-clockwise of other, and true if not.

Parameters:

• other – The other plane surface to merge with

• direction – The direction: either AxisX or AxisY

• logger – The logger to use

Returns:

The merged plane surface and a boolean indicating if surfaces are reversed

virtual std::string name() const override

Return properly formatted class name for screen output.

Returns:

String representation of the class name

Vector3 normal(const GeometryContext &gctx) const

Get the normal vector, independent of the location.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

The normal vector

virtual Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const final

Get the normal vector of this surface at a given local position.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is the local position is ignored

Returns:

Normal vector as Vector3 by value

Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Calculate the normal vector of the surface This overload requires an on-surface local position.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is the local position where the normal vector is constructed

Returns:

normal vector by value

Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const final

Calculate the normal vector of the surface This overload is fully generic, fulfills the Surface interface and accepts a global position and a direction.

For RegularSurface this is equivalent to the normal overload, ignoring the direction

Parameters:

• gctx – The current geometry context object, e.g. alignment

• pos – is the global position where the normal vector is constructed

• direction – is the direction of the normal vector (ignored for RegularSurface)

Returns:

Normal vector at the given position

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const final

Get the normal vector of this surface at a given global position.

Note

The position is required to be on-surface.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global positiono (for PlaneSurface this is ignored)

Returns:

The normal vector

Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const = 0

Calculate the normal vector of the surface This overload accepts a global position.

Parameters:

• position – is the global position where the normal vector is constructed

• gctx – The current geometry context object, e.g. alignment

Returns:

normal vector by value

PlaneSurface &operator=(const PlaneSurface &other)

Assignment operator.

Parameters:

other – The source PlaneSurface for assignment

Returns:

Reference to this PlaneSurface after assignment

virtual double pathCorrection(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const final

Method that calculates the correction due to incident angle.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position (ignored for PlaneSurface)

• direction – global 3D momentum direction (ignored for PlaneSurface)

Returns:

a double representing the scaling factor

virtual Polyhedron polyhedronRepresentation(const GeometryContext &gctx, unsigned int quarterSegments) const override

Return a Polyhedron for the surfaces.

Note

for planar surfaces without curved segments quarterSegments is ignored

Parameters:

• gctx – The current geometry context object, e.g. alignment

• quarterSegments – is the number of segments used to describe curved segments in a quarter of the phi range. If it is 1, then only the extrema points in phi are inserted next to the segment corners.

Returns:

A list of vertices and a face/facett description of it

RotationMatrix3 referenceFrame(const GeometryContext &gctx) const

Return method for the reference frame This is the frame in which the covariance matrix is defined (specialized by all surfaces)

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

RotationMatrix3 which defines the three axes of the measurement frame

RotationMatrix3 referenceFrame(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Return method for the reference frame This is the frame in which the covariance matrix is defined (specialized by all surfaces)

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position - considered to be on surface but not inside bounds (check is done)

• direction – global 3D momentum direction (optionally ignored)

Returns:

RotationMatrix3 which defines the three axes of the measurement frame

virtual Vector3 referencePosition(const GeometryContext &gctx, AxisDirection aDir) const final

The axis position is the position calculated for a certain axis type.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• aDir – is the axis direction of reference position request

Returns:

position that can be used for this axis

virtual SurfaceType type() const override

Return the surface type.

Returns:

Surface type identifier

template<StepperConcept stepper_t, NavigatorConcept navigator_t = VoidNavigator>
class Propagator : public std::conditional_t<SupportsBoundParameters_v<stepper_t>, detail::BasePropagatorHelper<Propagator<stepper_t, VoidNavigator>>, detail::PropagatorStub>

Propagator for particles (optionally in a magnetic field)

The Propagator works with a state objects given at function call This state object contains the thread local state objects

• Navigator::state_type for object navigation and screen output

• Stepper::state_type state for the actual transport caching (pos,dir,field)

This Propagator class serves as high-level steering code for propagating track parameters. The actual implementation of the propagation has to be implemented in the stepper_t object, which has to provide the following:

• a function for performing a single propagation step

• a type mapping for: initial track parameter type -> type of final track parameters

• a type mapping for: (initial track parameter type and destination surface type) -> type of final track parameters

• a type mapping for: initial track parameter type -> type of internal state object

• a type mapping for: (initial track parameter type and destination surface type) -> type of internal state object

Template Parameters:

• stepper_t – Type of stepper implementation of the propagation

• naviagor_t – Type of the navigator (optional)

Public Types

using Navigator = navigator_t

Type of the navigator in use.

using NavigatorOptions = typename Navigator::Options

Type of the navigator options.

using NavigatorState = typename Navigator::State

Type of the navigator state.

template<typename actor_list_t = ActorList<>>
using Options = PropagatorOptions<StepperOptions, NavigatorOptions, actor_list_t>

Type of the propagator options with actor list.

template<typename propagator_options_t>
using ResultType = typename result_type_helper<propagator_options_t>::type

Type of the propagation result derived from the propagator options.

Template Parameters:

propagator_options_t – Type of the propagator options

template<typename propagator_options_t>
using State = typename state_type_helper<propagator_options_t>::type

Type of the propagation state derived from the propagator options.

Template Parameters:

propagator_options_t – Type of the propagator options

using Stepper = stepper_t

Type of the stepper in use.

using StepperOptions = typename Stepper::Options

Type of the stepper options.

using StepperState = typename Stepper::State

Type of the stepper state.

Public Functions

inline explicit Propagator(Stepper stepper, Navigator navigator = Navigator(), std::shared_ptr<const Logger> _logger = getDefaultLogger("Propagator", Acts::Logging::INFO))

Constructor from implementation object.

Parameters:

• stepper – The stepper implementation is moved to a private member

• navigator – The navigator implementation, moved to a private member

• _logger – a logger instance

template<typename propagator_state_t, typename path_aborter_t = PathLimitReached>
Result<void> initialize(propagator_state_t &state, const BoundParameters &start) const

Initialize the propagator state.

This function initializes the propagator state for a new propagation.

Template Parameters:

• propagator_state_t – Type of the propagator state object

• path_aborter_t – The path aborter type to be added

Parameters:

• state – [inout] The propagator state object

• start – [in] Initial track parameters to propagate

Returns:

Indication if the initialization was successful

template<typename propagator_state_t, typename propagator_options_t>
Result<ResultType<propagator_options_t>> makeResult(propagator_state_t state, Result<void> result, const propagator_options_t &options, bool createFinalParameters, const Surface *target = nullptr) const

Builds the propagator result object.

This function creates the propagator result object from the propagator state object. The result is passed to pipe a potential error from the propagation call. The options are used to determine the type of the result object. The createFinalParameters flag is used to determine if the result should contain final track parameters.

Template Parameters:

• propagator_state_t – Type of the propagator state object

• propagator_options_t – Type of the propagator options

Parameters:

• state – [in] Propagator state object

• result – [in] Result of the propagation

• options – [in] Propagation options

• createFinalParameters – [in] Whether to produce parameters at the end of the propagation

• target – [in] Surface to be used for the final parameters, if createFinalParameters is true If nullptr, the current surface of the navigator will be used

Returns:

Propagation result

template<typename propagator_options_t, typename path_aborter_t = PathLimitReached>
auto makeState(const propagator_options_t &options) const

Builds the propagator state object.

This function creates the propagator state object from the initial track parameters and the propagation options.

Template Parameters:

• propagator_options_t – Type of the propagator options

• path_aborter_t – The path aborter type to be added

Parameters:

options – [in] Propagation options

Returns:

Propagator state object

template<typename propagator_options_t, typename target_aborter_t = SurfaceReached, typename path_aborter_t = PathLimitReached>
auto makeState(const Surface &target, const propagator_options_t &options) const

Builds the propagator state object.

This function creates the propagator state object from the initial track parameters, the target surface, and the propagation options.

Template Parameters:

• propagator_options_t – Type of the propagator options

• target_aborter_t – The target aborter type to be added

• path_aborter_t – The path aborter type to be added

Parameters:

• target – [in] Target surface of to propagate to

• options – [in] Propagation options

Returns:

Propagator state object

inline const Navigator &navigator() const

Access to the navigator instance.

Returns:

Const reference to the navigator

template<typename propagator_options_t, typename path_aborter_t = PathLimitReached>
Result<ResultType<propagator_options_t>> propagate(const BoundParameters &start, const propagator_options_t &options, bool createFinalParameters = true) const

Propagate track parameters.

This function performs the propagation of the track parameters using the internal stepper implementation, until at least one abort condition is fulfilled or the maximum number of steps/path length provided in the propagation options is reached.

Template Parameters:

• propagator_options_t – Type of the propagator options

• path_aborter_t – The path aborter type to be added

Parameters:

• start – [in] initial track parameters to propagate

• options – [in] Propagation options, type Options<,>

• createFinalParameters – [in] Whether to produce parameters at the end of the propagation

Returns:

Propagation result containing the propagation status, final track parameters, and output of actions (if they produce any)

template<typename propagator_options_t, typename target_aborter_t = SurfaceReached, typename path_aborter_t = PathLimitReached>
Result<ResultType<propagator_options_t>> propagate(const BoundParameters &start, const Surface &target, const propagator_options_t &options) const

Propagate track parameters - User method.

This function performs the propagation of the track parameters according to the internal implementation object until at least one abort condition is fulfilled, the destination surface is hit or the maximum number of steps/path length as given in the propagation options is reached.

Template Parameters:

• propagator_options_t – Type of the propagator options

• target_aborter_t – The target aborter type to be added

• path_aborter_t – The path aborter type to be added

Parameters:

• start – [in] Initial track parameters to propagate

• target – [in] Target surface of to propagate to

• options – [in] Propagation options

Returns:

Propagation result containing the propagation status, final track parameters, and output of actions (if they produce any)

template<typename propagator_state_t>
Result<void> propagate(propagator_state_t &state) const

Propagate track parameters.

This function performs the propagation of the track parameters according to the internal implementation object until at least one abort condition is fulfilled, the destination surface is hit or the maximum number of steps/path length as given in the propagation options is reached.

Note

Does not (yet) convert into the return_type of the propagation

Template Parameters:

propagator_state_t – Type of the propagator state with options

Parameters:

state – [inout] the propagator state object

Returns:

Propagation result

inline const Stepper &stepper() const

Access to the stepper instance.

Returns:

Const reference to the stepper

template<typename BinningType>
class ProtoSurfaceMaterialT : public Acts::ISurfaceMaterial

proxy to SurfaceMaterial hand over BinUtility or other suitable binning description

The ProtoSurfaceMaterial class acts as a proxy to the SurfaceMaterial to mark the layers and surfaces on which the material should be mapped on at construction time of the geometry and to hand over the granularity of of the material map with the bin Utility.

Public Functions

ProtoSurfaceMaterialT() = default

Constructor without binningType - homogeneous material.

inline explicit ProtoSurfaceMaterialT(const BinningType &binning, MappingType mappingType = MappingType::Default)

Constructor with BinningType.

Parameters:

• binning – a binning description for the material map binning

• mappingType – is the type of surface mapping associated to the surface

ProtoSurfaceMaterialT(const ProtoSurfaceMaterialT<BinningType> &smproxy) = default

Copy constructor.

Parameters:

smproxy – The source proxy

ProtoSurfaceMaterialT(ProtoSurfaceMaterialT<BinningType> &&smproxy) noexcept = default

Copy move constructor.

Parameters:

smproxy – The source proxy

~ProtoSurfaceMaterialT() override = default

Destructor.

inline const BinningType &binning() const

Return the BinUtility.

Returns:

Reference to the binning

inline virtual const MaterialSlab &materialSlab(const Vector2&) const final

Return method for full material description of the Surface - from local coordinates.

Returns:

will return dummy material

const MaterialSlab &materialSlab(const Vector2 &lp) const = 0

Return method for full material description of the Surface.

• from local coordinate on the surface

Parameters:

lp – is the local position used for the (eventual) lookup

Returns:

const MaterialSlab

MaterialSlab materialSlab(const Vector2 &lp, Direction pDir, MaterialUpdateMode mode) const

Return method for fully scaled material description of the Surface.

• from local coordinate on the surface

Parameters:

• lp – is the local position used for the (eventual) lookup

• pDir – is the positive direction through the surface

• mode – is the material update directive

Returns:

MaterialSlab

inline virtual const MaterialSlab &materialSlab(const Vector3&) const final

Return method for full material description of the Surface - from the global coordinates.

Returns:

will return dummy material

const MaterialSlab &materialSlab(const Vector3 &gp) const = 0

Return method for full material description of the Surface.

• from the global coordinates

Parameters:

gp – is the global position used for the (eventual) lookup

Returns:

const MaterialSlab

MaterialSlab materialSlab(const Vector3 &gp, Direction pDir, MaterialUpdateMode mode) const

Return method for full material description of the Surface.

• from the global coordinates

Parameters:

• gp – is the global position used for the (eventual) lookup

• pDir – is the positive direction through the surface

• mode – is the material update directive

Returns:

MaterialSlab

ProtoSurfaceMaterialT<BinningType> &operator=(const ProtoSurfaceMaterialT<BinningType> &smproxy) = default

Assignment operator.

Parameters:

smproxy – The source proxy

Returns:

Reference to this object

ProtoSurfaceMaterialT<BinningType> &operator=(ProtoSurfaceMaterialT<BinningType> &&smproxy) noexcept = default

Assignment move operator.

Parameters:

smproxy – The source proxy

Returns:

Reference to this object

inline virtual ProtoSurfaceMaterialT<BinningType> &scale(double) final

Scale operation - dummy implementation.

Returns:

Reference to this object

inline virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream, to be overloaded by child classes.

Parameters:

sl – is the output stream

Returns:

The output stream

class RadialBounds : public Acts::DiscBounds

Class to describe the bounds for a planar DiscSurface.

By providing an argument for hphisec, the bounds can be restricted to a phi-range around the center position.

Public Types

enum BoundValues

Enumeration for the bound values.

Values:

enumerator eMinR

enumerator eMaxR

enumerator eHalfPhiSector

enumerator eAveragePhi

enumerator eSize

Public Functions

inline explicit RadialBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor from array values.

Parameters:

values – The bound values

inline explicit RadialBounds(double minR, double maxR, double halfPhi = std::numbers::pi, double avgPhi = 0.) noexcept(false)

Constructor for full disc of symmetric disc around phi=0.

Parameters:

• minR – The inner radius (0 for full disc)

• maxR – The outer radius

• halfPhi – The half opening angle (Pi for full angular coverage)

• avgPhi – The average phi for the disc/ring sector

inline virtual double binningValuePhi() const final

Return a reference phi value for binning.

Returns:

Average phi value used as binning reference

inline virtual double binningValueR() const final

Return a reference radius for binning.

Returns:

Average radius value used as binning reference

virtual SquareMatrix2 boundToCartesianJacobian(const Vector2 &lposition) const final

Computes the bound to cartesian jacobian at a given local position.

Parameters:

lposition – is the local position at which the jacobian is computed

Returns:

the bound to cartesian jacobian

virtual SquareMatrix2 boundToCartesianMetric(const Vector2 &lposition) const final

Computes the bound to cartesian metric at a given local position.

Parameters:

lposition – is the local position at which the metric is computed

Returns:

the bound to cartesian metric

virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Note

For RadialBounds: returns ((rMin + rMax)/2, averagePhi) in polar coordinates

Returns:

Vector2 representing the center position in local coordinates

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

inline virtual bool coversFullAzimuth() const final

Returns true for full phi coverage.

Returns:

True if bounds cover full azimuthal range (2π), false otherwise

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

The boundary value corresponding to the requested parameter

virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

inline virtual bool insideRadialBounds(double R, double tolerance = 0.) const final

Checks if this is inside the radial coverage given the a tolerance.

Parameters:

• R – Radius value to check

• tolerance – Tolerance for the boundary check

Returns:

True if radius is within radial bounds considering tolerance

inline virtual bool isCartesian() const final

Check if the bound coordinates are cartesian.

Returns:

true if the bound coordinates are cartesian

inline virtual double rMax() const final

Return method for outer Radius.

Returns:

Maximum radius value of the bounds

inline virtual double rMin() const final

Return method for inner Radius.

Returns:

Minimum radius value of the bounds

virtual std::ostream &toStream(std::ostream &sl) const final

Outstream operator.

Parameters:

sl – is the ostream to be dumped into

Returns:

Reference to the output stream for chaining

inline virtual BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

the bounds type

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

class RectangleBounds : public Acts::PlanarBounds

Bounds for a rectangular, planar surface - it can be used to for rectangles that are symmetrically centered around (0./0.) and for generic shifted rectangles

Public Types

enum BoundValues

Enumeration for the bound values.

Values:

enumerator eMinX

enumerator eMinY

enumerator eMaxX

enumerator eMaxY

enumerator eSize

Public Functions

inline explicit RectangleBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor - from fixed size array - generic.

Parameters:

values – The parameter values

inline RectangleBounds(const Vector2 &min, const Vector2 &max) noexcept(false)

Constructor - from min/max - generic.

Parameters:

• min – The left bottom corner

• max – The right top corning

inline RectangleBounds(double halfX, double halfY) noexcept(false)

Constructor with halflength in x and y - symmetric.

Parameters:

• halfX – halflength in X

• halfY – halflength in Y

virtual const RectangleBounds &boundingBox() const final

Bounding box parameters.

Returns:

rectangle bounds for a bounding box

virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Note

For RectangleBounds: returns the geometric center (min + max) / 2

Returns:

Vector2 representing the center position in local coordinates

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

The requested bound value

inline double halfLengthX() const

Access to the half length in X.

Returns:

Half the width of the rectangle in X direction

inline double halfLengthY() const

Access to the half length in Y.

Returns:

Half the width of the rectangle in Y direction

virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

inline const Vector2 &max() const

Get the max vertex defining the bounds.

Returns:

The max vertex

inline const Vector2 &min() const

Get the min vertex defining the bounds.

Returns:

The min vertex

virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream.

Parameters:

sl – is the ostream for the dump

Returns:

Reference to the output stream after writing

inline virtual BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

the bounds type

virtual std::vector<double> values() const final

Access method for bound values, this is a dynamically sized vector containing the parameters needed to describe these bounds.

Returns:

of the stored values for this SurfaceBounds object

virtual std::vector<Vector2> vertices(unsigned int quarterSegments = 0u) const final

Return the vertices.

Note

the number of segments is ignored in this representation

Parameters:

quarterSegments – is the number of segments used to describe curved segments in a quarter of the phi range.

Returns:

vector for vertices in 2D

class RegularSurface : public Acts::Surface

A physical surface which does not depend on the direction you look at it from.

As such it narrows the interface of Surface and allows inspection without providing a global position and direction.

Subclassed by Acts::ConeSurface, Acts::CylinderSurface, Acts::DiscSurface, Acts::PlaneSurface

Public Functions

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const final

Convert a global position to a local one this is the most generic interface, which is implemented by all surfaces.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be converted

• direction – is the direction of the local position (ignored for RegularSurface)

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, double tolerance = s_onSurfaceTolerance) const = 0

Convert a global position to a local one.

Note

The position is required to be on-surface, which is indicated by the Result return value.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position to be converted

• tolerance – is the tolerance for the on-surface check

Returns:

Result type containing local position by value

bool isOnSurface(const GeometryContext &gctx, const Vector3 &position, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::None(), double tolerance = s_onSurfaceTolerance) const

The geometric onSurface method.

Geometrical check whether position is on Surface

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global position to be evaludated

• boundaryTolerance – BoundaryTolerance directive for this onSurface check

• tolerance – optional tolerance within which a point is considered on surface

Returns:

boolean indication if operation was successful

bool isOnSurface(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::None(), double tolerance = s_onSurfaceTolerance) const

The geometric onSurface method.

Geometrical check whether position is on Surface

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global position to be evaludated

• direction – global momentum direction (required for line-type surfaces)

• boundaryTolerance – BoundaryTolerance directive for this onSurface check

• tolerance – optional tolerance within which a point is considered on surface

Returns:

boolean indication if operation was successful

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Local to global transformation.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

Returns:

The global position by value

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const final

Local to global transformation.

This is the most generic interface, which is implemented by all surfaces.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

• direction – global 3D momentum direction (ignored for RegularSurface)

Returns:

The global position by value

virtual Vector3 normal(const GeometryContext &gctx, const Vector2 &lposition) const = 0

Calculate the normal vector of the surface This overload requires an on-surface local position.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – is the local position where the normal vector is constructed

Returns:

normal vector by value

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const final

Calculate the normal vector of the surface This overload is fully generic, fulfills the Surface interface and accepts a global position and a direction.

For RegularSurface this is equivalent to the normal overload, ignoring the direction

Parameters:

• gctx – The current geometry context object, e.g. alignment

• pos – is the global position where the normal vector is constructed

• direction – is the direction of the normal vector (ignored for RegularSurface)

Returns:

Normal vector at the given position

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &position) const = 0

Calculate the normal vector of the surface This overload accepts a global position.

Parameters:

• position – is the global position where the normal vector is constructed

• gctx – The current geometry context object, e.g. alignment

Returns:

normal vector by value

explicit Surface(const GeometryContext &gctx, const Surface &other, const Transform3 &shift) noexcept

Copy constructor with optional shift.

Note

copy construction invalidates the association to detector element and layer

Parameters:

• gctx – The current geometry context object, e.g. alignment

• other – Source surface for copy

• shift – Additional transform applied as: shift * transform

Surface(const Surface &other) noexcept = default

Copy constructor.

Note

copy construction invalidates the association to detector element and layer

Parameters:

other – Source surface for copy.

explicit Surface(const SurfacePlacementBase &placement) noexcept

Constructor from SurfacePlacement: Element proxy.

Note

The Surface does not take any ownership over the SurfacePlacementBase it is expected that the user ensures the life-time of the SurfacePlacementBase and that the Surface is actually owned by the SurfacePlacementBase instance

Parameters:

placement – Reference to the surface placement

explicit Surface(const Transform3 &transform = Transform3::Identity())

Constructor with Transform3 as a shared object.

Note

also acts as default constructor

Parameters:

transform – Transform3 positions the surface in 3D global space

template<typename T, typename E = std::error_code>
class Result

Class which encapsulates either a valid result, or an error.

Template Parameters:

• T – The valid result value

• E – The error, defaults to std::error_code

Public Types

using ErrorType = E

Type alias for the error type contained in failed result.

using ValueType = T

Type alias for the value type contained in successful result.

Public Functions

Result() = delete

Default construction is disallowed.

Result(const Result<T, E> &other) = delete

Copy construction is disallowed.

inline Result(Result<T, E> &&other) noexcept

Move construction is allowed.

Parameters:

other – The other result instance to move from

template<typename T2> inline  Result (T2 value) noexcept requires(!std

Constructor from arbitrary value This constructor allows construction from any value.

This constructor is only enabled if T and E are unambiguous, meaning they cannot be implicitly converted and there is T cannot be constructed from E and vice-versa. This means that when this is invoked, the value can be propagated to the underlying variant, and the assignment will be correct, and error will be an error, and a value will be a value.

Note

If T and E are ambiguous, use the success and failure static factory methods.

Template Parameters:

T2 – Type of the potential assignment

Parameters:

value – The potential value, could be an actual valid value or an error.

inline E error() && noexcept

Returns the error by-value.

Note

If res.ok() this method will abort (noexcept)

Returns:

The error

inline E &error() & noexcept

Returns a reference to the error stored in the result.

Note

If res.ok() this method will abort (noexcept)

Returns:

Reference to the error

inline const E &error() const & noexcept

Returns a reference to the error stored in the result.

Note

If res.ok() this method will abort (noexcept)

Returns:

Reference to the error

inline bool ok() const noexcept

Checks whether this result contains a valid value, and no error.

Returns:

bool Whether result contains an error or not.

inline const T &operator*() const noexcept

Returns a reference into the variant to the valid value.

Note

If !res.ok(), this method will abort (noexcept)

Returns:

Reference to value stored in the variant.

inline T &operator*() noexcept

Returns a reference into the variant to the valid value.

Note

If !res.ok(), this method will abort (noexcept)

Returns:

Reference to value stored in the variant.

inline const T *operator->() const noexcept

Allows to access members of the stored object with res->foo similar to std::optional.

Note

If !res.ok(), this method will abort (noexcept)

Returns:

Pointer to value stored in the variant.

inline T *operator->() noexcept

Allows to access members of the stored object with res->foo similar to std::optional.

Note

If !res.ok(), this method will abort (noexcept)

Returns:

Pointer to value stored in the variant.

Result<T, E> &operator=(const Result<T, E> &other) = delete

Assignment is disallowed.

inline Result<T, E> &operator=(Result<T, E> &&other) noexcept

Move assignment is allowed.

Parameters:

other – The other result instance, rvalue reference

Returns:

The assigned instance

template<typename T2> inline Result< T, E > & operator= (T2 value) noexcept requires(!std

Assignment operator from arbitrary value This operator allows construction from any value.

The same rules as for the Result(T2 value) constructor apply.

Template Parameters:

T2 – Type of the potential assignment

Parameters:

value – The potential value, could be an actual valid value or an error.

Returns:

The assigned instance

inline T &value() &

Retrieves the valid value from the result object.

Note

This is the lvalue version, returns a reference to the value

Returns:

The valid value as a reference

inline const T &value() const &

Retrieves the valid value from the result object.

Note

This is the lvalue version, returns a reference to the value

Returns:

The valid value as a reference

template<typename U> inline std::conditional_t< std::is_reference_v< U >, const T &, T > value_or (U &&v) const &requires(std

Retrieves the valid value from the result object, or returns a default value if no valid value exists.

Note

This is the lvalue version.

Note

This function always returns by value.

Parameters:

v – [in] The default value to use if no valid value exists.

Returns:

Either the valid value, or the given substitute.

Public Members

template<typename C> auto transform(C &&callable) const &requires std void checkValueAccess () const

Transforms the value contained in this result.

Applying a function f to a valid value x returns f(x), while applying f to an invalid value returns another invalid value.

Applying a function f to a valid value x returns f(x), while applying f to an invalid value returns another invalid value.

This function takes a function f and, if this result contains a valid value x, returns f(x). If the type of x is T, then f is expected to accept type T and return Result<U>. In this case, transform would return the unhelpful type Result<Result<U>>, so and_then strips away the outer layer to return Result<U>. If the value is invalid, this returns an invalid value in Result<U>.

This function takes a function f and, if this result contains a valid value x, returns f(x). If the type of x is T, then f is expected to accept type T and return Result<U>. In this case, transform would return the unhelpful type Result<Result<U>>, so and_then strips away the outer layer to return Result<U>. If the value is invalid, this returns an invalid value in Result<U>.

Note

This is the lvalue version.

Note

This functions is fmap on the functor in A of Result<A, E>.

Note

This is the rvalue version.

Note

This functions is fmap on the functor in A of Result<A, E>.

Note

This is the lvalue version.

Note

This functions is >>= on the functor in A of Result<A, E>.

Note

This is the rvalue version.

Note

This functions is >>= on the functor in A of Result<A, E>.

Param callable:

[in] The transformation function to apply.

Return:

The modified valid value if exists, or an error otherwise. Transforms the value contained in this result.

Param callable:

[in] The transformation function to apply.

Return:

The modified valid value if exists, or an error otherwise. Bind a function to this result monadically.

Param callable:

[in] The transformation function to apply.

Return:

The modified valid value if exists, or an error otherwise. Bind a function to this result monadically.

Param callable:

[in] The transformation function to apply.

Return:

The modified valid value if exists, or an error otherwise.

Public Static Functions

static inline Result<T, E> failure(E error)

Static helper factory which forces assignment as an error.

Parameters:

error – The error to assign. Will not be converted to T.

Returns:

Initialized result object

static inline Result<T, E> success(T value)

Static helper factory which forces assignment as valid value.

Parameters:

value – The valid value to assign. Will not be converted to E.

Returns:

Initialized result object

template<typename external_space_point_t>
class SeedFilter

Filter seeds at various stages with the currently available information.

Public Functions

explicit SeedFilter(const SeedFilterConfig &config, IExperimentCuts<external_space_point_t> *expCuts = nullptr)

Constructor with configuration and optional experimental cuts.

Parameters:

• config – Seed filter configuration

• expCuts – Optional experimental cuts (defaults to nullptr)

explicit SeedFilter(const SeedFilterConfig &config, std::unique_ptr<const Logger> logger, IExperimentCuts<external_space_point_t> *expCuts = nullptr)

Constructor with configuration, logger, and optional experimental cuts.

Parameters:

• config – Seed filter configuration

• logger – Logger for output messages

• expCuts – Optional experimental cuts (defaults to nullptr)

template<typename collection_t>
void filterSeeds_1SpFixed(SpacePointMutableData &mutableData, CandidatesForMiddleSp<const external_space_point_t> &candidatesCollector, collection_t &outputCollection) const

Filter seeds once all seeds for one middle space point have been created.

Parameters:

• mutableData – Container for mutable variables used in the seeding

• candidatesCollector – collection of seed candidates

• outputCollection – Output container for the seeds for all seeds with the same middle space point

template<typename collection_t>
void filterSeeds_1SpFixed(SpacePointMutableData &mutableData, std::vector<typename CandidatesForMiddleSp<const external_space_point_t>::value_type> &candidates, const std::size_t numQualitySeeds, collection_t &outputCollection) const

Filter seeds once all seeds for one middle space point have been created.

Parameters:

• mutableData – Container for mutable variables used in the seeding

• candidates – collection of seed candidates

• numQualitySeeds – number of high quality seeds in seed confirmation

• outputCollection – Output container for the seeds for all seeds with the same middle space point

void filterSeeds_2SpFixed(const SpacePointMutableData &mutableData, const external_space_point_t &bottomSp, const external_space_point_t &middleSp, const std::vector<const external_space_point_t*> &topSpVec, const std::vector<float> &invHelixDiameterVec, const std::vector<float> &impactParametersVec, SeedFilterState &seedFilterState, CandidatesForMiddleSp<const external_space_point_t> &candidatesCollector) const

Create Seeds for the all seeds with the same bottom and middle space point and discard all others.

Parameters:

• mutableData – Container for mutable variables used in the seeding

• bottomSp – fixed bottom space point

• middleSp – fixed middle space point

• topSpVec – vector containing all space points that may be compatible with both bottom and middle space point

• invHelixDiameterVec – vector containing 1/(2*r) values where r is the helix radius

• impactParametersVec – vector containing the impact parameters

• seedFilterState – holds quantities used in seed filter

• candidatesCollector – container for the seed candidates

inline const IExperimentCuts<external_space_point_t> *getExperimentCuts() const

Get the experimental cuts pointer.

Returns:

Pointer to experimental cuts (may be nullptr)

inline const SeedFilterConfig getSeedFilterConfig() const

Get the seed filter configuration.

Returns:

Copy of the seed filter configuration

Warning

doxygenclass: Cannot find class “Acts::SinglyChargedParticleHypothesis” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

class SolenoidBField : public Acts::MagneticFieldProvider

Analytical solenoid magnetic field implementation.

Concept

This class implements a multi-coil solenoid magnetic field. On every call, the field is evaluated at that exact position. The field has radially symmetry, the field vectors point in +z direction. The config exposes a target field value in the center. This value is used to empirically determine a scale factor which reproduces this field value in the center.

Implementation

• \(E_1(k^2)\) = complete elliptic integral of the 1st kind

• \(E_2(k^2)\) = complete elliptic integral of the 2nd kind

  \(E_1(k^2)\) and \(E_2(k^2)\) are usually indicated as \(K(k^2)\) and \(E(k^2)\) in literature, respectively

  \[ E_1(k^2) = \int_0^{\pi/2} \left( 1 - k^2 \sin^2{\theta} \right )^{-1/2} \mathrm{d}\theta \]
  \[ E_2(k^2) = \int_0^{\pi/2}\sqrt{1 - k^2 \sin^2{\theta}} \mathrm{d}\theta \]

  \(k^2\) is a function of the point \((r, z)\) and of the radius of the coil \(R\)

  \[ k^2 = \frac{4Rr}{(R+r)^2 + z^2} \]

Using these, you can evaluate the two components \(B_r\) and \(B_z\) of the magnetic field:

\[ B_r(r, z) = \frac{\mu_0 I}{4\pi} \frac{kz}{\sqrt{Rr^3}} \left[ \left(\frac{2-k^2}{2-2k^2}\right)E_2(k^2) - E_1(k^2) \right ] \]

\[ B_z(r,z) = \frac{\mu_0 I}{4\pi} \frac{k}{\sqrt{Rr}} \left[ \left( \frac{(R+r)k^2-2r}{2r(1-k^2)} \right ) E_2(k^2) + E_1(k^2) \right ] \]

In the implementation the factor of \((\mu_0\cdot I)\) is defined to be a scaling factor. It is evaluated and defined as the magnetic field in the center of the coil, i.e. the scale set in Acts::SolenoidBField::Config::bMagCenter.

Note

A configuration of

SolenoidBField::Config cfg;
cfg.length = 5.8_m;
cfg.radius = (2.56 + 2.46) * 0.5 * 0.5_m;
cfg.nCoils = 1154;
cfg.bMagCenter = 2_T;
SolenoidBField bField(cfg);

roughly corresponds to the solenoid wrapping the Inner Detector in ATLAS!

Warning

As the evaluation of \(E_1(k^2)\) and \(E_2(k^2)\) is slow. The Acts::InterpolatedBFieldMap easily outperforms Acts::SolenoidBField. A helper is provided that builds a map from the analytical implementation and is much faster to lookup: Acts::solenoidFieldMap.

Public Functions

explicit SolenoidBField(Config config)

the constructor with a shared pointer

Note

since it is a shared field, we enforce it to be const

Template Parameters:

bField – is the shared BField to be stored

Parameters:

config – Configuration struct containing solenoid parameters

Vector2 getField(const Vector2 &position) const

Retrieve magnetic field value in local (r,z) coordinates.

Parameters:

position – [in] local 2D position

Returns:

Magnetic field vector in local (r,z) coordinates

Vector3 getField(const Vector3 &position) const

Get the B field at a position.

Parameters:

position – The position to query at

Returns:

Magnetic field vector in global coordinates

virtual Result<Vector3> getField(const Vector3 &position, MagneticFieldProvider::Cache &cache) const override

Retrieve magnetic field value at a given location.

Requires an instance of Acts::MagneticFieldProvider::Cache created through makeCache.

Parameters:

• position – [in] global 3D position for the lookup

• cache – [inout] Field provider specific cache object

Returns:

magnetic field vector at given position

virtual MagneticFieldProvider::Cache makeCache(const MagneticFieldContext &mctx) const override

Make an opaque cache for the magnetic field.

Instructs the specific implementation to generate a Acts::MagneticFieldProvider::Cache instance for magnetic field lookup.

Parameters:

mctx – The magnetic field context to generate cache for

Returns:

Cache The opaque cache object

struct Cache

Cache payload for magnetic field evaluation.

Public Functions

inline explicit Cache(const MagneticFieldContext&)

Constructor with magnetic field context.

struct Config

Config struct for the SolenoidBfield.

Public Members

double bMagCenter

The target magnetic field strength at the center.

This will be used to scale coefficients

double length

Extent of the solenoid in z.

It goes from -length/2 to +length/2 by convention

std::size_t nCoils

The number of coils that make up the solenoid.

double radius

Radius at which the coils are located.

class SourceLink

Type-erased source link wrapper.

Public Functions

SourceLink(const SourceLink &other) = default

Copy constructor.

Parameters:

other – Source link to copy from

SourceLink(SourceLink &&other) = default

Move constructor.

Parameters:

other – Source link to move from

template<typename T> inline explicit  SourceLink (T &&upstream) requires(!std

Constructor from concrete source link.

Template Parameters:

T – The source link type

Parameters:

upstream – The upstream source link to store

template<typename T>
inline T &get()

Concrete source link class getter.

Template Parameters:

T – The source link type to retrieve

Returns:

Reference to the stored source link

template<typename T>
inline const T &get() const

Concrete source link class getter, const version.

Template Parameters:

T – The source link type to retrieve

Returns:

Const reference to the stored source link

template<typename T>
inline T *getPtr()

Concrete source link pointer getter.

Template Parameters:

T – The source link type to retrieve

Returns:

Pointer to the stored source link, or nullptr if the type doesn’t match or the SourceLink is empty

template<typename T>
inline const T *getPtr() const

Concrete source link pointer getter, const version.

Template Parameters:

T – The source link type to retrieve

Returns:

Const pointer to the stored source link, or nullptr if the type doesn’t match or the SourceLink is empty

SourceLink &operator=(const SourceLink &other) = default

Copy assignment operator.

Parameters:

other – Source link to copy from

Returns:

Reference to this source link

SourceLink &operator=(SourceLink &&other) = default

Move assignment operator.

Parameters:

other – Source link to move from

Returns:

Reference to this source link

class StraightLineStepper

straight line stepper based on Surface intersection

The straight line stepper is a simple navigation stepper to be used to navigate through the tracking geometry. It can be used for simple material mapping, navigation validation

Public Types

using BField = NullBField

Type alias for magnetic field (null field for straight line propagation)

using BoundParameters = BoundTrackParameters

Type alias for bound track parameters.

using BoundState = std::tuple<BoundParameters, Jacobian, double>

Type alias for bound state containing parameters, jacobian, and path length.

using Covariance = BoundMatrix

Type alias for covariance matrix.

using Jacobian = BoundMatrix

Type alias for transport jacobian matrix.

Public Functions

inline double absoluteMomentum(const State &state) const

Absolute momentum accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Absolute momentum magnitude

Result<BoundState> boundState(State &state, const Surface &surface, bool transportCov = true, const FreeToBoundCorrection &freeToBoundCorrection = FreeToBoundCorrection(false)) const

Create and return the bound state at the current position.

It does not check if the transported state is at the surface, this needs to be guaranteed by the propagator

Parameters:

• state – [in] State that will be presented as BoundState

• surface – [in] The surface to which we bind the state

• transportCov – [in] Flag steering covariance transport

• freeToBoundCorrection – [in] Correction for non-linearity effect during transform from free to bound

Returns:

A bound state:

• the parameters at the surface

• the stepwise jacobian towards it (from last bound)

• and the path length (from start - for ordering)

inline double charge(const State &state) const

Charge access.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Electric charge of the particle

BoundState curvilinearState(State &state, bool transportCov = true) const

Create and return a curvilinear state at the current position.

This creates a curvilinear state.

Parameters:

• state – [in] State that will be presented as CurvilinearState

• transportCov – [in] Flag steering covariance transport

Returns:

A curvilinear state:

• the curvilinear parameters at given position

• the stepweise jacobian towards it (from last bound)

• and the path length (from start - for ordering)

inline Vector3 direction(const State &state) const

Momentum direction accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Current normalized direction vector

inline Result<Vector3> getField(State&, const Vector3&) const

Get the field for the stepping, this gives back a zero field.

Returns:

Always returns zero magnetic field vector for straight-line propagation

inline double getStepSize(const State &state, ConstrainedStep::Type stype) const

Get the step size.

Parameters:

• state – [in] The stepping state (thread-local cache)

• stype – [in] The step size type to be returned

Returns:

Current step size for the specified constraint type

void initialize(State &state, const BoundParameters &par) const

Initialize the stepper state from bound track parameters.

Parameters:

• state – The stepper state to initialize

• par – The bound track parameters to initialize from

void initialize(State &state, const BoundVector &boundParams, const std::optional<BoundMatrix> &cov, ParticleHypothesis particleHypothesis, const Surface &surface) const

Initialize the stepper state from bound parameters and components.

Parameters:

• state – The stepper state to initialize

• boundParams – The bound parameter vector

• cov – Optional covariance matrix

• particleHypothesis – The particle hypothesis (mass, charge, etc.)

• surface – The reference surface

State makeState(const Options &options) const

Create a stepper state from propagation options.

Parameters:

options – The propagation options

Returns:

A new stepper state initialized with the provided options

inline Vector3 momentum(const State &state) const

Momentum accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Current momentum vector

inline std::string outputStepSize(const State &state) const

Output the Step Size - single component.

Parameters:

state – [in,out] The stepping state (thread-local cache)

Returns:

String representation of the current step size

inline const ParticleHypothesis &particleHypothesis(const State &state) const

Particle hypothesis.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Reference to the particle hypothesis used

inline Vector3 position(const State &state) const

Global particle position accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Current global position vector

inline bool prepareCurvilinearState(State &state) const

If necessary fill additional members needed for curvilinearState.

Compute path length derivatives in case they have not been computed yet, which is the case if no step has been executed yet.

Parameters:

state – [inout] The stepping state (thread-local cache)

Returns:

true if nothing is missing after this call, false otherwise.

inline double qOverP(const State &state) const

QoP direction accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Charge over momentum (q/p) value

inline void releaseStepSize(State &state, ConstrainedStep::Type stype) const

Release the Step size.

Parameters:

• state – [inout] The stepping state (thread-local cache)

• stype – [in] The step size type to be released

inline Result<double> step(State &state, Direction propDir, const IVolumeMaterial *material) const

Perform a straight line propagation step.

Note

The state contains the desired step size. It can be negative during backwards track propagation.

Parameters:

• state – [inout] State of the stepper

• propDir – is the direction of propagation

• material – is the optional volume material we are stepping through.

Returns:

the result of the step

inline double time(const State &state) const

Time access.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

The time coordinate from the free parameters vector

void transportCovarianceToBound(State &state, const Surface &surface, const FreeToBoundCorrection &freeToBoundCorrection = FreeToBoundCorrection(false)) const

Method for on-demand transport of the covariance to a new curvilinear frame at current position, or direction of the state - for the moment a dummy method.

Note

no check is done if the position is actually on the surface

Template Parameters:

surface_t – the surface type - ignored here

Parameters:

• state – [inout] The stepper state

• surface – [in] is the surface to which the covariance is forwarded to

• freeToBoundCorrection – [in] Correction for non-linearity effect during transform from free to bound

void transportCovarianceToCurvilinear(State &state) const

Method for on-demand transport of the covariance to a new curvilinear frame at current position, or direction of the state - for the moment a dummy method.

Parameters:

state – [inout] State of the stepper

void update(State &state, const FreeVector &freeParams, const BoundVector &boundParams, const Covariance &covariance, const Surface &surface) const

Method to update a stepper state to the some parameters.

Parameters:

• state – [inout] State object that will be updated

• freeParams – [in] Free parameters that will be written into state

• boundParams – [in] Corresponding bound parameters used to update jacToGlobal in state

• covariance – [in] Covariance that will be written into state

• surface – [in] The surface used to update the jacToGlobal

void update(State &state, const Vector3 &uposition, const Vector3 &udirection, double qop, double time) const

Method to update the stepper state.

Parameters:

• state – [inout] State object that will be updated

• uposition – [in] the updated position

• udirection – [in] the updated direction

• qop – [in] the updated qop value

• time – [in] the updated time value

inline void updateStepSize(State &state, const NavigationTarget &target, Direction direction, ConstrainedStep::Type stype) const

Update step size.

It checks the status to the reference surface & updates the step size accordingly

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• target – [in] The NavigationTarget

• direction – [in] The propagation direction

• stype – [in] The step size type to be set

inline void updateStepSize(State &state, double stepSize, ConstrainedStep::Type stype) const

Update step size - explicitly with a double.

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• stepSize – [in] The step size value

• stype – [in] The step size type to be set

inline IntersectionStatus updateSurfaceStatus(State &state, const Surface &surface, std::uint8_t index, Direction navDir, const BoundaryTolerance &boundaryTolerance, double surfaceTolerance, ConstrainedStep::Type stype, const Logger &logger = getDummyLogger()) const

Update surface status.

This method intersects the provided surface and update the navigation step estimation accordingly (hence it changes the state). It also returns the status of the intersection to trigger onSurface in case the surface is reached.

Parameters:

• state – [inout] The stepping state (thread-local cache)

• surface – [in] The surface provided

• index – [in] The surface intersection index

• navDir – [in] The navigation direction

• boundaryTolerance – [in] The boundary check for this status update

• surfaceTolerance – [in] Surface tolerance used for intersection

• stype – [in] The step size type to be set

• logger – [in] A logger instance

Returns:

Status of the intersection indicating whether surface was reached

struct Config

struct Options : public Acts::StepperPlainOptions

Configuration options for straight line propagation.

Public Functions

inline Options(const GeometryContext &gctx, const MagneticFieldContext &mctx)

Constructor from geometry and magnetic field contexts.

Parameters:

• gctx – The geometry context

• mctx – The magnetic field context

inline void setPlainOptions(const StepperPlainOptions &options)

Set plain stepper options.

Parameters:

options – The plain options to set

struct State

State for track parameter propagation.

Public Functions

inline explicit State(const Options &optionsIn)

Constructor from the initial bound track parameters.

Note

the covariance matrix is copied when needed

Parameters:

optionsIn – [in] The options for the stepper

Public Members

Covariance cov = Covariance::Zero()

Covariance matrix for track parameter uncertainties.

bool covTransport = false

Boolean to indicate if you need covariance transport.

FreeVector derivative = FreeVector::Zero()

The propagation derivative.

Jacobian jacobian = Jacobian::Identity()

The full jacobian of the transport entire transport.

BoundToFreeMatrix jacToGlobal = BoundToFreeMatrix::Zero()

Jacobian from local to the global frame.

FreeMatrix jacTransport = FreeMatrix::Identity()

Pure transport jacobian part from runge kutta integration.

std::size_t nSteps = 0

Total number of performed steps.

std::size_t nStepTrials = 0

Totoal number of attempted steps.

Options options

Configuration options for the stepper.

FreeVector pars = FreeVector::Zero()

Internal free vector parameters.

ParticleHypothesis particleHypothesis = ParticleHypothesis::pion()

Particle hypothesis.

double pathAccumulated = 0.

accumulated path length state

double previousStepSize = 0.

Previous step size for overstep estimation (ignored for straight line stepper)

StepperStatistics statistics

Statistics of the stepper.

ConstrainedStep stepSize

adaptive step size of the runge-kutta integration

class StrawSurface : public Acts::LineSurface

Class for a StrawSurface in the TrackingGeometry to describe dirft tube and straw like detectors.

Public Functions

inline virtual std::string name() const final

Return properly formatted class name for screen output */.

Returns:

String representation of the surface type name

virtual Polyhedron polyhedronRepresentation(const GeometryContext &gctx, unsigned int quarterSegments) const final

Return a Polyhedron for the surfaces.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• quarterSegments – is the number of segments used to describe curved segments in a quarter of the phi range. If it is 1, then only the extrema points in phi are inserted next to the segment corners.

Returns:

A list of vertices and a face/facett description of it

inline virtual SurfaceType type() const final

Return the surface type.

Returns:

Surface type identifier for straw surfaces

class Surface : public virtual Acts::GeometryObject, public std::enable_shared_from_this<Surface>

Abstract Base Class for tracking surfaces.

The Surface class builds the core of the Acts Tracking Geometry. All other geometrical objects are either extending the surface or are built from it.

Surfaces are either owned by Detector elements or the Tracking Geometry, in which case they are not copied within the data model objects.

Subclassed by Acts::LineSurface, Acts::RegularSurface

Public Types

enum SurfaceType

This enumerator simplifies the persistency & calculations, by saving a dynamic_cast, e.g.

for persistency

Values:

enumerator Cone

enumerator Cylinder

enumerator Disc

enumerator Perigee

enumerator Plane

enumerator Straw

enumerator Curvilinear

enumerator Other

Public Functions

~Surface() noexcept override

AlignmentToBoundMatrix alignmentToBoundDerivative(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const FreeVector &pathDerivative) const

The derivative of bound track parameters w.r.t.

alignment parameters of its reference surface (i.e. local frame origin in global 3D Cartesian coordinates and its rotation represented with extrinsic Euler angles)

Parameters:

• gctx – The current geometry context object, e.g. alignment change of alignment parameters

• position – global 3D position

• direction – global 3D momentum direction

• pathDerivative – is the derivative of free parameters w.r.t. path length

Returns:

Derivative of bound track parameters w.r.t. local frame alignment parameters

virtual AlignmentToPathMatrix alignmentToPathDerivative(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Calculate the derivative of path length at the geometry constraint or point-of-closest-approach w.r.t.

alignment parameters of the surface (i.e. local frame origin in global 3D Cartesian coordinates and its rotation represented with extrinsic Euler angles)

Note

Re-implementation is needed for surface whose intersection with track is not its local xy plane, e.g. LineSurface, CylinderSurface and ConeSurface

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Derivative of path length w.r.t. the alignment parameters

void assignIsSensitive(bool isSensitive)

Assign whether the surface is sensitive.

Parameters:

isSensitive – Boolean flag to set sensitivity

Throws:

logic_error – if the surface is associated to a detector element

void assignSurfaceMaterial(std::shared_ptr<const ISurfaceMaterial> material)

Assign the surface material description.

The material is usually derived in a complicated way and loaded from a framework given source. As various surfaces may share the same source this is provided by a shared pointer

Parameters:

material – Material description associated to this surface

void assignSurfacePlacement(const SurfacePlacementBase &placement)

Assign a placement object which may dynamically align the surface in space.

Parameters:

placement – Placement object defining the surface’s position

void assignThickness(double thick)

Assign the thickness of the surface in the orthogonal dimension.

Parameters:

thick – Thickness parameter to assign (>=0)

const Layer *associatedLayer() const

Return method for the associated Layer in which the surface is embedded.

Returns:

Layer by plain pointer, can be nullptr

void associateLayer(const Layer &lay)

Set Associated Layer Many surfaces can be associated to a Layer, but it might not be known yet during construction of the layer, this can be set afterwards.

Parameters:

lay – the assignment Layer by reference

virtual const SurfaceBounds &bounds() const = 0

Return method for SurfaceBounds.

Returns:

SurfaceBounds by reference

virtual BoundToFreeMatrix boundToFreeJacobian(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Calculate the jacobian from local to global which the surface knows best, hence the calculation is done here.

Note

In principle, the input could also be a free parameters vector as it could be transformed to a bound parameters. But the transform might fail in case the parameters is not on surface. To avoid the check inside this function, it takes directly the bound parameters as input (then the check might be done where this function is called).

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Jacobian from local to global

virtual Vector3 center(const GeometryContext &gctx) const

Return method for the surface center.

Note

the center is always recalculated in order to not keep a cache

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

center position by value

virtual Vector2 closestPointOnBoundary(const Vector2 &lposition, const SquareMatrix2 &metric) const

Calculates the closest point on the boundary of the surface to a given point in local coordinates.

Parameters:

• lposition – The local position to check

• metric – The metric to use for the calculation

Returns:

The closest point on the boundary of the surface

virtual double distanceToBoundary(const Vector2 &lposition) const

Calculates the distance to the boundary of the surface from a given point in local coordinates.

Parameters:

lposition – The local position to check

Returns:

The distance to the boundary of the surface

virtual FreeToBoundMatrix freeToBoundJacobian(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Calculate the jacobian from global to local which the surface knows best, hence the calculation is done here.

Note

It assumes the input free parameters is on surface, hence no onSurface check is done inside this function.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Jacobian from global to local

virtual FreeToPathMatrix freeToPathDerivative(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Calculate the derivative of path length at the geometry constraint or point-of-closest-approach w.r.t.

free parameters. The calculation is identical for all surfaces where the reference frame does not depend on the direction

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Derivative of path length w.r.t. free parameters

std::shared_ptr<Surface> getSharedPtr()

Retrieve a std::shared_ptr for this surface (non-const version)

Note

Will error if this was not created through the makeShared factory since it needs access to the original reference. In C++14 this is undefined behavior (but most likely implemented as a bad_weak_ptr exception), in C++17 it is defined as that exception.

Note

Only call this if you need shared ownership of this object.

Returns:

The shared pointer

std::shared_ptr<const Surface> getSharedPtr() const

Retrieve a std::shared_ptr for this surface (const version)

Note

Will error if this was not created through the makeShared factory since it needs access to the original reference. In C++14 this is undefined behavior, but most likely implemented as a bad_weak_ptr exception, in C++17 it is defined as that exception.

Note

Only call this if you need shared ownership of this object.

Returns:

The shared pointer

virtual Result<Vector2> globalToLocal(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, double tolerance = s_onSurfaceTolerance) const = 0

Global to local transformation Generalized global to local transformation for the surface types.

Since some surface types need the global momentum/direction to resolve sign ambiguity this is also provided

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position - considered to be on surface but not inside bounds (check is done)

• direction – global 3D momentum direction

• tolerance – optional tolerance within which a point is considered valid on surface

Returns:

a Result<Vector2> which can be !ok() if the operation fails

virtual bool insideBounds(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::None()) const

The insideBounds method for local positions.

Parameters:

• lposition – The local position to check

• boundaryTolerance – BoundaryTolerance directive for this onSurface check

Returns:

boolean indication if operation was successful

virtual MultiIntersection3D intersect(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::Infinite(), double tolerance = s_onSurfaceTolerance) const = 0

Straight line intersection schema from position/direction.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The position to start from

• direction – The direction at start

• boundaryTolerance – the BoundaryTolerance

• tolerance – the tolerance used for the intersection

Returns:

MultiIntersection3D intersection object

bool isAlignable() const

Returns whether the Surface is alignable.

Returns:

True if the surface is alignable

bool isOnSurface(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const BoundaryTolerance &boundaryTolerance = BoundaryTolerance::None(), double tolerance = s_onSurfaceTolerance) const

The geometric onSurface method.

Geometrical check whether position is on Surface

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global position to be evaludated

• direction – global momentum direction (required for line-type surfaces)

• boundaryTolerance – BoundaryTolerance directive for this onSurface check

• tolerance – optional tolerance within which a point is considered on surface

Returns:

boolean indication if operation was successful

bool isSensitive() const

Returns whether the Surface is sensitive.

Returns:

True if the surface is sensitive

virtual Matrix<2, 3> localCartesianToBoundLocalDerivative(const GeometryContext &gctx, const Vector3 &position) const = 0

Calculate the derivative of bound track parameters local position w.r.t.

position in local 3D Cartesian coordinates

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The position of the parameters in global

Returns:

Derivative of bound local position w.r.t. position in local 3D cartesian coordinates

virtual Vector3 localToGlobal(const GeometryContext &gctx, const Vector2 &lposition, const Vector3 &direction) const = 0

Local to global transformation Generalized local to global transformation for the surface types.

Since some surface types need the global momentum/direction to resolve sign ambiguity this is also provided

Parameters:

• gctx – The current geometry context object, e.g. alignment

• lposition – local 2D position in specialized surface frame

• direction – global 3D momentum direction

Returns:

The global position by value

const Transform3 &localToGlobalTransform(const GeometryContext &gctx) const

Return method for the surface Transform3 by reference In case a detector element is associated the surface transform is just forwarded to the detector element in order to keep the (mis-)alignment cache cetrally handled.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

the contextual transform

virtual std::string name() const = 0

Return properly formatted class name.

Returns:

The surface class name as a string

virtual Vector3 normal(const GeometryContext &gctx, const Vector3 &pos, const Vector3 &direction) const = 0

Return the surface normal at a given position and direction.

This method is fully generic, and valid for all surface types.

Note

For some surface types, the direction is ignored, but it is not safe to pass in a zero vector!

Parameters:

• gctx – The current geometry context object, e.g. alignment

• pos – The position at which to calculate the normal

• direction – The direction at which to calculate the normal

Returns:

The normal vector at the given position and direction

Surface &operator=(const Surface &other) noexcept = default

Assignment operator.

Note

copy construction invalidates the association to detector element and layer

Parameters:

other – Source surface for the assignment

Returns:

Reference to this surface after assignment

bool operator==(const Surface &other) const

Comparison (equality) operator The strategy for comparison is (a) first pointer comparison (b) then type comparison (c) then bounds comparison (d) then transform comparison.

Parameters:

other – source surface for the comparison

Returns:

True if surfaces are equal, false otherwise

virtual double pathCorrection(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const = 0

Calculation of the path correction for incident.

Note

The position is either ignored, or it is coerced to be on the surface, depending on the surface type.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position

• direction – global 3D momentum direction

Returns:

Path correction with respect to the nominal incident.

virtual Polyhedron polyhedronRepresentation(const GeometryContext &gctx, unsigned int quarterSegments = 2u) const = 0

Return a Polyhedron for surface objects.

Note

In order to symmetrize the code between sectoral and closed cylinders in case of closed cylinders, both (-pi, pi) are given as separate vertices

Note

An internal surface transform can invalidate the extrema in the transformed space

Parameters:

• gctx – The current geometry context object, e.g. alignment

• quarterSegments – The number of segemtns to approximate a 0.5*pi sector, which represents a quarter of the full circle

Returns:

A list of vertices and a face/facett description of it

virtual RotationMatrix3 referenceFrame(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Return method for the reference frame This is the frame in which the covariance matrix is defined (specialized by all surfaces)

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – global 3D position - considered to be on surface but not inside bounds (check is done)

• direction – global 3D momentum direction (optionally ignored)

Returns:

RotationMatrix3 which defines the three axes of the measurement frame

const ISurfaceMaterial *surfaceMaterial() const

Return method for the associated Material to this surface.

Returns:

SurfaceMaterial as plain pointer, can be nullptr

const std::shared_ptr<const ISurfaceMaterial> &surfaceMaterialSharedPtr() const

Return method for the shared pointer to the associated Material.

Returns:

SurfaceMaterial as shared_pointer, can be nullptr

const SurfacePlacementBase *surfacePlacement() const

Return the associated surface placement if there is any.

Returns:

Pointer to the surface placement, can be nullptr

double thickness() const

Return the thickness of the surface in the normal direction.

Returns:

The surface thickness

inline GeometryContextOstreamWrapper<Surface> toStream(const GeometryContext &gctx) const

Helper method for printing: the returned object captures the surface and the geometry context and will print the surface.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

The wrapper object for printing

std::string toString(const GeometryContext &gctx) const

Output into a std::string.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

String representation of the surface

virtual SurfaceType type() const = 0

Return method for the Surface type to avoid dynamic casts.

Returns:

The surface type enumeration value

void visualize(IVisualization3D &helper, const GeometryContext &gctx, const ViewConfig &viewConfig = s_viewSurface) const

Visualize the surface for debugging and inspection.

Parameters:

• helper – Visualization helper for 3D rendering

• gctx – Geometry context for coordinate transformations

• viewConfig – Visual configuration (color, style, etc.)

Public Static Functions

template<class T, typename ...Args>
static inline std::shared_ptr<T> makeShared(Args&&... args)

Factory for producing memory managed instances of Surface.

Will forward all parameters and will attempt to find a suitable constructor.

Parameters:

args – Constructor arguments to forward to surface creation

Returns:

Shared pointer to the created surface instance

Public Static Attributes

static constexpr std::array<std::string_view, Surface::SurfaceType::Other + 1> s_surfaceTypeNames = {"Cone", "Cylinder", "Disc", "Perigee", "Plane", "Straw", "Curvilinear", "Other"}

Helper strings for screen output.

Friends

friend struct GeometryContextOstreamWrapper< Surface >

friend std::ostream &operator<<(std::ostream &os, SurfaceType type)

class SurfaceArray

Provides Surface binning in 2 dimensions.

Uses Grid under the hood to implement the storage and lookup Contains a lookup struct which talks to the Grid and performs utility actions. This struct needs to be initialised externally and passed to SurfaceArray on construction.

Public Functions

SurfaceArray(const GeometryContext &gctx, std::vector<std::shared_ptr<const Surface>> surfaces, std::shared_ptr<RegularSurface> representative, double tolerance, std::tuple<const IAxis&, const IAxis&> axes)

Constructor to create a surface grid lookup for a given representative surface, tolerance, and axes.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• surfaces – The input vector of surfaces that will be accessible through this SurfaceArray.

• representative – The surface which is used as representative

• tolerance – The tolerance used for intersection checks

• axes – The axes used for the grid

explicit SurfaceArray(std::shared_ptr<const Surface> srf)

Constructor with a single surface.

Parameters:

srf – The one and only surface

SurfaceArray(std::unique_ptr<ISurfaceGridLookup> gridLookup, std::vector<std::shared_ptr<const Surface>> surfaces, const Transform3 &transform = Transform3::Identity())

Default constructor which takes a SurfaceLookup and a vector of surfaces.

Parameters:

• gridLookup – The grid storage. SurfaceArray does not fill it on its own

• surfaces – The input vector of surfaces. This is only for bookkeeping, so we can ask

• transform – Optional additional transform for this SurfaceArray

inline std::span<const Surface*const> at(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Get all surfaces in bin given by position pos.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – the lookup position

• direction – the lookup direction

Returns:

span of surface pointers of the bin at that position

inline const std::vector<const Surface*> &at(const Vector3 &position, const Vector3 &direction) const

Get all surfaces in bin given by position pos.

Parameters:

• position – the lookup position

• direction – the lookup direction

Returns:

const reference to surface vector contained in bin at that position

inline std::span<const Surface*const> at(std::array<std::size_t, 2> gridIndices, std::uint8_t neighborDistance) const

Get all surfaces in bin given by local grid indices and neighbor distance.

Parameters:

• gridIndices – the local grid indices

• neighborDistance – the neighbor distance to include in the lookup

Returns:

span of surface pointers of the bin at that position and its neighbors

inline std::vector<const Surface*> &at(std::size_t bin)

Get all surfaces in bin given by global bin index bin.

Parameters:

bin – the global bin index

Returns:

mutable reference to surface vector contained in bin

inline const std::vector<const Surface*> &at(std::size_t bin) const

Get all surfaces in bin given by global bin index.

Parameters:

bin – the global bin index

Returns:

const reference to surface vector contained in bin

inline std::vector<AxisDirection> binningValues() const

The binning values described by this surface grid lookup.

They are in order of the axes

Returns:

Vector of axis directions for binning

inline std::vector<const IAxis*> getAxes() const

Get vector of axes spanning the grid as AnyAxis.

Note

The axes in the vector are copies. Only use for introspection and querying.

Returns:

vector of AnyAxis

inline Vector3 getBinCenter(std::size_t bin) const

Get the center of the bin identified by global bin index bin.

Parameters:

bin – the global bin index

Returns:

Center position of the bin in global coordinates

inline const ISurfaceGridLookup &gridLookup() const

Return the lookup object.

Returns:

Reference to the surface grid lookup interface

inline bool isValidBin(std::size_t bin) const

Checks if global bin is valid.

Note

Valid means that the index points to a bin which is not a under or overflow bin or out of range in any axis.

Parameters:

bin – the global bin index

Returns:

bool if the bin is valid

inline std::uint8_t maxNeighborDistance() const

Get the maximum neighbor distance that is supported by this lookup.

This is used to determine how many neighbors to include in neighbor lookups.

Returns:

Maximum neighbor distance

inline std::span<const Surface*const> neighbors(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const

Get all surfaces in bin at pos and its neighbors.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The position to lookup

• direction – The direction to lookup

Returns:

span of surface pointers of neighbors and nominal

inline const std::vector<const Surface*> &neighbors(const Vector3 &position, const Vector3 &direction) const

Get all surfaces in bin at pos and its neighbors.

Parameters:

• position – The position to lookup

• direction – The direction to lookup

Returns:

Merged surface vector of neighbors and nominal

inline std::array<std::size_t, 2> numLocalBins() const

Get the number of local bins in each dimension.

This is used to determine the size of the grid for neighbor lookups.

Returns:

Array of number of local bins in each dimension

inline std::size_t size() const

Get the size of the underlying grid structure including under/overflow bins.

Returns:

the size

inline const Surface *surfaceRepresentation() const

Get the representative surface used for this surface array.

Returns:

Surface pointer

inline const std::vector<const Surface*> &surfaces() const

Get all surfaces attached to this SurfaceArray.

Note

This does not reflect the actual state of the grid. It only returns what was given in the constructor, without any checks if that is actually what’s in the grid.

Returns:

Reference to vector of all surfaces

std::ostream &toStream(const GeometryContext &gctx, std::ostream &sl) const

Get string representation of this SurfaceArray.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• sl – Output stream to write to

Returns:

the output stream given as sl

inline const Transform3 &transform() const

Get the transform of this surface array.

Deprecated:

This is an implementation detail and will be removed soon

Returns:

Reference to the transformation matrix

struct ISurfaceGridLookup

Base interface for all surface lookups.

Subclassed by Acts::SurfaceArray::SingleElementLookup, Acts::SurfaceArray::SurfaceGridLookup< Axis1, Axis2 >

Public Functions

virtual ~ISurfaceGridLookup() = default

virtual std::span<const Surface*const> at(std::array<std::size_t, 2> gridIndices, std::uint8_t neighborDistance) const = 0

Get all surfaces in bin given by local grid indices and neighbor distance.

Parameters:

• gridIndices – the local grid indices

• neighborDistance – the neighbor distance to include in the lookup

Returns:

span of surface pointers of the bin at that position and its neighbors

inline virtual std::vector<AxisDirection> binningValues() const

The binning values described by this surface grid lookup.

They are in order of the axes (optional) and empty for eingle lookups

Returns:

Vector of axis directions for binning

virtual void fill(const GeometryContext &gctx, std::span<const Surface*const> surfaces) = 0

Fill provided surfaces into the contained Grid.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• surfaces – Input surface pointers

virtual std::vector<const IAxis*> getAxes() const = 0

Returns copies of the axes used in the grid as AnyAxis.

Note

This returns copies. Use for introspection and querying.

Returns:

The axes

virtual Vector3 getBinCenter(std::size_t bin) const = 0

Gets the center position of bin bin in global coordinates.

Parameters:

bin – the global bin index

Returns:

The bin center

virtual bool isValidBin(std::size_t bin) const = 0

Checks if global bin is valid.

Note

Valid means that the index points to a bin which is not a under or overflow bin or out of range in any axis.

Parameters:

bin – the global bin index

Returns:

bool if the bin is valid

virtual std::span<const Surface*const> lookup(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const = 0

Performs lookup at pos and returns bin content as const reference.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – Lookup position

• direction – Lookup direction

Returns:

A span of surface pointers

virtual const std::vector<const Surface*> &lookup(const Vector3 &position, const Vector3 &direction) const = 0

Performs lookup at pos and returns bin content as const reference.

Parameters:

• position – Lookup position

• direction – Lookup direction

Returns:

A vector of surfaces at given bin

virtual const std::vector<const Surface*> &lookup(std::size_t bin) const = 0

Performs lookup at global bin and returns bin content as const reference.

Parameters:

bin – Global lookup bin

Returns:

A vector of surfaces at given bin

virtual std::vector<const Surface*> &lookup(std::size_t bin) = 0

Performs lookup at global bin and returns bin content as reference.

Parameters:

bin – Global lookup bin

Returns:

A vector of surfaces at given bin

virtual std::uint8_t maxNeighborDistance() const = 0

Get the maximum neighbor distance that is supported by this lookup.

This is used to determine how many neighbors to include in neighbor lookups.

Returns:

Maximum neighbor distance

virtual std::span<const Surface*const> neighbors(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const = 0

Performs a lookup at pos, but returns neighbors as well.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – Lookup position

• direction – Lookup direction

Returns:

A span of surface pointers

virtual const std::vector<const Surface*> &neighbors(const Vector3 &position, const Vector3 &direction) const = 0

Performs a lookup at pos, but returns neighbors as well.

Parameters:

• position – Lookup position

• direction – Lookup direction

Returns:

A vector of surfaces at given bin. Copy of all bins selected

virtual std::array<std::size_t, 2> numLocalBins() const = 0

Get the number of local bins in each dimension.

This is used to determine the size of the grid for neighbor lookups.

Returns:

Array of number of local bins in each dimension

virtual std::size_t size() const = 0

Returns the total size of the grid (including under/overflow bins)

Returns:

Size of the grid data structure

virtual const Surface *surfaceRepresentation() const = 0

Get the representative surface used for this lookup.

Returns:

Surface pointer

struct SingleElementLookup : public Acts::SurfaceArray::ISurfaceGridLookup

Lookup implementation which wraps one element and always returns this element when lookup is called.

Deprecated:

Construct the SurfaceArray directly with a single surface

Public Functions

inline explicit SingleElementLookup(const std::vector<const Surface*> &elements)

Default constructor.

Parameters:

elements – the surfaces that are provided through a single lookup

inline explicit SingleElementLookup(const Surface *element)

Default constructor.

Parameters:

element – the one and only element.

inline virtual std::span<const Surface*const> at(std::array<std::size_t, 2> gridIndices, std::uint8_t neighborDistance) const override

Get all surfaces in bin given by local grid indices and neighbor distance.

Parameters:

• gridIndices – the local grid indices

• neighborDistance – the neighbor distance to include in the lookup

Returns:

span of surface pointers of the bin at that position and its neighbors

inline virtual void fill(const GeometryContext&, std::span<const Surface*const>) override

Comply with concept and provide fill method.

Note

Does nothing

inline virtual std::vector<const IAxis*> getAxes() const override

Returns an empty vector of AnyAxis.

Returns:

empty vector

inline virtual Vector3 getBinCenter(std::size_t) const override

Gets the bin center, but always returns (0, 0, 0)

Returns:

(0, 0, 0)

inline virtual bool isValidBin(std::size_t) const override

Returns if the bin is valid (it is)

Returns:

always true

inline virtual std::span<const Surface*const> lookup(const GeometryContext&, const Vector3&, const Vector3&) const override

Lookup, always returns element.

Returns:

span of surface pointers containing only element

inline virtual const std::vector<const Surface*> &lookup(const Vector3&, const Vector3&) const override

Lookup, always returns element.

Returns:

reference to vector containing only element

inline virtual const std::vector<const Surface*> &lookup(std::size_t) const override

Lookup, always returns element.

Returns:

reference to vector containing only element

inline virtual std::vector<const Surface*> &lookup(std::size_t) override

Lookup, always returns element.

Returns:

reference to vector containing only element

inline virtual std::uint8_t maxNeighborDistance() const override

Get the maximum neighbor distance that is supported by this lookup.

This is used to determine how many neighbors to include in neighbor lookups.

Returns:

Maximum neighbor distance

inline virtual std::span<const Surface*const> neighbors(const GeometryContext&, const Vector3&, const Vector3&) const override

Lookup, always returns element.

Returns:

span of surface pointers containing only element

inline virtual const std::vector<const Surface*> &neighbors(const Vector3&, const Vector3&) const override

Lookup, always returns element.

Returns:

reference to vector containing only element

inline virtual std::array<std::size_t, 2> numLocalBins() const override

Get the number of local bins in each dimension.

This is used to determine the size of the grid for neighbor lookups.

Returns:

Array of number of local bins in each dimension

inline virtual std::size_t size() const override

Returns the total size of the grid (including under/overflow bins)

Returns:

1

inline virtual const Surface *surfaceRepresentation() const override

Get the representative surface used for this lookup.

Returns:

Surface pointer

template<class Axis1, class Axis2>
struct SurfaceGridLookup : public Acts::SurfaceArray::ISurfaceGridLookup

Lookup helper which encapsulates a Grid.

Deprecated:

This is deprecated in favor of direct SurfaceArray constructors.

Template Parameters:

• Axis1 – The first axis

• Axis2 – The second axis

Public Functions

inline SurfaceGridLookup(std::shared_ptr<RegularSurface> representative, double tolerance, std::tuple<Axis1, Axis2> axes, const std::vector<AxisDirection> &bValues = {}, std::uint8_t maxNeighborDistance = 1)

Construct a surface grid lookup.

Parameters:

• representative – The surface which is used as representative

• tolerance – The tolerance used for intersection checks

• axes – The axes used for the grid

• bValues – Optional vector of axis directions for binning

• maxNeighborDistance – Maximum next neighbor distance to be included in neighbor lookups

inline virtual std::span<const Surface*const> at(std::array<std::size_t, 2> gridIndices, std::uint8_t neighborDistance) const override

Get all surfaces in bin given by local grid indices and neighbor distance.

Parameters:

• gridIndices – the local grid indices

• neighborDistance – the neighbor distance to include in the lookup

Returns:

span of surface pointers of the bin at that position and its neighbors

inline virtual std::vector<AxisDirection> binningValues() const override

The binning values described by this surface grid lookup.

They are in order of the axes (optional) and empty for eingle lookups

Returns:

Vector of axis directions for binning

inline virtual void fill(const GeometryContext &gctx, std::span<const Surface*const> surfaces) override

Fill provided surfaces into the contained Grid.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• surfaces – Input surface pointers

inline virtual std::vector<const IAxis*> getAxes() const override

Returns copies of the axes used in the grid as AnyAxis.

Note

This returns copies. Use for introspection and querying.

Returns:

The axes

inline virtual Vector3 getBinCenter(std::size_t bin) const override

Gets the center position of bin bin in global coordinates.

Parameters:

bin – the global bin index

Returns:

The bin center

inline virtual bool isValidBin(std::size_t bin) const override

Checks if global bin is valid.

Note

Valid means that the index points to a bin which is not a under or overflow bin or out of range in any axis.

Parameters:

bin – the global bin index

Returns:

bool if the bin is valid

inline virtual std::span<const Surface*const> lookup(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const override

Performs lookup at pos and returns bin content as const reference.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – Lookup position

• direction – Lookup direction

Returns:

A span of surface pointers

inline virtual const std::vector<const Surface*> &lookup(const Vector3 &position, const Vector3 &direction) const override

Performs lookup at pos and returns bin content as const reference.

Parameters:

• position – Lookup position

• direction – Lookup direction

Returns:

A vector of surfaces at given bin

inline virtual const std::vector<const Surface*> &lookup(std::size_t bin) const override

Performs lookup at global bin and returns bin content as const reference.

Parameters:

bin – Global lookup bin

Returns:

A vector of surfaces at given bin

inline virtual std::vector<const Surface*> &lookup(std::size_t bin) override

Performs lookup at global bin and returns bin content as reference.

Parameters:

bin – Global lookup bin

Returns:

A vector of surfaces at given bin

inline virtual std::uint8_t maxNeighborDistance() const override

Get the maximum neighbor distance that is supported by this lookup.

This is used to determine how many neighbors to include in neighbor lookups.

Returns:

Maximum neighbor distance

inline virtual std::span<const Surface*const> neighbors(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction) const override

Performs a lookup at pos, but returns neighbors as well.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – Lookup position

• direction – Lookup direction

Returns:

A span of surface pointers

inline virtual const std::vector<const Surface*> &neighbors(const Vector3 &position, const Vector3 &direction) const override

Performs a lookup at pos, but returns neighbors as well.

Parameters:

• position – Lookup position

• direction – Lookup direction

Returns:

A vector of surfaces at given bin. Copy of all bins selected

inline virtual std::array<std::size_t, 2> numLocalBins() const override

Get the number of local bins in each dimension.

This is used to determine the size of the grid for neighbor lookups.

Returns:

Array of number of local bins in each dimension

inline virtual std::size_t size() const override

Returns the total size of the grid (including under/overflow bins)

Returns:

Size of the grid data structure

inline virtual const Surface *surfaceRepresentation() const override

Get the representative surface used for this lookup.

Returns:

Surface pointer

class SurfaceArrayCreator

It is designed create sub surface arrays to be ordered on Surfaces.

Public Functions

inline explicit SurfaceArrayCreator(const Config &cfg, std::unique_ptr<const Logger> logger = getDefaultLogger("SurfaceArrayCreator", Logging::INFO))

Constructor with explicit config.

Parameters:

• cfg – Explicit config struct

• logger – logging instance

inline explicit SurfaceArrayCreator(std::unique_ptr<const Logger> logger = getDefaultLogger("SurfaceArrayCreator", Logging::INFO))

Constructor with default config.

Parameters:

logger – logging instance

virtual ~SurfaceArrayCreator() = default

Destructor.

inline void setLogger(std::unique_ptr<const Logger> logger)

Set logging instance.

Parameters:

logger – is the logging instance to be set

std::unique_ptr<SurfaceArray> surfaceArrayOnCylinder(const GeometryContext &gctx, std::vector<std::shared_ptr<const Surface>> surfaces, BinningType bTypePhi = equidistant, BinningType bTypeZ = equidistant, std::optional<ProtoLayer> protoLayerOpt = std::nullopt, const Transform3 &transform = Transform3::Identity(), std::uint8_t maxNeighborDistance = 1) const

SurfaceArrayCreator interface method.

• create an array in a cylinder, binned in phi, z when extrema and bin numbers are unknown - this method goes through the surfaces and finds out the needed information

Warning

This function requires the cylinder aligned with the z-axis

Parameters:

• surfaces – is the vector of pointers to sensitive surfaces to be ordered on the cylinder

• gctx – [in] The geometry context for this building call

• protoLayerOpt – The proto layer containing the layer size

• bTypePhi – the binning type in phi direction (equidistant/arbitrary)

• bTypeZ – the binning type in z direction (equidistant/arbitrary)

• transform – is the (optional) additional transform applied

• maxNeighborDistance – Maximum next neighbor distance to be included in neighbor lookups

Pre:

the pointers to the sensitive surfaces in the surfaces vectors all need to be valid, since no check is performed

Returns:

a unique pointer a new SurfaceArray

std::unique_ptr<SurfaceArray> surfaceArrayOnCylinder(const GeometryContext &gctx, std::vector<std::shared_ptr<const Surface>> surfaces, std::size_t binsPhi, std::size_t binsZ, std::optional<ProtoLayer> protoLayerOpt = std::nullopt, const Transform3 &transform = Transform3::Identity(), std::uint8_t maxNeighborDistance = 1) const

SurfaceArrayCreator interface method.

• create an array in a cylinder, binned in phi, z when extrema and bin numbers are known

Warning

This function requires the cylinder aligned with the z-axis

Parameters:

• surfaces – is the vector of pointers to sensitive surfaces to be ordered on the cylinder

• gctx – [in] The geometry context for this building call

• protoLayerOpt – The proto layer containing the layer size

• binsPhi – is the number of bins in phi for the surfaces

• binsZ – is the number of bin in Z for the surfaces

• transform – is the (optional) additional transform applied

• maxNeighborDistance – Maximum next neighbor distance to be included in neighbor lookups

Pre:

the pointers to the sensitive surfaces in the surfaces vectors all need to be valid, since no check is performed

Returns:

a unique pointer to a new SurfaceArray

std::unique_ptr<SurfaceArray> surfaceArrayOnDisc(const GeometryContext &gctx, std::vector<std::shared_ptr<const Surface>> surfaces, BinningType bTypeR, BinningType bTypePhi, std::optional<ProtoLayer> protoLayerOpt = std::nullopt, const Transform3 &transform = Transform3::Identity(), std::uint8_t maxNeighborDistance = 1) const

SurfaceArrayCreator interface method.

• create an array in a cylinder, binned in phi, r when extrema and bin numbers are unknown - this method goes through the surfaces and finds out the needed information

Note

If there is more than on R-Ring, number of phi bins will be set to lowest number of surfaces of any R-ring. This ignores bTypePhi and produces equidistant binning in phi

Warning

This function requires the disc aligned with the z-axis

Parameters:

• surfaces – is the vector of pointers to sensitive surfaces to be ordered on the disc

• gctx – [in] The geometry context for this building call

• protoLayerOpt – The proto layer containing the layer size

• bTypeR – the binning type in r direction (equidistant/arbitrary)

• bTypePhi – the binning type in phi direction (equidistant/arbitrary)

• transform – is the (optional) additional transform applied

• maxNeighborDistance – Maximum next neighbor distance to be included in neighbor lookups

Pre:

the pointers to the sensitive surfaces in the surfaces vectors all need to be valid, since no check is performed

Returns:

a unique pointer a new SurfaceArray

std::unique_ptr<SurfaceArray> surfaceArrayOnDisc(const GeometryContext &gctx, std::vector<std::shared_ptr<const Surface>> surfaces, std::size_t binsR, std::size_t binsPhi, std::optional<ProtoLayer> protoLayerOpt = std::nullopt, const Transform3 &transform = Transform3::Identity(), std::uint8_t maxNeighborDistance = 1) const

SurfaceArrayCreator interface method.

• create an array on a disc, binned in r, phi when extrema and bin numbers are known

Warning

This function requires the disc aligned with the z-axis

Parameters:

• surfaces – is the vector of pointers to sensitive surfaces to be ordered on the disc

• gctx – [in] The geometry context for this building call

• protoLayerOpt – The proto layer containing the layer size

• binsPhi – is the number of bins in phi for the surfaces

• binsR – is the number of bin in R for the surfaces

• transform – is the (optional) additional transform applied

• maxNeighborDistance – Maximum next neighbor distance to be included in neighbor lookups

Pre:

the pointers to the sensitive surfaces in the surfaces vectors all need to be valid, since no check is performed

Returns:

a unique pointer a new SurfaceArray

std::unique_ptr<SurfaceArray> surfaceArrayOnPlane(const GeometryContext &gctx, std::vector<std::shared_ptr<const Surface>> surfaces, std::size_t bins1, std::size_t bins2, AxisDirection aDir, std::optional<ProtoLayer> protoLayerOpt = std::nullopt, const Transform3 &transform = Transform3::Identity(), std::uint8_t maxNeighborDistance = 1) const

SurfaceArrayCreator interface method.

• create an array on a plane

Warning

This function requires the plane aligned with either the x-, y- or z-axis

Parameters:

• gctx – [in] The geometry context for this building call

• surfaces – [in] is the vector of pointers to sensitive surfaces to be ordered on the plane

• bins1 – [in] is the number of bins in the orthogonal direction to aDir

• bins2 – [in] is the number of bins in the orthogonal direction to aDir

• aDir – [in] Direction of the aligned surfaces

• protoLayerOpt – [in] Optional ProtoLayer instance

• transform – [in] is the (optional) additional transform applied

• maxNeighborDistance – Maximum next neighbor distance to be included in neighbor lookups

Pre:

the pointers to the sensitive surfaces in the surfaces vectors all need to be valid, since no check is performed

Returns:

a unique pointer a new SurfaceArray

Public Static Functions

static inline bool isSurfaceEquivalent(const GeometryContext &gctx, AxisDirection aDir, const Surface *a, const Surface *b)

Static check function for surface equivalent.

Parameters:

• gctx – [in] the geometry context for this check

• aDir – the axis direction for the binning

• a – first surface for checking

• b – second surface for checking

Returns:

true if surfaces are equivalent for binning purposes

Friends

friend struct ActsTests::SurfaceArrayCreatorFixture

friend class SurfaceArray

struct Config

Configuration options for the surface array creator.

Public Members

bool doPhiBinningOptimization = true

Optimize the binning in phi for disc layers.

Reduces the number of bins to the lowest number of non-equivalent phi surfaces of all r-bins. If false, this step is skipped.

SurfaceMatcher surfaceMatcher = SurfaceArrayCreator::isSurfaceEquivalent

Type-erased function which determines whether two surfaces are supposed to be considered equivalent in terms of the binning.

struct ProtoAxis

Prototype axis definition for surface binning.

Public Functions

inline std::size_t getBin(AxisScalar x) const

Get the bin index for a given value.

Parameters:

x – The value to find the bin for

Returns:

The bin index

Public Members

AxisDirection axisDir = AxisDirection::AxisX

Axis direction for binning.

std::vector<AxisScalar> binEdges

Bin edges for variable binning.

BinningType bType = BinningType::equidistant

Binning type (equidistant or variable)

AxisScalar max = 0

Maximum value of the axis.

AxisScalar min = 0

Minimum value of the axis.

std::size_t nBins = 0

Number of bins.

class SurfaceBounds

Interface for surface bounds.

Surface bounds provide:

• inside() checks

• distance to boundary calculations

• the BoundsType and a set of parameters to simplify persistency

Subclassed by Acts::ConeBounds, Acts::CylinderBounds, Acts::DiscBounds, Acts::InfiniteBounds, Acts::LineBounds, Acts::PlanarBounds

Public Types

enum BoundsType

This is nested to the SurfaceBounds, as also VolumeBounds will have Bounds Type.

Values:

enumerator eCone

enumerator eCylinder

enumerator eDiamond

enumerator eDisc

enumerator eEllipse

enumerator eLine

enumerator eRectangle

enumerator eTrapezoid

enumerator eTriangle

enumerator eDiscTrapezoid

enumerator eConvexPolygon

enumerator eAnnulus

enumerator eBoundless

enumerator eOther

Public Functions

virtual ~SurfaceBounds() = default

virtual SquareMatrix2 boundToCartesianJacobian(const Vector2 &lposition) const = 0

Computes the bound to cartesian jacobian at a given local position.

Parameters:

lposition – is the local position at which the jacobian is computed

Returns:

the bound to cartesian jacobian

virtual SquareMatrix2 boundToCartesianMetric(const Vector2 &lposition) const = 0

Computes the bound to cartesian metric at a given local position.

Parameters:

lposition – is the local position at which the metric is computed

Returns:

the bound to cartesian metric

virtual Vector2 center() const = 0

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Returns:

Vector2 representing the center position in local coordinates

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const = 0

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

inline virtual double distance(const Vector2 &lposition) const

Calculates the distance to the bounds from a given local position.

Parameters:

lposition – is the local position

Returns:

the distance to the bounds

virtual bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

virtual bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

virtual bool isCartesian() const = 0

Check if the bound coordinates are cartesian.

Returns:

true if the bound coordinates are cartesian

virtual std::ostream &toStream(std::ostream &os) const = 0

Output Method for std::ostream, to be overloaded by child classes.

Parameters:

os – is the outstream in which the string dump is done

Returns:

Modified ostream for chaining

virtual BoundsType type() const = 0

Return the bounds type - for persistency optimization.

Returns:

the bounds type

virtual std::vector<double> values() const = 0

Access method for bound values, this is a dynamically sized vector containing the parameters needed to describe these bounds.

Returns:

of the stored values for this SurfaceBounds object

Friends

inline friend std::ostream &operator<<(std::ostream &os, const SurfaceBounds &sb)

inline friend bool operator==(const SurfaceBounds &lhs, const SurfaceBounds &rhs)

class SympyStepper

Stepper implementation using sympy-generated expressions.

Public Types

using BoundParameters = BoundTrackParameters

Type alias for bound track parameters.

using BoundState = std::tuple<BoundParameters, Jacobian, double>

Bound state tuple containing parameters, Jacobian, and path length.

using Covariance = BoundMatrix

Type alias for covariance matrix.

using Jacobian = BoundMatrix

Type alias for jacobian matrix.

Public Functions

explicit SympyStepper(const Config &config)

Constructor with configuration.

Parameters:

config – The configuration of the stepper

explicit SympyStepper(std::shared_ptr<const MagneticFieldProvider> bField)

Constructor requires knowledge of the detector’s magnetic field.

Parameters:

bField – The magnetic field provider

inline double absoluteMomentum(const State &state) const

Absolute momentum accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Absolute momentum

Result<BoundState> boundState(State &state, const Surface &surface, bool transportCov = true, const FreeToBoundCorrection &freeToBoundCorrection = FreeToBoundCorrection(false)) const

Create and return the bound state at the current position.

This transports (if necessary) the covariance to the surface and creates a bound state. It does not check if the transported state is at the surface, this needs to be guaranteed by the propagator

Parameters:

• state – [in] State that will be presented as BoundState

• surface – [in] The surface to which we bind the state

• transportCov – [in] Flag steering covariance transport

• freeToBoundCorrection – [in] Correction for non-linearity effect during transform from free to bound

Returns:

A bound state:

• the parameters at the surface

• the stepwise jacobian towards it (from last bound)

• and the path length (from start - for ordering)

inline double charge(const State &state) const

Charge access.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Particle charge

BoundState curvilinearState(State &state, bool transportCov = true) const

Create and return a curvilinear state at the current position.

This transports (if necessary) the covariance to the current position and creates a curvilinear state.

Parameters:

• state – [in] State that will be presented as CurvilinearState

• transportCov – [in] Flag steering covariance transport

Returns:

A curvilinear state:

• the curvilinear parameters at given position

• the stepweise jacobian towards it (from last bound)

• and the path length (from start - for ordering)

inline Vector3 direction(const State &state) const

Momentum direction accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Direction vector

inline Result<Vector3> getField(State &state, const Vector3 &pos) const

Get the field for the stepping, it checks first if the access is still within the Cell, and updates the cell if necessary.

Parameters:

• state – [inout] is the propagation state associated with the track the magnetic field cell is used (and potentially updated)

• pos – [in] is the field position

Returns:

Magnetic field vector

inline double getStepSize(const State &state, ConstrainedStep::Type stype) const

Get the step size.

Parameters:

• state – [in] The stepping state (thread-local cache)

• stype – [in] The step size type to be returned

Returns:

Step size

void initialize(State &state, const BoundParameters &par) const

Initialize the state from bound track parameters.

Parameters:

• state – The state to initialize

• par – The bound track parameters

void initialize(State &state, const BoundVector &boundParams, const std::optional<BoundMatrix> &cov, ParticleHypothesis particleHypothesis, const Surface &surface) const

Initialize the state from bound parameters.

Parameters:

• state – The state to initialize

• boundParams – Bound track parameters vector

• cov – Covariance matrix

• particleHypothesis – Particle hypothesis

• surface – Reference surface

State makeState(const Options &options) const

Create a state object.

Parameters:

options – Stepper options

Returns:

State object

inline Vector3 momentum(const State &state) const

Momentum accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Momentum vector

inline std::string outputStepSize(const State &state) const

Output the Step Size - single component.

Parameters:

state – [in,out] The stepping state (thread-local cache)

Returns:

String representation of step size

inline const ParticleHypothesis &particleHypothesis(const State &state) const

Particle hypothesis.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Particle hypothesis

inline Vector3 position(const State &state) const

Global particle position accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Position vector

bool prepareCurvilinearState(State &state) const

If necessary fill additional members needed for curvilinearState.

Compute path length derivatives in case they have not been computed yet, which is the case if no step has been executed yet.

Parameters:

state – [inout] State of the stepper

Returns:

true if nothing is missing after this call, false otherwise.

inline double qOverP(const State &state) const

QoP direction accessor.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Charge over momentum

inline void releaseStepSize(State &state, ConstrainedStep::Type stype) const

Release the Step size.

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• stype – [in] The step size type to be released

Result<double> step(State &state, Direction propDir, const IVolumeMaterial *material) const

Perform a Runge-Kutta track parameter propagation step.

Note

The state contains the desired step size. It can be negative during backwards track propagation, and since we’re using an adaptive algorithm, it can be modified by the stepper class during propagation.

Parameters:

• state – [inout] State of the stepper

• propDir – is the direction of propagation

• material – is the optional volume material we are stepping through.

Returns:

the result of the step

inline double time(const State &state) const

Time access.

Parameters:

state – [in] The stepping state (thread-local cache)

Returns:

Time

void transportCovarianceToBound(State &state, const Surface &surface, const FreeToBoundCorrection &freeToBoundCorrection = FreeToBoundCorrection(false)) const

Method for on-demand transport of the covariance to a new curvilinear frame at current position, or direction of the state.

Note

no check is done if the position is actually on the surface

Template Parameters:

surface_t – the Surface type

Parameters:

• state – [inout] State of the stepper

• surface – [in] is the surface to which the covariance is forwarded to

• freeToBoundCorrection – [in] Correction for non-linearity effect during transform from free to bound

void transportCovarianceToCurvilinear(State &state) const

Method for on-demand transport of the covariance to a new curvilinear frame at current position, or direction of the state.

Parameters:

state – [inout] State of the stepper

void update(State &state, const FreeVector &freeParams, const BoundVector &boundParams, const Covariance &covariance, const Surface &surface) const

Method to update a stepper state to the some parameters.

Parameters:

• state – [inout] State object that will be updated

• freeParams – [in] Free parameters that will be written into state

• boundParams – [in] Corresponding bound parameters used to update jacToGlobal in state

• covariance – [in] The covariance that will be written into state

• surface – [in] The surface used to update the jacToGlobal

void update(State &state, const Vector3 &uposition, const Vector3 &udirection, double qOverP, double time) const

Method to update the stepper state.

Parameters:

• state – [inout] State object that will be updated

• uposition – [in] the updated position

• udirection – [in] the updated direction

• qOverP – [in] the updated qOverP value

• time – [in] the updated time value

inline void updateStepSize(State &state, const NavigationTarget &target, Direction direction, ConstrainedStep::Type stype) const

Update step size.

This method intersects the provided surface and update the navigation step estimation accordingly (hence it changes the state). It also returns the status of the intersection to trigger onSurface in case the surface is reached.

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• target – [in] The NavigationTarget

• direction – [in] The propagation direction

• stype – [in] The step size type to be set

inline void updateStepSize(State &state, double stepSize, ConstrainedStep::Type stype) const

Update step size - explicitly with a double.

Parameters:

• state – [in,out] The stepping state (thread-local cache)

• stepSize – [in] The step size value

• stype – [in] The step size type to be set

inline IntersectionStatus updateSurfaceStatus(State &state, const Surface &surface, std::uint8_t index, Direction navDir, const BoundaryTolerance &boundaryTolerance, double surfaceTolerance, ConstrainedStep::Type stype, const Logger &logger = getDummyLogger()) const

Update surface status.

It checks the status to the reference surface & updates the step size accordingly

Parameters:

• state – [inout] The stepping state (thread-local cache)

• surface – [in] The surface provided

• index – [in] The surface intersection index

• navDir – [in] The navigation direction

• boundaryTolerance – [in] The boundary check for this status update

• surfaceTolerance – [in] Surface tolerance used for intersection

• stype – [in] The step size type to be set

• logger – [in] A Logger instance

Returns:

Intersection status

struct Config

Configuration for the sympy stepper.

Public Members

std::shared_ptr<const MagneticFieldProvider> bField

Magnetic field provider.

struct Options : public Acts::StepperPlainOptions

Runtime options for sympy propagation.

Public Functions

inline Options(const GeometryContext &gctx, const MagneticFieldContext &mctx)

Constructor.

Parameters:

• gctx – Geometry context

• mctx – Magnetic field context

inline void setPlainOptions(const StepperPlainOptions &options)

Set plain stepper options.

Parameters:

options – Plain stepper options

Public Members

bool doDense = true

Whether to perform dense output.

double maxXOverX0Step = 1

Maximum radiation length fraction per step.

struct State

State for track parameter propagation.

It contains the stepping information and is provided thread local by the propagator

Public Functions

inline State(const Options &optionsIn, MagneticFieldProvider::Cache fieldCacheIn)

Constructor from the initial bound track parameters.

Note

the covariance matrix is copied when needed

Parameters:

• optionsIn – [in] is the configuration of the stepper

• fieldCacheIn – [in] is the cache object for the magnetic field

Public Members

Covariance cov = Covariance::Zero()

Covariance matrix for error propagation.

bool covTransport = false

Covariance matrix (and indicator) associated with the initial error on track parameters.

FreeVector derivative = FreeVector::Zero()

The propagation derivative.

MagneticFieldProvider::Cache fieldCache

This caches the current magnetic field cell and stays (and interpolates) within it as long as this is valid.

See step() code for details.

Jacobian jacobian = Jacobian::Identity()

The full jacobian of the transport entire transport.

BoundToFreeMatrix jacToGlobal = BoundToFreeMatrix::Zero()

Jacobian from local to the global frame.

FreeMatrix jacTransport = FreeMatrix::Identity()

Pure transport jacobian part from runge kutta integration.

detail::MaterialEffectsAccumulator materialEffectsAccumulator

Accumulator for material effects along the trajectory.

std::size_t nSteps = 0

Total number of performed steps.

std::size_t nStepTrials = 0

Totoal number of attempted steps.

Options options

Configuration options for the stepper.

FreeVector pars = FreeVector::Zero()

Internal free vector parameters.

ParticleHypothesis particleHypothesis = ParticleHypothesis::pion()

Particle hypothesis.

double pathAccumulated = 0.

Accumulated path length state.

double previousStepSize = 0.

Last performed step (for overstep limit calculation)

StepperStatistics statistics

Statistics of the stepper.

ConstrainedStep stepSize

Adaptive step size of the runge-kutta integration.

template<TrackContainerBackend track_container_t, CommonMultiTrajectoryBackend traj_t, template<typename> class holder_t = RefHolder>
class TrackContainer

Track container interface class.

This type represents a collections of tracks. It uses a backend to store both the actual tracks and the associated track states.

Template Parameters:

• track_container_t – the track container backend

• traj_t – the track state container backend

• holder_t – ownership management class for the backend

TrackContainer construction

Constructors for the track container by using a set of backends (track + track state). The container can either take ownership of the backends or just hold references to them. This is driven by the holder_t template parameter, where you can also supply a custom holder type. Template deduction is used to try to guess the correct holder type.

inline TrackContainer(holder_t<track_container_t> container, holder_t<traj_t> traj)

Constructor from a track container backend and a track state container backend.

Parameters:

• container – the track container backend

• traj – the track state container backend

inline  TrackContainer (auto &container, auto &traj) requires(std

Constructor from references to a track container backend and to a track state container backend.

Note

The track container will not assume ownership over the backends in this case. You need to ensure suitable lifetime

Parameters:

• container – the track container backend

• traj – the track state container backend

inline  TrackContainer (const auto &container, const auto &traj) requires(std

Constructor from const references to a track container backend and to a track state container backend.

Note

The track container will not assume ownership over the backends in this case. You need to ensure suitable lifetime

Parameters:

• container – the track container backend

• traj – the track state container backend

TrackContainer track (proxy) access and manipulation

These methods allow accessing tracks, i.e. adding or retrieving a track proxy that points at a specific track in the container.

inline ConstTrackProxy getTrack(IndexType itrack) const

Get a const track proxy for a track index.

Parameters:

itrack – the track index in the container

Returns:

A const track proxy for the index

inline TrackProxy getTrack(IndexType itrack)
requires (!ReadOnly)

Get a mutable track proxy for a track index.

Note

Only available if the track container is not read-only

Parameters:

itrack – the track index in the container

Returns:

A mutable track proxy for the index

inline ConstTrackProxy at(IndexType itrack) const

Get a const track proxy for a track index.

Parameters:

itrack – the track index in the container

Returns:

A const track proxy for the index

inline TrackProxy at(IndexType itrack)
requires (!ReadOnly)

Get a mutable track proxy for a track index.

Note

Only available if the track container is not read-only

Parameters:

itrack – the track index in the container

Returns:

A mutable track proxy for the index

inline IndexType addTrack()
requires (!ReadOnly)

Add a track to the container.

Note this only creates the logical track and allocates memory. You can combine this with getTrack to obtain a track proxy

Note

Only available if the track container is not read-only

Returns:

the index to the newly added track

inline TrackProxy makeTrack()
requires (!ReadOnly)

Add a track to the container and return a track proxy to it This effectively calls addTrack and getTrack.

Note

Only available if the track container is not read-only

Returns:

a track proxy to the newly added track

inline void removeTrack(IndexType itrack)
requires (!ReadOnly)

Remove a track at index itrack from the container.

Note

Only available if the track container is not read-only

Note

This invalidates track proxies that point to tracks with larger indices than itrack!

Parameters:

itrack – The index of the track to remove

inline iterator begin()
requires (!ReadOnly)

Get a mutable iterator to the first track in the container.

Note

Only available if the track container is not read-only

Returns:

a mutable iterator to the first track

inline iterator end()
requires (!ReadOnly)

Get a past-the-end iterator for this container.

Note

Only available if the track container is not read-only

Returns:

a past-the-end iterator

inline const_iterator begin() const

Get an const iterator to the first track in the container.

Returns:

a const iterator to the first track

inline const_iterator end() const

Get a past-the-end iterator for this container.

Returns:

a past-the-end iterator

TrackContainer column management

TrackContainer can manage a set of common static columns, and dynamic columns that can be added at runtime.

This set of methods allows you to manage the dynamic columns.

template<typename T>
inline constexpr void addColumn(std::string_view key)
requires (!ReadOnly)

Add a dynamic column to the track container.

Note

Only available if the track container is not read-only

Parameters:

key – the name of the column to be added

inline constexpr bool hasColumn(const std::string &key) const

Check if this track container has a specific dynamic column.

Parameters:

key – the key to check for

Returns:

true if the column exists

inline constexpr bool hasColumn(HashedString key) const

Check if a this track container has a specific dynamic column.

Parameters:

key – the key to check for

Returns:

true if the column exists

template<typename other_track_container_t>
inline void ensureDynamicColumns(const other_track_container_t &other)
requires (!ReadOnly)

Helper function to make this track container match the dynamic columns of another one.

This will only work if the track container supports this source, and depends on the implementation details of the dynamic columns of the container

Note

Only available if the track container is not read-only

Template Parameters:

other_track_container_t – Type of the other track container

Parameters:

other – The other track container

TrackContainer backend access

These methods allow accessing the backend of the track container.

In most cases, this is not necessary for interacting with the container.

inline auto &container()
requires (!ReadOnly)

Get a mutable reference to the track container backend.

Note

Only available if the track container is not read-only

Returns:

a mutable reference to the backend

inline const auto &container() const

Get a const reference to the track container backend.

Returns:

a const reference to the backend

inline auto &trackStateContainer()
requires (!ReadOnly)

Get a mutable reference to the track state container backend.

Note

Only available if the track container is not read-only

Returns:

a mutable reference to the backend

inline auto &trackStateContainerHolder()
requires (!ReadOnly)

Retrieve the holder of the track state container.

Note

Only available if the track container is not read-only

Returns:

The track state container including it’s holder

inline const auto &trackStateContainer() const

Get a const reference to the track state container backend.

Returns:

a const reference to the backend

inline const auto &trackStateContainerHolder() const

Retrieve the holder of the track state container.

Returns:

The track state container including it’s holder

Public Types

using const_iterator = detail::ContainerIterator<TrackContainer, ConstTrackProxy, IndexType, true>

Type alias for const iterator over tracks in container.

using ConstTrackProxy = Acts::TrackProxy<track_container_t, traj_t, holder_t, true>

Alias for the const version of a track proxy, with the same backends as this container.

using ConstTrackStateProxy = typename MultiTrajectory<traj_t>::ConstTrackStateProxy

Type alias for const track state proxy from multi-trajectory.

using IndexType = TrackIndexType

The index type of the track container, taken from the container backend.

using iterator = detail::ContainerIterator<TrackContainer, TrackProxy, IndexType, false>

Type alias for mutable iterator over tracks in container.

using size_type = IndexType

Type alias for size type of track container.

using TrackContainerBackend = track_container_t

Type alias for track container backend type.

using TrackProxy = Acts::TrackProxy<track_container_t, traj_t, holder_t, false>

Alias for the mutable version of a track proxy, with the same backends as this container.

using TrackStateContainerBackend = traj_t

Type alias for track state container backend type.

using TrackStateProxy = typename MultiTrajectory<traj_t>::TrackStateProxy

Type alias for mutable track state proxy from multi-trajectory.

Public Functions

inline void clear()
requires (!ReadOnly)

Clear the content of the track container.

Note

Only available if the track container is not read-only

inline constexpr IndexType size() const

Get the size (number of tracks) of the track container.

Returns:

the sixe

Public Static Attributes

static constexpr IndexType kInvalid = kTrackIndexInvalid

Sentinel value that indicates an invalid index.

static constexpr bool ReadOnly = IsReadOnlyTrackContainer<track_container_t>::value

Indicates if this track container is read-only, or if it can be modified.

static constexpr bool TrackStateReadOnly = IsReadOnlyMultiTrajectory<traj_t>::value

Indicates if the track state container is read-only, or if it can be modified.

template<typename track_container_t, typename trajectory_t, template<typename> class holder_t, bool read_only = true>
class TrackProxy : public Acts::TrackProxyCommon<TrackProxy<track_container_t, trajectory_t, holder_t, true>, track_container_t::IndexType, true>

Proxy class representing a single track.

This class provides a view into an associated TrackContainer, and has reference semantics. You can think of it as a pointer to a vector of tracks, which exposes an object-oriented interface for accessing the track properties.

Template Parameters:

• track_container_t – the container backend

• trajectory_t – the track state container backend

• holder_t – ownership management class for the backend

• read_only – true if this track container is not mutable

Constructors and assignment operator

Public constructors and assignment operators for TrackProxy only allow construction from another TrackProxy. You should generally not have to construct TrackProxy manually.

TrackProxy(const TrackProxy &other) = default

Copy constructor: const to const or mutable to mutable.

Parameters:

other – the other track proxy

TrackProxy &operator=(const TrackProxy &other) = default

Copy assignment operator: const to const or mutable to mutable.

Parameters:

other – the other track proxy

Returns:

reference to this track proxy

inline explicit TrackProxy(const MutableTrackProxy &other)
requires ReadOnly

Constructor from mutable track proxy.

Note

Only available if the track proxy is read-only

Parameters:

other – the other track proxy

inline TrackProxy &operator=(const MutableTrackProxy &other)
requires ReadOnly

Copy assignment operator from mutable track proxy.

Note

Only available if the track proxy is read-only

Parameters:

other – the other track proxy

Returns:

reference to this track proxy

TrackProxy properties

Methods that give access to the properties of a track represented by TrackProxy.

Many of these methods come in a const and a non-const version. The non-const version is only available if you have an instance of TrackProxy that does not have the read_only template parameter set to true, even if you hold it as an lvalue.

inline const Surface &referenceSurface() const

Get the reference surface of the track (e.g.

the perigee)

Returns:

the reference surface

inline void setReferenceSurface(std::shared_ptr<const Surface> srf)
requires (!ReadOnly)

Set a new reference surface for this track.

Parameters:

srf – The surface to set

inline bool hasReferenceSurface() const

Returns whether the track has a reference surface or not.

Returns:

whether a surface exists or not

inline ConstParameters parameters() const

Get the parameters of the track at the reference surface (e.g.

perigee). Const version

Returns:

Proxy vector for the parameters

inline ConstCovariance covariance() const

Get the covariance of the track at the reference surface (e.g.

perigee). Const version

Returns:

Proxy matrix for the covariance

inline Parameters parameters()
requires (!ReadOnly)

Get the parameters of the track at the reference surface (e.g.

perigee). Mutable version

Note

Only available if the track proxy is not read-only

Returns:

Proxy vector for the parameters

inline Covariance covariance()
requires (!ReadOnly)

Get the covariance of the track at the reference surface (e.g.

perigee). Mutable version

Note

Only available if the track proxy is not read-only

Returns:

Proxy matrix for the covariance

inline ParticleHypothesis particleHypothesis() const

Get the particle hypothesis.

Returns:

the particle hypothesis

inline void setParticleHypothesis(const ParticleHypothesis &particleHypothesis)
requires (!ReadOnly)

Set a new particle hypothesis for this track.

Note

Only available if the track proxy is not read-only

Parameters:

particleHypothesis – The particle hypothesis to set

inline unsigned int nTrackStates() const

Return the number of track states associated to this track.

Note

This is calculated by iterating over the track states which is somewhat expensive. Consider caching this value if you need It more than once.

Returns:

The number of track states

inline IndexType index() const

Return the index of this track in the track container.

Note

This is separate from the tip index

Returns:

the track index

inline double absoluteMomentum() const

Get the absolute momentum.

Returns:

The absolute momentum value

inline double charge() const

Get the charge.

Returns:

The charge value

inline float chi2() const

Return the local chi-squared contribution.

Returns:

The chi-squared value

inline float &chi2()
requires (!read_only)

Return a mutable reference to the local chi-squared contribution.

Returns:

Mutable reference to the chi-squared value

inline Vector3 direction() const

Get a unit vector along the track direction at the reference surface.

Returns:

The direction unit vector

inline Vector4 fourMomentum() const

Get the four-momentum vector: (px, py, pz, e)

Returns:

the four-momentum vector

inline bool isForwardLinked() const

Return whether the track is forward-linked, i.e.

whether each track state has a valid next-state index. Forward-linking is required to use the inside-out trackStates() range.

Returns:

True if the track is forward-linked

inline double loc0() const

Access the loc0 parameter of the track at the reference surface.

Returns:

The loc0 parameter

inline double loc1() const

Access the loc1 parameter of the track at the reference surface.

Returns:

The loc1 parameter

inline Vector3 momentum() const

Get the global momentum vector.

Returns:

the global momentum vector

inline unsigned int nDoF() const

Return the number of degrees of freedom.

Returns:

The number of degrees of freedom

inline unsigned int &nDoF()
requires (!read_only)

Return a mutable reference to the number of degrees of freedom.

Returns:

Mutable reference to the number of degrees of freedom

inline unsigned int nHoles() const

Return the number of holes on this track.

Returns:

The number of holes

inline unsigned int &nHoles()
requires (!read_only)

Return a mutable reference to the number of holes.

Returns:

Mutable reference to the number of holes

inline unsigned int nMeasurements() const

Return the number of measurements assigned to this track.

Returns:

The number of measurements

inline unsigned int &nMeasurements()
requires (!read_only)

Return a mutable reference to the number of measurements.

Returns:

Mutable reference to the number of measurements

inline unsigned int nOutliers() const

Return the number of outliers for this track.

Returns:

The number of outliers

inline unsigned int &nOutliers()
requires (!read_only)

Return a mutable reference to the number of outliers.

Returns:

Mutable reference to the number of outliers

inline unsigned int nSharedHits() const

Return the number of shared hits for this track.

Returns:

The number of shared hits

inline unsigned int &nSharedHits()
requires (!read_only)

Return a mutable reference to the number of shared hits.

Returns:

Mutable reference to the number of shared hits

inline double phi() const

Access the phi parameter of the track at the reference surface.

Returns:

The phi parameter

inline double qOverP() const

Access the q/p (curvature) parameter of the track at the reference surface.

Returns:

The q/p parameter

inline IndexType stemIndex() const

Get the stem index, i.e.

the innermost track state in the track.

Returns:

The stem index

inline IndexType &stemIndex()
requires (!read_only)

Get a mutable reference to the stem index.

Returns:

Mutable reference to the stem index

inline double theta() const

Access the theta parameter of the track at the reference surface.

Returns:

The theta parameter

inline double time() const

Access the time parameter of the track at the reference surface.

Returns:

The time parameter

inline IndexType tipIndex() const

Get the tip index, i.e.

the entry point into the track state container.

Returns:

The tip index

inline IndexType &tipIndex()
requires (!read_only)

Get a mutable reference to the tip index.

Returns:

Mutable reference to the tip index

inline double transverseMomentum() const

Get the transverse momentum.

Returns:

The transverse momentum value

TrackProxy track state access

Methods that give access to the track states of a track represented by TrackProxy.

inline ConstTrackStateProxy outermostTrackState() const

Return a const track state proxy to the outermost track state.

Returns:

The outermost track state proxy

inline TrackStateProxy outermostTrackState()
requires (!ReadOnly)

Return a mutable track state proxy to the outermost track state.

Returns:

The outermost track state proxy

inline auto innermostTrackState() const

Return a const track state proxy to the innermost track state.

Note

This is only available, if the track is forward linked

Returns:

The innermost track state proxy

inline auto innermostTrackState()
requires (!ReadOnly)

Return a mutable track state proxy to the innermost track state.

Note

This is only available, if the track is forward linked

Note

Only available if the track proxy is not read-only

Returns:

The innermost track state proxy

inline auto trackStatesReversed() const

Get a range over the track states of this track.

Return value is compatible with range based for loop. Const version

Note

This range is from the outside inwards!

Returns:

Track state range to iterate over

inline auto trackStatesReversed()
requires (!ReadOnly)

Get a range over the track states of this track.

Return value is compatible with range based for loop. Mutable version

Note

Only available if the track proxy is not read-only

Note

This range is from the outside inwards!

Returns:

Track state range to iterate over

inline auto trackStates() const

Get a range over the track states of this track.

Return value is compatible with range based for loop. This overload returns a const-only track state range, which means you cannot modify the track states obtained in the iteration.

Note

This range is from the inside out!

Warning

This access direction is only possible if the track states are forward-linked.

Returns:

Track state range to iterate over

inline auto trackStates()
requires (!ReadOnly)

Get a range over the track states of this track.

Return value is compatible with range based for loop. This overload returns a mutable track state range, which means you can modify the track states obtained in the iteration.

Note

Only available if the track proxy is not read-only

Note

This range is from the inside out!

Warning

This access direction is only possible if the track states are forward-linked.

Returns:

Track state range to iterate over

TrackProxy track state manipulation

Methods that manipulate the track states of a track represented by TrackProxy.

Copy Methods Overview:

Three main copy methods are available with different behaviors:

• copyFrom(): Deep copy including all track states (creates new track states)

• copyFromWithoutStates(): Copy only track properties, invalidate track state indices

• copyFromShallow(): Shallow copy sharing the same track states (copy indices only)

Choose based on your needs:

• Use copyFrom() for independent track copies with separate track states

• Use copyFromWithoutStates() to update track metadata without affecting trajectories

• Use copyFromShallow() for lightweight copies when track states can be shared

inline void linkForward()
requires (!ReadOnly)

Forward connect a track.

This means setting indices from the inside out on all track states.

Note

Only available if the track proxy is not read-only

inline auto appendTrackState(TrackStatePropMask mask = TrackStatePropMask::All)
requires (!ReadOnly)

Append a track state to this track.

This will modify the tip index to point at the newly created track state, which will be directly after the previous track state at tip index.

Note

Only available if the track proxy is not read-only

Parameters:

mask – The allocation prop mask for the new track state

Returns:

The newly added track state

template<TrackProxyConcept track_proxy_t>
inline void copyFrom(const track_proxy_t &other)
requires (!ReadOnly)

Create a complete deep copy of another track, including all track states.

This creates new track states in the destination trajectory and copies all data from the source track states. The track state sequence order is preserved.

Implementation details:

• Track states are initially copied in reversed order for efficiency

• The track state links are then updated using reverseTrackStates()

• As a consequence, the resulting track is forward-linked

What gets copied:

• All track-level properties (parameters, covariance, particle hypothesis, etc.)

• Reference surface (shared pointer is copied)

• Track summary data (nMeasurements, nHoles, chi2, etc.)

• All dynamic track columns

• Complete sequence of track states with all their data

• All dynamic track state columns

Result:

• The destination track will have newly created track states

• tipIndex() and stemIndex() will point to the new track states

• Track state indices will be different from the source

• All track state data will be identical to the source

• The track will be forward-linked (stemIndex() will be valid)

Note

Only available if the track proxy is not read-only

Note

Both track containers must have compatible dynamic columns

Template Parameters:

track_proxy_t – the other track proxy’s type

Parameters:

other – The source track proxy to copy from

template<TrackProxyConcept track_proxy_t>
inline void copyFromWithoutStates(const track_proxy_t &other)
requires (!ReadOnly)

Copy track-level properties from another track, but not the track states.

This copies all track metadata and properties but leaves the track state sequence unchanged. Useful when you want to copy track properties to an existing track that may already have track states.

What gets copied:

• Track parameters at reference surface

• Covariance matrix at reference surface

• Particle hypothesis

• Reference surface (shared pointer is copied)

• Track summary data (nMeasurements, nHoles, nOutliers, nSharedHits, chi2, nDoF)

• All dynamic track columns

What does NOT get copied:

• Track states (existing track states remain unchanged in the container)

Result:

• All track-level properties are updated to match the source

• tipIndex() and stemIndex() are set to kInvalid (track states become inaccessible)

• Existing track states remain in the container but are no longer linked to this track

• nTrackStates() will return 0 due to invalid indices

Note

Only available if the track proxy is not read-only

Note

Both track containers must have compatible dynamic columns

Template Parameters:

track_proxy_t – the other track proxy’s type

Parameters:

other – The source track proxy to copy properties from

template<TrackProxyConcept track_proxy_t>
inline void copyFromShallow(const track_proxy_t &other)
requires (!ReadOnly)

Create a shallow copy from another track, sharing the same track states.

This copies all track-level properties and makes the destination track point to the same track state sequence as the source. The track states themselves are not duplicated - both tracks will reference the same track state objects in memory.

What gets copied:

• All track-level properties (parameters, covariance, particle hypothesis, etc.)

• Reference surface (shared pointer is copied)

• Track summary data (nMeasurements, nHoles, chi2, etc.)

• All dynamic track columns

• tipIndex() and stemIndex() (track state linking information)

What gets shared (not duplicated):

• Track states (both tracks reference the same track state objects)

Result:

• The destination track will have the same nTrackStates() as the source

• Both tracks will iterate over the same track state sequence

• Modifications to track states will be visible in both tracks

• Track state indices will be identical between tracks

• The destination track will have a different track index than the source

Note

Only available if the track proxy is not read-only

Note

Both track containers must have compatible dynamic columns

Warning

Modifying track states through either track will affect both tracks since they share the same track state objects

Warning

It is the user’s responsibility to ensure that the tip and stem indices from the source track are valid in the destination track’s track state container. No validation is performed - invalid indices will lead to undefined behavior when accessing track states

Template Parameters:

track_proxy_t – the other track proxy’s type

Parameters:

other – The source track proxy to create a shallow copy from

inline void reverseTrackStates(bool invertJacobians = false)
requires (!ReadOnly)

Reverse the ordering of track states for this track Afterwards, the previous endpoint of the track state sequence will be the “innermost” track state.

Note

Only available if the track proxy is not read-only

Note

This is dangerous with branching track state sequences, as it will break them

Note

This also automatically forward-links the track!

Parameters:

invertJacobians – Whether to invert the Jacobians of the track states

TrackProxy generic component access

Methods that give access to generic components of a track represented by TrackProxy.

Internally, a compile-time hash of the component name is used to identify which component is being requested. Most of the named methods in TrackProxy properties use these methods to retrieve the actual data.

A number of overloads exist, where you can either supply the HashedString key as a template parameter or a runtime argument. The former has the advantage of being guaranteed to be evaluated at compile-time.

template<typename T, HashedString key>
inline constexpr T &component()
requires (!ReadOnly)

Retrieve a mutable reference to a component.

Template Parameters:

• T – The type of the component to access

• key – String key for the component to access

Returns:

Mutable reference to the component given by key

template<typename T>
inline constexpr T &component(HashedString key)
requires (!ReadOnly)

Retrieve a mutable reference to a component.

Template Parameters:

T – The type of the component to access

Parameters:

key – String key for the component to access

Returns:

Mutable reference to the component given by key

template<typename T>
inline constexpr T &component(std::string_view key)
requires (!ReadOnly)

Retrieve a mutable reference to a component.

Note

This might hash the key at runtime instead of compile-time

Template Parameters:

T – The type of the component to access

Parameters:

key – String key for the component to access

Returns:

Mutable reference to the component given by key

template<typename T, HashedString key>
inline constexpr const T &component() const

Retrieve a const reference to a component.

Template Parameters:

• T – The type of the component to access

• key – String key for the component to access

Returns:

Const reference to the component given by key

inline bool hasColumn(HashedString key) const

Check whether a dynamic column exists.

Parameters:

key – String key for the component to check

Returns:

whether the column exists

template<typename T>
inline constexpr const T &component(HashedString key) const

Retrieve a const reference to a component.

Template Parameters:

T – The type of the component to access

Parameters:

key – String key for the component to access

Returns:

Const reference to the component given by key

template<typename T>
inline constexpr const T &component(std::string_view key) const

Retrieve a const reference to a component.

Note

This might hash the key at runtime instead of compile-time

Template Parameters:

T – The type of the component to access

Parameters:

key – String key for the component to access

Returns:

Const reference to the component given by key

Public Types

using ConstCovariance = typename detail_tsp::FixedSizeTypes<eBoundSize, true>::CovarianceMap

Same as Covariance, but with const semantics.

using ConstParameters = typename detail_tsp::FixedSizeTypes<eBoundSize, true>::CoefficientsMap

Same as Parameters, but with const semantics.

using ConstProxyType = ConstTrackProxy

Alias for an associated const track proxy, with the same backends.

using ConstTrackProxy = TrackProxy<track_container_t, trajectory_t, holder_t, true>

Alias for the const version of this track proxy, with the same backends.

using ConstTrackStateProxy = typename Trajectory::ConstTrackStateProxy

Alias for an associated const track state proxy, with the same backends.

using Container = track_container_t

The track container backend given as a template parameter.

using Covariance = typename detail_tsp::FixedSizeTypes<eBoundSize, false>::CovarianceMap

Map-type for a bound covariance.

This has reference semantics, i.e. points at a matrix by an internal pointer.

using IndexType = TrackIndexType

The index type of the track container.

using MutableTrackProxy = TrackProxy<track_container_t, trajectory_t, holder_t, false>

Alias for the mutable version of this track proxy, with the same backends.

using Parameters = typename detail_tsp::FixedSizeTypes<eBoundSize, false>::CoefficientsMap

Map-type for a bound parameter vector.

This has reference semantics, i.e. points at a matrix by an internal pointer.

using TrackStateProxy = typename Trajectory::TrackStateProxy

Alias for an associated mutable track state proxy, with the same backends.

using Trajectory = trajectory_t

The track state container backend given as a template parameter.

Public Functions

inline const auto &container() const

Return a reference to the track container backend, const version.

Returns:

reference to the track container backend

inline auto &container()
requires (!ReadOnly)

Return a reference to the track container backend, mutable version.

Note

Only available if the track proxy is not read-only

Returns:

reference to the track container backend

inline BoundTrackParameters createParametersAtReference() const

Return the track parameters at the reference surface.

Note

The parameters are created on the fly

Returns:

the track parameters

inline BoundTrackParameters createParametersFromState(const ConstTrackStateProxy &trackState) const

Convert a track state into track parameters.

Note

The parameters are created on the fly

Parameters:

trackState – Track state to convert to parameters

Returns:

the track parameters

inline bool operator==(const TrackProxy &other) const

Equality operator with another track proxy Checks the container identity and the track index.

Parameters:

other – Other track proxy to compare with

Returns:

True if the track proxies refer to the same track

Public Static Attributes

static constexpr IndexType kInvalid = kTrackIndexInvalid

Sentinel value that indicates an invalid index.

static constexpr bool ReadOnly = read_only

Indicates whether this track proxy is read-only or if it can be modified.

template<typename trajectory_t, std::size_t M, bool read_only = true>
class TrackStateProxy : public Acts::TrackStateProxyCommon<TrackStateProxy<trajectory_t, M, true>, true>

Proxy object to access a single point on the trajectory.

Template Parameters:

• SourceLink – Type to link back to an original measurement

• M – Maximum number of measurement dimensions

• read_only – true for read-only access to underlying storage

Constructors and assignment operator

Public constructors and assignment operators for TrackStateProxy only allow construction from another TrackStateProxy. You should generally not have to construct TrackStateProxy manually.

TrackStateProxy(const TrackStateProxy &other) = default

Copy constructor: const to const or mutable to mutable.

Parameters:

other – The other TrackStateProxy to construct from

TrackStateProxy &operator=(const TrackStateProxy &other) = default

Copy assignment operator: const to const or mutable to mutable.

Parameters:

other – The other TrackStateProxy to assign from

Returns:

Reference to this TrackStateProxy

inline explicit TrackStateProxy(const TrackStateProxy<Trajectory, M, false> &other)
requires ReadOnly

Constructor from mutable TrackStateProxy.

Note

Only available if the track state proxy is read-only

Parameters:

other – The other TrackStateProxy to construct from

inline TrackStateProxy &operator=(const TrackStateProxy<Trajectory, M, false> &other)
requires ReadOnly

Assignment operator to from mutable TrackStateProxy.

Note

Only available if the track state proxy is read-only

Parameters:

other – The other TrackStateProxy to assign from

Returns:

Reference to this TrackStateProxy

Track state properties

Properties of the track state represented by TrackStateProxy.

Many of these methods come in a const and a non-const version. The non-const version is only available if you have an instance of TrackStateProxy that does not have the read_only template parameter set to true, even if you hold it as an lvalue.

The track states each have an index in the track state container. The sequence of track states is implemented as a one or two-way linked list, which uses indices into the same container.

Each track state has a previous index, which points at the track state immediately preceding. A track state with a previous index of kInvalid is the first (innermost) track state in a track or track candidate. This is also referred to as a stem at the track level.

During track finding and fitting, track states are usually appended to the sequence, populating the previous index of the new track state. Combinatorial track finding can produce track states which fork in this way, by having more than one track state with the same previous index.

The track states have static, optional and dynamic properties. Static properties are always present, and can always be retrieved. Optional components use an extra indirection mechanism that coordinates with the backend to allow both not having the component set, or sharing it with other track states. An example is a branching trajectory from track finding which shares the same predicted parameter vector and associated covariance.

Optional components are

• predicted parameters and covariance

• filtered parameters and covariance

• smoothed parameters and covariance

• jacobian

• calibrated measurement info including projector

They can be unset via unset, getMask can be used to check which components are present. The first four are shareable between track states via shareFrom.

inline IndexType index() const

Index within the trajectory.

Returns:

the index

inline void unset(TrackStatePropMask target)
requires (!ReadOnly)

Unset an optional track state component.

Note

Only available if the track state proxy is not read-only

Parameters:

target – The component to unset

inline void addComponents(TrackStatePropMask mask)
requires (!ReadOnly)

Add additional components to the track state.

Note

Only available if the track state proxy is not read-only

Parameters:

mask – The bitmask that instructs which components to allocate

inline const Surface &referenceSurface() const

Reference surface.

Returns:

the reference surface

inline bool hasReferenceSurface() const

Returns if the track state has a non nullptr surface associated.

Returns:

whether a surface exists or not

inline void setReferenceSurface(std::shared_ptr<const Surface> srf)
requires (!ReadOnly)

Set the reference surface to a given value.

Note

This overload is only present in case ReadOnly is false.

Parameters:

srf – Shared pointer to the surface to set

Track state measurement properties

Properties of the measurement associated with the track state represented. This consists of a vector and an associated square matrix of a measurement dimension which is between one and the size of the track parametrization. The measurement coordinate frame is required to be a strict subset of the bound track parametrization on the local geometry coordinate frame, i.e. using a pure projector matrix to convert from the bound parametrization to the measurement frame is possible.

The track state stores the parameter vector and covariance, and the backend is given the possibility to do so in a jagged way, i.e. only storing the number of values needed. This requires calling allocateCalibrated before storing the measurements (even if it might be a no-op).

The projector matrix is packed as a bitset, which is converted to a matrix on-demand (and therefore returned by value).

The track state also includes a SourceLink which acts as a proxy to the original uncalibrated measurement that the calibrated measurement was derived from. It is set and returned by value, to allow unpacking / repacking by the backend, if needed.

SourceLink getUncalibratedSourceLink() const

Uncalibrated measurement in the form of a source link.

Const version

Returns:

The uncalibrated measurement source link

inline void setUncalibratedSourceLink(SourceLink &&sourceLink)
requires (!ReadOnly)

Set an uncalibrated source link.

Parameters:

sourceLink – The uncalibrated source link to set

inline IndexType calibratedSize() const

Return the (dynamic) number of dimensions stored for this measurement.

Note

Depending on the backend, this size is used to determine the memory range of the measurement vector and covariance.

Returns:

The number of dimensions

inline void allocateCalibrated(std::size_t measdim)
requires (!ReadOnly)

Allocate storage to be able to store a measurement of size measdim.

This must be called before setting the measurement content.

Note

This does not allocate if an allocation of the same size already exists

Note

This will zero-initialize the allocated storage

Note

This is an error if an existing allocation has different size

Parameters:

measdim – Number of measurement dimensions to allocate

Sharing and copying

Methods to share and copy track state components. Sharing means setting up more than one track state to point to the same component.

Shareable components are

• predicted parameters and covariance

• filtered parameters and covariance

• smoothed parameters and covariance

• jacobian

See TrackStatePropMask.

inline void shareFrom(TrackStatePropMask shareSource, TrackStatePropMask shareTarget)
requires (!ReadOnly)

Share a shareable component within this track state.

Parameters:

• shareSource – Which component to share from

• shareTarget – Which component to share as. This should be different from as shareSource, e.g. predicted can be shared as filtered.

template<bool ReadOnlyOther>
inline void shareFrom(const TrackStateProxy<Trajectory, M, ReadOnlyOther> &other, TrackStatePropMask component)
requires (!ReadOnly)

Share a shareable component from another track state.

Note

The track states both need to be stored in the same MultiTrajectory instance

Parameters:

• other – Track state proxy to share component from

• component – Which component to share.

template<bool ReadOnlyOther>
inline void shareFrom(const TrackStateProxy<Trajectory, M, ReadOnlyOther> &other, TrackStatePropMask shareSource, TrackStatePropMask shareTarget)
requires (!ReadOnly)

Share a shareable component from another track state.

Note

Shareable components are predicted, filtered, smoothed, calibrated, jacobian, or projector. See TrackStatePropMask.

Parameters:

• other – Track state proxy to share component(s) from

• shareSource – Which component to share from

• shareTarget – Which component to share as. This can be be different from as shareSource, e.g. predicted can be shared as filtered.

template<TrackStateProxyConcept track_state_proxy_t>
inline void copyFrom(const track_state_proxy_t &other, TrackStatePropMask mask = TrackStatePropMask::All, bool onlyAllocated = true)
requires (!ReadOnly)

Copy the contents of another track state proxy into this one.

Note

If the this track state proxy does not have compatible allocations with the source track state proxy, and onlyAllocated is false, an exception is thrown.

Note

The mask parameter will not cause a copy of components that are not allocated in the source track state proxy.

Parameters:

• other – The other track state to copy from

• mask – An optional mask to determine what to copy from

• onlyAllocated – Whether to only copy allocated components

Track state proxy Generic component access

template<HashedString key>
inline constexpr bool has() const

Check if a component is set.

Template Parameters:

key – Hashed string key to check for

Returns:

true if the component exists, false if not

inline constexpr bool has(HashedString key) const

Check if a component is set.

Parameters:

key – Hashed string key to check for

Returns:

true if the component exists, false if not

inline constexpr bool has(std::string_view key) const

Check if a component is set.

Note

This might hash the key at runtime instead of compile-time

Parameters:

key – String key to check for

Returns:

true if the component exists, false if not

template<typename T, HashedString key>
inline constexpr T &component()
requires (!ReadOnly)

Retrieve a mutable reference to a component.

Template Parameters:

• T – The type of the component to access

• key – String key for the component to access

Returns:

Mutable reference to the component given by key

template<typename T>
inline constexpr T &component(HashedString key)
requires (!ReadOnly)

Retrieve a mutable reference to a component.

Template Parameters:

T – The type of the component to access

Parameters:

key – String key for the component to access

Returns:

Mutable reference to the component given by key

template<typename T>
inline constexpr T &component(std::string_view key)
requires (!ReadOnly)

Retrieve a mutable reference to a component.

Note

This might hash the key at runtime instead of compile-time

Template Parameters:

T – The type of the component to access

Parameters:

key – String key for the component to access

Returns:

Mutable reference to the component given by key

template<typename T, HashedString key>
inline constexpr const T &component() const

Retrieve a const reference to a component.

Template Parameters:

• T – The type of the component to access

• key – String key for the component to access

Returns:

Const reference to the component given by key

template<typename T>
inline constexpr const T &component(HashedString key) const

Retrieve a const reference to a component.

Template Parameters:

T – The type of the component to access

Parameters:

key – String key for the component to access

Returns:

Const reference to the component given by key

template<typename T>
inline constexpr const T &component(std::string_view key) const

Retrieve a const reference to a component.

Note

This might hash the key at runtime instead of compile-time

Template Parameters:

T – The type of the component to access

Parameters:

key – String key for the component to access

Returns:

Const reference to the component given by key

Public Types

template<std::size_t N>
using Calibrated = typename TrackStateTraits<N, false>::Calibrated

Map-type for a calibrated measurement vector, where the local measurement dimension is variable.

template<std::size_t N>
using CalibratedCovariance = typename TrackStateTraits<N, false>::CalibratedCovariance

Map-type for a calibrated measurement covariance matrix, where the local measurement dimension is variable.

template<std::size_t N>
using ConstCalibrated = typename TrackStateTraits<N, true>::Calibrated

Same as Calibrated, but with const semantics.

template<std::size_t N>
using ConstCalibratedCovariance = typename TrackStateTraits<N, true>::CalibratedCovariance

Same as CalibratedCovariance, but with const semantics.

using ConstCovariance = typename TrackStateTraits<M, true>::Covariance

Same as Covariance, but with const semantics.

using ConstEffectiveCalibrated = typename TrackStateTraits<M, true>::EffectiveCalibrated

Same as EffectiveCalibrated, but with const semantics.

using ConstEffectiveCalibratedCovariance = typename TrackStateTraits<M, true>::EffectiveCalibratedCovariance

Same as EffectiveCalibratedCovariance, but with const semantics.

using ConstJacobian = typename TrackStateTraits<M, true>::Covariance

Jacobian shape is identical to Covariance.

using ConstParameters = typename TrackStateTraits<M, true>::Parameters

Same as Parameters, but with const semantics.

using ConstProxyType = TrackStateProxy<trajectory_t, M, true>

Alias for an associated const track state proxy, with the same backends.

using Covariance = typename TrackStateTraits<M, false>::Covariance

Map-type for a bound covariance.

This has reference semantics, i.e. points at a matrix by an internal pointer.

using EffectiveCalibrated = typename TrackStateTraits<M, false>::EffectiveCalibrated

Map-type for a measurement vector, where the local measurement dimension is variable.

using EffectiveCalibratedCovariance = typename TrackStateTraits<M, false>::EffectiveCalibratedCovariance

Map-type for a measurement covariance matrix, where the local measurement dimension is variable.

using IndexType = TrackIndexType

The index type of the track state container.

using Jacobian = typename TrackStateTraits<M, false>::Covariance

Jacobian shape is identical to Covariance.

using Parameters = typename TrackStateTraits<M, false>::Parameters

Map-type for a bound parameter vector.

This has reference semantics, i.e. points at a matrix by an internal pointer.

using Trajectory = trajectory_t

The track state container backend given as a template parameter.

Public Functions

template<typename val_t, typename cov_t> inline void allocateCalibrated (const Eigen::DenseBase< val_t > &val, const Eigen::DenseBase< cov_t > &cov) requires(!read_only &&Concepts

Allocate and initialize calibrated data from static-size Eigen objects.

Template Parameters:

• val_t – Eigen vector type holding calibrated values.

• cov_t – Eigen matrix type holding the covariance.

Parameters:

• val – Vector to copy into the calibrated storage.

• cov – Covariance matrix to copy into the calibrated storage.

template<std::size_t measdim>
inline TrackStateTraits<measdim, true>::Calibrated calibrated() const

Access calibrated measurement data with compile-time dimension.

Template Parameters:

measdim – Measurement dimension.

Returns:

Eigen map referencing the calibrated measurement vector.

template<std::size_t measdim>
inline TrackStateTraits<measdim, false>::Calibrated calibrated()
requires (!read_only)

Access calibrated measurement data with compile-time dimension.

Template Parameters:

measdim – Measurement dimension.

Returns:

Mutable Eigen map referencing the calibrated measurement vector.

template<std::size_t measdim>
inline TrackStateTraits<measdim, true>::CalibratedCovariance calibratedCovariance() const

Access calibrated covariance data with compile-time dimension.

Template Parameters:

measdim – Measurement dimension.

Returns:

Eigen map referencing the covariance matrix.

template<std::size_t measdim>
inline TrackStateTraits<measdim, false>::CalibratedCovariance calibratedCovariance()
requires (!read_only)

Access calibrated covariance data with compile-time dimension.

Template Parameters:

measdim – Measurement dimension.

Returns:

Mutable Eigen map referencing the covariance matrix.

inline float chi2() const

Retrieve the local chi2 contribution.

Returns:

Chi2 value associated with this state.

inline float &chi2()
requires (!read_only)

Retrieve a mutable reference to the local chi2 contribution.

Returns:

Mutable chi2 value.

inline const auto &container() const

Get a const reference to the track state container backend.

Returns:

a const reference to the backend

inline auto &container()
requires (!ReadOnly)

Get a mutable reference to the track state container backend.

Returns:

a mutable reference to the backend

inline ConstCovarianceMap covariance() const

Access the best available covariance (smoothed, filtered, or predicted).

Returns:

Bound covariance map for the state.

inline ConstEffectiveCalibratedMap effectiveCalibrated() const

Access the calibrated measurement values with runtime dimension.

Returns:

Eigen map referencing the calibrated measurement vector.

inline EffectiveCalibratedMap effectiveCalibrated()
requires (!read_only)

Access mutable calibrated measurement values with runtime dimension.

Returns:

Eigen map referencing the calibrated measurement vector.

inline ConstEffectiveCalibratedCovarianceMap effectiveCalibratedCovariance() const

Access the calibrated covariance with runtime dimension.

Returns:

Eigen map referencing the measurement covariance matrix.

inline EffectiveCalibratedCovarianceMap effectiveCalibratedCovariance()
requires (!read_only)

Access mutable calibrated covariance with runtime dimension.

Returns:

Eigen map referencing the measurement covariance matrix.

inline ConstParametersMap filtered() const

Access the filtered parameter vector.

Returns:

Bound parameter map for the filtered state.

inline ParametersMap filtered()
requires (!read_only)

Access the filtered parameter vector.

Returns:

Mutable bound parameter map for the filtered state.

inline ConstCovarianceMap filteredCovariance() const

Access the filtered covariance matrix.

Returns:

Bound covariance map for the filtered state.

inline CovarianceMap filteredCovariance()
requires (!read_only)

Access the filtered covariance matrix.

Returns:

Mutable bound covariance map for the filtered state.

inline TrackStatePropMask getMask() const

Compute the property mask describing which components are present.

Returns:

Bit mask of available properties.

inline bool hasCalibrated() const

Check for presence of calibrated measurement data.

Returns:

True if calibrated measurements exist.

inline bool hasColumn(HashedString key) const

Check if the track state has a specific dynamic column.

Parameters:

key – The hashed column key

Returns:

true if the column exists

inline bool hasFiltered() const

Check for presence of filtered track parameters.

Returns:

True if the filtered component exists.

inline bool hasJacobian() const

Check for presence of a transport Jacobian.

Returns:

True if a Jacobian is stored.

inline bool hasPredicted() const

Check for presence of predicted track parameters.

Returns:

True if the predicted component exists.

inline bool hasPrevious() const

Check whether this state links to a previous state.

Returns:

True if the previous index is valid.

inline bool hasProjector() const

Check for presence of a measurement projector.

Returns:

True if projector indices are stored.

inline bool hasSmoothed() const

Check for presence of smoothed track parameters.

Returns:

True if the smoothed component exists.

inline ConstCovariance jacobian() const

Returns the jacobian from the previous trackstate to this one.

Note

Const version

Returns:

The jacobian matrix

inline Covariance jacobian()
requires (!ReadOnly)

Returns the jacobian from the previous trackstate to this one.

Note

Mutable version

Returns:

The jacobian matrix

inline ConstParametersMap parameters() const

Access the best available parameters (smoothed, filtered, or predicted).

Returns:

Bound parameter map for the state.

inline double pathLength() const

Retrieve the accumulated path length.

Returns:

Path length stored on the state.

inline double &pathLength()
requires (!read_only)

Retrieve a mutable reference to the accumulated path length.

Returns:

Mutable path length.

inline ConstParametersMap predicted() const

Access the predicted parameter vector.

Returns:

Bound parameter map for the predicted state.

inline ParametersMap predicted()
requires (!read_only)

Access the predicted parameter vector.

Returns:

Mutable bound parameter map for the predicted state.

inline ConstCovarianceMap predictedCovariance() const

Access the predicted covariance matrix.

Returns:

Bound covariance map for the predicted state.

inline CovarianceMap predictedCovariance()
requires (!read_only)

Access the predicted covariance matrix.

Returns:

Mutable bound covariance map for the predicted state.

inline TrackIndexType previous() const

Retrieve the previous track state index in the linked trajectory.

Returns:

Index of the previous state or kTrackIndexInvalid.

inline TrackIndexType &previous()
requires (!read_only)

Retrieve a mutable reference to the previous track state index.

Returns:

Mutable index of the previous state.

template<std::size_t measdim>
inline FixedBoundSubspaceHelper<measdim> projectorSubspaceHelper() const

Creates a fixed size subspace helper.

Returns:

The subspace helper

inline VariableBoundSubspaceHelper projectorSubspaceHelper() const

Creates a variable size subspace helper.

Returns:

The subspace helper

template<std::size_t measdim>
inline SubspaceIndices<measdim> projectorSubspaceIndices() const

Returns the projector subspace indices.

Returns:

The projector subspace indices

inline BoundSubspaceIndices projectorSubspaceIndices() const

Decode the measurement projector indices.

Returns:

Bound parameter indices used for projection.

template<std::ranges::sized_range index_range_t> inline void setProjectorSubspaceIndices (const index_range_t &subspaceIndices) requires(!read_only &&std

Store subspace indices describing the measurement projector.

Template Parameters:

index_range_t – Range of indices to encode.

Parameters:

subspaceIndices – Collection of bound indices forming the projector rows.

inline ConstParametersMap smoothed() const

Access the smoothed parameter vector.

Returns:

Bound parameter map for the smoothed state.

inline ParametersMap smoothed()
requires (!read_only)

Access the smoothed parameter vector.

Returns:

Mutable bound parameter map for the smoothed state.

inline ConstCovarianceMap smoothedCovariance() const

Access the smoothed covariance matrix.

Returns:

Bound covariance map for the smoothed state.

inline CovarianceMap smoothedCovariance()
requires (!read_only)

Access the smoothed covariance matrix.

Returns:

Mutable bound covariance map for the smoothed state.

inline const MultiTrajectory<Trajectory> &trajectory() const

Return a const reference to the underlying backend container.

Returns:

A const reference to the backend container

inline MultiTrajectory<Trajectory> &trajectory()
requires (!ReadOnly)

Return a mutable reference to the underlying backend container.

Returns:

A reference to the backend container

inline ConstTrackStateTypeMap typeFlags() const

Retrieve the track-state type flags.

Returns:

Bit mask describing the state type.

inline MutableTrackStateTypeMap typeFlags()
requires (!read_only)

Retrieve mutable track-state type flags.

Returns:

Mutable bit mask describing the state type.

Public Static Attributes

static constexpr IndexType kInvalid = kTrackIndexInvalid

Sentinel value that indicates an invalid index.

static constexpr bool ReadOnly = read_only

Indicates whether this track state proxy is read-only or if it can be modified.

Friends

friend class Acts::MultiTrajectory< Trajectory >

class TrackingGeometry

The TrackingGeometry class is the owner of the constructed TrackingVolumes.

It enables both, a global search for an asociatedVolume (respectively, if existing, a global search of an associated Layer or the next associated Layer), such as a continuous navigation by BoundarySurfaces between the confined TrackingVolumes.

Public Types

enum class GeometryVersion

Which type of geometry this represents: Gen1 or Gen3.

Values:

enumerator Gen1

enumerator Gen3

Public Functions

explicit TrackingGeometry(const std::shared_ptr<TrackingVolume> &highestVolume, const IMaterialDecorator *materialDecorator = nullptr, const GeometryIdentifierHook &hook = {}, const Logger &logger = getDummyLogger(), bool close = true)

Constructor.

Parameters:

• highestVolume – is the world volume

• materialDecorator – is a dediated decorator that can assign surface or volume based material to the TrackingVolume

• hook – Identifier hook to be applied to surfaces

• logger – instance of a logger (defaulting to the “silent” one)

• close – If true, run the Gen1 geometry closure

~TrackingGeometry()

Destructor.

template<typename Callable> inline void apply (Callable &&callable) const requires(detail

Apply an arbitrary callable as a visitor to the tracking volume.

Note

The visitor can be overloaded on any of the arguments that the methods in TrackingGeometryMutableVisitor receive.

Parameters:

callable – The callable to apply

template<typename Callable> inline void apply (Callable &&callable) requires(detail

Apply an arbitrary callable as a visitor to the tracking volume.

Note

The visitor can be overloaded on any of the arguments that the methods in TrackingGeometryVisitor receive.

Parameters:

callable – The callable to apply

void apply(TrackingGeometryMutableVisitor &visitor)

Apply a visitor to the tracking volume.

Parameters:

visitor – The visitor to apply

void apply(TrackingGeometryVisitor &visitor) const

Apply a visitor to the tracking volume.

Parameters:

visitor – The visitor to apply

const Layer *associatedLayer(const GeometryContext &gctx, const Vector3 &gp) const

Forward the associated Layer information.

Parameters:

• gctx – is the context for this request (e.g. alignment)

• gp – is the global position of the call

Returns:

plain pointer to assocaiated layer

const Surface *findSurface(GeometryIdentifier id) const

Search for a surface with the given identifier.

Parameters:

id – is the geometry identifier of the surface

Return values:

• nullptr – if no such surface exists

• pointer – to the found surface otherwise.

const TrackingVolume *findVolume(GeometryIdentifier id) const

Search for a volume with the given identifier.

Parameters:

id – is the geometry identifier of the volume

Return values:

• nullptr – if no such volume exists

• pointer – to the found volume otherwise.

const std::unordered_map<GeometryIdentifier, const Surface*> &geoIdSurfaceMap() const

Access to the GeometryIdentifier - Surface association map.

Returns:

Const reference to the geometry ID to surface map

GeometryVersion geometryVersion() const

Return the generation of this TrackingGeometry

Returns:

the generation of this TrackingGeometry

TrackingVolume *highestTrackingVolume()

Access to the world volume.

Returns:

plain pointer to the world volume

const TrackingVolume *highestTrackingVolume() const

Access to the world volume.

Returns:

plain pointer to the world volume

std::shared_ptr<const TrackingVolume> highestTrackingVolumePtr() const

Access to the world volume.

Returns:

shared pointer to the world volume

const TrackingVolume *lowestTrackingVolume(const GeometryContext &gctx, const Vector3 &gp) const

return the lowest tracking Volume

Parameters:

• gctx – The current geometry context object, e.g. alignment

• gp – is the global position of the call

Returns:

plain pointer to the lowest TrackingVolume

template<SurfaceVisitor visitor_t>
inline void visitSurfaces(visitor_t &&visitor) const

Visit all sensitive surfaces.

Note

If a context is needed for the visit, the visitor has to provide this, e.g. as a private member

Template Parameters:

visitor_t – Type of the callable visitor

Parameters:

visitor – The callable. Will be called for each sensitive surface that is found, a selection of the surfaces can be done in the visitor

template<SurfaceVisitor visitor_t>
inline void visitSurfaces(visitor_t &&visitor, bool restrictToSensitives) const

Visit all reachable surfaces.

Note

If a context is needed for the visit, the visitor has to provide this, e.g. as a private member

Template Parameters:

visitor_t – Type of the callable visitor

Parameters:

• visitor – The callable. Will be called for each reachable surface that is found, a selection of the surfaces can be done in the visitor

• restrictToSensitives – If true, only sensitive surfaces are visited

template<TrackingVolumeVisitor visitor_t>
inline void visitVolumes(visitor_t &&visitor) const

Visit all reachable tracking volumes.

Note

If a context is needed for the visit, the visitor has to provide this, e.g. as a private member

Template Parameters:

visitor_t – Type of the callable visitor

Parameters:

visitor – The callable. Will be called for each reachable volume that is found, a selection of the volumes can be done in the visitor

void visualize(IVisualization3D &helper, const GeometryContext &gctx, const ViewConfig &viewConfig = s_viewVolume, const ViewConfig &portalViewConfig = s_viewPortal, const ViewConfig &sensitiveViewConfig = s_viewSensitive) const

Visualize a tracking geometry including substructure.

Parameters:

• helper – The visualization helper that implement the output

• gctx – The geometry context

• viewConfig – Global view config

• portalViewConfig – View config for portals

• sensitiveViewConfig – View configuration for sensitive surfaces

class TrackingVolume : public Acts::Volume

Full Volume description used in Tracking, it inherits from Volume to get the geometrical structure.

A TrackingVolume at navigation level can provide the (layer) material

information / internal navigation with in 5 different ways:

--- a) Static confinement of Layers
--- b) detached sub volumes
--- b) unordered (arbitrarily oriented) layers
--- d) unordered sub volumes
--- e) unordered layers AND unordered subvolumes

The TrackingVolume can also be a simple container of other TrackingVolumes

In addition it is capable of holding a subarray of Layers and TrackingVolumes.

Unnamed Group

const Layer *associatedLayer(const GeometryContext &gctx, const Vector3 &position) const

Interface of TrackingVolume in the Gen1 geometry model.

Note

This interface is being replaced, and is subject to removal Return the associated Layer to the global position

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the associated global position

Returns:

plain pointer to layer object

boost::container::small_vector<NavigationTarget, 10> compatibleLayers(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const NavigationOptions<Layer> &options) const

Resolves the volume into (compatible) Layers.

This is the method for the propagator/extrapolator

Template Parameters:

options_t – Type of navigation options object for decomposition

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – Position for the search

• direction – Direction for the search

• options – The templated navigation options

Returns:

vector of compatible intersections with layers

boost::container::small_vector<NavigationTarget, 4> compatibleBoundaries(const GeometryContext &gctx, const Vector3 &position, const Vector3 &direction, const NavigationOptions<Surface> &options, const Logger &logger = getDummyLogger()) const

Returns all boundary surfaces sorted by the user.

Template Parameters:

• options_t – Type of navigation options object for decomposition

• sorter_t – Type of the boundary surface sorter

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – The position for searching

• direction – The direction for searching

• options – The templated navigation options

• logger – A Logger instance

Returns:

is the templated boundary intersection

const LayerArray *confinedLayers() const

Return the confined static layer array - if it exists.

Returns:

the BinnedArray of static layers if exists

std::shared_ptr<const TrackingVolumeArray> confinedVolumes() const

Return the confined volumes of this container array - if it exists.

Returns:

Shared pointer to array of contained tracking volumes or nullptr

MutableTrackingVolumeVector denseVolumes() const

Return the confined dense volumes.

Returns:

Vector of pointers to dense tracking volumes

const TrackingVolumeBoundaries &boundarySurfaces() const

Method to return the BoundarySurfaces.

Returns:

Reference to vector of boundary surface pointers

void assignBoundaryMaterial(std::shared_ptr<const ISurfaceMaterial> surfaceMaterial, BoundarySurfaceFace bsFace)

Set the boundary surface material description.

The material is usually derived in a complicated way and loaded from a framework given source. As various volumes could potentially share the the same material description, it is provided as a shared object

Parameters:

• surfaceMaterial – Material description of this volume

• bsFace – Specifies which boundary surface to assign the material to

void glueTrackingVolume(const GeometryContext &gctx, BoundarySurfaceFace bsfMine, TrackingVolume *neighbor, BoundarySurfaceFace bsfNeighbor)

Glue another tracking volume to this one.

• if common face is set the glued volumes are sharing the boundary, down to the last navigation volume

Parameters:

• gctx – The current geometry context object, e.g. alignment

• bsfMine – is the boundary face indicator where to glue

• neighbor – is the TrackingVolume to be glued

• bsfNeighbor – is the boundary surface of the neighbor

void glueTrackingVolumes(const GeometryContext &gctx, BoundarySurfaceFace bsfMine, const std::shared_ptr<TrackingVolumeArray> &neighbors, BoundarySurfaceFace bsfNeighbor)

Glue another tracking volume to this one.

• if common face is set the glued volumes are sharing the boundary, down to the last navigation volume

Parameters:

• gctx – The current geometry context object, e.g. alignment

• bsfMine – is the boundary face indicator where to glue

• neighbors – are the TrackingVolumes to be glued

• bsfNeighbor – are the boundary surface of the neighbors

void updateBoundarySurface(BoundarySurfaceFace bsf, std::shared_ptr<const BoundarySurfaceT<TrackingVolume>> bs, bool checkmaterial = true)

Provide a new BoundarySurface from the glueing.

Parameters:

• bsf – is the boundary face indicator where to glue

• bs – is the new boundary surface

• checkmaterial – is a flag how to deal with material, if true:

  • if the old boundary surface had a material description but the new one has not, keep the current one

  • in all other cases just assign the new boundary surface

void registerGlueVolumeDescriptor(std::unique_ptr<GlueVolumesDescriptor> gvd)

Register the outside glue volumes - ordering is in the TrackingVolume Frame:

• negativeFaceXY

• (faces YZ, ZY, radial faces)

• positiveFaceXY

Parameters:

gvd – register a new GlueVolumeDescriptor

void clearBoundarySurfaces()

Clear boundary surfaces for this tracking volume.

GlueVolumesDescriptor &glueVolumesDescriptor()

Register the outside glue volumes - ordering is in the TrackingVolume Frame:

• negativeFaceXY

• (faces YZ, ZY, radial faces)

• positiveFaceXY

Returns:

Reference to the glue volumes descriptor

void visualize(IVisualization3D &helper, const GeometryContext &gctx, const ViewConfig &viewConfig, const ViewConfig &portalViewConfig, const ViewConfig &sensitiveViewConfig) const

Produces a 3D visualization of this tracking volume.

Parameters:

• helper – The visualization helper describing the output format

• gctx – The geometry context

• viewConfig – The view configuration

• portalViewConfig – View configuration for portals

• sensitiveViewConfig – View configuration for sensitive surfaces

const INavigationPolicy *navigationPolicy() const

Access the navigation policy if any that is registered on this volume.

Returns:

a pointer to the navigation policy, or nullptr if none is set

INavigationPolicy *navigationPolicy()

Access the navigation policy if any that is registered on this volume.

Returns:

a pointer to the navigation policy, or nullptr if none is set

void setNavigationPolicy(std::unique_ptr<INavigationPolicy> policy)

Register a navigation policy with this volume.

The argument can not be nullptr.

Parameters:

policy – is the navigation policy to be registered

void initializeNavigationCandidates(const GeometryContext &gctx, const NavigationArguments &args, NavigationPolicyState &state, AppendOnlyNavigationStream &stream, const Logger &logger) const

Populate the navigation stream with navigation candidates from this volume.

Internally, this consults the registered navigation policy, where the default is a noop.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• args – are the navigation arguments

• state – is the navigation policy state

• stream – is the navigation stream to be updated

• logger – is the logger

Public Types

using MutablePortalRange = detail::TransformRange<detail::Dereference, std::vector<std::shared_ptr<Portal>>>

Type alias for mutable range of portals in tracking volume.

using MutableSurfaceRange = detail::TransformRange<detail::Dereference, std::vector<std::shared_ptr<Surface>>>

Type alias for mutable range of surfaces in tracking volume.

using MutableVolumeRange = detail::TransformRange<detail::Dereference, std::vector<std::unique_ptr<TrackingVolume>>>

Type alias for mutable range of tracking volumes in container.

using PortalRange = detail::TransformRange<detail::ConstDereference, const std::vector<std::shared_ptr<Portal>>>

Type alias for const range of portals in tracking volume.

using SurfaceRange = detail::TransformRange<detail::ConstDereference, const std::vector<std::shared_ptr<Surface>>>

Type alias for const range of surfaces in tracking volume.

using VolumeRange = detail::TransformRange<detail::ConstDereference, const std::vector<std::unique_ptr<TrackingVolume>>>

Type alias for const range of tracking volumes in container.

Public Functions

TrackingVolume() = delete

TrackingVolume(const TrackingVolume&) = delete

TrackingVolume(const Transform3 &transform, std::shared_ptr<VolumeBounds> volbounds, const std::string &volumeName = "undefined")

Constructor for a container Volume.

• vacuum filled volume either as a for other tracking volumes

Parameters:

• transform – is the global 3D transform to position the volume in space

• volbounds – is the description of the volume boundaries

• volumeName – is a string identifier

TrackingVolume(const Transform3 &transform, std::shared_ptr<VolumeBounds> volumeBounds, std::shared_ptr<const IVolumeMaterial> volumeMaterial, std::unique_ptr<const LayerArray> staticLayerArray = nullptr, std::shared_ptr<const TrackingVolumeArray> containedVolumeArray = nullptr, MutableTrackingVolumeVector denseVolumeVector = {}, const std::string &volumeName = "undefined")

Constructor for a full equipped Tracking Volume.

Parameters:

• transform – is the global 3D transform to position the volume in space

• volumeBounds – is the description of the volume boundaries

• volumeMaterial – is are materials of the tracking volume

• staticLayerArray – is the confined layer array (optional)

• containedVolumeArray – are the sub volumes if the volume is a container

• denseVolumeVector – The contained dense volumes

• volumeName – is a string identifier

explicit TrackingVolume(const Volume &volume, const std::string &volumeName = "undefined")

Constructor from a regular volume.

Parameters:

• volume – is the volume to be converted

• volumeName – is a string identifier

TrackingVolume(TrackingVolume&&) noexcept

Move constructor for transferring ownership of tracking volume resources.

TrackingVolume(VolumePlacementBase &placement, std::shared_ptr<VolumeBounds> volbounds, const std::string &volumeName = "undefined")

Constructor for an aligned container volume container Volume.

• vacuum filled volume either as a for other tracking volumes

Parameters:

• placement – is the volume placement object dynamically positioning the volume in space

• volbounds – is the description of the volume boundaries

• volumeName – is a string identifier

~TrackingVolume() override

void addPortal(std::shared_ptr<Portal> portal)

Add a portal to this tracking volume.

Parameters:

portal – The portal to add

void addSurface(std::shared_ptr<Surface> surface)

Add a surface to this tracking volume.

Parameters:

surface – The surface to add

TrackingVolume &addVolume(std::unique_ptr<TrackingVolume> volume)

Add a child volume to this tracking volume.

Note

The volume will have its mother volume assigned to this. It will throw if volume already has a mother volume set

Parameters:

volume – The volume to add

Returns:

Reference to the added volume

template<typename Callable> inline void apply (Callable &&callable) const requires(detail

Apply an arbitrary callable as a visitor to the tracking volume.

Note

The visitor can be overloaded on any of the arguments that the methods in TrackingGeometryMutableVisitor receive.

Parameters:

callable – The callable to apply

template<typename Callable> inline void apply (Callable &&callable) requires(detail

Apply an arbitrary callable as a visitor to the tracking volume.

Note

The visitor can be overloaded on any of the arguments that the methods in TrackingGeometryVisitor receive.

Parameters:

callable – The callable to apply

void apply(TrackingGeometryMutableVisitor &visitor)

Apply a mutable visitor to the tracking volume.

Parameters:

visitor – The visitor to apply

void apply(TrackingGeometryVisitor &visitor) const

Apply a visitor to the tracking volume.

Parameters:

visitor – The visitor to apply

void assignVolumeMaterial(std::shared_ptr<const IVolumeMaterial> material)

Set the volume material description.

The material is usually derived in a complicated way and loaded from a framework given source. As various volumes could potentially share the the same material description, it is provided as a shared object

Parameters:

material – Material description of this volume

const TrackingVolume *lowestTrackingVolume(const GeometryContext &gctx, const Vector3 &position, const double tol = 0.) const

Return the associated sub Volume, returns THIS if no subVolume exists.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• position – is the global position associated with that search

• tol – Search position tolerance for dense volumes

Returns:

plain pointer to associated with the position

TrackingVolume *motherVolume()

Return the MotherVolume - if it exists.

Returns:

Mutable pointer to mother volume or nullptr if this is the root volume

const TrackingVolume *motherVolume() const

Return the MotherVolume - if it exists.

Returns:

Pointer to mother volume or nullptr if this is the root volume

TrackingVolume &operator=(const TrackingVolume&) = delete

TrackingVolume &operator=(TrackingVolume&&) noexcept

Move assignment operator for transferring ownership of tracking volume resources.

Returns:

Reference to this TrackingVolume after move assignment

MutablePortalRange portals()

Return mutable view of the registered portals under this tracking volume.

Returns:

the range of portals

PortalRange portals() const

Return all portals registered under this tracking volume.

Returns:

the range of portals

void setMotherVolume(TrackingVolume *mvol)

Set the MotherVolume.

Parameters:

mvol – is the mother volume

void setVolumeName(std::string_view volumeName)

Set the volume name to volumeName.

Parameters:

volumeName – is the new name of

MutableSurfaceRange surfaces()

Return mutable view of the registered surfaces under this tracking volume.

Returns:

the range of surfaces

SurfaceRange surfaces() const

Return all surfaces registered under this tracking volume.

Returns:

the range of surfaces

template<SurfaceVisitor visitor_t>
inline void visitSurfaces(visitor_t &&visitor) const

Visit all sensitive surfaces.

Note

If a context is needed for the visit, the vistitor has to provide this, e.g. as a private member

Template Parameters:

visitor_t – Type of the callable visitor

Parameters:

visitor – The callable. Will be called for each sensitive surface that is found, a selection of the surfaces can be done in the visitor

template<SurfaceVisitor visitor_t>
inline void visitSurfaces(visitor_t &&visitor, bool restrictToSensitives) const

Visit all reachable surfaces.

Note

If a context is needed for the visit, the vistitor has to provide this, e.g. as a private member

Template Parameters:

visitor_t – Type of the callable visitor

Parameters:

• visitor – The callable. Will be called for each reachable surface that is found, a selection of the surfaces can be done in the visitor

• restrictToSensitives – If true, only sensitive surfaces are visited

template<TrackingVolumeVisitor visitor_t>
inline void visitVolumes(visitor_t &&visitor) const

Visit all reachable tracking volumes.

Note

If a context is needed for the visit, the vistitor has to provide this, e.g. as a private member

Template Parameters:

visitor_t – Type of the callable visitor

Parameters:

visitor – The callable. Will be called for each reachable volume that is found, a selection of the volumes can be done in the visitor

const IVolumeMaterial *volumeMaterial() const

Return the material of the volume.

Returns:

Pointer to volume material or nullptr if no material assigned

const std::shared_ptr<const IVolumeMaterial> &volumeMaterialPtr() const

Return the material of the volume as shared pointer.

Returns:

Shared pointer to volume material

const std::string &volumeName() const

Returns the VolumeName - for debug reason, might be depreciated later.

Returns:

Reference to the volume name string

MutableVolumeRange volumes()

Return mutable view of the registered volumes under this tracking volume.

Returns:

the range of volumes

VolumeRange volumes() const

Return all volumes registered under this tracking volume.

Returns:

the range of volumes

class TrapezoidBounds : public Acts::PlanarBounds

Bounds for a trapezoidal, planar Surface.

Public Types

enum BoundValues

Enumeration for the bound values.

Values:

enumerator eHalfLengthXnegY

enumerator eHalfLengthXposY

enumerator eHalfLengthY

enumerator eRotationAngle

enumerator eSize

Public Functions

explicit TrapezoidBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor for symmetric Trapezoid - from fixed size array.

Parameters:

values – the values to be stream in

explicit TrapezoidBounds(double halfXnegY, double halfXposY, double halfY, double rotAngle = 0.) noexcept(false)

Constructor for symmetric Trapezoid.

Parameters:

• halfXnegY – minimal half length X, definition at negative Y

• halfXposY – maximal half length X, definition at positive Y

• halfY – half length Y - defined at x=0

• rotAngle – rotation angle of the bounds w.r.t coordinate axes

virtual const RectangleBounds &boundingBox() const final

Bounding box parameters.

Returns:

rectangle bounds for a bounding box

virtual Vector2 center() const final

Calculate the center of the surface bounds in local coordinates.

This method returns a representative center point of the bounds region. The exact definition varies by bounds type and coordinate system:

Cartesian bounds (Rectangle, Diamond, Trapezoid):

• Returns the geometric center or center of symmetry

• For symmetric shapes: center of bounding box or origin (0,0)

Polar/Cylindrical bounds (Radial, Cylinder, Cone):

• Returns (r, phi) where r is average radius, phi is average angle

• Coordinates are in the bounds’ natural coordinate system

Complex bounds (Annulus, ConvexPolygon):

• Annulus: Pre-calculated from corner vertices (accounts for coordinate transforms)

• Polygon: Average of all vertices (vertex centroid, not area centroid)

Infinite bounds: Returns conceptual center at (0,0)

Note

The returned point is guaranteed to be a reasonable representative center, but may not be the true geometric centroid for all shapes.

Note

For TrapezoidBounds: returns center of symmetry (0,0), accounting for rotation

Returns:

Vector2 representing the center position in local coordinates

virtual Vector2 closestPoint(const Vector2 &lposition, const SquareMatrix2 &metric) const final

Calculates the closest point on the bounds to a given local position.

Parameters:

• lposition – is the local position

• metric – to be used for the distance calculation

Returns:

the closest point on the bounds

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

The bound value at the specified index

virtual bool inside(const Vector2 &lposition) const final

Inside check for the bounds object.

The orientation of the Trapezoid is according to the figure above, in words: the shorter of the two parallel sides of the trapezoid intersects with the negative \( y \) - axis of the local frame.

The cases are:

(0)

\( y \) or \( x \)

bounds are 0 || 0

(1) the local position is outside

\( y \)

bounds

(2) the local position is inside

\( y \) bounds, but outside maximum \( x \)

bounds

(3) the local position is inside

\( y \) bounds AND inside minimum \( x \)

bounds

(4) the local position is inside

\( y \) bounds AND inside maximum \( x \) bounds, so that it depends on the \( eta \) coordinate (5) the local position fails test of (4)

The inside check is done using single equations of straight lines and one has to take care if a point lies on the positive \( x \) half area(I) or the negative one(II). Denoting \( |x_{min}| \) and \( | x_{max} | \) as minHalfX respectively maxHalfX, such as \( | y_{H} | \) as halfY, the equations for the straing lines in (I) and (II) can be written as:

• (I): \( y = \kappa_{I} x + \delta_{I} \)

• (II): \( y = \kappa_{II} x + \delta_{II} \)

  ,

  where

  \( \kappa_{I} = - \kappa_{II} = 2 \frac{y_{H}}{x_{max} - x_{min}} \) and \( \delta_{I} = \delta_{II} = - \frac{1}{2}\kappa_{I}(x_{max} + x_{min}) \)

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition) const = 0

Inside check for the bounds object.

Parameters:

lposition – is the local position

Returns:

true if the local position is inside the bounds

bool inside(const Vector2 &lposition, const BoundaryTolerance &boundaryTolerance) const

Inside check for the bounds object given a boundary tolerance.

Parameters:

• lposition – is the local position

• boundaryTolerance – is the boundary tolerance object

Returns:

true if the local position is inside the bounds and tolerance

virtual std::ostream &toStream(std::ostream &sl) const final

Output Method for std::ostream.

Parameters:

sl – is the ostream to be dumped into

Returns:

Modified ostream for chaining

inline virtual BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

the bounds type

virtual std::vector<double> values() const final

Access method for bound values, this is a dynamically sized vector containing the parameters needed to describe these bounds.

Returns:

of the stored values for this SurfaceBounds object

virtual std::vector<Vector2> vertices(unsigned int ignoredSegments = 0u) const final

Return the vertices.

Note

the number of segments is ignored in this representation

Parameters:

ignoredSegments – is and ignored parameter used to describe the number of segments to approximate curved sectors.

Returns:

vector for vertices in 2D

class TrapezoidVolumeBounds : public Acts::VolumeBounds

Bounds for a trapezoidal shaped Volume, the orientedSurface(…) method creates a vector of 6 surfaces:

BoundarySurfaceFace [index]:

• negativeFaceXY [0] : Trazpezoidal Acts::PlaneSurface, parallel to \( xy \) plane at negative \(z\)

• positiveFaceXY [1] : Trazpezoidal Acts::PlaneSurface, parallel to \( xy \) plane at positive \(z\)

• trapezoidFaceAlpha [2] : Rectangular Acts::PlaneSurface, attached to [0] and [1] at negative \(x\) (associated to alpha)

• trapezoidFaceBeta [3] : Rectangular Acts::PlaneSurface, attached to [0] and [1] at positive \( x\) (associated to beta)

• negativeFaceZX [4] : Rectangular Acts::PlaneSurface, parallel to \( zx \) plane at negative \(y\)

• positiveFaceZX [5] : Rectangular Acts::PlaneSurface, parallel to \( zx \) plane at positive \(y\)

PositiveZFaceXY--------+          PositiveYFaceZX
                       |                   |
TrapezoidFaceAlpha     |                   v
         |             | +----------------------------------+
         |             v |                                  |
         |    +       +--+------------------------------++  |
         |   /|      /   |                            +-+   |
         |  / |     /    |                          +-+     |           +
     +---+ /  |    /     |                        +-+       |          ++
     |    /   |   /      +----------------------+-+---------+        +-+|
     |   /    |  /                            +-+                  +-+  |
     |  /     + /                           +-+                  +-+    |
     | /     / /                          +-+                  +-+      |
     v/     / /                         +-+                  +-+        +
     /     / /                        +-+                  +-+         +-
    /     / /    +------------------+-+------------++    +-+         +-+
   /     / /    /                 +-+            +-+   +-+         +-+
  /     / /    /                +-+            +-+   +-+         +-+
 /     / +----X-----------------+            +-+   +-+         +-+
+     /      /                             +-+   +-+         +-+
| +--X------X------------+               +-+    -+         +-+
| | /      /             |             +-+     +         +-+
| |/      /              |           +-+       |       +-+  ^
| X      /               |         +-+         |     +-+    |
|/|     /                |       +-+           |   +-+      |
+ |    /                 |     +-+             | +-+        |  z ^   ^ y
  +---X------------------+   +-+  ^            |-+    +-----+    |  /
     /        ^            +-+    |            +      |          | /
    +---------++-----------+      |                   |          |/
               |                  |                   |          X------> x
      NegativeYFaceZX      NegativeZFaceXY            |
                                             TrapezoidFaceBeta

Public Types

enum BoundValues

for access / streaming

Values:

enumerator eHalfLengthXnegY

halflength in x at negative y

enumerator eHalfLengthXposY

halflength in x at positive y

enumerator eHalfLengthY

halflength in y

enumerator eHalfLengthZ

halflength in z

enumerator eAlpha

opening angle alpha (in point A)

enumerator eBeta

opening angle beta (in point B)

enumerator eSize

length of the bounds vector

enum class Face : unsigned int

Enum describing the possible faces of a trapezoidal volume.

Note

These values are synchronized with the BoundarySurfaceFace enum. Once Gen1 is removed, this can be changed.

Values:

enumerator NegativeZFaceXY

enumerator PositiveZFaceXY

enumerator TrapezoidFaceAlpha

enumerator TrapezoidFaceBeta

enumerator NegativeYFaceZX

enumerator PositiveYFaceZX

Public Functions

TrapezoidVolumeBounds() = delete

inline explicit TrapezoidVolumeBounds(const std::array<double, eSize> &values) noexcept(false)

Constructor - from a fixed size array.

Parameters:

values – The bound values

TrapezoidVolumeBounds(const TrapezoidVolumeBounds &trabo) = default

Copy constructor.

Parameters:

trabo – Source trapezoidal volume bounds to copy from

TrapezoidVolumeBounds(double minhalex, double haley, double halez, double alpha, double beta) noexcept(false)

Constructor - the trapezoid boundaries (arbitrary trapezoid)

Parameters:

• minhalex – is the half length in x at minimal y

• haley – is the half length in y

• halez – is the half length in z

• alpha – is the opening angle at -x,-y

• beta – is the opening angle at +x,-y

TrapezoidVolumeBounds(double minhalex, double maxhalex, double haley, double halez) noexcept(false)

Constructor - the trapezoid boundaries (symmetric trapezoid)

Parameters:

• minhalex – is the half length in x at minimal y

• maxhalex – is the half length in x at maximal y

• haley – is the half length in y

• halez – is the half length in z

~TrapezoidVolumeBounds() override = default

Default destructor.

virtual Volume::BoundingBox boundingBox(const Transform3 *trf = nullptr, const Vector3 &envelope = {0, 0, 0}, const Volume *entity = nullptr) const final

Construct bounding box for this shape.

Parameters:

• trf – Optional transform

• envelope – Optional envelope to add / subtract from min/max

• entity – Entity to associate this bounding box with

Returns:

Constructed bounding box

inline double get(BoundValues bValue) const

Access to the bound values.

Parameters:

bValue – the class nested enum for the array access

Returns:

The bound value at the specified index

virtual bool inside(const Vector3 &pos, double tol = 0.) const override

This method checks if position in the 3D volume frame is inside the cylinder.

Parameters:

• pos – is the global position to be checked

• tol – is the tolerance applied

Returns:

boolean indicator if position is inside

TrapezoidVolumeBounds &operator=(const TrapezoidVolumeBounds &trabo) = default

Copy assignment operator.

Parameters:

trabo – Source trapezoidal volume bounds to assign from

Returns:

Reference to this object

virtual std::vector<OrientedSurface> orientedSurfaces(const Transform3 &transform = Transform3::Identity()) const override

Oriented surfaces, i.e.

the decomposed boundary surfaces and the according navigation direction into the volume given the normal vector on the surface

It will throw an exception if the orientation prescription is not adequate

Parameters:

transform – is the 3D transform to be applied to the boundary surfaces to position them in 3D space

Returns:

a vector of surfaces bounding this volume

virtual std::ostream &toStream(std::ostream &os) const override

Output Method for std::ostream.

Parameters:

os – is the output stream

Returns:

Modified ostream for chaining

inline virtual VolumeBounds::BoundsType type() const final

Return the bounds type - for persistency optimization.

Returns:

is a BoundsType enum

virtual std::vector<double> values() const final

Return the bound values as dynamically sized vector.

Returns:

this returns a copy of the internal values

Warning

doxygenclass: Cannot find class “Acts::TryAllNavigator” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

Warning

doxygenclass: Cannot find class “Acts::TryAllOverstepNavigator” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

class VectorMultiTrajectory : public Acts::detail_vmt::VectorMultiTrajectoryBase, public Acts::MultiTrajectory<VectorMultiTrajectory>

In-memory transient multi-trajectory implementation using std::vector as backend.

Public Functions

VectorMultiTrajectory() = default

void reserve(std::size_t n)

Reserve space for track states.

Parameters:

n – Number of track states to reserve space for

inline Statistics statistics() const

Get statistics about memory usage.

Returns:

Statistics object

class Volume : public Acts::GeometryObject

It inherits from GeometryObject for geometry identification.

Base class for all volumes inside the tracking realm, it defines the interface for inherited Volume classes regarding the geometrical information.

Subclassed by Acts::TrackingVolume, Acts::VolumeStack

Public Types

using BoundingBox = AxisAlignedBoundingBox<Volume, double, 3>

Type alias for the axis-aligned bounding box of the volume.

Used to define the spatial extent of the volume in 3D space

Public Functions

Volume(const Transform3 &transform, std::shared_ptr<VolumeBounds> volbounds) noexcept

Explicit constructor with shared arguments.

Parameters:

• transform – is the transform to position the volume in 3D space

• volbounds – is the volume boundary definitions

Volume(const Volume &vol) noexcept = default

Copy Constructor.

Parameters:

vol – is the source volume for the copy

Volume(VolumePlacementBase &positioner, std::shared_ptr<VolumeBounds> volbounds) noexcept

Constructor that connects the volume to an external alignment I.e.

the volume may move with the alignment of the surfaces The placement of the volume is delegated to the positioner

Parameters:

• positioner – Reference to the object aligning the volume

• volbounds – is the volume boundary definitions

~Volume() noexcept override = default

void assignVolumeBounds(std::shared_ptr<VolumeBounds> volbounds)

Set volume bounds and update volume bounding boxes implicitly.

Parameters:

volbounds – The volume bounds to be assigned

BoundingBox boundingBox(const Vector3 &envelope = {0, 0, 0}) const

Construct bounding box for this shape.

Parameters:

envelope – Optional envelope to add / subtract from min/max

Returns:

Constructed bounding box pointing to this volume

Vector3 center(const GeometryContext &gctx) const

Get the center position of the volume.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

Const reference to the center position vector

const Transform3 &globalToLocalTransform(const GeometryContext &gctx) const

Get the transformation matrix from the global experiment’s frame to the local volume frame.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

The global to local transformation matrix

bool inside(const GeometryContext &gctx, const Vector3 &gpos, double tol = 0.) const

Inside() method for checks.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• gpos – is the position to be checked

• tol – is the tolerance parameter

Returns:

boolean indicator if the position is inside

bool isAlignable() const

Is the volume connected to the experiment’s alignment system (I.e.

it’s constructed with a volumePlacement)

Returns:

Whether the volume can be externally aligned

const Transform3 &localToGlobalTransform(const GeometryContext &gctx) const

Get the transformation matrix from the local volume frame to the global experiment’s frame.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

The local to global transformation matrix

Volume &operator=(const Volume &vol) noexcept = default

Assignment operator.

Parameters:

vol – is the source volume to be copied

Returns:

Reference to this volume for assignment chaining

Volume &operator=(Volume &&other) noexcept = default

Move assignment operator.

Parameters:

other – is the other volume to be moved

Returns:

Reference to this volume for assignment chaining

bool operator==(const Volume &other) const

Compare this volume with another for equality.

Parameters:

other – The other volume to compare with

Returns:

True if the volumes are equal

BoundingBox orientedBoundingBox() const

Construct oriented bounding box for this shape.

Note

This will build an oriented bounding box with an envelope value of (0.05, 0.05, 0.05)mm

Returns:

Constructed oriented bounding box pointing to this volume

virtual Vector3 referencePosition(const GeometryContext &gctx, AxisDirection aDir) const override

The binning position method.

• as default the center is given, but may be overloaded

Parameters:

• gctx – The current geometry context object, e.g. alignment

• aDir – is the axis direction for the reference position

Returns:

vector 3D that can be used for the binning

void setTransform(const Transform3 &transform)

Set the transform matrix for the volume and update internal state.

Parameters:

transform – The new transform matrix to be applied

Volume shifted(const GeometryContext &gctx, const Transform3 &shift) const

Shift the volume by a transform.

Parameters:

• shift – is the transform to shift the volume by

• gctx – The current geometry context object, e.g. alignment

Returns:

The shifted volume

virtual void update(const GeometryContext &gctx, std::shared_ptr<VolumeBounds> volbounds, std::optional<Transform3> transform = std::nullopt, const Logger &logger = Acts::getDummyLogger())

Set the volume bounds and optionally also update the volume transform.

Parameters:

• gctx – The current geometry context object, e.g. alignment

• volbounds – The volume bounds to be assigned

• transform – The transform to be assigned, can be optional

• logger – A logger object to log messages

void visualize(IVisualization3D &helper, const GeometryContext &gctx, const ViewConfig &viewConfig) const

Produces a 3D visualization of this volume.

Parameters:

• helper – The visualization helper describing the output format

• gctx – The geometry context

• viewConfig – The view configuration

VolumeBounds &volumeBounds()

Get mutable access to the volume bounds.

Returns:

Reference to the volume bounds object

const VolumeBounds &volumeBounds() const

Get the volume bounds that define the shape of the volume.

Returns:

Const reference to the volume bounds object

std::shared_ptr<VolumeBounds> volumeBoundsPtr()

Get shared pointer to the mutable volume bounds.

Returns:

Shared pointer to the volume bounds object

std::shared_ptr<const VolumeBounds> volumeBoundsPtr() const

Get shared pointer to the const volume bounds.

Returns:

Const shared pointer to the volume bounds object

VolumePlacementBase *volumePlacement()

VolumePlacement object that dynamically aligns the volume.

Returns:

Pointer to the VolumePlacement (Might be nullptr)

const VolumePlacementBase *volumePlacement() const

VolumePlacement object that dynamically aligns the volume.

Returns:

Pointer to the VolumePlacement (Might be nullptr)

class VolumeBounds

Pure Absract Base Class for Volume bounds.

Acts::VolumeBounds are a set of up to six confining Surfaces that are stored in a std::vector. Each type of Acts::VolumeBounds has to implement a orientedSurfaces() and a inside() method.

The Volume, retrieving a set of Surfaces from the VolumeBounds, can turn the Surfaces into BoundarySurfaces.

Subclassed by Acts::ConeVolumeBounds, Acts::CuboidVolumeBounds, Acts::CutoutCylinderVolumeBounds, Acts::CylinderVolumeBounds, Acts::DiamondVolumeBounds, Acts::GenericCuboidVolumeBounds, Acts::TrapezoidVolumeBounds

Public Types

enum class BoundsType

This is nested to the VolumeBounds, as also SurfaceBounds will have Bounds Type.

Values:

enumerator eCone

enumerator eCuboid

enumerator eCutoutCylinder

enumerator eCylinder

enumerator eGenericCuboid

enumerator eTrapezoid

enumerator eDiamond

enumerator eOther

Public Functions

VolumeBounds() = default

virtual ~VolumeBounds() = default

virtual Volume::BoundingBox boundingBox(const Transform3 *trf = nullptr, const Vector3 &envelope = {0, 0, 0}, const Volume *entity = nullptr) const = 0

Construct bounding box for this shape.

Parameters:

• trf – Optional transform

• envelope – Optional envelope to add / subtract from min/max

• entity – Entity to associate this bounding box with

Returns:

Constructed bounding box

inline virtual std::vector<AxisDirection> canonicalAxes() const

Get the canonical axis direction that fully describe the shape’s extent.

Note

This is the default implementation that returns the bounding box binning. Individual shapes should override this method

Returns:

vector of canonical axis directions

virtual bool inside(const Vector3 &gpos, double tol = 0.) const = 0

Checking if position given in volume frame is inside.

Parameters:

• gpos – is the global position to be checked

• tol – is the tolerance applied for the inside check

Returns:

boolean indicating if the position is inside

virtual std::vector<OrientedSurface> orientedSurfaces(const Transform3 &transform = Transform3::Identity()) const = 0

Oriented surfaces, i.e.

the decomposed boundary surfaces and the according navigation direction into the volume given the normal vector on the surface

It will throw an exception if the orientation prescription is not adequate

Parameters:

transform – is the 3D transform to be applied to the boundary surfaces to position them in 3D space

Returns:

a vector of surfaces bounding this volume

inline virtual double referenceBorder(AxisDirection aDir) const

Binning borders in double.

Parameters:

aDir – is the binning schema used

Returns:

float offset to be used for the binning

inline virtual Vector3 referenceOffset(AxisDirection aDir) const

Binning offset - overloaded for some R-binning types.

Parameters:

aDir – is the binning schema used

Returns:

vector 3D to be used for the binning

virtual std::ostream &toStream(std::ostream &sl) const = 0

Output Method for std::ostream, to be overloaded by child classes.

Parameters:

sl – is the output stream to be dumped into

Returns:

Modified ostream for chaining

virtual BoundsType type() const = 0

Return the bounds type - for persistency optimization.

Returns:

is a BoundsType enum

virtual std::vector<double> values() const = 0

Access method for bound values, this is a dynamically sized vector containing the parameters needed to describe these bounds.

Returns:

of the stored values for this SurfaceBounds object

Public Static Attributes

static const std::vector<std::string> s_boundsTypeNames

Static member to get the name of the BoundsType.

class VolumeStack : public Acts::Volume

A stack of volumes.

Note

This is a base class for the different types of volume stacks

Subclassed by Acts::CuboidVolumeStack, Acts::CylinderVolumeStack

Public Functions

const std::vector<std::shared_ptr<Volume>> &gaps() const

Access the gap volume that were created during attachment or resizing.

Returns:

the vector of gap volumes

bool isGapVolume(const Volume &volume) const

Check if a volume is a gap volume.

Parameters:

volume – is the volume to check

Returns:

true if the volume is a gap volume, false otherwise

class DD4hepDetectorElement : public ActsPlugins::TGeoDetectorElement

DetectorElement class implementation for DD4hep geometry.

DetectorElement plugin for DD4hep detector elements. DD4hep is based on TGeo shapes, therefore the DD4hepDetectorElement inherits from TGeoDetectorElement in order to perform the conversion.

The full geometrical information is provided by the TGeoDetectorElement. The DD4hepDetectorElement extends the TGeoDetectorElement by containing a segmentation for the readout.

Public Types

using ContextType = Acts::GeometryContext

Broadcast the context type.

using DD4hepVolumeID = dd4hep::DDSegmentation::VolumeID

Type alias for DD4hep volume identifier used in segmentation.

using Store = std::map<std::string, std::vector<std::shared_ptr<DD4hepDetectorElement>>>

Define a string based store.

Public Functions

explicit DD4hepDetectorElement(const dd4hep::DetElement detElement, TGeoAxes axes = "XYZ", double scalor = 1., std::shared_ptr<const Acts::ISurfaceMaterial> material = nullptr)

Constructor.

Example options are:

• ”XYZ” -> identical frame definition (default value)

• ”YZX” -> node y axis is tracking x axis, etc.

• ”XzY” -> negative node z axis is tracking y axis, etc.

Note

In the translation from a 3D geometry (TGeo) which only knows tubes to a 2D geometry (Tracking geometry) a distinction if the module should be described as a cylinder or a disc surface needs to be done. Since this information can not be taken just from the geometry description (both can be described as TGeoTubeSeg), one needs to set the flag ‘isDisc’ in case a volume with shape TGeoTubeSeg should be translated to a disc surface. Per default it will be translated into a cylindrical surface.

Parameters:

• scalor – is the scale factor for unit conversion if needed

• material – Optional material of detector element

• detElement – The DD4hep DetElement which should be associated to an ACTS surface

• axes – is the axis orientation with respect to the tracking frame it is a string of the three characters x, y and z (standing for the three axes) There is a distinction between capital and lower case characters :

  • capital -> positive orientation of the axis

  • lower case -> negative orientation of the axis

~DD4hepDetectorElement() override = default

inline const dd4hep::DetElement &sourceElement() const

Give access to the DD4hep detector element.

Returns:

Reference to the underlying DD4hep detector element

class Geant4DetectorElement : public Acts::SurfacePlacementBase

Detector element representative for Geant4 sensitive elements.

Public Types

using ContextType = Acts::GeometryContext

Broadcast the context type.

Public Functions

Geant4DetectorElement(std::shared_ptr<Acts::Surface> surface, const G4VPhysicalVolume &g4physVol, const Acts::Transform3 &toGlobal, double thickness)

Constructor with arguments.

Parameters:

• surface – the surface representing this detector element

• g4physVol – the physical volume representing this detector element

• toGlobal – the global transformation before the volume

• thickness – the thickness of this detector element

const G4VPhysicalVolume &g4PhysicalVolume() const

Returns:

to the Geant4 physical volume

inline virtual bool isSensitive() const final

Is the detector element a sensitive element.

Returns:

True as this is always sensitive

virtual const Acts::Transform3 &localToGlobalTransform(const Acts::GeometryContext &gctx) const override

Return local to global transform associated with this detector element.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

Reference to the local-to-global transformation matrix

virtual const Acts::Surface &surface() const override

Return surface associated with this detector element.

Returns:

Const reference to the associated surface

virtual Acts::Surface &surface() override

Non-const access to surface associated with this detector element.

Returns:

Mutable reference to the associated surface

virtual double thickness() const

Return the thickness of this detector element.

Returns:

The thickness value in length units

class Geant4DetectorSurfaceFactory

A factory to convert Geant4 physical volumes into Geant4 detector elements.

Public Types

using ElementFactory = std::function<std::shared_ptr<Geant4DetectorElement>(std::shared_ptr<Acts::Surface>, const G4VPhysicalVolume&, const Acts::Transform3&, double)>

Type alias for detector element factory function.

using Geant4PassiveSurface = std::shared_ptr<Acts::Surface>

Type alias for passive surface.

using Geant4SensitiveSurface = std::tuple<std::shared_ptr<Geant4DetectorElement>, std::shared_ptr<Acts::Surface>>

Type alias for sensitive surface with detector element.

Public Functions

Geant4DetectorSurfaceFactory() = delete

The Geant4 detector element factory.

inline explicit Geant4DetectorSurfaceFactory(const Config &config, std::unique_ptr<const Acts::Logger> mlogger = Acts::getDefaultLogger("Geant4DetectorSurfaceFactory", Acts::Logging::INFO))

The Geant4 detector element factory with a configuration.

Parameters:

• config – the configuration of the factory

• mlogger – a screen output logger

void construct(Cache &cache, const G4Transform3D &g4ToGlobal, const G4VPhysicalVolume &g4PhysVol, const Options &option)

Construction method of the detector elements.

Parameters:

• cache – [in,out] into which the Elements are filled

• g4ToGlobal – the transformation to global

• g4PhysVol – the current physical volume

• option – the factory creation option

struct Cache

Nested cache that records the conversion status.

Public Members

std::size_t convertedMaterials = 0

matching and conversion statistics: materials

std::size_t convertedSurfaces = 0

matching and conversion statistics: surfaces

std::size_t matchedG4Volumes = 0

matching and conversion statistics: volumes

std::vector<Geant4PassiveSurface> passiveSurfaces

The created non-const surfaces - for further processing,.

std::vector<Geant4SensitiveSurface> sensitiveSurfaces

The created detector elements - for the detector store.

struct Config

Nested configuration struct that holds global lifetime configuration.

struct Options

Nested option struct that allows per call changeable configuration.

Public Members

double convertedMaterialThickness = -1

Converted material thickness (< 0 indicates keeping original thickness)

bool convertMaterial = false

Convert the material.

std::shared_ptr<IGeant4PhysicalVolumeSelector> passiveSurfaceSelector = nullptr

A selector for passive surfaces.

double scaleConversion = 1.

Convert the length scale.

std::shared_ptr<IGeant4PhysicalVolumeSelector> sensitiveSurfaceSelector = nullptr

A selector for sensitive surfaces.

class IGeant4PhysicalVolumeSelector

Interface class for selectors from physical volumes.

Subclassed by ActsPlugins::Geant4PhysicalVolumeSelectors::AllSelector, ActsPlugins::Geant4PhysicalVolumeSelectors::NameSelector, ActsPlugins::Geant4PhysicalVolumeSelectors::PositionSelector

Public Functions

virtual ~IGeant4PhysicalVolumeSelector() = default

virtual bool select(const G4VPhysicalVolume &g4Phys) const = 0

The main interface method.

Parameters:

g4Phys – the physical volume to be checked

Returns:

a boolean indicating if it should be selected or not

class TGeoDetectorElement : public Acts::SurfacePlacementBase

DetectorElement plugin for ROOT TGeo shapes.

Added possibility to hand over transformation matrix.

Subclassed by ActsPlugins::DD4hepDetectorElement

Public Types

using ContextType = Acts::GeometryContext

Broadcast the context type.

using Identifier = identifier_type

Identifier alias.

using identifier_diff = long long

Identifier difference type.

using identifier_type = unsigned long long

Identifier type.

Public Functions

TGeoDetectorElement(const Identifier &identifier, const TGeoNode &tGeoNode, const Acts::Transform3 &tgTransform, const std::shared_ptr<const Acts::DiscBounds> &tgBounds, double tgThickness = 0.)

Constructor with pre-computed disk surface.

Note

this detector element constructor needs everything pre-computed.

Parameters:

• identifier – is the detector identifier

• tGeoNode – is the TGeoNode which should be represented

• tgTransform – the transform of this detector element

• tgBounds – the bounds of this surface

• tgThickness – the thickness of this detector element

TGeoDetectorElement(const Identifier &identifier, const TGeoNode &tGeoNode, const Acts::Transform3 &tgTransform, const std::shared_ptr<const Acts::PlanarBounds> &tgBounds, double tgThickness = 0.)

Constructor with pre-computed surface.

Note

this detector element constructor needs everything pre-computed.

Parameters:

• identifier – is the detector identifier

• tGeoNode – is the TGeoNode which should be represented

• tgTransform – the transform of this detector element

• tgBounds – the bounds of this surface

• tgThickness – the thickness of this detector element

TGeoDetectorElement(const Identifier &identifier, const TGeoNode &tGeoNode, const TGeoMatrix &tGeoMatrix = TGeoIdentity(), TGeoAxes axes = "XYZ", double scalor = 10., std::shared_ptr<const Acts::ISurfaceMaterial> material = nullptr)

Constructor.

Note

this constructor used auto-translation

Note

This parameter only needs to be set for plane modules

Note

In the translation from a 3D geometry (TGeo) which only knows tubes to a 2D geometry (Tracking geometry) a distinction if the module should be described as a cylinder or a disc surface needs to be done. Since this information can not be taken just from the geometry description (both can be described as TGeoTubeSeg), one needs to set the flag ‘isDisc’ in case a volume with shape TGeoTubeSeg should be translated to a disc surface. Per default it will be translated into a cylindrical surface.

Parameters:

• identifier – is the detector identifier

• tGeoNode – is the TGeoNode which should be represented

• tGeoMatrix – The Matrix to global (i.e. ACTS transform)

• axes – is the axis orientation with respect to the tracking frame it is a string of the three characters x, y and z (standing for the three axes) there is a distinction between capital and lower case characters :

  • capital -> positive orientation of the axis

  • lower case -> negative orientation of the axis example options are “XYZ” -> identical frame definition (default value) “YZX” -> node y axis is tracking x axis, etc. “XzY” -> negative node z axis is tracking y axis, etc.

• scalor – is the scale factor for unit conversion if needed

• material – Possible material of detector element

~TGeoDetectorElement() override

inline Identifier identifier() const

Get the detector element identifier.

Returns:

The unique identifier for this detector element

inline virtual bool isSensitive() const final

Is the detector element a sensitive element.

Returns:

Always true for this detector element type

inline virtual const Acts::Transform3 &localToGlobalTransform(const Acts::GeometryContext &gctx) const override

Return local to global transform associated with this identifier.

Parameters:

gctx – The current geometry context object, e.g. alignment

Returns:

Reference to the transformation matrix from local to global coordinates

const Acts::Transform3 &nominalTransform() const

Return the nominal - non-contextual transform.

Returns:

Reference to the nominal transformation matrix

inline virtual const Acts::Surface &surface() const override

Return surface associated with this detector element.

Returns:

Const reference to the surface

inline virtual Acts::Surface &surface() override

Return surface associated with this detector element.

Note

this is the non-const access

Returns:

Mutable reference to the surface

inline const TGeoNode &tgeoNode() const

Return the TGeoNode for back navigation.

Returns:

Reference to the underlying TGeoNode

inline double thickness() const

Returns the thickness of the module.

Returns:

Thickness of the detector element in units of length

Enums

enum class Acts::AxisBoundaryType

Enum which determines how the axis handle its outer boundaries possible values values.

Values:

enumerator Open

Default behaviour: out of bounds positions are filled into the over or underflow bins.

enumerator Bound

Out-of-bounds positions resolve to first/last bin respectively.

enumerator Closed

Out-of-bounds positions resolve to the outermost bin on the opposite side.

enum class Acts::AxisDirection : int

to specify a local axis direction

Values:

enumerator AxisX

AxisX, AxisY, AxisZ are the cartesian directions in the local frame.

enumerator AxisY

enumerator AxisZ

enumerator AxisR

AxisR is a radial direction.

enumerator AxisPhi

AxisPhi is the azimuthal direction.

enumerator AxisRPhi

AxisRPhi is the radial-azimuthal direction.

enumerator AxisTheta

AxisTheta is the polar angle direction.

enumerator AxisEta

AxisEta is the pseudorapidity direction.

enumerator AxisMag

AxisMag is the magnitude of the vector.

enum class Acts::AxisType

Enum which determines the binning type of the axis.

Values:

enumerator Equidistant

An axis where all bins have the same size.

enumerator Variable

An axis where bins can have different sizes.

enum Acts::BinningType

, BinningOption & BinningAccess

• BinningType:

  Enumeration to qualify the binning type for the use of the LayerArrayCreator and the TrackingVolumeArrayCreator

  • BinningOption: open: [0,max] closed: 0 -> nextbin -> max -> 0

  • AxisDirection necessary access to global positions

Values:

enumerator equidistant

enumerator arbitrary

enum Acts::BoundIndices

Components of a bound track parameters vector.

To be used to access components by named indices instead of just numbers. This must be a regular enum and not a scoped enum class to allow implicit conversion to an integer. The enum value are thus visible directly in namespace Acts and are prefixed to avoid naming collisions.

Values:

enumerator eBoundLoc0

enumerator eBoundLoc1

enumerator eBoundPhi

enumerator eBoundTheta

enumerator eBoundQOverP

enumerator eBoundTime

enumerator eBoundSize

enum class Acts::ComponentMergeMethod

Available reduction methods for the reduction of a Gaussian mixture.

Values:

enumerator eMean

enumerator eMaxWeight

enum Acts::FreeIndices

Components of a free track parameters vector.

To be used to access components by named indices instead of just numbers. This must be a regular enum and not a scoped enum class to allow implicit conversion to an integer. The enum value are thus visible directly in namespace Acts and are prefixed to avoid naming collisions.

Values:

enumerator eFreePos0

enumerator eFreePos1

enumerator eFreePos2

enumerator eFreeTime

enumerator eFreeDir0

enumerator eFreeDir1

enumerator eFreeDir2

enumerator eFreeQOverP

enumerator eFreeSize

enum class Acts::MagneticFieldError

Error codes for magnetic field operations.

Values:

enumerator OutOfBounds

The lookup position was outside of the validitiy domain of the underlying magnetic field instance.

enumerator NotImplemented

An operation for this magnetic field type is not implemented.

enum class Acts::TrackStatePropMask : std::uint8_t

Collection of bit masks to enable steering which components of a track state should be initialized, and which should be left invalid.

These mask values can be combined using binary operators, so (TrackStatePropMask::Predicted | TrackStatePropMask::Jacobian) will instruct allocating storage for both predicted parameters (including covariance) and a jacobian. The enum is used as a strong type wrapper around the bits to prevent autoconversion from integer

Values:

enumerator None

enumerator Predicted

enumerator Filtered

enumerator Smoothed

enumerator Jacobian

enumerator Calibrated

enumerator All

Functions

inline const Logger &Acts::CylinderVolumeBuilder::logger() const

Private access to the logger.

Returns:

a const reference to the logger

std::unique_ptr<const Logger> Acts::getDefaultLogger(const std::string &name, const Logging::Level &lvl, std::ostream *log_stream = &std::cout)

get default debug output logger

This function returns a pointer to a Logger instance with the following decorations enabled:

• time stamps

• name of logging instance

• debug level

Parameters:

• name – [in] name of the logger instance

• lvl – [in] debug threshold level

• log_stream – [in] output stream used for printing debug messages

Returns:

pointer to logging instance

const Logger &Acts::getDummyLogger()

Get a dummy logger that discards all output.

Returns:

Reference to dummy logger instance

AtlasBetheHeitlerApprox Acts::makeDefaultBetheHeitlerApprox(bool clampToRange = false)

Creates a AtlasBetheHeitlerApprox object based on an ATLAS configuration, that are stored as static data in the source code.

This may not be an optimal configuration, but should allow to run the GSF without the need to load files

Parameters:

clampToRange – Whether to clamp values to the valid range

Returns:

AtlasBetheHeitlerApprox with default ATLAS configuration parameters

void Acts::reduceMixtureLargestWeights(std::vector<GsfComponent> &cmpCache, std::size_t maxCmpsAfterMerge, const Surface &surface)

Very simple mixture reduction method: Just removes the components with the smallest weight until the required number of components is reached.

Parameters:

• cmpCache – the component collection

• maxCmpsAfterMerge – the number of components we want to reach

• surface – the surface type on which the components are (unused here)

void Acts::reduceMixtureWithKLDistance(std::vector<GsfComponent> &cmpCache, std::size_t maxCmpsAfterMerge, const Surface &surface)

Greedy component reduction algorithm.

Reduces the components with the minimal symmetric KL-distance (applied only to the q/p-dimension) until the required number of components is reached.

Parameters:

• cmpCache – the component collection

• maxCmpsAfterMerge – the number of components we want to reach

• surface – the surface type on which the components are

std::unique_ptr<const Acts::TrackingGeometry> ActsPlugins::convertDD4hepDetector(dd4hep::DetElement worldDetElement, const Acts::Logger &logger, Acts::BinningType bTypePhi = Acts::equidistant, Acts::BinningType bTypeR = Acts::equidistant, Acts::BinningType bTypeZ = Acts::equidistant, double layerEnvelopeR = Acts::UnitConstants::mm, double layerEnvelopeZ = Acts::UnitConstants::mm, double defaultLayerThickness = Acts::UnitConstants::fm, const std::function<void(std::vector<dd4hep::DetElement> &detectors)> &sortSubDetectors = sortDetElementsByID, const Acts::GeometryContext &gctx = Acts::GeometryContext::dangerouslyDefaultConstruct(), std::shared_ptr<const Acts::IMaterialDecorator> matDecorator = nullptr, std::shared_ptr<const Acts::GeometryIdentifierHook> geometryIdentifierHook = std::make_shared<Acts::GeometryIdentifierHook>(), const DD4hepLayerBuilder::ElementFactory &detectorElementFactory = DD4hepLayerBuilder::defaultDetectorElementFactory)

Global method which creates the TrackingGeometry from DD4hep input.

This method returns a std::unique_ptr of the TrackingGeometry from the World DD4hep DetElement.

Attention

The default thickness should be set thin enough that no touching or overlapping with the next layer can happen.

Note

Possible binningtypes:

• arbitrary - of the sizes if the surfaces and the distance in between vary. This mode finds out the bin boundaries by scanning through the surfaces.

• equidistant - if the sensitive surfaces are placed equidistantly

Note

equidistant binningtype is recommended because it is faster not only while building the geometry but also for look up during the extrapolation

Note

Layers containing surfaces per default are not allowed to be attached to each other (navigation will fail at this point). However, to allow material layers (not containing surfaces) to be attached to each other, this default thickness is needed. In this way, the layer will be thin (with space to the next layer), but the material will have the ‘real’ thickness.

Parameters:

• worldDetElement – [in] the DD4hep DetElement of the world

• logger – [in] A logger instance geometry building

• bTypePhi – [in] is how the sensitive surfaces (modules) should be binned in a layer in phi direction.

• bTypeR – [in] is how the sensitive surfaces (modules) should be binned in a layer in r direction

• bTypeZ – [in] is how the sensitive surfaces (modules) should be binned in a layer in z direction

• layerEnvelopeR – [in] the tolerance added to the geometrical extension in r of the layers contained to build the volume envelope around

• layerEnvelopeZ – [in] the tolerance added to the geometrical extension in z of the layers contained to build the volume envelope around

• defaultLayerThickness – [in] In case no surfaces (to be contained by the layer) are handed over, the layer thickness will be set to this value

• sortSubDetectors – [in] std::function which should be used in order to sort all sub detectors (=all Detelements collected by the method collectSubDetectors() ) from bottom to top to ensure correct wrapping of the volumes, which is needed for navigation. Therefore the different hierarchies need to be sorted ascending. The default is sorting by ID.

• gctx – The geometry context to use

• matDecorator – is the material decorator that loads material maps

• geometryIdentifierHook – Hook to apply to surfaces during geometry closure.

• detectorElementFactory – Factory function to create ActsPlugins::DD4hepDetectorElement or derived classes

Throws:

std::logic_error – if an error in the translation occurs

Pre:

Before using this method make sure, that the preconditions described in DD4hepPlugins are met.

Returns:

std::unique_ptr to the full TrackingGeometry

• The Tracking geometry needs to be built from bottom to top to ensure Navigation. Therefore the different hierarchies need to be sorted ascending. Per default the sub detectors are sorted by the id of their dd4hep::DetElement. In case another sorting needs to be applied, the users can provide their own function

Structs

Warning

doxygenstruct: Cannot find class “Acts::ActorList” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

template<typename track_container_t>
struct CombinatorialKalmanFilterExtensions

Extension struct which holds the delegates to customize the CKF behavior.

Public Types

using BranchStopper = Delegate<BranchStopperResult(const TrackProxy&, const TrackStateProxy&)>

Type alias for branch stopper delegate function.

using BranchStopperResult = CombinatorialKalmanFilterBranchStopperResult

Type alias for branch stopper result enumeration.

using TrackProxy = typename track_container_t::TrackProxy

Type alias for track proxy from the container.

using TrackStateCreator = Delegate<Result<CkfTypes::BranchVector<TrackIndexType>>(const GeometryContext &geoContext, const CalibrationContext &calibrationContext, const Surface &surface, const CkfTypes::BoundState &boundState, TrackIndexType prevTip, std::vector<TrackStateProxy> &trackStateCandidates, traj_t &trajectory, const Logger &logger)>

Delegate the extension of the trajectory onto the given surface to an external unit.

Note

Expected to create track states for measurements associated to the given surface which match the given bound state. Moreover the The “filtered” data is not expected to be set, but the outlier flag should be set for states that are considered to be outlier.

Param geoContext:

The current geometry context

Param calibrationContext:

pointer to the current calibration context

Param surface:

the surface at which new track states are to be created

Param boundState:

the current bound state of the trajectory

Param prevTip:

Index pointing at previous trajectory state (i.e. tip)

Param trackStateCandidates:

a temporary buffer that can be used to collect track states

Param trajectory:

the trajectory to which the new states are to be added

Param logger:

a logger for messages

Return:

indices of new track states which extend the trajectory given by prevTip

using TrackStateProxy = typename track_container_t::TrackStateProxy

Type alias for track state proxy from the container.

using traj_t = typename track_container_t::TrackStateContainerBackend

Type alias for track state container backend.

using Updater = typename KalmanFitterExtensions<traj_t>::Updater

Type alias for Kalman filter updater delegate.

Public Members

BranchStopper branchStopper = {DelegateFuncTag<voidBranchStopper>{}}

The branch stopper is called during the filtering by the Actor.

TrackStateCreator createTrackStates

The delegate to create new track states.

Note

a reference implementation can be found in TrackStateCreator which makes uses of MeasurementSelector and SourceLinkAccessor

Updater updater = {DelegateFuncTag<detail::voidFitterUpdater<traj_t>>{}}

The updater incorporates measurement information into the track parameters.

template<typename track_container_t>
struct CombinatorialKalmanFilterOptions

Combined options for the combinatorial Kalman filter.

Template Parameters:

• source_link_iterator_t – Type of the source link iterator

• track_container_t – Type of the track container

Public Types

using TrackStateContainerBackend = typename track_container_t::TrackStateContainerBackend

Type alias for track state container backend.

using TrackStateProxy = typename track_container_t::TrackStateProxy

Type alias for track state proxy from the container.

Public Functions

CombinatorialKalmanFilterOptions() = delete

Contexts are required and the options must not be default-constructible.

inline CombinatorialKalmanFilterOptions(const GeometryContext &gctx, const MagneticFieldContext &mctx, std::reference_wrapper<const CalibrationContext> cctx, CombinatorialKalmanFilterExtensions<track_container_t> extensions_, const PropagatorPlainOptions &pOptions, bool mScattering = true, bool eLoss = true)

PropagatorOptions with context.

Parameters:

• gctx – The geometry context for this track finding/fitting

• mctx – The magnetic context for this track finding/fitting

• cctx – The calibration context for this track finding/fitting

• extensions_ – The extension struct

• pOptions – The plain propagator options

• mScattering – Whether to include multiple scattering

• eLoss – Whether to include energy loss

Public Members

std::reference_wrapper<const CalibrationContext> calibrationContext

context object for the calibration

bool energyLoss = true

Whether to consider energy loss.

CombinatorialKalmanFilterExtensions<track_container_t> extensions

The filter extensions.

std::reference_wrapper<const GeometryContext> geoContext

Context object for the geometry.

std::reference_wrapper<const MagneticFieldContext> magFieldContext

Context object for the magnetic field.

bool multipleScattering = true

Whether to consider multiple scattering.

PropagatorPlainOptions propagatorPlainOptions

The trivial propagator options.

bool skipPrePropagationUpdate = false

Skip the pre propagation call.

This effectively skips the first surface

Note

This is useful if the first surface should not be considered in a second reverse pass

const Surface *targetSurface = nullptr

The target surface.

Note

This is useful if the filtering should be terminated at a certain surface

struct State

Nested State struct.

It acts as an internal state which is created for every propagation/extrapolation step and keep thread-local navigation information

Public Functions

inline explicit State(const Options &options_)

Constructor from options.

Parameters:

options_ – The navigator options

inline bool endOfSurfaces() const

Check if we have reached the end of the surface sequence.

Returns:

True if no more surfaces remain in the propagation direction

inline const Surface &navSurface() const

Get the current navigation surface.

Returns:

Reference to the surface at the current surface index

inline void nextSurface()

Move to the next surface in the sequence Increments or decrements surface index based on propagation direction.

inline int remainingSurfaces() const

Get the number of surfaces remaining in the sequence.

Returns:

Number of surfaces left to process in the propagation direction

inline void resetSurfaceIndex()

Reset the surface index to the initial position Sets index to before first surface (forward) or after last surface (backward)

Public Members

const Surface *currentSurface = nullptr

Navigation state - external interface: the current surface.

Direction direction = Direction::Forward()

Propagation direction (forward or backward)

bool navigationBreak = false

Navigation state - external interface: a break has been detected.

Options options

Configuration options for the direct navigator.

NavigatorStatistics statistics

Navigation statistics.

std::int32_t surfaceIndex = -1

Index of the next surface to try.

Note

-1 means before the first surface in the sequence and size() means after the last surface in the sequence

struct EigenStepperDefaultExtension

Default evaluator of the k_i’s and elements of the transport matrix D of the RKN4 stepping.

This is a pure implementation by textbook.

struct EigenStepperDenseExtension

Evaluator of the k_i’s and elements of the transport matrix D of the RKN4 stepping.

This implementation involves energy loss due to ionisation, bremsstrahlung, pair production and photonuclear interaction in the propagation and the Jacobian. These effects will only occur if the propagation is in a TrackingVolume with attached material.

Public Members

double currentMomentum = 0.

Momentum at a certain point.

EigenStepperDefaultExtension defaultExtension

Fallback extension.

double dgdqopValue = 0.

Derivative d(dEds)d(q/p) evaluated at the initial point.

std::array<double, 4> dLdl = {}

Derivatives dLambda’’dlambda at each sub-step point.

std::array<double, 4> dPds = {}

Derivatives dPds at each sub-step.

std::array<double, 4> energy = {}

Energy at each sub-step.

double g = 0.

Derivative dEds at the initial point.

double initialMomentum = 0.

Particles momentum at k1.

std::array<double, 4> Lambdappi = {}

Lambda’’_i.

Material material = Material::Vacuum()

Material that will be passed TODO : Might not be needed anymore.

std::array<double, 4> qop = {}

q/p at each sub-step

std::array<double, 4> tKi = {}

k_i equivalent for the time propagation

template<typename propagator_t, typename traj_t>
struct GaussianSumFitter

Gaussian Sum Fitter implementation.

Note

This GSF implementation tries to be as compatible to the KalmanFitter as possible. However, strict compatibility is not garantueed.

Note

Currently there is no possibility to export the states of the individual components from the GSF, the only information returned in the MultiTrajectory are the means of the states. Therefore, also NO dedicated component smoothing is performed as described e.g. by R. Fruewirth.

Template Parameters:

• propagator_t – The propagator type on which the algorithm is built on, usually an instance of Acts::Propagator

• traj_t – The MultiTrajectory type (backend)

Public Types

using GsfActor = detail::Gsf::GsfActor<traj_t>

The actor type.

using GsfNavigator = typename propagator_t::Navigator

The navigator type.

Public Functions

inline GaussianSumFitter(propagator_t &&propagator, std::shared_ptr<const BetheHeitlerApprox> bha, std::unique_ptr<const Logger> _logger = getDefaultLogger("GSF", Logging::INFO))

Constructor with propagator, Bethe-Heitler approximation, and logger.

Parameters:

• propagator – Propagator for track propagation

• bha – Bethe-Heitler approximation for energy loss modeling

• _logger – Logger for diagnostic output

template<typename source_link_it_t, typename start_parameters_t, TrackContainerFrontend track_container_t>
inline auto fit(source_link_it_t begin, source_link_it_t end, const start_parameters_t &sParameters, const GsfOptions<traj_t> &options, const std::vector<const Surface*> &sSequence, track_container_t &trackContainer) const

The fit function for the Direct navigator.

Parameters:

• begin – Iterator to the start of source links

• end – Iterator to the end of source links

• sParameters – Starting track parameters for the fit

• options – Options for the GSF fit

• sSequence – Sequence of surfaces to navigate through

• trackContainer – Container to store the fitted track

Returns:

Result containing fitted track proxy or error

template<typename source_link_it_t, typename start_parameters_t, TrackContainerFrontend track_container_t>
inline auto fit(source_link_it_t begin, source_link_it_t end, const start_parameters_t &sParameters, const GsfOptions<traj_t> &options, track_container_t &trackContainer) const

The fit function for the standard navigator.

Parameters:

• begin – Iterator to the start of source links

• end – Iterator to the end of source links

• sParameters – Starting track parameters for the fit

• options – Options for the GSF fit

• trackContainer – Container to store the fitted track

Returns:

Result containing fitted track proxy or error

template<typename source_link_it_t, typename start_parameters_t, typename fwd_prop_initializer_t, typename bwd_prop_initializer_t, TrackContainerFrontend track_container_t>
inline Acts::Result<typename track_container_t::TrackProxy> fit_impl(source_link_it_t begin, source_link_it_t end, const start_parameters_t &sParameters, const GsfOptions<traj_t> &options, const fwd_prop_initializer_t &fwdPropInitializer, const bwd_prop_initializer_t &bwdPropInitializer, track_container_t &trackContainer) const

The generic implementation of the fit function.

TODO check what this function does with the referenceSurface is e.g. the first measurementSurface

Parameters:

• begin – Iterator to the start of source links

• end – Iterator to the end of source links

• sParameters – Starting track parameters for the fit

• options – Options for the GSF fit

• fwdPropInitializer – Initializer for forward propagation

• bwdPropInitializer – Initializer for backward propagation

• trackContainer – Container to store the fitted track

Returns:

Result containing fitted track proxy with forward and backward propagation results

inline const Logger &logger() const

Get the logger instance.

Returns:

Reference to the logger

Public Members

std::unique_ptr<const Logger> m_actorLogger

Logger instance for actor debugging.

std::shared_ptr<const BetheHeitlerApprox> m_betheHeitlerApproximation

The fitter holds the instance of the bethe heitler approx.

std::unique_ptr<const Logger> m_logger

The logger.

propagator_t m_propagator

The propagator instance used by the fit function.

template<typename traj_t>
struct GsfOptions

Options for configuring the Gaussian-sum filter fit.

Public Functions

inline GsfOptions(const GeometryContext &geoCtxt, const MagneticFieldContext &magFieldCtxt, const CalibrationContext &calibCtxt)

Constructor from contexts.

Parameters:

• geoCtxt – The geometry context

• magFieldCtxt – The magnetic field context

• calibCtxt – The calibration context

Public Members

bool abortOnError = false

Abort the fit if an error occurs.

std::reference_wrapper<const CalibrationContext> calibrationContext

Calibration context for this fit.

ComponentMergeMethod componentMergeMethod = ComponentMergeMethod::eMaxWeight

Method for merging components.

bool disableAllMaterialHandling = false

Disable all material handling during the fit.

GsfExtensions<traj_t> extensions

Extensions for GSF components.

std::string_view finalMultiComponentStateColumn = ""

Column name for final multi-component state storage.

std::reference_wrapper<const GeometryContext> geoContext

Geometry context for this fit.

std::reference_wrapper<const MagneticFieldContext> magFieldContext

Magnetic field context for this fit.

std::size_t maxComponents = 4

Maximum number of components in the mixture.

PropagatorPlainOptions propagatorPlainOptions

Propagator options.

const Surface *referenceSurface = nullptr

Reference surface for the final track parameters.

double reverseFilteringCovarianceScaling = 100.0

Scaling factor for the covariance matrix before reverse filtering.

Note that the default value is not tuned and might need adjustment for different use cases.

bool useExternalSurfaces = true

Whether to use the external-surfaces mechanism of the navigator which switches off the boundary-check for measurement surfaces.

double weightCutoff = 1.e-4

Minimum weight required to keep a component.

struct MultiStepperSurfaceReached : public Acts::ForcedSurfaceReached

Aborter that stops when all components reach the target surface.

Public Functions

MultiStepperSurfaceReached() = default

template<typename propagator_state_t, typename stepper_t, typename navigator_t>
inline bool checkAbort(propagator_state_t &state, const stepper_t &stepper, const navigator_t &navigator, const Logger &logger) const

boolean operator for abort condition without using the result

Template Parameters:

• propagator_state_t – Type of the propagator state

• stepper_t – Type of the stepper

• navigator_t – Type of the navigator

Parameters:

• state – [inout] The propagation state object

• stepper – [in] Stepper used for propagation

• navigator – [in] Navigator used for the propagation

• logger – a logger instance

Returns:

True if the abort condition is met, false otherwise

Public Members

bool averageOnSurface = true

If this is set, we are also happy if the mean of the components is on the surface.

How the averaging is performed depends on the stepper implementation

double averageOnSurfaceTolerance = 0.2

A configurable tolerance within which distance to the intersection we consider the surface as reached.

Has no effect if averageOnSurface is false

struct State

Nested State struct.

It acts as an internal state which is created for every propagation and meant to keep thread-local navigation information.

Public Functions

inline explicit State(const Options &options_)

Constructor with navigation options.

Parameters:

options_ – The navigation options for this state

inline NavigationTarget &navBoundary()

Get reference to current navigation boundary.

Returns:

Reference to current boundary intersection

inline NavigationTarget &navCandidate()

Get reference to current navigation candidate.

Returns:

Reference to current boundary intersection

inline NavigationTarget &navLayer()

Get reference to current navigation layer.

Returns:

Reference to current layer intersection

inline NavigationTarget &navSurface()

Get reference to current navigation surface.

Returns:

Reference to current navigation target

inline void resetAfterLayerSwitch()

Reset navigation state after switching layers.

inline void resetAfterVolumeSwitch()

Reset navigation state after switching volumes.

inline void resetForRenavigation()

Completely reset navigation state to initial conditions.

Public Members

const Layer *currentLayer = nullptr

Current layer during navigation.

const Surface *currentSurface = nullptr

Current surface during navigation.

const TrackingVolume *currentVolume = nullptr

Current volume during navigation.

std::vector<std::pair<const Surface*, bool>> freeCandidates = {}

Free candidates not part of the tracking geometry.

and a boolean indicating whether the surface has already been reached during propagation

std::vector<const Surface*> freeSurfaces

Surfaces that are not part of the tracking geometry.

NavigationBoundaries navBoundaries = {}

the vector of boundary surfaces to work through

std::optional<std::size_t> navBoundaryIndex

the current boundary index of the navigation state

std::optional<std::size_t> navCandidateIndex

the current candidate index of the navigation state

NavigationCandidates navCandidates = {}

the vector of navigation candidates to work through

bool navigationBreak = false

Flag to break navigation loop.

Stage navigationStage = Stage::initial

Current navigation stage in the state machine.

std::optional<std::size_t> navLayerIndex

the current layer index of the navigation state

NavigationLayers navLayers = {}

the vector of navigation layers to work through

std::optional<std::size_t> navSurfaceIndex

the current surface index of the navigation state

NavigationSurfaces navSurfaces = {}

the vector of navigation surfaces to work through

Options options

Navigation options configuration.

NavigationPolicyStateManager policyStateManager

Management of policy state allocation and deallocation.

const Layer *startLayer = nullptr

Layer where the navigation started.

const Surface *startSurface = nullptr

Surface where the navigation started.

const TrackingVolume *startVolume = nullptr

Volume where the navigation started.

NavigatorStatistics statistics

Statistics collection for navigation performance.

NavigationStream stream

Stream for navigation debugging and monitoring.

const Surface *targetSurface = nullptr

Target surface for navigation.

Warning

doxygenstruct: Cannot find class “Acts::Neutral” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

struct OrientedSurface

Helper bundle of a surface and its orientation.

Public Members

Direction direction = Direction::AlongNormal()

Surface orientation.

std::shared_ptr<RegularSurface> surface

The surface.

struct PathLimitReached

This is the condition that the pathLimit has been reached.

Public Functions

template<typename propagator_state_t, typename stepper_t, typename navigator_t>
inline bool checkAbort(propagator_state_t &state, const stepper_t &stepper, const navigator_t &navigator, const Logger &logger) const

boolean operator for abort condition without using the result

Template Parameters:

• propagator_state_t – Type of the propagator state

• stepper_t – Type of the stepper

• navigator_t – Type of the navigator

Parameters:

• state – [inout] The propagation state object

• stepper – [in] Stepper used for propagation

• navigator – [in] Navigator used for propagation

• logger – a logger instance

Returns:

True if path limit exceeded and propagation should abort

Public Members

double internalLimit = std::numeric_limits<double>::max()

Internal path limit for loop protection.

template<typename stepper_options_t, typename navigator_options_t, typename actor_list_t = ActorList<>>
struct PropagatorOptions : public Acts::detail::PurePropagatorPlainOptions

Options for propagate() call.

Template Parameters:

actor_list_t – List of action types called after each propagation step with the current propagation and stepper state

Public Types

using actor_list_type = actor_list_t

Type alias for actor list.

using navigator_options_type = navigator_options_t

Type alias for navigator options.

using stepper_options_type = stepper_options_t

Type alias for stepper options.

Public Functions

inline PropagatorOptions(const GeometryContext &gctx, const MagneticFieldContext &mctx)

PropagatorOptions with context.

Parameters:

• gctx – Geometry context for propagation

• mctx – Magnetic field context for propagation

inline explicit PropagatorOptions(const PropagatorPlainOptions &pOptions)

PropagatorOptions with context and plain options.

Parameters:

pOptions – Plain options to initialize from

template<typename extended_actor_list_t>
inline PropagatorOptions<stepper_options_t, navigator_options_t, extended_actor_list_t> extend(extended_actor_list_t extendedActorList) const

Expand the options with extended actors.

Template Parameters:

extended_actor_list_t – Type of the new actor list

Parameters:

extendedActorList – The new actor list to be used (internally)

Returns:

PropagatorOptions with the extended actor list

inline explicit operator PropagatorPlainOptions() const

Convert to plain options.

inline void setPlainOptions(const PropagatorPlainOptions &pOptions)

Set the plain options.

Parameters:

pOptions – The plain options

Public Members

actor_list_t actorList

List of actions.

std::reference_wrapper<const GeometryContext> geoContext

The context object for the geometry.

std::reference_wrapper<const MagneticFieldContext> magFieldContext

The context object for the magnetic field.

navigator_options_t navigation

Navigator options.

stepper_options_t stepping

Stepper options.

struct PropagatorPlainOptions : public Acts::detail::PurePropagatorPlainOptions

Holds the generic propagator options.

Public Functions

inline PropagatorPlainOptions(const GeometryContext &gctx, const MagneticFieldContext &mctx)

PropagatorPlainOptions with context.

Parameters:

• gctx – Geometry context for propagation

• mctx – Magnetic field context for propagation

Public Members

std::reference_wrapper<const GeometryContext> geoContext

The context object for the geometry.

std::reference_wrapper<const MagneticFieldContext> magFieldContext

The context object for the magnetic field.

NavigatorPlainOptions navigation

Navigator plain options.

StepperPlainOptions stepping

Stepper plain options.

struct SeedConfirmationRangeConfig

Contains parameters for quality seed confirmation.

Note

Requirements on the number of compatible space-points and impact parameters can be defined for different (r, z) regions of the detector (e.g. forward or central region) by SeedConfirmationRange. Seeds are classified as “high-quality” seeds and normal quality seeds. Normal quality seeds are only selected if no other “high-quality” seed has been found for that inner-middle doublet. For optimization reasons, the algorithm only calls the seed confirmation for a certain inner-middle doublet, in case a configurable minimum number of inner-middle-outer triplets have been found.

Public Members

float minImpactSeedConf = 1. * Acts::UnitConstants::mm

Minimum impact parameter of seed required in quality seed confirmation.

std::size_t nTopForLargeR = 0

Minimum number of compatible outer space-points required in quality seed confirmation if inner space-points radius is larger than rMaxSeedConf.

std::size_t nTopForSmallR = 0

Minimum number of compatible outer space-points required in quality seed confirmation if inner space-points radius is smaller than rMaxSeedConf.

float rMaxSeedConf = std::numeric_limits<float>::max()

Radius position of inner seed component that is used to split the region of the detector for seed confirmation.

float seedConfMaxZOrigin = 150. * Acts::UnitConstants::mm

Maximum longitudinal impact parameter of seed required in quality seed confirmation.

float seedConfMinBottomRadius = 60. * Acts::UnitConstants::mm

Minimum radius for inner seed component required in quality seed confirmation.

float zMaxSeedConf = std::numeric_limits<float>::max()

Maximum z position of middle component of the seed used to split the region of the detector for seed confirmation.

float zMinSeedConf = std::numeric_limits<float>::lowest()

Minimum z position of middle component of the seed used to split the region of the detector for seed confirmation.

Warning

doxygenstruct: Cannot find class “Acts::SinglyCharged” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

template<typename source_link_iterator_t, typename track_container_t>
struct TrackStateCreator

Create track states for selected measurements associated to a surface.

• First get a source link range covering relevant measurements associated to the given surface. This task is delegated to a SourceLinkAccessor.

• Then create temporary track states for all measurements defined by a source link range, calibrate the measurements and fill the the calibrated data of these track states using a dedicated calibrator

• The measurement selection is delegated to a dedicated measurement selector.

• Finally add branches to the given trajectory for the selected, temporary track states. The track states of these branches still lack the filtered data which is to be filled by the next stage e.g. the CombinatorialKalmanFilter. All track states, the temporary track states and track states for selected measurements, are created in the given trajectory. The resulting container may become big. Thus, it is advisable to copy selected tracks and their track states to a separate container after each track finding step.

Public Types

using BoundState = std::tuple<BoundTrackParameters, BoundMatrix, double>

Type alias for bound state tuple containing parameters, jacobian and path length.

using Calibrator = typename KalmanFitterExtensions<TrackStateContainerBackend>::Calibrator

Type alias for calibrator delegate to process measurements from source links.

using candidate_container_t = typename std::vector<typename track_container_t::TrackStateProxy>

Type alias for container of candidate track state proxies.

using MeasurementSelector = Delegate<Result<std::pair<typename candidate_container_t::iterator, typename candidate_container_t::iterator>>(candidate_container_t &trackStates, bool&, const Logger&)>

Type alias for delegate to select measurements from track state candidates.

using SourceLinkAccessor = Delegate<std::pair<source_link_iterator_t, source_link_iterator_t>(const Surface&)>

Type alias for delegate to access source link ranges for a surface.

using TrackProxy = typename track_container_t::TrackProxy

Type alias for track proxy from track container.

using TrackStateContainerBackend = typename track_container_t::TrackStateContainerBackend

Type alias for track state container backend from track container.

using TrackStateProxy = typename track_container_t::TrackStateProxy

Type alias for track state proxy from track container.

using TrackStatesResult = Acts::Result<CkfTypes::BranchVector<TrackIndexType>>

Type alias for result of track states creation operation.

Public Functions

inline Result<CkfTypes::BranchVector<TrackIndexType>> createSourceLinkTrackStates(const GeometryContext &gctx, const CalibrationContext &calibrationContext, [[maybe_unused]] const Surface &surface, const BoundState &boundState, const source_link_iterator_t &slBegin, const source_link_iterator_t &slEnd, TrackIndexType prevTip, std::vector<TrackStateProxy> &trackStateCandidates, TrackStateContainerBackend &trajectory, const Logger &logger) const

Create track states for selected measurements given by the source links.

Parameters:

• gctx – The current geometry context

• calibrationContext – pointer to the current calibration context

• surface – the surface the sourceLinks are associated to

• boundState – Bound state from the propagation on this surface

• slBegin – Begin iterator for sourceLinks

• slEnd – End iterator for sourceLinks

• prevTip – Index pointing at previous trajectory state (i.e. tip)

• trackStateCandidates – a temporary buffer which can be used to to keep track of newly created temporary track states.

• trajectory – the trajectory to which new track states for selected measurements will be added

• logger – the logger for messages.

Returns:

Result containing vector of track state indices or error

inline Result<CkfTypes::BranchVector<TrackIndexType>> createTrackStates(const GeometryContext &gctx, const CalibrationContext &calibrationContext, [[maybe_unused]] const Surface &surface, const BoundState &boundState, TrackIndexType prevTip, std::vector<TrackStateProxy> &trackStateCandidates, TrackStateContainerBackend &trajectory, const Logger &logger) const

extend the trajectory onto the given surface.

Extend or branch the trajectory onto the given surface. This may create new track states using measurements which match the predicted bound state. This may create multiple branches. The new track states still miss the “filtered” data.

Parameters:

• gctx – The geometry context to be used for this task

• calibrationContext – The calibration context used to fill the calibrated data

• surface – The surface onto which the trajectory is extended

• boundState – the predicted bound state on the given surface

• prevTip – the tip of the trajectory which is to be extended

• trackStateCandidates – a temporary buffer which can be used to to keep track of newly created temporary track states.

• trajectory – the trajectory to be extended.

• logger – a logger for messages.

Returns:

a list of indices of newly created track states which extend the trajectory onto the given surface and match the bound state, or an error.

inline Result<CkfTypes::BranchVector<TrackIndexType>> processSelectedTrackStates(typename std::vector<TrackStateProxy>::const_iterator begin, typename std::vector<TrackStateProxy>::const_iterator end, TrackStateContainerBackend &trackStates, bool isOutlier, const Logger &logger) const

Create track states for the given trajectory from candidate track states.

Parameters:

• begin – begin iterator of the list of candidate track states

• end – end iterator of the list of candidate track states

• trackStates – the trajectory to which the new track states are added

• isOutlier – true if the candidate(s) is(are) an outlier(s).

• logger – the logger for messages

Returns:

Result containing vector of track state indices or error

Public Members

Calibrator calibrator = {DelegateFuncTag<detail::voidFitterCalibrator<TrackStateContainerBackend>>{}}

The Calibrator is a dedicated calibration algorithm that allows to calibrate measurements using track information, this could be e.g.

sagging for wires, module deformations, etc.

MeasurementSelector measurementSelector = {DelegateFuncTag<voidMeasurementSelector>{}}

Delegate for measurement selection on surfaces.

SourceLinkAccessor sourceLinkAccessor

The source link accessor will return an source link range for a surface which link to the associated measurements.

Public Static Functions

static inline Result<std::pair<typename std::vector<TrackStateProxy>::iterator, typename std::vector<TrackStateProxy>::iterator>> voidMeasurementSelector(typename std::vector<TrackStateProxy> &candidates, bool&, const Logger&)

Default measurement selector which will return all measurements.

Parameters:

candidates – Measurement track state candidates

Returns:

Iterator pair representing the range of all candidates

struct AllSelector : public ActsPlugins::IGeant4PhysicalVolumeSelector

Struct that selects all G4VPhysicalVolume objects.

Public Functions

inline virtual bool select(const G4VPhysicalVolume&) const final

The main interface method.

Parameters:

g4Phys – the physical volume to be checked

Returns:

a boolean indicating if it should be selected or not

struct NameSelector : public ActsPlugins::IGeant4PhysicalVolumeSelector

Struct that selects G4VPhysicalVolume objects that match one of the provided names, exact or partially.

Public Functions

inline explicit NameSelector(const std::vector<std::string> &ns, bool e = false)

Constructor with arguments.

Parameters:

• ns – the provided list of names

• e – whether to select them exact or not

virtual bool select(const G4VPhysicalVolume &g4PhysVol) const final

Secect function for the volume.

Parameters:

g4PhysVol – the volume that is checked

Returns:

a boolean indicating the selection

Public Members

bool exact = false

Flag indicating exact name matching vs partial matching.

std::vector<std::string> names = {}

List of volume names for selection criteria.

struct PositionSelector : public ActsPlugins::IGeant4PhysicalVolumeSelector

Struct that selects G4VPhysicalVolume objects based on the allowed range of their position.

Note

Can be used for preselection of volumes before a KDTree search. This way the memory consumption can be reduced, compromising the execution speed

Note

Careful with axis conventions as Geant4 uses a different one than Acts

Public Functions

inline explicit PositionSelector(const std::map<unsigned int, std::tuple<double, double>> &ranges)

Constructor with arguments.

Parameters:

ranges – the provided map of axes of ranges

virtual bool select(const G4VPhysicalVolume &g4PhysVol) const final

Secect function for the volume.

Parameters:

g4PhysVol – the volume that is checked

Returns:

a boolean indicating the selection

Public Members

std::map<unsigned int, std::tuple<double, double>> m_ranges

Map of axis indices to position ranges for volume selection.

Types

template<unsigned int kRows, unsigned int kCols>
using Acts::ActsMatrix = Matrix<kRows, kCols>

Fixed-size matrix type for NxM matrices.

Deprecated:

Use Matrix instead

Template Parameters:

• kRows – Number of rows

• kCols – Number of columns

template<unsigned int kSize>
using Acts::ActsSquareMatrix = SquareMatrix<kSize>

Fixed-size square matrix type for NxN matrices.

Deprecated:

Use SquareMatrix instead

Template Parameters:

kSize – The dimension of the square matrix

template<unsigned int kSize>
using Acts::ActsVector = Vector<kSize>

Fixed-size vector type for N-dimensional vectors.

Deprecated:

Use Vector instead

Template Parameters:

kSize – The dimension of the vector

using Acts::AngleAxis3 = Eigen::AngleAxis<double>

Rotation defined by an angle around a rotation axis in 3D.

using Acts::BoundMatrix = Matrix<eBoundSize, eBoundSize>

Matrix type for bound track parameter transformations.

using Acts::BoundToFreeMatrix = Matrix<eFreeSize, eBoundSize>

Matrix type for mapping from bound to free track parameters.

Warning

doxygentypedef: Cannot find typedef “Acts::BoundTrackParameters” in doxygen xml output for project “Acts” from directory: _build/doxygen-xml

using Acts::BoundVector = Vector<eBoundSize>

Vector type for bound track parameters.

using Acts::BoundarySurface = BoundarySurfaceT<TrackingVolume>

Type alias for boundary surface with TrackingVolume.

using Acts::FreeMatrix = Matrix<eFreeSize, eFreeSize>

Matrix type for free track parameter transformations.

using Acts::FreeToBoundMatrix = Matrix<eBoundSize, eFreeSize>

Matrix type for mapping from free to bound track parameters.

using Acts::FreeToPathMatrix = Matrix<1, eFreeSize>

Matrix type for mapping from free parameters to path length.

using Acts::FreeVector = Vector<eFreeSize>

Vector type for free track parameters.

using Acts::HashedString = std::uint32_t

Type alias for hashed string representation.

Represents a string as a compile-time hash value for efficient comparison

using Acts::Intersection3D = Intersection<3>

Type alias for 3D intersection.

typedef BinnedArray<LayerPtr> Acts::LayerArray

A BinnedArray to a std::shared_ptr of a layer.

Layers are constructed with shared_ptr factories, hence the layer array is describes as:

typedef detail::SingleComponentReducer<detail::MaxWeightComponent> Acts::MaxWeightReducerLoop

Type alias for loop reducer based on maximum weight.

Reduces multiple loop iterations based on weight criteria

using Acts::RotationMatrix2 = SquareMatrix2

2D rotation matrix

using Acts::RotationMatrix3 = SquareMatrix3

3D rotation matrix

using Acts::SquareMatrix2 = SquareMatrix<2>

2x2 square matrix type, typically used for 2D coordinate covariance

using Acts::SquareMatrix3 = SquareMatrix<3>

3x3 square matrix type, typically used for 3D coordinate covariance

using Acts::SquareMatrix4 = SquareMatrix<4>

4x4 square matrix type, typically used for 4D coordinate covariance

typedef std::vector<const Surface*> Acts::SurfaceVector

Vector of pointers to constant Surface objects.

using Acts::Transform2 = Eigen::Transform<double, 2, Eigen::AffineCompact>

2D affine transformation stored as a compact 2x3 matrix

using Acts::Transform3 = Eigen::Transform<double, 3, Eigen::Affine>

3D affine transformation stored as a 4x4 matrix

using Acts::Translation2 = Eigen::Translation<double, 2>

2D translation transformation

using Acts::Translation3 = Eigen::Translation<double, 3>

3D translation transformation

using Acts::Vector2 = Vector<2>

2-dimensional vector type for 2D coordinates

using Acts::Vector3 = Vector<3>

3-dimensional vector type for e.g. spatial coordinates and momenta

using Acts::Vector4 = Vector<4>

4-dimensional vector type for space-time coordinates