Detailed Description

A description of magnetic field configurations for algorithms.

The magnetic field component of ACTS provides functionality to describe arbitrary magnetic field configurations in an experiment. It is implemented in a generic way and can be extended to connect to an experiment specific upstream source of field data.

Algorithms which need magnetic field information (e.g. Acts::AtlasStepper, Acts::EigenStepper) accept the magnetic field as an explicit argument.

The documentation of Acts::MagneticFieldProvider provides a good overview of the design and patterns associated with the magnetic field component.
The potentially event-context dependent configuration of the magnetic field is documented in Acts::MagneticFieldContext.

Classes of field providers in the library:

Analytical magnetic fields like Acts::SolenoidBField that calculate their respective field values on the fly.
Special magnetic fields like Acts::ConstantBField or Acts::NullBField
The main Acts::InterpolatedBFieldMap that is most commonly used by experiments to provide magnetic field maps from discrete data.

Classes
class	Acts::ConstantBField
	The simplest magnetic field implementation is a constant field, which returns the same field values at every queried location. More...
class	Acts::InterpolatedBFieldMap< grid_t >
	Interpolates magnetic field value from field values on a given grid. More...
class	Acts::InterpolatedMagneticField
	Base class for interpolated magnetic field providers. More...
class	Acts::MagneticFieldContext
	Context object for lookup of magnetic field values. More...
class	Acts::MagneticFieldProvider
	Base class for all magnetic field providers. More...
class	Acts::MultiRangeBField
	Magnetic field provider modelling a magnetic field consisting of several (potentially overlapping) regions of constant values. More...
class	Acts::NullBField
	Null bfield which returns 0 always. More...
class	Acts::SolenoidBField
	Analytical solenoid magnetic field implementation. More...
class	ActsPlugins::DD4hepFieldAdapter

Functions
Acts::InterpolatedBFieldMap< Acts::Grid< Acts::Vector2, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant > > >	Acts::fieldMapRZ (const std::function< std::size_t(std::array< std::size_t, 2 > binsRZ, std::array< std::size_t, 2 > nBinsRZ)> &localToGlobalBin, std::vector< double > rPos, std::vector< double > zPos, const std::vector< Acts::Vector2 > &bField, double lengthUnit=UnitConstants::mm, double BFieldUnit=UnitConstants::T, bool firstQuadrant=false)
	Method to setup the FieldMap.
Acts::InterpolatedBFieldMap< Acts::Grid< Acts::Vector3, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant > > >	Acts::fieldMapXYZ (const std::function< std::size_t(std::array< std::size_t, 3 > binsXYZ, std::array< std::size_t, 3 > nBinsXYZ)> &localToGlobalBin, std::vector< double > xPos, std::vector< double > yPos, std::vector< double > zPos, const std::vector< Acts::Vector3 > &bField, double lengthUnit=UnitConstants::mm, double BFieldUnit=UnitConstants::T, bool firstOctant=false)
	Method to setup the FieldMap.
InterpolatedBFieldMap< Grid< Vector2, Axis< AxisType::Equidistant >, Axis< AxisType::Equidistant > > >	Acts::makeMagneticFieldMapRzFromText (const std::function< std::size_t(std::array< std::size_t, 2 > binsRZ, std::array< std::size_t, 2 > nBinsRZ)> &localToGlobalBin, const std::string &fieldMapFile, double lengthUnit, double BFieldUnit, bool firstQuadrant=false, const std::string &delimiter="")
	Method to setup the FieldMapper.
InterpolatedBFieldMap< Grid< Vector3, Axis< AxisType::Equidistant >, Axis< AxisType::Equidistant >, Axis< AxisType::Equidistant > > >	Acts::makeMagneticFieldMapXyzFromText (const std::function< std::size_t(std::array< std::size_t, 3 > binsXYZ, std::array< std::size_t, 3 > nBinsXYZ)> &localToGlobalBin, const std::string &fieldMapFile, double lengthUnit, double BFieldUnit, bool firstOctant=false, const std::string &delimiter="")
	Method to setup the FieldMapper.
Acts::InterpolatedBFieldMap< Acts::Grid< Acts::Vector2, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant > > >	Acts::solenoidFieldMap (const std::pair< double, double > &rLim, const std::pair< double, double > &zLim, const std::pair< std::size_t, std::size_t > &nBins, const SolenoidBField &field)
	Function which takes an existing SolenoidBField instance and creates a field mapper by sampling grid points from the analytical solenoid field.
