Reference stepper with a configurable Runge-Kutta tableau. More...

#include <Acts/Propagator/GenericRungeKuttaStepper.hpp>

Classes
struct	Config
	Configuration for the Runge-Kutta stepper. More...
struct	Options
	Runtime options for Runge-Kutta propagation. More...
struct	State
	State for track parameter propagation. More...

Public Types
using	BoundParameters = BoundTrackParameters
	Type alias for bound track parameters.
using	Covariance = BoundMatrix
	Type alias for covariance matrix.
enum class	ErrorEstimation { None , Embedded , StepDoubling }
	Error estimate for the adaptive step size. More...
using	FieldAndGradient = MagneticFieldProvider::FieldAndGradient
	Type alias for the magnetic field and its gradient.
using	Jacobian = BoundMatrix
	Type alias for jacobian matrix.

Public Member Functions
	GenericRungeKuttaStepper (const Config &config)
	Constructor with configuration.
	GenericRungeKuttaStepper (std::shared_ptr< const MagneticFieldProvider > bField)
	Constructor requires knowledge of the detector's magnetic field.
double	absoluteMomentum (const State &state) const
	Absolute momentum accessor.
Result< BoundParameters >	boundParameters (const State &state, const Surface &surface) const
	Get the bound parameters at the current position.
double	charge (const State &state) const
	Charge access.
const std::optional< Covariance > &	covariance (const State &state) const
	Get the covariance at the anchor.
Result< Vector3 >	curvature (State &state) const
	Current global geometric curvature d(direction)/ds in inverse length.
BoundParameters	curvilinearParameters (const State &state) const
	Get the curvilinear parameters at the current position.
Vector3	direction (const State &state) const
	Momentum direction accessor.
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.
Result< FieldAndGradient >	getFieldAndGradient (State &state, const Vector3 &pos, bool withGradient) const
	Get the field and optionally its gradient at a position.
double	getStepSize (const State &state, ConstrainedStep::Type stype) const
	Get the step size.
bool	hasCovariance (const State &state) const
	Check if the state carries a covariance.
void	initialize (State &state, const BoundParameters &par) const
	Initialize the state from 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.
State	makeState (const Options &options) const
	Create a state object.
Vector3	momentum (const State &state) const
	Momentum accessor.
std::string	outputStepSize (const State &state) const
	Output the Step Size - single component.
const ParticleHypothesis &	particleHypothesis (const State &state) const
	Particle hypothesis.
double	pathLength (const State &state) const
	Get the path length.
Vector3	position (const State &state) const
	Global particle position accessor.
bool	prepareCurvilinearState (State &state) const
	If necessary fill additional members needed for transportToCurvilinear.
double	qOverP (const State &state) const
	QoP direction accessor.
void	releaseStepSize (State &state, ConstrainedStep::Type stype) const
	Release the Step size.
void	setCovariance (State &state, const Covariance &covariance) const
	Set the covariance at the anchor.
const StepperStatistics &	statistics (const State &state) const
	Get the stepper statistics.
Result< double >	step (State &state, Direction propDir, const IVolumeMaterial *material) const
	Perform a Runge-Kutta track parameter propagation step.
const ConstrainedStep &	stepSize (const State &state) const
	Get the step size constraints.
double	time (const State &state) const
	Time access.
Result< Jacobian >	transportToBound (State &state, const Surface &surface, const FreeToBoundCorrection &freeToBoundCorrection=FreeToBoundCorrection(false)) const
	Transport the covariance to a surface at the current position.
Jacobian	transportToCurvilinear (State &state) const
	Transport the covariance to the curvilinear frame at the current position.
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.
void	update (State &state, const Vector3 &uposition, const Vector3 &udirection, double qop, double time) const
	Method to update the stepper state.
void	updateStepSize (State &state, const NavigationTarget &target, Direction direction, ConstrainedStep::Type stype) const
	Update step size.
void	updateStepSize (State &state, double stepSize, ConstrainedStep::Type stype) const
	Update step size - explicitly with a double.
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 Vector3 &curvature=Vector3::Zero()) const
	Update surface status.

Detailed Description

Reference stepper with a configurable Runge-Kutta tableau.

The stepper integrates the equation of motion in vacuum for the free parameters y = (r, t, T, q/p),

dy/ds = f(y) = (T, 1/beta, (q/p) T x B(r), 0),

with any explicit ButcherTableau. It is not optimised. It is meant as a reference to compare other steppers against.

