Acts::Experimental::BlueprintBuilder< BackendT > Class Template Reference

High-level builder that converts a backend detector element hierarchy into a blueprint node tree. More...

#include <Acts/Geometry/BlueprintBuilder.hpp>

Inheritance diagram for Acts::Experimental::BlueprintBuilder< BackendT >:

Public Types
using	AxisDefinition
	Axis definition type, or std::monostate when the backend does not support axis definitions.
using	Backend = BackendT
	The backend type.
using	BarrelEndcapAssembler
	The BarrelEndcapAssembler specialisation for this backend.
using	Element = typename Backend::Element
	Backend detector element handle type.
using	ElementLayerAssembler
	The ElementLayerAssembler specialisation for this backend.
using	LayerSpec = typename Backend::LayerSpec
	Backend layer-specification type.
using	SensorLayer = ::Acts::Experimental::SensorLayer<Backend>
	The SensorLayer specialisation for this backend.
using	SensorLayerAssembler
	The SensorLayerAssembler specialisation for this backend.

Public Member Functions
	BlueprintBuilder (const typename Backend::Config &cfg, std::unique_ptr< const Acts::Logger > logger_=Acts::getDefaultLogger("BlueprintBuilder", Acts::Logging::INFO))
	Construct a BlueprintBuilder from a backend configuration.
const Backend &	backend () const
	Return the backend associated with this builder.
BarrelEndcapAssembler	barrelEndcap () const
	Create a BarrelEndcapAssembler bound to this builder.
std::vector< Element >	findBarrelElements (const Element &assembly) const
	Collect all barrel tracker elements within an assembly subtree.
std::optional< Element >	findDetElementByName (const Element &parent, const std::string &name) const
	Search for a detector element by exact name within a subtree.
std::optional< Element >	findDetElementByName (const std::string &name) const
	Search for a detector element by exact name starting from the world root.
std::vector< Element >	findDetElementByNamePattern (const Element &parent, const std::regex &pattern) const
	Collect all elements in a subtree whose names match a regex.
std::vector< Element >	findEndcapElements (const Element &assembly) const
	Collect all endcap tracker elements within an assembly subtree.
std::string	getPathToElementName (const Element &elem, std::string_view separator="|") const
	Build a separator-joined path string from the world root down to elem.
SensorLayer	layerFromSensors () const
	Create a SensorLayer bound to this builder.
ElementLayerAssembler	layers () const
	Create an ElementLayerAssembler bound to this builder.
SensorLayerAssembler	layersFromSensors () const
	Create a SensorLayerAssembler bound to this builder.
const Acts::Logger &	logger () const
	Return the logger associated with this builder.
std::shared_ptr< LayerBlueprintNode >	makeLayer (const Element &layerElement, const LayerSpec &layerSpec) const
	Create a LayerBlueprintNode from a single detector element.
std::shared_ptr< LayerBlueprintNode >	makeLayer (const Element &parent, std::span< const Element > sensitives, const LayerSpec &layerSpec) const
	Create a LayerBlueprintNode from an explicit list of sensitive elements.
std::shared_ptr< LayerBlueprintNode >	makeLayer (std::span< const Element > sensitives, const LayerSpec &layerSpec) const
	Create a LayerBlueprintNode from sensitive elements without a parent/context element.
std::vector< Element >	resolveSensitives (const Element &detElement) const
	Recursively collect all sensitive descendant elements.

Detailed Description

template<detail::BlueprintBackend BackendT>
class Acts::Experimental::BlueprintBuilder< BackendT >

High-level builder that converts a backend detector element hierarchy into a blueprint node tree.

BlueprintBuilder provides the entry points for blueprint construction:

• BlueprintBuilder::layers() returns an ElementLayerAssembler for building a layer stack from layer-representative detector elements,
• BlueprintBuilder::layersFromSensors() returns a SensorLayerAssembler for building multiple layers directly from sensor elements (groupBy required),
• BlueprintBuilder::layerFromSensors() returns a SensorLayer for building a single layer directly from sensor elements,
• BlueprintBuilder::barrelEndcap() returns a BarrelEndcapAssembler for combined barrel+endcap sub-detectors.

It also exposes helpers for traversing and querying the detector element hierarchy, which are used internally by the assembler classes.

The builder is parameterised on a backend type BackendT. The backend must be constructible from its Config plus an Acts::Logger, expose Element and LayerSpec types, traverse the detector hierarchy via world() / children() / parent() / nameOf(), classify sensitive elements with isSensitive(), and build ACTS surfaces from sensitive elements and a layer specification. It encapsulates all geometry-framework-specific knowledge (e.g. DD4hep DetElement navigation, type-flag interpretation, surface conversion).

Template Parameters

BackendT

Geometry backend that provides detector elements, layer specifications, hierarchy traversal, sensitive-element classification, and surface construction.

Member Typedef Documentation

