File CombinatorialKalmanFilter.hpp

namespace Acts

Set the Geometry Context PLUGIN.

Set the Calibration Context PLUGIN.

Convenience functions to ease creation of and Acts::InterpolatedMaterialMap and to avoid code duplication.

Set the Mangetic Field Context PLUGIN.

Convenience functions to ease creation of and Acts::InterpolatedBFieldMap and to avoid code duplication.

Currently implemented for the two most common formats: rz and xyz.

template<typename propagator_t, typename updater_t = VoidKalmanUpdater, typename smoother_t = VoidKalmanSmoother, typename branch_stopper_t = VoidBranchStopper>
class CombinatorialKalmanFilter
#include <Acts/TrackFinding/CombinatorialKalmanFilter.hpp>

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.

tparam propagator_t

Type of the propagator

tparam updater_t

Type of the Kalman updater

tparam smoother_t

Type of the Kalman smoother

tparam branch_stopper_t

Type of the branch stopper

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 (track finding) by the Actor.

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.

Public Functions

CombinatorialKalmanFilter() = delete

Default constructor is deleted.

inline CombinatorialKalmanFilter(propagator_t pPropagator)

Constructor from arguments.

template<typename source_link_accessor_t, typename start_parameters_container_t, typename calibrator_t, typename measurement_selector_t, typename parameters_t = BoundTrackParameters>
inline std::vector<Result<CombinatorialKalmanFilterResult<typename source_link_accessor_t::Value>>> findTracks(const typename source_link_accessor_t::Container &sourcelinks, const start_parameters_container_t &initialParameters, const CombinatorialKalmanFilterOptions<source_link_accessor_t, calibrator_t, measurement_selector_t> &tfOptions) const

Combinatorial Kalman Filter implementation, calls the the Kalman filter and smoother.

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.

Template Parameters

  • source_link_accessor_t – Type of the source link accessor

  • start_parameters_container_t – Type of the initial parameters container

  • calibrator_t – Type of the source link calibrator

  • measurement_selector_t – Type of the measurement selector

  • parameters_t – Type of parameters used for local parameters

Parameters

  • sourcelinks – The fittable uncalibrated measurements

  • initialParameters – The initial track parameters

  • tfOptions – CombinatorialKalmanFilterOptions steering the track finding

Returns

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

Private Types

using KalmanNavigator = typename propagator_t::Navigator

Private Members

propagator_t m_propagator

The propgator for the transport and material update.

template<typename source_link_accessor_t, typename parameters_t, typename calibrator_t, typename measurement_selector_t>
class Aborter

Public Types

using action_type = Actor<source_link_accessor_t, parameters_t, calibrator_t, measurement_selector_t>

Broadcast the result_type.

Public Functions

template<typename propagator_state_t, typename stepper_t, typename result_t>
inline bool operator()(propagator_state_t&, const stepper_t&, const result_t &result) const
template<typename source_link_accessor_t, typename parameters_t, typename calibrator_t, typename measurement_selector_t>
class Actor

Propagator Actor plugin for the CombinatorialKalmanFilter.

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

  • The measurement selector is called during the filtering by the Actor.

tparam source_link_accessor_t

The type of source link accessor

tparam parameters_t

The type of parameters used for “local” paremeters.

tparam calibrator_t

The type of source link calibrator.

tparam measurement_selector_t

The type of the measurement selector.

The CombinatorialKalmanFilter Actor does not rely on the measurements to be sorted along the track.

Public Types

using BoundState = std::tuple<BoundTrackParameters, BoundMatrix, double>
using CurvilinearState = std::tuple<CurvilinearTrackParameters, BoundMatrix, double>
using result_type = CombinatorialKalmanFilterResult<SourceLink>

Broadcast the result_type.

using SourceLink = typename source_link_accessor_t::Value
using SourceLinkContainer = typename source_link_accessor_t::Container
using TipState = CombinatorialKalmanFilterTipState

Public Functions

inline size_t addNonSourcelinkState(const TrackStatePropMask &stateMask, const BoundState &boundState, result_type &result, bool isSensitive, size_t prevTip = SIZE_MAX, LoggerWrapper logger = getDummyLogger()) const

CombinatorialKalmanFilter actor operation : add hole or material track state.

