File KalmanFitter.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>
class KalmanFitter
#include <Acts/TrackFitting/KalmanFitter.hpp>

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

Public Functions

inline KalmanFitter(propagator_t pPropagator)
template<typename source_link_iterator_t, typename start_parameters_t, typename parameters_t = BoundTrackParameters, bool _isdn = isDirectNavigator>
inline auto fit(source_link_iterator_t it, source_link_iterator_t end, const start_parameters_t &sParameters, const KalmanFitterOptions &kfOptions) const -> std::enable_if_t<!_isdn, Result<KalmanFitterResult>>

Fit implementation of the foward 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

  • start_parameters_t – Type of the initial parameters

  • parameters_t – Type of parameters used for local parameters

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

Returns

the output as an output track

template<typename source_link_iterator_t, typename start_parameters_t, typename parameters_t = BoundTrackParameters, bool _isdn = isDirectNavigator>
inline auto fit(source_link_iterator_t it, source_link_iterator_t end, const start_parameters_t &sParameters, const KalmanFitterOptions &kfOptions, const std::vector<const Surface*> &sSequence) const -> std::enable_if_t<_isdn, Result<KalmanFitterResult>>

Fit implementation of the foward 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

  • start_parameters_t – Type of the initial parameters

  • parameters_t – Type of parameters used for local parameters

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

Returns

the output as an output track

Private Types

using KalmanNavigator = typename propagator_t::Navigator

The navigator type.

Private Members

propagator_t m_propagator

The propgator for the transport and material update.

Private Static Attributes

static constexpr bool isDirectNavigator = std::is_same<KalmanNavigator, DirectNavigator>::value

The navigator has DirectNavigator type or not.

template<typename parameters_t>
class Aborter

Public Types

using action_type = Actor<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 parameters_t>
class Actor

Propagator Actor plugin for the KalmanFilter.

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

Template Parameters

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

  • calibrator_t – The type of calibrator

  • outlier_finder_t – Type of the outlier finder class

Public Types

using result_type = KalmanFitterResult

Broadcast the result_type.

Public Functions

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

Kalman actor operation : update.

Template Parameters

  • propagator_state_t – is the type of 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

Kalman 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

Kalman actor operation.

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 Result<void> reverse(propagator_state_t &state, stepper_t &stepper, result_type &result) const

Kalman actor operation : reverse direction.

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 objecte

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

Kalman actor operation : update in reversed direction.

Template Parameters

  • propagator_state_t – is the type of 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

Public Members

bool energyLoss = true

Whether to consider energy loss.

KalmanFitterExtensions extensions
FreeToBoundCorrection freeToBoundCorrection

Whether to include non-linear correction during global to local transformation.

const std::map<GeometryIdentifier, std::reference_wrapper<const SourceLink>> *inputMeasurements = nullptr

Allows retrieving measurements for a surface.

bool multipleScattering = true

Whether to consider multiple scattering.

bool reversedFiltering = false

Whether run reversed filtering.

double reversedFilteringCovarianceScaling = 1.0
SurfaceReached targetReached

The Surface beeing.

const Surface *targetSurface = nullptr

The target surface.

struct KalmanFitterExtensions
#include <Acts/TrackFitting/KalmanFitter.hpp>

Extension struct which holeds delegates to customize the KF behavior.

Public Types

using Calibrator = Delegate<void(const GeometryContext&, TrackStateProxy)>
using ConstTrackStateProxy = MultiTrajectory::ConstTrackStateProxy
using OutlierFinder = Delegate<bool(ConstTrackStateProxy)>
using Parameters = TrackStateProxy::Parameters
using ReverseFilteringLogic = Delegate<bool(ConstTrackStateProxy)>
using Smoother = Delegate<Result<void>(const GeometryContext&, MultiTrajectory&, size_t, LoggerWrapper)>
using TrackStateProxy = MultiTrajectory::TrackStateProxy
using Updater = Delegate<Result<void>(const GeometryContext&, TrackStateProxy, NavigationDirection, LoggerWrapper)>

Public Functions

inline KalmanFitterExtensions()

Default constructor which connects the default void components.

Public Members

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.

OutlierFinder outlierFinder

Determines whether a measurement is supposed to be considered as an outlier.

ReverseFilteringLogic reverseFilteringLogic

Decides whether the smoothing stage uses linearized transport or full reverse propagation.

Smoother smoother

The smoother back-propagates measurement information along the track.

Updater updater

The updater incorporates measurement information into the track parameters.

struct KalmanFitterOptions
#include <Acts/TrackFitting/KalmanFitter.hpp>

Combined options for the Kalman fitter.

Template Parameters

SourceLink – Source link type

Public Functions

inline KalmanFitterOptions(const GeometryContext &gctx, const MagneticFieldContext &mctx, std::reference_wrapper<const CalibrationContext> cctx, KalmanFitterExtensions extensions_, LoggerWrapper logger_, const PropagatorPlainOptions &pOptions, const Surface *rSurface = nullptr, bool mScattering = true, bool eLoss = true, bool rFiltering = false, double rfScaling = 1.0, const FreeToBoundCorrection &freeToBoundCorrection_ = FreeToBoundCorrection(false))

PropagatorOptions with context.

Parameters

  • gctx – The goemetry context for this fit

  • mctx – The magnetic context for this fit

  • cctx – The calibration context for this fit

  • extensions_ – The KF extensions

  • logger_ – The logger wrapper

  • pOptions – The plain propagator options

  • rSurface – The reference surface for the fit to be expressed at

  • mScattering – Whether to include multiple scattering

  • eLoss – Whether to include energy loss

  • rFiltering – Whether to run filtering in reversed direction as smoothing

  • rfScaling – Scale factor for the covariance matrix before the backward filtering

  • freeToBoundCorrection_ – Correction for non-linearity effect during transform from free to bound

KalmanFitterOptions() = 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.

KalmanFitterExtensions extensions
FreeToBoundCorrection freeToBoundCorrection

Whether to include non-linear correction during global to local transformation.

std::reference_wrapper<const GeometryContext> geoContext

Context object for the geometry.

LoggerWrapper logger

Logger.

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 reversedFiltering = false

Whether to run filtering in reversed direction overwrite the ReverseFilteringLogic.

double reversedFilteringCovarianceScaling = 1.0

Factor by which the covariance of the input of the reversed filtering is scaled.

This is only used in the backwardfiltering (if reversedFiltering is true or if the ReverseFilteringLogic return true for the track of interest)

struct KalmanFitterResult
#include <Acts/TrackFitting/KalmanFitter.hpp>

Public Members

bool finished = false
std::optional<BoundTrackParameters> fittedParameters
MultiTrajectory fittedStates
size_t lastMeasurementIndex = SIZE_MAX
size_t lastTrackIndex = SIZE_MAX
size_t measurementHoles = 0
size_t measurementStates = 0
std::vector<const Surface*> missedActiveSurfaces
std::vector<const Surface*> passedAgainSurfaces
size_t processedStates = 0
Result<void> result = {Result<void>::success()}
bool reversed = false
bool smoothed = false