Acts::InterpolatedBFieldMap< Acts::Grid< Acts::Vector3, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant > > >	Acts::toroidFieldMapCyl (const std::pair< double, double > &rLim, const std::pair< double, double > &phiLim, const std::pair< double, double > &zLim, const std::tuple< std::size_t, std::size_t, std::size_t > &nBins, const ToroidField &field)
	Function which takes an existing ToroidField instance and creates a cylindrical field mapper by sampling grid points from the analytical toroidal field.
Acts::InterpolatedBFieldMap< Acts::Grid< Acts::Vector3, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant > > >	Acts::toroidFieldMapXYZ (const std::pair< double, double > &xLim, const std::pair< double, double > &yLim, const std::pair< double, double > &zLim, const std::tuple< std::size_t, std::size_t, std::size_t > &nBins, const ToroidField &field)
	Function which takes an existing ToroidField instance and creates a Cartesian field mapper by sampling grid points from the analytical toroidal field.

Function Documentation

◆ fieldMapRZ()

Acts::InterpolatedBFieldMap< Acts::Grid< Acts::Vector2, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant > > > Acts::fieldMapRZ	(	const std::function< std::size_t(std::array< std::size_t, 2 > binsRZ, std::array< std::size_t, 2 > nBinsRZ)> &	localToGlobalBin,
		std::vector< double >	rPos,
		std::vector< double >	zPos,
		const std::vector< Acts::Vector2 > &	bField,
		double	lengthUnit = UnitConstants::mm,
		double	BFieldUnit = UnitConstants::T,
		bool	firstQuadrant = false )

Method to setup the FieldMap.

Parameters

localToGlobalBin Function mapping the local bins of r,z to the global bin of the map magnetic field value

e.g.: we have small grid with the values: r={2,3}, z ={4,5}, the corresponding indices are i (belonging to r) and j (belonging to z), the globalIndex is M (belonging to the value of the magnetic field B(r,z)) and the field map is:

r	i	z	j	B(r,z)	M
2	0	4	0	2.323	0
2	0	5	1	2.334	1
3	1	4	0	2.325	2
3	1	5	1	2.331	3

In this case the function would look like:

[](std::array<std::size_t, 2> binsRZ, std::array<std::size_t, 2> nBinsRZ) {
   return (binsRZ.at(0) * nBinsRZ.at(1) + binsRZ.at(1));
}

Parameters

[in] rPos Values of the grid points in r

Note: The values do not need to be sorted or unique (this will be done inside the function)

Parameters

[in] zPos Values of the grid points in z

Note: The values do not need to be sorted or unique (this will be done inside the function)

Parameters

[in] bField The magnetic field values inr r and z for all given grid points stored in a vector

Note: The function localToGlobalBin determines how the magnetic field was stored in the vector in respect to the grid values

Parameters

[in]	lengthUnit	The unit of the grid points
[in]	BFieldUnit	The unit of the magnetic field
[in]	firstQuadrant	Flag if set to true indicating that only the first quadrant of the grid points and the BField values has been given.

Note: If firstQuadrant is true will create a field that is symmetric for all quadrants. e.g. we have the grid values r={0,1} with BFieldValues={2,3} on the r axis. If the flag is set to true the r-axis grid values will be set to {-1,0,1} and the BFieldValues will be set to {3,2,3}.

Returns: A field map instance for use in interpolation.

◆ fieldMapXYZ()

Acts::InterpolatedBFieldMap< Acts::Grid< Acts::Vector3, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant > > > Acts::fieldMapXYZ	(	const std::function< std::size_t(std::array< std::size_t, 3 > binsXYZ, std::array< std::size_t, 3 > nBinsXYZ)> &	localToGlobalBin,
		std::vector< double >	xPos,
		std::vector< double >	yPos,
		std::vector< double >	zPos,
		const std::vector< Acts::Vector3 > &	bField,
		double	lengthUnit = UnitConstants::mm,
		double	BFieldUnit = UnitConstants::T,
		bool	firstOctant = false )

Method to setup the FieldMap.

Parameters

localToGlobalBin Function mapping the local bins of x,y,z to the global bin of the map magnetic field value

e.g.: we have small grid with the values: x={2,3}, y={3,4}, z ={4,5}, the corresponding indices are i (belonging to x), j (belonging to y) and k (belonging to z), the globalIndex is M (belonging to the value of the magnetic field B(x,y,z)) and the field map is:

x	i	y	j	z	k	B(x,y,z)	M
2	0	3	0	4	0	2.323	0
2	0	3	0	5	1	2.334	1
2	0	4	1	4	0	2.325	2
2	0	4	1	5	1	2.331	3
3	1	3	0	4	0	2.323	4
3	1	3	0	5	1	2.334	5
3	1	4	1	4	0	2.325	6
3	1	4	1	5	1	2.331	7