Parameters

  • stateMask – The bitmask that instructs which components to allocate

  • boundState – The bound state on current surface

  • result – is the mutable result state object and which to leave invalid

  • isSensitive – The surface is sensitive or passive

  • prevTip – The index of the previous state

  • logger – The logger wrapper

Returns

The tip of added state

inline Result<std::pair<size_t, TipState>> addSourcelinkState(const TrackStatePropMask &stateMask, const BoundState &boundState, const SourceLink &sourcelink, const BoundVariantMeasurement<SourceLink> &measurement, bool isOutlier, result_type &result, const GeometryContext &geoContext, const size_t &prevTip, const TipState &prevTipState, size_t neighborTip = SIZE_MAX, size_t sharedTip = SIZE_MAX, LoggerWrapper logger = getDummyLogger()) const

CombinatorialKalmanFilter actor operation : add track state with source link: measurement or outlier.

Parameters

  • stateMask – The bitmask that instructs which components to allocate and which to leave invalid

  • boundState – The bound state on current surface

  • sourcelink – The source link to be stored

  • measurement – The calibrated measurement to be stored

  • isOutlier – Indicator for outlier or not

  • result – is the mutable result state object

  • geoContext – The geometry context (needed for Kalman update)

  • prevTip – Previous tip index

  • prevTipState – Previous tip state

  • neighborTip – The neighbor state tip on this surface (the predicted parameters could be shared between neighbors)

  • sharedTip – The tip of state with shared source link

  • logger – The logger wrapper

Returns

The tip of added state and its state

template<typename propagator_state_t, typename stepper_t>
inline Result<void> filter(const Surface *surface, propagator_state_t &state, const stepper_t &stepper, result_type &result) const

CombinatorialKalmanFilter actor operation :

  • filtering for all measurement(s) on surface

  • store selected track states in multiTrajectory

  • update propagator state to the (last) selected track state

Template Parameters

  • propagator_state_t – Type of the Propagagor state

  • stepper_t – Type of the stepper

Parameters

  • surface – The surface where the update happens

  • state – The mutable propagator state object

  • stepper – The stepper in use

  • result – The mutable result state object

template<typename propagator_state_t, typename stepper_t>
inline Result<void> finalize(propagator_state_t &state, const stepper_t &stepper, result_type &result) const

Kalman actor operation : finalize.

Template Parameters

  • propagator_state_t – is the type of Propagagor state

  • stepper_t – Type of the stepper

Parameters

  • state – is the mutable propagator state object

  • stepper – The stepper in use

  • result – is the mutable result state object

template<typename propagator_state_t, typename stepper_t>
inline void materialInteractor(const Surface *surface, propagator_state_t &state, stepper_t &stepper, const MaterialUpdateStage &updateStage = fullUpdate) const

CombinatorialKalmanFilter actor operation : material interaction.

Template Parameters

  • propagator_state_t – is the type of Propagagor state

  • stepper_t – Type of the stepper

Parameters

  • surface – The surface where the material interaction happens

  • state – The mutable propagator state object

  • stepper – The stepper in use

  • updateStage – The materal update stage

template<typename propagator_state_t, typename stepper_t>
inline void operator()(propagator_state_t &state, const stepper_t &stepper, result_type &result) const

CombinatorialKalmanFilter actor operation.

Template Parameters

  • propagator_state_t – Type of the Propagagor state

  • stepper_t – Type of the stepper

Parameters

  • state – is the mutable propagator state object

  • stepper – is the stepper in use

  • result – is the mutable result state object

template<typename propagator_state_t, typename stepper_t>
inline void reset(propagator_state_t &state, stepper_t &stepper, result_type &result) const

Kalman actor operation : reset propagation.

Template Parameters

  • propagator_state_t – Type of Propagagor state

  • stepper_t – Type of the stepper

Parameters

  • state – is the mutable propagator state object

  • stepper – is the stepper in use

  • result – is the mutable result state object

Public Members

bool energyLoss = true

Whether to consider energy loss.

branch_stopper_t m_branchStopper

The branch propagation stopper.

calibrator_t m_calibrator

The source link calibrator.

measurement_selector_t m_measurementSelector

The measurement selector.