The transport jacobian is the exact derivative of the discrete step. The stepper differentiates each stage with the chain rule,

dY_i = I + h sum_j a_ij dK_j, dK_i = J_f(Y_i) dY_i, D = I + h sum_i b_i dK_i,

so it works for every tableau. Here dY_i, dK_i and D are the derivatives of the stage, of the stage slope and of the step by the free parameters at the start of the step. J_f = df/dy has the non-zero blocks

d(r)/dT = I, d(t)/d(q/p) = d(1/beta)/d(q/p), d(T)/dr = (q/p) [T x] dB/dr, d(T)/dT = -(q/p) [B x], d(T)/d(q/p) = T x B.

The stepper takes dB/dr from the field provider. If the provider does not implement the gradient, the stepper computes it with central finite differences of the field, so the jacobian is exact up to the O(epsilon^2) error of the gradient, see Options::fieldGradientEpsilon. Without the gradient term (Options::includeFieldGradient) the jacobian is not exact.

After the step, the stepper normalises the direction to unit length. This is part of the discrete step, so the stepper also applies its derivative (I - T T^T / |T|^2) / |T| to the direction rows of D.

The stepper adapts the step size to StepperPlainOptions::stepTolerance with one of two error estimates, see ErrorEstimation. The error estimate is the maximum norm of the position (mm), the time (mm) and the dimensionless direction components, with the same absolute tolerance. In vacuum q/p does not change, so it does not contribute. The step size control follows Hairer, Nørsett, Wanner, Solving Ordinary Differential Equations I, 2nd ed., Section II.4.

As for HelixStepper, a step to the straight-line distance of a surface can pass it, and the next step goes back. A target aborter must accept an intersection that far behind the track.

Note: The order of a tableau only holds in a smooth field. An interpolated field map is continuous but not differentiable at the cell faces. A step that crosses a face has a local error of order h^2 for every tableau. The number of crossings does not decrease with h, so in a field map every tableau is only accurate to about second order.; The stepper propagates in vacuum only. It ignores volume material.

Member Enumeration Documentation

◆ ErrorEstimation

enum class Acts::GenericRungeKuttaStepper::ErrorEstimation

strong

Error estimate for the adaptive step size.

Both use the same tolerance. The embedded estimate is for the lower-order solution, so the propagated solution is usually 100 to 1000 times more accurate than the tolerance. Step doubling estimates the propagated solution itself, so its local error is about the tolerance.

Enumerator

None

Fixed step size.

Embedded

Solution minus embedded solution. Needs embedded weights.

StepDoubling

One step of h against two steps of h/2, which are propagated.

Works for every tableau, at about three times the cost.

Constructor & Destructor Documentation

◆ GenericRungeKuttaStepper() [1/2]

Acts::GenericRungeKuttaStepper::GenericRungeKuttaStepper ( std::shared_ptr< const MagneticFieldProvider > bField )

explicit

Constructor requires knowledge of the detector's magnetic field.

Parameters

bField The magnetic field provider

◆ GenericRungeKuttaStepper() [2/2]

Acts::GenericRungeKuttaStepper::GenericRungeKuttaStepper ( const Config & config )

explicit

Constructor with configuration.

Parameters

config The configuration of the stepper

Member Function Documentation

◆ absoluteMomentum()

double Acts::GenericRungeKuttaStepper::absoluteMomentum ( const State & state ) const

Absolute momentum accessor.

Parameters

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

Returns: Absolute momentum

◆ boundParameters()

Result< BoundParameters > Acts::GenericRungeKuttaStepper::boundParameters	(	const State &	state,
		const Surface &	surface ) const

Get the bound parameters at the current position.

The parameters carry the covariance at the anchor if the state has one.

Note: It does not check if the state is on surface or anchored on it

Parameters

[in]	state	The stepping state (thread-local cache)
[in]	surface	The surface of the parameters

Returns: The bound parameters, or a failure if the position cannot be expressed on surface

◆ charge()

double Acts::GenericRungeKuttaStepper::charge ( const State & state ) const

Charge access.

Parameters

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

Returns: Particle charge

◆ covariance()

const std::optional< Covariance > & Acts::GenericRungeKuttaStepper::covariance ( const State & state ) const

Get the covariance at the anchor.

The anchor is the frame of the last initialization, transport or update.

Parameters

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

Returns: The covariance at the anchor, or no value if the state does not carry a covariance

◆ curvature()