AxisDefinition

template<detail::BlueprintBackend BackendT>

using Acts::Experimental::BlueprintBuilder< BackendT >::AxisDefinition

Initial value:

 
      std::conditional_t<detail::HasAxisDefinition<Backend>,
                         typename Backend::AxisDefinition, std::monostate>

Axis definition type, or std::monostate when the backend does not support axis definitions.

BarrelEndcapAssembler

template<detail::BlueprintBackend BackendT>

using Acts::Experimental::BlueprintBuilder< BackendT >::BarrelEndcapAssembler

Initial value:

 
      ::Acts::Experimental::BarrelEndcapAssembler<Backend>

The BarrelEndcapAssembler specialisation for this backend.

ElementLayerAssembler

template<detail::BlueprintBackend BackendT>

using Acts::Experimental::BlueprintBuilder< BackendT >::ElementLayerAssembler

Initial value:

 
      ::Acts::Experimental::ElementLayerAssembler<Backend>

The ElementLayerAssembler specialisation for this backend.

SensorLayerAssembler

template<detail::BlueprintBackend BackendT>

using Acts::Experimental::BlueprintBuilder< BackendT >::SensorLayerAssembler

Initial value:

 
      ::Acts::Experimental::SensorLayerAssembler<Backend>

The SensorLayerAssembler specialisation for this backend.

Constructor & Destructor Documentation

BlueprintBuilder()

template<detail::BlueprintBackend BackendT>

Acts::Experimental::BlueprintBuilder< BackendT >::BlueprintBuilder ( const typename Backend::Config & cfg, std::unique_ptr< const Acts::Logger > logger_ = Acts::getDefaultLogger("BlueprintBuilder< BackendT >", Acts::Logging::INFO) )

explicit

Construct a BlueprintBuilder from a backend configuration.

Parameters

cfg	Backend-specific configuration object passed directly to the backend constructor.
logger_	Optional logger; defaults to an INFO-level logger named "BlueprintBuilder".

Member Function Documentation

backend()

template<detail::BlueprintBackend BackendT>

const Backend & Acts::Experimental::BlueprintBuilder< BackendT >::backend

(

)

const

Return the backend associated with this builder.

Returns

Const reference to the backend instance.

barrelEndcap()

template<detail::BlueprintBackend BackendT>

BarrelEndcapAssembler Acts::Experimental::BlueprintBuilder< BackendT >::barrelEndcap ( ) const

nodiscard

Create a BarrelEndcapAssembler bound to this builder.

The returned assembler must be configured (assembly element, axes, layer filter) and then finalised via BarrelEndcapAssembler::build() or BarrelEndcapAssembler::addTo().

Returns

A new BarrelEndcapAssembler instance.

findBarrelElements()

template<detail::BlueprintBackend BackendT>

std::vector< Element > Acts::Experimental::BlueprintBuilder< BackendT >::findBarrelElements

(

const Element &

assembly

)

const

Collect all barrel tracker elements within an assembly subtree.

An element is included when the backend reports it as both a tracker element and a barrel element.

Parameters

assembly

Root element of the assembly subtree to search.

Returns

Vector of barrel elements in depth-first order.

findDetElementByName() [1/2]

template<detail::BlueprintBackend BackendT>

std::optional< Element > Acts::Experimental::BlueprintBuilder< BackendT >::findDetElementByName	(	const Element &	parent,
		const std::string &	name ) const

Search for a detector element by exact name within a subtree.

Performs a depth-first search starting at parent.

Parameters

parent	Starting element for the search.
name	Exact element name to match.

Returns

The first matching element, or std::nullopt if not found.

findDetElementByName() [2/2]

template<detail::BlueprintBackend BackendT>

std::optional< Element > Acts::Experimental::BlueprintBuilder< BackendT >::findDetElementByName

(

const std::string &

name

)

const

Search for a detector element by exact name starting from the world root.

Parameters

name	Exact element name to match.

Returns

The first matching element, or std::nullopt if not found.

findDetElementByNamePattern()

template<detail::BlueprintBackend BackendT>

std::vector< Element > Acts::Experimental::BlueprintBuilder< BackendT >::findDetElementByNamePattern	(	const Element &	parent,
		const std::regex &	pattern ) const

Collect all elements in a subtree whose names match a regex.

Performs a depth-first traversal of the subtree rooted at parent and returns every element whose name fully matches pattern (std::regex_match).

Parameters

parent	Root of the subtree to search.
pattern	Regular expression matched against each element name.

Returns

Vector of matching elements in depth-first order.

findEndcapElements()

template<detail::BlueprintBackend BackendT>

std::vector< Element > Acts::Experimental::BlueprintBuilder< BackendT >::findEndcapElements

(

const Element &

assembly

)

const

Collect all endcap tracker elements within an assembly subtree.

An element is included when the backend reports it as both a tracker element and an endcap element.

Parameters