smoother_t m_smoother

The CombinatorialKalmanFilter smoother.

source_link_accessor_t m_sourcelinkAccessor

The source link accesor.

updater_t m_updater

The CombinatorialKalmanFilter updater.

bool multipleScattering = true

Whether to consider multiple scattering.

bool smoothing = true

Whether to run smoothing to get fitted parameter.

SurfaceReached targetReached

The Surface beeing.

const Surface *targetSurface = nullptr

The target surface.

template<typename source_link_accessor_t, typename calibrator_t, typename measurement_selector_t>
struct CombinatorialKalmanFilterOptions
#include <Acts/TrackFinding/CombinatorialKalmanFilter.hpp>

Combined options for the combinatorial Kalman filter.

tparam source_link_accessor_t

Source link accessor type, should be semiregular.

tparam calibrator_t

Source link calibrator type, should be semiregular.

tparam measurement_selector_t

Selector type, should be semiregular.

Public Types

using Calibrator = calibrator_t
using MeasurementSelector = measurement_selector_t
using SourceLinkAccessor = source_link_accessor_t

Public Functions

inline CombinatorialKalmanFilterOptions(const GeometryContext &gctx, const MagneticFieldContext &mctx, std::reference_wrapper<const CalibrationContext> cctx, SourceLinkAccessor accessor_, Calibrator calibrator_, MeasurementSelector measurementSelector_, LoggerWrapper logger_, const PropagatorPlainOptions &pOptions, const Surface *rSurface = nullptr, bool mScattering = true, bool eLoss = true, bool rSmoothing = 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

  • accessor_ – The source link accessor

  • calibrator_ – The source link calibrator

  • measurementSelector_ – The measurement selector

  • logger_ – The logger wrapper

  • pOptions – The plain propagator options

  • rSurface – The reference surface for the eventual track fitting to be expressed at

  • mScattering – Whether to include multiple scattering

  • eLoss – Whether to include energy loss

  • rSmoothing – Whether to run smoothing to get fitted parameter

CombinatorialKalmanFilterOptions() = delete

Contexts are required and the options must not be default-constructible.

Public Members

std::reference_wrapper<const CalibrationContext> calibrationContext

context object for the calibration

Calibrator calibrator

The source link calibrator.

bool energyLoss = true

Whether to consider energy loss.

std::reference_wrapper<const GeometryContext> geoContext

Context object for the geometry.

LoggerWrapper logger

Logger instance.

std::reference_wrapper<const MagneticFieldContext> magFieldContext

Context object for the magnetic field.

MeasurementSelector measurementSelector

The measurement selector.

bool multipleScattering = true

Whether to consider multiple scattering.

PropagatorPlainOptions propagatorPlainOptions

The trivial propagator options.

const Surface *referenceSurface = nullptr

The reference Surface.

bool smoothing = true

Whether to run smoothing to get fitted parameter.

SourceLinkAccessor sourcelinkAccessor

The source link accessor.

template<typename source_link_t>
struct CombinatorialKalmanFilterResult
#include <Acts/TrackFinding/CombinatorialKalmanFilter.hpp>

Public Members

std::vector<std::pair<size_t, CombinatorialKalmanFilterTipState>> activeTips
bool filtered = false
bool finished = false
std::unordered_map<size_t, BoundTrackParameters> fittedParameters
MultiTrajectory<source_link_t> fittedStates
size_t iSmoothed = 0
std::vector<size_t> lastMeasurementIndices
std::vector<size_t> lastTrackIndices
std::vector<size_t> measurementCandidateIndices
std::vector<std::pair<size_t, double>> measurementChi2
Result<void> result = {Result<void>::success()}
bool smoothed = false
std::unordered_map<const Surface*, std::unordered_map<size_t, size_t>> sourcelinkTips
struct CombinatorialKalmanFilterTipState
#include <Acts/TrackFinding/CombinatorialKalmanFilter.hpp>

Track quality summary for one trajectory.

This could be used to decide if a track is to be recorded when the filtering is done or to be terminated due to its bad quality

Public Members

size_t nHoles = 0
size_t nMeasurements = 0
size_t nOutliers = 0
size_t nSensitiveSurfaces = 0
size_t nStates = 0