Result< Vector3 > Acts::GenericRungeKuttaStepper::curvature ( State & state ) const

Current global geometric curvature d(direction)/ds in inverse length.

Unchanged under propagation reversal; reflects current momentum and field.

Parameters

state Stepping state; the field cache may be updated

Returns: Curvature vector, or a field lookup error

◆ curvilinearParameters()

BoundParameters Acts::GenericRungeKuttaStepper::curvilinearParameters ( const State & state ) const

Get the curvilinear parameters at the current position.

The parameters carry the covariance at the anchor if the state has one.

Parameters

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

Returns: The curvilinear parameters

◆ direction()

Vector3 Acts::GenericRungeKuttaStepper::direction ( const State & state ) const

Momentum direction accessor.

Parameters

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

Returns: Direction vector

◆ getField()

Result< Vector3 > Acts::GenericRungeKuttaStepper::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

[in,out]	state	is the propagation state associated with the track the magnetic field cell is used (and potentially updated)
[in]	pos	is the field position

Returns: Magnetic field vector

◆ getFieldAndGradient()

Result< FieldAndGradient > Acts::GenericRungeKuttaStepper::getFieldAndGradient	(	State &	state,
		const Vector3 &	pos,
		bool	withGradient ) const

Get the field and optionally its gradient at a position.

Parameters

[in,out]	state	The stepper state with the field cache
[in]	pos	The position of the lookup
[in]	withGradient	Whether the gradient is needed

Returns: The field and the gradient, which is zero without withGradient

◆ getStepSize()

double Acts::GenericRungeKuttaStepper::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

◆ hasCovariance()

bool Acts::GenericRungeKuttaStepper::hasCovariance ( const State & state ) const

Check if the state carries a covariance.

Parameters

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

Returns: True if the covariance is transported

◆ initialize() [1/2]

void Acts::GenericRungeKuttaStepper::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

◆ initialize() [2/2]

void Acts::GenericRungeKuttaStepper::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

◆ makeState()

State Acts::GenericRungeKuttaStepper::makeState ( const Options & options ) const

Create a state object.

Parameters

options Stepper options

Returns: State object

Exceptions

std::invalid_argument for an embedded error estimate without embedded weights

◆ momentum()

Vector3 Acts::GenericRungeKuttaStepper::momentum ( const State & state ) const

Momentum accessor.

Parameters

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

Returns: Momentum vector

◆ outputStepSize()

std::string Acts::GenericRungeKuttaStepper::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

◆ particleHypothesis()

const ParticleHypothesis & Acts::GenericRungeKuttaStepper::particleHypothesis ( const State & state ) const

Particle hypothesis.

Parameters

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

Returns: Particle hypothesis

◆ pathLength()

double Acts::GenericRungeKuttaStepper::pathLength ( const State & state ) const

Get the path length.

Parameters

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

Returns: The path length since the last initialization

◆ position()

Vector3 Acts::GenericRungeKuttaStepper::position ( const State & state ) const

Global particle position accessor.

Parameters

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

Returns: Position vector

◆ prepareCurvilinearState()

bool Acts::GenericRungeKuttaStepper::prepareCurvilinearState ( State & state ) const

If necessary fill additional members needed for transportToCurvilinear.

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

Parameters

[in,out] state State of the stepper

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

◆ qOverP()

double Acts::GenericRungeKuttaStepper::qOverP ( const State & state ) const

QoP direction accessor.

Parameters

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

Returns: Charge over momentum

◆ releaseStepSize()

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

Release the Step size.

Parameters

	state	[in,out] The stepping state (thread-local cache)
[in]	stype	The step size type to be released

◆ setCovariance()

void Acts::GenericRungeKuttaStepper::setCovariance	(	State &	state,
		const Covariance &	covariance ) const

Set the covariance at the anchor.

The state must already carry a covariance, because the stepper only transports the Jacobian while it has one.

Parameters

[in,out]	state	The stepping state (thread-local cache)
[in]	covariance	The new covariance at the anchor

Exceptions

std::logic_error if the state does not carry a covariance

◆ statistics()

const StepperStatistics & Acts::GenericRungeKuttaStepper::statistics ( const State & state ) const

Get the stepper statistics.

Parameters

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

Returns: The statistics since the last initialization

◆ step()

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

Perform a Runge-Kutta track parameter propagation step.

Parameters

[in,out]	state	State of the stepper
	propDir	is the direction of propagation
	material	is ignored, the stepper propagates in vacuum only

