Detailed Description

Error Handling in ACTS

ACTS uses std::error_code from the C++ Standard Library for type-safe, extensible error handling. This approach allows error codes to be returned from functions without throwing exceptions, while maintaining compatibility with the standard error handling mechanisms. Error codes are typically used with the Acts::Result type for ergonomic error propagation.

std::error_code Overview

std::error_code is a platform-dependent error code that consists of:

An integer error value
A reference to an error category (error domain)

Various ACTS components define their own strongly-typed error enum class and register it with the standard library's error code system using std::is_error_code_enum specialization. This allows seamless conversion to std::error_code while preserving type safety.

Error Enum Pattern

All ACTS error enums follow a consistent pattern:

enum class MyComponentError {
  ErrorValue1 = 1,  // All error values must be non-zero
  ErrorValue2,
  // ...
};
 
// Factory function to create std::error_code
std::error_code make_error_code(MyComponentError e);

The enums are registered with STL by specializing std::is_error_code_enum<T> to enable implicit conversion to std::error_code.

Usage with Result Type

Error codes are typically used with the Acts::Result type, which encapsulates either a successful result or an error:

Acts::Result<Track> fitTrack(const TrackParameters& params) {
  if (params.momentum < 0) {
    return Acts::KalmanFitterError::UpdateFailed;
  }
  Track track{42};
  return track;  // Success
}
 
void processTrack() {
  TrackParameters params{100.0};
 
  // Usage
  auto result = fitTrack(params);
  if (!result.ok()) {
    std::error_code error = result.error();
    // Handle error
    std::cerr << "Error: " << error.message() << std::endl;
  } else {
    Track track = std::move(result).value();
    std::cout << "Track fitted successfully: " << track.id << std::endl;
  }
}

The Acts::Result type defaults to using std::error_code as its error type, making it compatible with all ACTS error enums.

Benefits

Type Safety: Each component has its own error enum preventing confusion between different error domains
No Exceptions: Errors are returned as values, enabling explicit error handling without exception overhead
Standard Compatibility: Integration with std::error_code allows use with standard library error handling facilities
Extensibility: New error types can be added to any enum without breaking binary compatibility

Enumerations
enum class	Acts::CombinatorialKalmanFilterError { Acts::CombinatorialKalmanFilterError::UpdateFailed = 1 , Acts::CombinatorialKalmanFilterError::SmoothFailed , Acts::CombinatorialKalmanFilterError::OutputConversionFailed , Acts::CombinatorialKalmanFilterError::MeasurementSelectionFailed , Acts::CombinatorialKalmanFilterError::PropagationReachesMaxSteps , Acts::CombinatorialKalmanFilterError::NoMeasurementExpected }
	Error codes for combinatorial Kalman filter operations. More...
enum class	ActsFatras::DigitizationError { ActsFatras::DigitizationError::SmearingOutOfRange = 1 , ActsFatras::DigitizationError::SmearingError , ActsFatras::DigitizationError::UndefinedSurface , ActsFatras::DigitizationError::MaskingError , ActsFatras::DigitizationError::MaximumRetriesExceeded }
enum class	Acts::EigenStepperError { Acts::EigenStepperError::StepSizeStalled = 1 , Acts::EigenStepperError::StepInvalid , Acts::EigenStepperError::StepSizeAdjustmentFailed }
	Error codes for Eigen stepper operations. More...
enum class	ActsPlugins::GeoModelConversionError { ActsPlugins::GeoModelConversionError::WrongShapeForConverter = 1 , ActsPlugins::GeoModelConversionError::InvalidShapeParameters , ActsPlugins::GeoModelConversionError::UnkownShape , ActsPlugins::GeoModelConversionError::MissingLogicalVolume }
enum class	Acts::Experimental::GlobalChiSquareFitterError { Acts::Experimental::GlobalChiSquareFitterError::AIsNotInvertible = 1 , Acts::Experimental::GlobalChiSquareFitterError::DidNotConverge = 2 , Acts::Experimental::GlobalChiSquareFitterError::NotEnoughMeasurements = 3 , Acts::Experimental::GlobalChiSquareFitterError::UpdatePushedToNewVolume = 4 }
enum class	Acts::GsfError { Acts::GsfError::StartParametersHaveNoCovariance , Acts::GsfError::NoMeasurementStatesCreatedForward , Acts::GsfError::NoMeasurementStatesCreatedBackward , Acts::GsfError::NoMeasurementStatesCreatedFinal }
	Error codes for Gaussian Sum Filter operations. More...
enum class	Acts::KalmanFitterError { Acts::KalmanFitterError::UpdateFailed = 1 , Acts::KalmanFitterError::SmoothFailed , Acts::KalmanFitterError::OutputConversionFailed , Acts::KalmanFitterError::NoMeasurementFound , Acts::KalmanFitterError::ReversePropagationFailed , Acts::KalmanFitterError::InconsistentTrackStates }
	Error codes for Kalman filter operations. More...