In this case the function would look like:

[](std::array<std::size_t, 3> binsXYZ, std::array<std::size_t, 3> nBinsXYZ)
{
  return (binsXYZ.at(0) * (nBinsXYZ.at(1) * nBinsXYZ.at(2))
       + binsXYZ.at(1) * nBinsXYZ.at(2)
       + binsXYZ.at(2));
}

Note: The grid point values xPos, yPos and zPos do not need to be sorted or unique (this will be done inside the function)

Parameters

[in]	xPos	Values of the grid points in x
[in]	yPos	Values of the grid points in y
[in]	zPos	Values of the grid points in z
[in]	bField	The magnetic field values inr r and z for all given grid points stored in a vector

Note: The function localToGlobalBin determines how the magnetic field was stored in the vector in respect to the grid values

Parameters

[in]	lengthUnit	The unit of the grid points
[in]	BFieldUnit	The unit of the magnetic field
[in]	firstOctant	Flag if set to true indicating that only the first octant of the grid points and the BField values has been given.

Note: If firstOctant is true, the function will assume a symmetrical field for all quadrants. e.g. we have the grid values z={0,1} with BFieldValues={2,3} on the r axis. If the flag is set to true the z-axis grid values will be set to {-1,0,1} and the BFieldValues will be set to {3,2,3}.

Returns: A field map instance for use in interpolation.

◆ makeMagneticFieldMapRzFromText()

InterpolatedBFieldMap< Grid< Vector2, Axis< AxisType::Equidistant >, Axis< AxisType::Equidistant > > > Acts::makeMagneticFieldMapRzFromText	(	const std::function< std::size_t(std::array< std::size_t, 2 > binsRZ, std::array< std::size_t, 2 > nBinsRZ)> &	localToGlobalBin,
		const std::string &	fieldMapFile,
		double	lengthUnit,
		double	BFieldUnit,
		bool	firstQuadrant = false,
		const std::string &	delimiter = "" )

Method to setup the FieldMapper.

Parameters

localToGlobalBin Function mapping the local bins of r,z to the global bin of the map magnetic field value e.g.: we have small grid with the values: r={2,3}, z ={4,5}, the corresponding indices are i(r) and j(z), the globalIndex is M and the field map is:

|| r | i || z | j || |B(r,z)| || M ||

|| 2 | 0 || 4 | 0 || 2.323 || 0 || || 2 | 0 || 5 | 1 || 2.334 || 1 || || 3 | 1 || 4 | 0 || 2.325 || 2 || || 3 | 1 || 5 | 1 || 2.331 || 3 ||

In this case the function would look like:
[](std::array<std::size_t, 2> binsRZ, std::array<std::size_t, 2> nBinsRZ) {
   return (binsRZ.at(0) * nBinsRZ.at(1) + binsRZ.at(1));
}

Parameters

[in]	fieldMapFile	Path to file containing field map in txt format
[in]	lengthUnit	The unit of the grid points
[in]	BFieldUnit	The unit of the magnetic field

Note: This information is only used as a hint for the required size of the internal vectors. A correct value is not needed, but will help to speed up the field map initialization process.

Parameters

[in]	firstQuadrant	Flag if set to true indicating that only the first quadrant of the grid points and the BField values has been given and that the BFieldMap should be created symmetrically for all quadrants. e.g. we have the grid values r={0,1} with BFieldValues={2,3} on the r axis. If the flag is set to true the r-axis grid values will be set to {-1,0,1} and the BFieldValues will be set to {3,2,3}.
	delimiter	The delimiter used in the text file to separate values

◆ makeMagneticFieldMapXyzFromText()

InterpolatedBFieldMap< Grid< Vector3, Axis< AxisType::Equidistant >, Axis< AxisType::Equidistant >, Axis< AxisType::Equidistant > > > Acts::makeMagneticFieldMapXyzFromText	(	const std::function< std::size_t(std::array< std::size_t, 3 > binsXYZ, std::array< std::size_t, 3 > nBinsXYZ)> &	localToGlobalBin,
		const std::string &	fieldMapFile,
		double	lengthUnit,
		double	BFieldUnit,
		bool	firstOctant = false,
		const std::string &	delimiter = "" )

Method to setup the FieldMapper.

Parameters

localToGlobalBin Function mapping the local bins of x,y,z to the global bin of the map magnetic field value e.g.: we have small grid with the values: x={2,3}, y={3,4}, z ={4,5}, the corresponding indices are i(x), j(y) and z(k), the globalIndex is M and the field map is:

|| x | i || y | j || z | k || |B(x,y,z)| || M ||

|| 2 | 0 || 3 | 0 || 4 | 0 || 2.323 || 0 || || 2 | 0 || 3 | 0 || 5 | 1 || 2.334 || 1 || || 2 | 0 || 4 | 1 || 4 | 0 || 2.325 || 2 || || 2 | 0 || 4 | 1 || 5 | 1 || 2.331 || 3 || || 3 | 1 || 3 | 0 || 4 | 0 || 2.323 || 4 || || 3 | 1 || 3 | 0 || 5 | 1 || 2.334 || 5 || || 3 | 1 || 4 | 1 || 4 | 0 || 2.325 || 6 || || 3 | 1 || 4 | 1 || 5 | 1 || 2.331 || 7 ||

In this case the function would look like:
[](std::array<std::size_t, 3> binsXYZ, std::array<std::size_t, 3> nBinsXYZ)
{
  return (binsXYZ.at(0) * (nBinsXYZ.at(1) * nBinsXYZ.at(2))
       + binsXYZ.at(1) * nBinsXYZ.at(2)
       + binsXYZ.at(2));
}

Parameters

[in]	fieldMapFile	Path to file containing field map in txt format
[in]	lengthUnit	The unit of the grid points
[in]	BFieldUnit	The unit of the magnetic field

Note: This information is only used as a hint for the required size of the internal vectors. A correct value is not needed, but will help to speed up the field map initialization process.

Parameters

[in]	firstOctant	Flag if set to true indicating that only the first octant of the grid points and the BField values has been given and that the BFieldMap should be created symmetrically for all quadrants. e.g. we have the grid values z={0,1} with BFieldValues={2,3} on the r axis. If the flag is set to true the z-axis grid values will be set to {-1,0,1} and the BFieldValues will be set to {3,2,3}.
	delimiter	The delimiter used in the text file to separate values

◆ solenoidFieldMap()

Acts::InterpolatedBFieldMap< Acts::Grid< Acts::Vector2, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant > > > Acts::solenoidFieldMap	(	const std::pair< double, double > &	rLim,
		const std::pair< double, double > &	zLim,
		const std::pair< std::size_t, std::size_t > &	nBins,
		const SolenoidBField &	field )

Function which takes an existing SolenoidBField instance and creates a field mapper by sampling grid points from the analytical solenoid field.

Parameters

rLim	pair of r bounds
zLim	pair of z bounds
nBins	pair of bin counts
field	the solenoid field instance

Returns: A field map instance for use in interpolation.

◆ toroidFieldMapCyl()

Acts::InterpolatedBFieldMap< Acts::Grid< Acts::Vector3, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant > > > Acts::toroidFieldMapCyl	(	const std::pair< double, double > &	rLim,
		const std::pair< double, double > &	phiLim,
		const std::pair< double, double > &	zLim,
		const std::tuple< std::size_t, std::size_t, std::size_t > &	nBins,
		const ToroidField &	field )

Function which takes an existing ToroidField instance and creates a cylindrical field mapper by sampling grid points from the analytical toroidal field.

Parameters

rLim	pair of r bounds
phiLim	pair of phi bounds
zLim	pair of z bounds
nBins	tuple of bin counts
field	the toroid field instance

Returns: A field map instance for use in interpolation.

◆ toroidFieldMapXYZ()

Acts::InterpolatedBFieldMap< Acts::Grid< Acts::Vector3, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant >, Acts::Axis< Acts::AxisType::Equidistant > > > Acts::toroidFieldMapXYZ	(	const std::pair< double, double > &	xLim,
		const std::pair< double, double > &	yLim,
		const std::pair< double, double > &	zLim,
		const std::tuple< std::size_t, std::size_t, std::size_t > &	nBins,
		const ToroidField &	field )

Function which takes an existing ToroidField instance and creates a Cartesian field mapper by sampling grid points from the analytical toroidal field.

Parameters

xLim	pair of x bounds
yLim	pair of y bounds
zLim	pair of z bounds
nBins	tuple of bin counts
field	the toroid field instance

Returns: A field map instance for use in interpolation.

Detailed Description

Classes

Functions

Function Documentation

◆ fieldMapRZ()

◆ fieldMapXYZ()

◆ makeMagneticFieldMapRzFromText()

|| r | i || z | j || |B(r,z)| || M ||

◆ makeMagneticFieldMapXyzFromText()

|| x | i || y | j || z | k || |B(x,y,z)| || M ||

◆ solenoidFieldMap()

◆ toroidFieldMapCyl()

◆ toroidFieldMapXYZ()