Returns: the result of the step

Exceptions

std::invalid_argument for an embedded error estimate without embedded weights

Note: The state contains the desired step size. It can be negative during backwards track propagation, and since the step size is adaptive, it can be modified by the stepper class during propagation.

◆ stepSize()

const ConstrainedStep & Acts::GenericRungeKuttaStepper::stepSize ( const State & state ) const

Get the step size constraints.

Parameters

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

Returns: The step size constraints

◆ time()

double Acts::GenericRungeKuttaStepper::time ( const State & state ) const

Time access.

Parameters

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

Returns: Time

◆ transportToBound()

Result< Jacobian > Acts::GenericRungeKuttaStepper::transportToBound	(	State &	state,
		const Surface &	surface,
		const FreeToBoundCorrection &	freeToBoundCorrection = FreeToBoundCorrection(false) ) const

Transport the covariance to a surface at the current position.

This anchors the state on surface. Without a covariance the state does not change. The state must be on surface, and it stays unchanged if it is not.

Parameters

[in,out]	state	State of the stepper
[in]	surface	The surface to transport the covariance to
[in]	freeToBoundCorrection	Correction for non-linearity effect during transform from free to bound

Returns: The jacobian from the previous anchor to surface, or a failure if the state is not on surface

◆ transportToCurvilinear()

Jacobian Acts::GenericRungeKuttaStepper::transportToCurvilinear ( State & state ) const

Transport the covariance to the curvilinear frame at the current position.

This anchors the state on the curvilinear frame. Without a covariance the state does not change.

Parameters

[in,out] state State of the stepper

Returns: The jacobian from the previous anchor to the curvilinear frame

◆ update() [1/2]

void Acts::GenericRungeKuttaStepper::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.

This anchors the state on surface.

Parameters

[in,out]	state	State object that will be updated
[in]	freeParams	Free parameters that will be written into `state`
[in]	boundParams	Corresponding bound parameters used to update jacToGlobal in `state`
[in]	covariance	The covariance that will be written into `state` if the state carries a covariance
[in]	surface	The surface used to update the jacToGlobal

◆ update() [2/2]

void Acts::GenericRungeKuttaStepper::update	(	State &	state,
		const Vector3 &	uposition,
		const Vector3 &	udirection,
		double	qop,
		double	time ) const

Method to update the stepper state.

Parameters

[in,out]	state	State object that will be updated
[in]	uposition	the updated position
[in]	udirection	the updated direction
[in]	qop	the updated qop value
[in]	time	the updated time value

◆ updateStepSize() [1/2]

void Acts::GenericRungeKuttaStepper::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

◆ updateStepSize() [2/2]

void Acts::GenericRungeKuttaStepper::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

◆ updateSurfaceStatus()

IntersectionStatus Acts::GenericRungeKuttaStepper::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 Vector3 &	curvature = Vector3::Zero() ) const

Update surface status.

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

Parameters

[in,out]	state	The stepping state (thread-local cache)
[in]	surface	The surface provided
[in]	index	The surface intersection index
[in]	navDir	The navigation direction
[in]	boundaryTolerance	The boundary check for this status update
[in]	surfaceTolerance	Surface tolerance used for intersection
[in]	stype	The step size type to be set
[in]	logger	A `Logger` instance
	curvature	Global geometric curvature for the crossing estimate

Returns: Intersection status

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ ErrorEstimation

Constructor & Destructor Documentation

◆ GenericRungeKuttaStepper() [1/2]

◆ GenericRungeKuttaStepper() [2/2]

Member Function Documentation

◆ absoluteMomentum()

◆ boundParameters()

◆ charge()

◆ covariance()

◆ curvature()

◆ curvilinearParameters()

◆ direction()

◆ getField()

◆ getFieldAndGradient()

◆ getStepSize()

◆ hasCovariance()

◆ initialize() [1/2]

◆ initialize() [2/2]

◆ makeState()

◆ momentum()

◆ outputStepSize()

◆ particleHypothesis()

◆ pathLength()

◆ position()

◆ prepareCurvilinearState()

◆ qOverP()

◆ releaseStepSize()

◆ setCovariance()

◆ statistics()

◆ step()

◆ stepSize()

◆ time()

◆ transportToBound()

◆ transportToCurvilinear()

◆ update() [1/2]

◆ update() [2/2]

◆ updateStepSize() [1/2]

◆ updateStepSize() [2/2]

◆ updateSurfaceStatus()