enum class	Acts::MagneticFieldError { Acts::MagneticFieldError::OutOfBounds = 1 , Acts::MagneticFieldError::NotImplemented = 2 }
	Error codes for magnetic field operations. More...
enum class	Acts::MultiStepperError { Acts::MultiStepperError::ComponentNotOnSurface = 1 , Acts::MultiStepperError::StateOfMultipleComponentsRequested = 2 , Acts::MultiStepperError::AverageTrackLeftCurrentVolume = 3 , Acts::MultiStepperError::AllComponentsSteppingError = 4 , Acts::MultiStepperError::AllComponentsConversionToBoundFailed = 5 , Acts::MultiStepperError::SomeComponentsConversionToBoundFailed = 6 }
	Error codes for multi-stepper operations. More...
enum class	Acts::NavigatorError { Acts::NavigatorError::NotInsideExpectedVolume = 1 , Acts::NavigatorError::NotOnExpectedSurface = 2 , Acts::NavigatorError::NoStartVolume = 3 }
	Error codes for navigator operations. More...
enum class	Acts::PortalError { Acts::PortalError::PositionNotOnAnyChildPortalLink = 1 }
	Error codes for portal operations. More...
enum class	Acts::PropagatorError { Acts::PropagatorError::Failure = 1 , Acts::PropagatorError::StepCountLimitReached , Acts::PropagatorError::NextTargetLimitReached }
	Error codes for propagator operations. More...
enum class	Acts::SpacePointFormationError { Acts::SpacePointFormationError::ClusterPairDistanceExceeded = 1 , Acts::SpacePointFormationError::ClusterPairThetaDistanceExceeded = 2 , Acts::SpacePointFormationError::ClusterPairPhiDistanceExceeded = 3 , Acts::SpacePointFormationError::CosmicToleranceNotMet = 4 , Acts::SpacePointFormationError::OutsideLimits = 5 , Acts::SpacePointFormationError::OutsideRelaxedLimits = 6 , Acts::SpacePointFormationError::NoSolutionFound = 7 }
	Error codes for space point formation operations. More...
enum class	Acts::SurfaceError { Acts::SurfaceError::GlobalPositionNotOnSurface = 1 }
	Error codes for surface operations. More...
enum class	Acts::TrackExtrapolationError { Acts::TrackExtrapolationError::CompatibleTrackStateNotFound = 1 , Acts::TrackExtrapolationError::ReferenceSurfaceUnreachable = 2 }
	Error codes for track extrapolation operations. More...
enum class	Acts::VertexingError { Acts::VertexingError::NumericFailure = 1 , Acts::VertexingError::EmptyInput , Acts::VertexingError::SeedingError , Acts::VertexingError::NotConverged , Acts::VertexingError::ElementNotFound , Acts::VertexingError::NoCovariance , Acts::VertexingError::SingularMatrix , Acts::VertexingError::NonPositiveVariance , Acts::VertexingError::MatrixNotPositiveDefinite , Acts::VertexingError::InvalidInput , Acts::VertexingError::CouldNotRemoveTrack }
	Error codes for vertexing operations. More...

Enumeration Type Documentation

◆ CombinatorialKalmanFilterError

enum class Acts::CombinatorialKalmanFilterError

strong

Error codes for combinatorial Kalman filter operations.

Enumerator
UpdateFailed	Kalman update failed.
SmoothFailed	Kalman smooth failed.
OutputConversionFailed	Kalman output conversion failed.
MeasurementSelectionFailed	Measurement selection failed.
PropagationReachesMaxSteps	Propagation reaches max steps before track finding is finished.
NoMeasurementExpected	No measurement expected on the current surface.

◆ DigitizationError

enum class ActsFatras::DigitizationError

strong

Enumerator
SmearingOutOfRange	Smeared out of surface bounds.
SmearingError	Smearing error occurred.
UndefinedSurface	Surface undefined for this operation.
MaskingError	Surface mask could not be applied.
MaximumRetriesExceeded	Maximum number of retries exceeded.

◆ EigenStepperError

enum class Acts::EigenStepperError

strong

Error codes for Eigen stepper operations.

Enumerator
StepSizeStalled	Step size fell below minimum threshold.
StepInvalid	Step calculation was invalid.
StepSizeAdjustmentFailed	Step size adjustment exceeds maximum trials.

◆ GeoModelConversionError

enum class ActsPlugins::GeoModelConversionError

strong

Enumerator
WrongShapeForConverter	Wrong shape provided for this converter.
InvalidShapeParameters	Shape parameters can not be converted to Surface representation.
UnkownShape	Unknown Shape provided, no converter available.
MissingLogicalVolume	No logical volume found for the shape.

◆ GlobalChiSquareFitterError

enum class Acts::Experimental::GlobalChiSquareFitterError

strong

Enumerator
AIsNotInvertible	aMatrix is not invertible.
DidNotConverge	Did not converge in 'nUpdateMax' updates.
NotEnoughMeasurements	Not enough measurements.
UpdatePushedToNewVolume	Update pushed the parameters to a new volume.

