SHiP Namespace Reference

Namespaces
namespace	detail

Classes
class	ActsFieldAdapter
	Acts::MagneticFieldProvider wrapping an IFieldEvaluator, the ACTS counterpart of G4MagFieldAdapter. More...
class	CovfieFieldSource
	Concrete IFieldSource aggregating one covfie-backed evaluator per magnet. More...
struct	FieldBox
	Axis-aligned box, lengths in mm. More...
struct	FieldMap
	One field map: grid, symmetry, and per-node field components in Tesla, stored in FieldMapGrid::index order. More...
struct	FieldMapGrid
	Equidistant Cartesian grid in the map's local frame. More...
struct	FieldMapPlacements
	Contents of a placement manifest: where each magnet's map sits, and the geometry version those positions were taken from. More...
struct	FieldMapProvenance
	Where a map came from. Informational only; never affects evaluation. More...
class	FieldMapSource
	IFieldSource with one evaluator per magnet, read from field-map files. More...
struct	FieldMapSymmetry
	Reflection symmetry. More...
struct	FieldMapWriteOptions
struct	FieldRegion
	One magnet's worth of field, tagged by a host-geometry volume pattern. More...
class	G4MagFieldAdapter
	Thin G4MagneticField wrapping an IFieldEvaluator. More...
class	IFieldEvaluator
	Framework-agnostic point-query evaluator for one magnetic field region. More...
class	IFieldSource
	Source of one or more named field regions. More...

Functions
std::shared_ptr< IFieldEvaluator >	loadCovfieField (std::string const &cvf_path)
	Build an IFieldEvaluator backed by a covfie .cvf file (CPU backend, trilinear interpolation, clamped at the boundary).
void	validate (FieldMap const &map)
	Throw std::invalid_argument unless map is well formed: non-empty name, at least two nodes and a positive extent per axis, value arrays of grid.size() finite entries, mirrored axes starting at 0, parities of +-1.
std::shared_ptr< IFieldEvaluator >	makeFieldEvaluator (FieldMap const &map)
	Build a thread-safe evaluator for map: trilinear interpolation, clamped to the boundary value outside the grid, with map.symmetry applied.
FieldBox	extent (FieldMap const &map)
	Region map covers in its local frame.
std::shared_ptr< IFieldEvaluator >	translated (std::shared_ptr< IFieldEvaluator > inner, std::array< double, 3 > const &offset)
	Evaluator for inner placed with its origin at offset (mm): the field at p is inner's field at p - offset.
std::shared_ptr< IFieldEvaluator >	zeroOutside (std::shared_ptr< IFieldEvaluator > inner, FieldBox const &box)
	Evaluator that returns inner's field inside box, given in inner's frame, and 0 outside it, where map evaluators would clamp.
std::string	resolveFieldMapPath (std::string const &path)
	Canonical path of a map file.
std::vector< FieldMap >	readFieldMaps (std::string const &path)
	Read every map in path.
FieldMap	readFieldMap (std::string const &path, std::string const &name)
	Read the map called name from path; throws if there is none.
void	writeFieldMaps (std::string const &path, std::span< FieldMap const > maps, FieldMapWriteOptions const &options={})
	Write maps to a new file at path, replacing any existing file.
std::shared_ptr< IFieldEvaluator >	loadFieldMap (std::string const &file, std::string const &map)
	Evaluator for map map in file.
FieldMapPlacements	readFieldMapPlacements (std::string const &path)
	Read the placement manifest at path, resolved as in resolveFieldMapPath (so a bare "placements.json" finds the one under $SHIPFIELD_ROOT/share/field/).

Variables
constexpr std::uint16_t	kFieldMapFormatMajor = 1
	Format version written by this library.
constexpr std::uint16_t	kFieldMapFormatMinor = 0
constexpr char const *	kFieldMapNTupleName = "field_maps"
	Name of the RNTuple holding the maps.
constexpr int	kPlacementsFormatVersion = 1
	Placement manifest version this library reads (docs/placements_format.md).

Function Documentation

extent()

FieldBox SHiP::extent

(

FieldMap const &

map

)

Region map covers in its local frame.

A mirrored axis covers [-max, max], since its grid stores only the half at or above 0.

loadCovfieField()

std::shared_ptr< IFieldEvaluator > SHiP::loadCovfieField

(

std::string const &

cvf_path

)