assembly

Root element of the assembly subtree to search.

Returns

Vector of endcap elements in depth-first order.

getPathToElementName()

template<detail::BlueprintBackend BackendT>

std::string Acts::Experimental::BlueprintBuilder< BackendT >::getPathToElementName	(	const Element &	elem,
		std::string_view	separator = "|" ) const

Build a separator-joined path string from the world root down to elem.

The path consists of element names at each level of the hierarchy, from the immediate child of the world element down to elem, joined by separator.

Parameters

elem	Target element.
separator	String inserted between successive name components (default: "|").

Returns

The assembled path string.

layerFromSensors()

template<detail::BlueprintBackend BackendT>

SensorLayer Acts::Experimental::BlueprintBuilder< BackendT >::layerFromSensors ( ) const

nodiscard

Create a SensorLayer bound to this builder.

Use when all sensor elements belong to exactly one layer and no grouping is needed. The layer name must be set explicitly via SensorLayer::setLayerName. The result is a single LayerBlueprintNode (no container wrapper).

Returns

A new SensorLayer instance.

layers()

template<detail::BlueprintBackend BackendT>

ElementLayerAssembler Acts::Experimental::BlueprintBuilder< BackendT >::layers ( ) const

nodiscard

Create an ElementLayerAssembler bound to this builder.

Use when layer-representative detector elements exist in the hierarchy. Each element becomes one layer; name and transform are deduced from it.

Returns

A new ElementLayerAssembler instance.

layersFromSensors()

template<detail::BlueprintBackend BackendT>

SensorLayerAssembler Acts::Experimental::BlueprintBuilder< BackendT >::layersFromSensors ( ) const

nodiscard

Create a SensorLayerAssembler bound to this builder.

Use when sensor elements are supplied directly and no layer-representative element exists. A SensorLayerAssembler::groupBy function is required; sensors sharing the same key are merged into one layer per key. For a single layer without grouping, use layerFromSensors() instead.

Returns

A new SensorLayerAssembler instance.

logger()

template<detail::BlueprintBackend BackendT>

const Acts::Logger & Acts::Experimental::BlueprintBuilder< BackendT >::logger

(

)

const

Return the logger associated with this builder.

Returns

Reference to the logger instance.

makeLayer() [1/3]

template<detail::BlueprintBackend BackendT>

std::shared_ptr< LayerBlueprintNode > Acts::Experimental::BlueprintBuilder< BackendT >::makeLayer	(	const Element &	layerElement,
		const LayerSpec &	layerSpec ) const

Create a LayerBlueprintNode from a single detector element.

Recursively collects all sensitive descendants of layerElement and delegates to the two-argument overload.

Parameters

layerElement	Layer element whose subtree is scanned for sensitive volumes.
layerSpec	Specification controlling surface axes and optional name/transform overrides.

Returns

Shared pointer to the constructed LayerBlueprintNode.

makeLayer() [2/3]

template<detail::BlueprintBackend BackendT>

std::shared_ptr< LayerBlueprintNode > Acts::Experimental::BlueprintBuilder< BackendT >::makeLayer	(	const Element &	parent,
		std::span< const Element >	sensitives,
		const LayerSpec &	layerSpec ) const

Create a LayerBlueprintNode from an explicit list of sensitive elements.

This is a low-level forwarding API: layerSpec is passed to the backend as-is.

Parameters

parent	Detector element that contextualises the layer (used for naming and transform extraction).
sensitives	Span of sensitive detector elements to be converted to surfaces and assigned to the node.
layerSpec	Specification controlling surface axes and optional name/transform overrides.

Returns

Shared pointer to the constructed LayerBlueprintNode.

makeLayer() [3/3]

template<detail::BlueprintBackend BackendT>

std::shared_ptr< LayerBlueprintNode > Acts::Experimental::BlueprintBuilder< BackendT >::makeLayer	(	std::span< const Element >	sensitives,
		const LayerSpec &	layerSpec ) const

Create a LayerBlueprintNode from sensitive elements without a parent/context element.

This variant cannot perform parent-based transform extraction. layerSpec.layerName must be set and is used verbatim.

Parameters

sensitives	Span of sensitive detector elements to be converted to surfaces and assigned to the node.
layerSpec	Specification controlling surface axes and name.

Exceptions

std::runtime_error

if layerSpec.layerName is not set.

Returns

Shared pointer to the constructed LayerBlueprintNode.

resolveSensitives()

template<detail::BlueprintBackend BackendT>

std::vector< Element > Acts::Experimental::BlueprintBuilder< BackendT >::resolveSensitives

(

const Element &

detElement

)

const

Recursively collect all sensitive descendant elements.

Traverses the subtree rooted at detElement and returns every element for which the backend's isSensitive() predicate returns true.

Parameters

detElement

Root of the subtree to scan.

Returns

Vector of sensitive elements in depth-first order.