File CombinatorialKalmanFilter.hpp

namespace Acts

Note

This file is foreseen for the Geometry module to replace Extent

Typedefs

using SourceLinkAccessorDelegate = Delegate<std::pair<source_link_iterator_t, source_link_iterator_t>(const Surface&)>

Delegate type that retrieves a range of source links to for a given surface to be processed by the CKF.

template<typename propagator_t, typename traj_t>
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.

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.

Template Parameters

propagator_t – Type of the propagator

Public Functions

CombinatorialKalmanFilter() = delete

Default constructor is deleted.

inline CombinatorialKalmanFilter(propagator_t pPropagator)

Constructor from arguments.

template<typename source_link_iterator_t, typename start_parameters_container_t, typename parameters_t = BoundTrackParameters>
inline std::vector<Result<CombinatorialKalmanFilterResult<traj_t>>> findTracks(const start_parameters_container_t &initialParameters, const CombinatorialKalmanFilterOptions<source_link_iterator_t, traj_t> &tfOptions) const

Combinatorial Kalman Filter implementation, calls 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_iterator_t – Type of the source link iterator

  • 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

  • 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>
class Aborter

Public Types

using action_type = Actor<source_link_accessor_t, parameters_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>
class Actor

Propagator Actor plugin for the CombinatorialKalmanFilter.

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

Template Parameters

  • source_link_accessor_t – The type of source link accessor

  • parameters_t – The type of parameters used for “local” parameters.

Public Types

using BoundState = std::tuple<parameters_t, BoundMatrix, double>
using CurvilinearState = std::tuple<CurvilinearTrackParameters, BoundMatrix, double>
using result_type = CombinatorialKalmanFilterResult<traj_t>

Broadcast the result_type.

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

template<typename source_link_iterator_t>
inline void createSourceLinkTrackStates(const Acts::GeometryContext &gctx, result_type &result, const BoundState &boundState, size_t prevTip, source_link_iterator_t slBegin, source_link_iterator_t slEnd) const

Create and fill track states for all source links.

Parameters

  • gctx – The current geometry context

  • result – Reference to the result struct of the actor

  • boundState – Bound state from the propagation on this surface

  • prevTip – Index pointing at previous trajectory state (i.e. tip)

  • slBegin – Begin iterator for sourcelinks

  • slEnd – End iterator for sourcelinks

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 = MaterialUpdateStage::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

inline Result<void> processSelectedTrackStates(const Acts::GeometryContext &gctx, typename std::vector<typename MultiTrajectory<traj_t>::TrackStateProxy>::const_iterator begin, typename std::vector<typename MultiTrajectory<traj_t>::TrackStateProxy>::const_iterator end, result_type &result, bool isOutlier, const TipState &prevTipState, size_t &nBranchesOnSurface, LoggerWrapper logger) const

Handle the list of selected track states.

Parameters

  • gctx – The current geometry context

  • begin – The start iterator for selected track states

  • end – The end iterator for selected track states

  • result – Reference to the actor result struct

  • isOutlier – If this track state is a single outlier one

  • prevTipState – Tip state prior to this surface

  • nBranchesOnSurface – [inout] Number of branches on surface, will be updated

  • logger – A logging instance

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.

CombinatorialKalmanFilterExtensions<traj_t> m_extensions
source_link_accessor_t m_sourcelinkAccessor

The source link accesor.

bool multipleScattering = true

Whether to consider multiple scattering.

bool smoothing = true

Whether to run smoothing to get fitted parameter.

SurfaceReached targetReached

The Surface being targeted.

const Surface *targetSurface = nullptr

The target surface.

template<typename traj_t>
struct CombinatorialKalmanFilterExtensions
#include <Acts/TrackFinding/CombinatorialKalmanFilter.hpp>

Extension struct which holds the delegates to customize the CKF behavior.

Public Types

using BranchStopper = Delegate<bool(const CombinatorialKalmanFilterTipState&)>
using candidate_container_t = typename std::vector<typename MultiTrajectory<traj_t>::TrackStateProxy>
using MeasurementSelector = Delegate<Result<std::pair<typename candidate_container_t::iterator, typename candidate_container_t::iterator>>(candidate_container_t &trackStates, bool&, LoggerWrapper)>

Public Functions

inline CombinatorialKalmanFilterExtensions()

Default constructor which connects the default void components.

Public Members

BranchStopper branchStopper
KalmanFitterExtensions<traj_t>::Calibrator calibrator

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

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

KalmanFitterExtensions<traj_t>::Smoother smoother

The smoother back-propagates measurement information along the track.

KalmanFitterExtensions<traj_t>::Updater updater

The updater incorporates measurement information into the track parameters.

Private Static Functions

static inline bool voidBranchStopper(const CombinatorialKalmanFilterTipState &tipState)

Default branch stopper which will never stop.

Parameters

tipState – The tip state to decide whether to stop (unused)

Returns

false

static inline Result<std::pair<typename std::vector<typename MultiTrajectory<traj_t>::TrackStateProxy>::iterator, typename std::vector<typename MultiTrajectory<traj_t>::TrackStateProxy>::iterator>> voidMeasurementSelector(typename std::vector<typename MultiTrajectory<traj_t>::TrackStateProxy> &candidates, bool &isOutlier, LoggerWrapper logger)

Default measurement selector which will return all measurements.

Parameters

  • candidates – Measurement track state candidates

  • isOutlier – Output variable indicating whether the returned state is an outlier (unused)

  • logger – A logger instance

template<typename source_link_iterator_t, typename traj_t>
struct CombinatorialKalmanFilterOptions
#include <Acts/TrackFinding/CombinatorialKalmanFilter.hpp>

Combined options for the combinatorial Kalman filter.

Template Parameters

source_link_accessor_t – Source link accessor type, should be semiregular.

Public Types

using SourceLinkAccessor = SourceLinkAccessorDelegate<source_link_iterator_t>
using SourceLinkIterator = source_link_iterator_t

Public Functions

inline CombinatorialKalmanFilterOptions(const GeometryContext &gctx, const MagneticFieldContext &mctx, std::reference_wrapper<const CalibrationContext> cctx, SourceLinkAccessor accessor_, CombinatorialKalmanFilterExtensions<traj_t> extensions_, 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

  • extensions_ – The extension struct

  • 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

bool energyLoss = true

Whether to consider energy loss.

CombinatorialKalmanFilterExtensions<traj_t> extensions

The filter extensions.

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.

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 traj_t>
struct CombinatorialKalmanFilterResult
#include <Acts/TrackFinding/CombinatorialKalmanFilter.hpp>

Public Members

std::vector<std::pair<MultiTrajectoryTraits::IndexType, CombinatorialKalmanFilterTipState>> activeTips
bool filtered = false
bool finished = false
std::unordered_map<MultiTrajectoryTraits::IndexType, BoundTrackParameters> fittedParameters
traj_t fittedStates
MultiTrajectoryTraits::IndexType iSmoothed = 0
std::vector<MultiTrajectoryTraits::IndexType> lastMeasurementIndices
std::vector<MultiTrajectoryTraits::IndexType> lastTrackIndices
Result<void> result = {Result<void>::success()}
bool smoothed = false
std::unordered_map<const Surface*, std::unordered_map<size_t, size_t>> sourcelinkTips
traj_t stateBuffer
std::vector<typename MultiTrajectory<traj_t>::TrackStateProxy> trackStateCandidates
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