◆ GsfError

enum class Acts::GsfError

strong

Error codes for Gaussian Sum Filter operations.

Enumerator
StartParametersHaveNoCovariance	Start parameters have no Covariance.
NoMeasurementStatesCreatedForward	No measurement states found in the forward pass.
NoMeasurementStatesCreatedBackward	No measurement states found in the backward pass.
NoMeasurementStatesCreatedFinal	No measurement states in the final trajectory.

◆ KalmanFitterError

enum class Acts::KalmanFitterError

strong

Error codes for Kalman filter operations.

Enumerator
UpdateFailed	Kalman update failed.
SmoothFailed	Kalman smooth failed.
OutputConversionFailed	Kalman output conversion failed.
NoMeasurementFound	No measurement detected during the propagation.
ReversePropagationFailed	Reverse propagation failed.
InconsistentTrackStates

◆ MagneticFieldError

enum class Acts::MagneticFieldError

strong

Error codes for magnetic field operations.

Enumerator
OutOfBounds	The lookup position was outside of the validitiy domain of the underlying magnetic field instance.
NotImplemented	An operation for this magnetic field type is not implemented.

◆ MultiStepperError

enum class Acts::MultiStepperError

strong

Error codes for multi-stepper operations.

Enumerator
ComponentNotOnSurface	Component is not on a surface.
StateOfMultipleComponentsRequested	The global BoundState/CurvilinearState can only be computed if only one component exists.
AverageTrackLeftCurrentVolume	The average track has left the current volume.
AllComponentsSteppingError	Stepping error occurred in all components.
AllComponentsConversionToBoundFailed	The conversion to the bound state failed for all components.
SomeComponentsConversionToBoundFailed	The conversion to the bound state failed for some components.

◆ NavigatorError

enum class Acts::NavigatorError

strong

Error codes for navigator operations.

Enumerator
NotInsideExpectedVolume	We did not end up inside the volume.
NotOnExpectedSurface	Stepper not on surface.
NoStartVolume	No start volume could be resolved.

◆ PortalError

enum class Acts::PortalError

strong

Error codes for portal operations.

Enumerator
PositionNotOnAnyChildPortalLink	Position not on any of the composite child portal links.

◆ PropagatorError

enum class Acts::PropagatorError

strong

Error codes for propagator operations.

Enumerator
Failure	Propagation failed.
StepCountLimitReached	Propagation reached the configured maximum number of steps.
NextTargetLimitReached	Propagation reached the configured maximum number of next target calls.

◆ SpacePointFormationError

enum class Acts::SpacePointFormationError

strong

Error codes for space point formation operations.

Enumerator
ClusterPairDistanceExceeded	Cluster pair distance exceeded.
ClusterPairThetaDistanceExceeded	Cluster pair theta distance exceeded.
ClusterPairPhiDistanceExceeded	Cluster pair phi distance exceeded.
CosmicToleranceNotMet	Cosmic tolerance not met.
OutsideLimits	Outside limits.
OutsideRelaxedLimits	Outside relaxed limits.
NoSolutionFound	No solution found.

◆ SurfaceError

enum class Acts::SurfaceError

strong

Error codes for surface operations.

Enumerator
GlobalPositionNotOnSurface	Global to local transformation failed: position not on surface.

◆ TrackExtrapolationError

enum class Acts::TrackExtrapolationError

strong

Error codes for track extrapolation operations.

Enumerator
CompatibleTrackStateNotFound	Did not find a compatible track state.
ReferenceSurfaceUnreachable	Provided reference surface is unreachable.

◆ VertexingError

enum class Acts::VertexingError

strong

Error codes for vertexing operations.

Enumerator
NumericFailure	Numeric failure in calculation.
EmptyInput	Empty input provided.
SeedingError	Error while finding vertex seed.
NotConverged	Unable to converge.
ElementNotFound	Unable to find element.
NoCovariance	No covariance provided.
SingularMatrix	Encountered non-invertible matrix.
NonPositiveVariance	Encountered negative or zero variance.
MatrixNotPositiveDefinite	Encountered a matrix that is not positive definite.
InvalidInput	Invalid input provided.
CouldNotRemoveTrack	Could not remove track from collection.

Detailed Description

Error Handling in ACTS

std::error_code Overview

Error Enum Pattern

Usage with Result Type

Benefits

Enumerations

Enumeration Type Documentation

◆ CombinatorialKalmanFilterError

◆ DigitizationError

◆ EigenStepperError

◆ GeoModelConversionError

◆ GlobalChiSquareFitterError

◆ GsfError

◆ KalmanFitterError

◆ MagneticFieldError

◆ MultiStepperError

◆ NavigatorError

◆ PortalError

◆ PropagatorError

◆ SpacePointFormationError

◆ SurfaceError

◆ TrackExtrapolationError

◆ VertexingError