Build an IFieldEvaluator backed by a covfie .cvf file (CPU backend, trilinear interpolation, clamped at the boundary).

Bare filenames are resolved against $SHIPFIELD_ROOT/share/field/.

Deprecated:

.cvf is covfie's internal serialisation and changes with covfie versions. Store maps in the SHiP field-map format (docs/field_map_format.md) and load them with FieldMapSource from the MapIO component instead. .cvf support will be removed in a later release.

loadFieldMap()

std::shared_ptr< IFieldEvaluator > SHiP::loadFieldMap	(	std::string const &	file,
		std::string const &	map
	)

Evaluator for map map in file.

Bare filenames are resolved as in resolveFieldMapPath. Evaluators are cached by (file, map), so magnets sharing a map hold its values in memory only once.

makeFieldEvaluator()

std::shared_ptr< IFieldEvaluator > SHiP::makeFieldEvaluator

(

FieldMap const &

map

)

Build a thread-safe evaluator for map: trilinear interpolation, clamped to the boundary value outside the grid, with map.symmetry applied.

The returned evaluator owns a copy of the values, so map may be discarded.

readFieldMap()

FieldMap SHiP::readFieldMap	(	std::string const &	path,
		std::string const &	name
	)

Read the map called name from path; throws if there is none.

readFieldMapPlacements()

FieldMapPlacements SHiP::readFieldMapPlacements

(

std::string const &

path

)

Read the placement manifest at path, resolved as in resolveFieldMapPath (so a bare "placements.json" finds the one under $SHIPFIELD_ROOT/share/field/).

Throws std::runtime_error if the file is not valid JSON, has an unknown format_version, or a magnet entry is malformed or refers to a map the manifest does not list.

readFieldMaps()

std::vector< FieldMap > SHiP::readFieldMaps

(

std::string const &

path

)

Read every map in path.

Throws std::runtime_error if the file is not a field-map file, uses an unknown major version, or holds a malformed map.

resolveFieldMapPath()

std::string SHiP::resolveFieldMapPath

(

std::string const &

path

)

Canonical path of a map file.

A path that does not exist as given is looked up by its bare filename in $SHIPFIELD_ROOT/share/field/; throws std::runtime_error if neither exists.

translated()

std::shared_ptr< IFieldEvaluator > SHiP::translated	(	std::shared_ptr< IFieldEvaluator >	inner,
		std::array< double, 3 > const &	offset
	)

Evaluator for inner placed with its origin at offset (mm): the field at p is inner's field at p - offset.

Returns inner itself for a zero offset. Throws std::invalid_argument if inner is null or offset is not finite.

validate()

void SHiP::validate

(

FieldMap const &

map

)

Throw std::invalid_argument unless map is well formed: non-empty name, at least two nodes and a positive extent per axis, value arrays of grid.size() finite entries, mirrored axes starting at 0, parities of +-1.

writeFieldMaps()

void SHiP::writeFieldMaps	(	std::string const &	path,
		std::span< FieldMap const >	maps,
		FieldMapWriteOptions const &	options = {}
	)

Write maps to a new file at path, replacing any existing file.

Each map is validated and names must be unique. Empty provenance.producer and provenance.created_utc are filled in with this library and the current time.

zeroOutside()

std::shared_ptr< IFieldEvaluator > SHiP::zeroOutside	(	std::shared_ptr< IFieldEvaluator >	inner,
		FieldBox const &	box
	)

Evaluator that returns inner's field inside box, given in inner's frame, and 0 outside it, where map evaluators would clamp.

Use extent(map) as the box to get the FairShip ShipBFieldMap behaviour. Throws std::invalid_argument if inner is null.

Variable Documentation

kFieldMapFormatMajor

constexpr std::uint16_t SHiP::kFieldMapFormatMajor = 1

inlineconstexpr

Format version written by this library.

Readers accept any minor version of a major version they know.

kFieldMapFormatMinor

constexpr std::uint16_t SHiP::kFieldMapFormatMinor = 0

inlineconstexpr

kFieldMapNTupleName

constexpr char const* SHiP::kFieldMapNTupleName = "field_maps"

inlineconstexpr

Name of the RNTuple holding the maps.

kPlacementsFormatVersion

constexpr int SHiP::kPlacementsFormatVersion = 1

inlineconstexpr

Placement manifest version this library reads (docs/placements_format.md).