Acts::Experimental::BlueprintNode Class Reference

Base class for all nodes in the blueprint tree. More...

#include <Acts/Geometry/BlueprintNode.hpp>

Inheritance diagram for Acts::Experimental::BlueprintNode:

Public Types
using	ChildRange
	A range-like object that allows range based for loops and index access.
using	MutableChildRange
	A range-like object that allows range based for loops and index access.

Public Member Functions
virtual	~BlueprintNode ()=default
	Virtual destructor to ensure correct cleanup.
BlueprintNode &	addChild (std::shared_ptr< BlueprintNode > child)
	Register a child to this node.
virtual void	addToGraphviz (std::ostream &os) const
	Method that writes a representatiohn of this node only to graphviz.
MutableChildRange	children ()
	Return a MutableChildRange to the children of this node.
ChildRange	children () const
	Return a ChildRange to the children of this node.
void	clearChildren ()
	Remove all children from this node.
std::size_t	depth () const
	Return the depth of this node in the blueprint tree.
void	graphviz (std::ostream &os) const
	Print the node tree starting from this node to graphviz format.
virtual const std::string &	name () const =0
	Get the name of this node.
Construction methods
These methods constitute the primary interface of the node that participates in the geometry construction.
virtual Volume &	build (const BlueprintOptions &options, const GeometryContext &gctx, const Logger &logger=Acts::getDummyLogger())=0
	This method is called during the build phase of the blueprint tree construction.
virtual PortalShellBase &	connect (const BlueprintOptions &options, const GeometryContext &gctx, const Logger &logger=Acts::getDummyLogger())=0
	This method is called during the connect phase.
virtual void	finalize (const BlueprintOptions &options, const GeometryContext &gctx, TrackingVolume &parent, const Logger &logger=Acts::getDummyLogger())=0
	This method is called during the finalize phase.
Convenience methods
These methods are meant to make the construction of a blueprint tree in code more ergonomic. They usually take an optional callback parameter. The primary use for this parameter is structural, as it facilitates introducing scopes to indicate in code that objects are nested. Blueprint::Config cfg; auto root = std::make_unique<Blueprint>(cfg); root->addStaticVolume( base, std::make_shared<CylinderVolumeBounds>(50_mm, 400_mm, 1000_mm), "PixelWrapper", [&](auto& wrapper) { // This scope can be used to equip `wrapper` }); Alternatively, they can also be used without a callback, as the newly created node is also returned by reference: auto& wrapper = root->addStaticVolume( base, std::make_shared<CylinderVolumeBounds>(50_mm, 400_mm, 1000_mm), "PixelWrapper"); In both cases, it's not necessary to register the newly created node with a parent node.
StaticBlueprintNode &	addStaticVolume (std::unique_ptr< TrackingVolume > volume, const std::function< void(StaticBlueprintNode &cylinder)> &callback={})
	This method creates a new Acts::Experimental::StaticBlueprintNode wrapping volume and adds it to this node as a child.
StaticBlueprintNode &	addStaticVolume (const Transform3 &transform, std::shared_ptr< VolumeBounds > volumeBounds, const std::string &volumeName="undefined", const std::function< void(StaticBlueprintNode &cylinder)> &callback={})
	Alternative overload for creating a Acts::Experimental::StaticBlueprintNode.
CylinderContainerBlueprintNode &	addCylinderContainer (const std::string &name, AxisDirection direction, const std::function< void(CylinderContainerBlueprintNode &cylinder)> &callback={})
	Convenience method for creating a cylinder specialization of Acts::Experimental::ContainerBlueprintNode.
CuboidContainerBlueprintNode &	addCuboidContainer (const std::string &name, AxisDirection direction, const std::function< void(CuboidContainerBlueprintNode &cylinder)> &callback={})
	Convenience method for creating a cuboid specialization of Acts::Experimental::ContainerBlueprintNode.
MaterialDesignatorBlueprintNode &	addMaterial (const std::string &name, const std::function< void(MaterialDesignatorBlueprintNode &material)> &callback={})
	Convenience method for creating a Acts::Experimental::MaterialDesignatorBlueprintNode.
LayerBlueprintNode &	addLayer (const std::string &name, const std::function< void(LayerBlueprintNode &layer)> &callback={})
	Convenience method for creating a Acts::Experimental::LayerBlueprintNode.
GeometryIdentifierBlueprintNode &	withGeometryIdentifier (const std::function< void(GeometryIdentifierBlueprintNode &geometryIdentifier)> &callback={})
	Convenience method for creating a Acts::Experimental::GeometryIdentifierBlueprintNode.

Protected Member Functions
std::string	indent () const
	An indentation depending on the depth of this node.
std::string	prefix () const
	Printing helper returning a prefix including an indent depending on the depth.
void	setDepth (std::size_t depth)
	Set the depth to depth and update children recursively.
virtual void	toStream (std::ostream &os) const
	Virtual method to determine stream representation.

Detailed Description

Base class for all nodes in the blueprint tree.

This class defines the three-phase construction process. The three phases are

1. Build: Construct volume representation + compute final sizing
2. Connect: Create and connect portals at volume boundaries
3. Finalize: Register portals with volumes + create acceleration structures

During the build phase, the build method of all nodes in the tree are called recursively. Some nodes, like Acts::Experimental::ContainerBlueprintNode, will take action on the volumes returns from its children, and perform sizing to connect them. See the Acts::Experimental::ContainerBlueprintNode and Acts::CylinderVolumeStack documentation for details on how the sizing is carried out.

Member Typedef Documentation

ChildRange

using Acts::Experimental::BlueprintNode::ChildRange

Initial value:

 Acts::detail::TransformRange<
      Acts::detail::ConstDereference,
      const std::vector<std::shared_ptr<BlueprintNode>>>

A range-like object that allows range based for loops and index access.

This type's iterators and accessors return const references when dereferenced.

MutableChildRange

using Acts::Experimental::BlueprintNode::MutableChildRange

Initial value:

 
      Acts::detail::TransformRange<Acts::detail::Dereference,
                                   std::vector<std::shared_ptr<BlueprintNode>>>

A range-like object that allows range based for loops and index access.

This type's iterators and accessors return mutable references when dereferenced.

Constructor & Destructor Documentation

~BlueprintNode()

virtual Acts::Experimental::BlueprintNode::~BlueprintNode ( )

virtualdefault

Virtual destructor to ensure correct cleanup.

Member Function Documentation

addChild()

BlueprintNode & Acts::Experimental::BlueprintNode::addChild

(

std::shared_ptr< BlueprintNode >

child

)

Register a child to this node.

Warning

This method throws if adding the child would create a cycle in the blueprint tree!

Parameters

child

The child node to add

Returns

A reference this node (not the child!)

addCuboidContainer()

CuboidContainerBlueprintNode & Acts::Experimental::BlueprintNode::addCuboidContainer	(	const std::string &	name,
		AxisDirection	direction,
		const std::function< void(CuboidContainerBlueprintNode &cylinder)> &	callback = {} )

Convenience method for creating a cuboid specialization of Acts::Experimental::ContainerBlueprintNode.

Parameters

name	The name of the container node. This name is only reflected in the node tree for debugging, as no extra volumes is created for the container.
direction	The direction of the stack configuration. See Acts::CuboidVolumeStack for details.
callback	An optional callback that receives the node as an argument

Returns

Reference to the newly created cuboid container blueprint node

addCylinderContainer()

CylinderContainerBlueprintNode & Acts::Experimental::BlueprintNode::addCylinderContainer	(	const std::string &	name,
		AxisDirection	direction,
		const std::function< void(CylinderContainerBlueprintNode &cylinder)> &	callback = {} )

Convenience method for creating a cylinder specialization of Acts::Experimental::ContainerBlueprintNode.

Parameters

name	The name of the container node. This name is only reflected in the node tree for debugging, as no extra volumes is created for the container.
direction	The direction of the stack configuration. See Acts::CylinderVolumeStack for details.
callback	An optional callback that receives the node as an argument

Returns

Reference to the newly created cylinder container blueprint node

addLayer()

LayerBlueprintNode & Acts::Experimental::BlueprintNode::addLayer	(	const std::string &	name,
		const std::function< void(LayerBlueprintNode &layer)> &	callback = {} )

Convenience method for creating a Acts::Experimental::LayerBlueprintNode.

Parameters

name	The name of the layer node.
callback	An optional callback that receives the node as an argument

Returns

Reference to the newly created layer blueprint node

addMaterial()

MaterialDesignatorBlueprintNode & Acts::Experimental::BlueprintNode::addMaterial	(	const std::string &	name,
		const std::function< void(MaterialDesignatorBlueprintNode &material)> &	callback = {} )

Convenience method for creating a Acts::Experimental::MaterialDesignatorBlueprintNode.

Parameters

name	The name of the material designator node. Used for debugging the node tree only.
callback	An optional callback that receives the node as an argument

Returns

Reference to the newly created material designator blueprint node

addStaticVolume() [1/2]

StaticBlueprintNode & Acts::Experimental::BlueprintNode::addStaticVolume	(	const Transform3 &	transform,
		std::shared_ptr< VolumeBounds >	volumeBounds,
		const std::string &	volumeName = "undefined",
		const std::function< void(StaticBlueprintNode &cylinder)> &	callback = {} )

Alternative overload for creating a Acts::Experimental::StaticBlueprintNode.

This overload will invoke the constructor of Acts::TrackingVolume and use that volume to create the node.

Parameters

transform	The transform of the volume
volumeBounds	The bounds of the volume
volumeName	The name of the volume
callback	An optional callback that receives the node as an argument

Returns

Reference to the newly created static blueprint node

addStaticVolume() [2/2]

StaticBlueprintNode & Acts::Experimental::BlueprintNode::addStaticVolume	(	std::unique_ptr< TrackingVolume >	volume,
		const std::function< void(StaticBlueprintNode &cylinder)> &	callback = {} )

This method creates a new Acts::Experimental::StaticBlueprintNode wrapping volume and adds it to this node as a child.

Parameters

volume	The volume to add
callback	An optional callback that receives the node as an argument

Returns

A reference to the created node

addToGraphviz()

virtual void Acts::Experimental::BlueprintNode::addToGraphviz ( std::ostream & os ) const

virtual

Method that writes a representatiohn of this node only to graphviz.

This should generally not be called on its own, but through the BlueprintNode::graphviz method.

Parameters

os	The stream to print to

Reimplemented in Acts::Experimental::Blueprint, Acts::Experimental::ContainerBlueprintNode, and Acts::Experimental::StaticBlueprintNode.

build()

virtual Volume & Acts::Experimental::BlueprintNode::build ( const BlueprintOptions & options, const GeometryContext & gctx, const Logger & logger = Acts::getDummyLogger() )

pure virtual

This method is called during the build phase of the blueprint tree construction.

It returns a single Acts::Volume which represents transform and bounds of the entire subtree. This does not have to correspond to the final Acts::TrackingVolume, some node types will produce temporary volume representations. Lifetime of the returned volume is managed by the source node! Nodes higher in the hierarchy will issue resizes down the tree hierarchy. This is not done through a direct hierarchy, but coordinated by the respective node type, by internally consulting its children.

Note

Generally, you should not need to to call this method directly. The construction should usually be done through the special Acts::Experimental::Blueprint class.

Parameters

options	The global construction options
gctx	The geometry context for construction (usually nominal)
logger	The logger to use for output during construction

Returns

The volume used for communicating transform and size up the hierarchy

Implemented in Acts::Experimental::Blueprint, Acts::Experimental::ContainerBlueprintNode, Acts::Experimental::GeometryIdentifierBlueprintNode, Acts::Experimental::LayerBlueprintNode, Acts::Experimental::MaterialDesignatorBlueprintNode, and Acts::Experimental::StaticBlueprintNode.

children() [1/2]

MutableChildRange Acts::Experimental::BlueprintNode::children

(

)

Return a MutableChildRange to the children of this node.

Returns

A range-like object to the children

children() [2/2]

ChildRange Acts::Experimental::BlueprintNode::children

(

)

const

Return a ChildRange to the children of this node.

Returns

A range-like object to the children

clearChildren()

void Acts::Experimental::BlueprintNode::clearChildren

(

)

Remove all children from this node.

connect()

virtual PortalShellBase & Acts::Experimental::BlueprintNode::connect ( const BlueprintOptions & options, const GeometryContext & gctx, const Logger & logger = Acts::getDummyLogger() )

pure virtual

This method is called during the connect phase.

This phase handles the creation and connection of portals (instances of Acts::PortalLinkBase). After the build-phase has completed, the volume sizes are final. Each node will consult its fully sized volume to produce boundary surfaces. Each boundary surface is then turned into a Acts::TrivialPortalLink, which in turn produces a one-sided portal (see Acts::Portal documentation)

Some nodes (like Acts::Experimental::ContainerBlueprintNode) will take action on their children, and unify the connected portals.

After a node's processing has completed, it returns a reference to a Acts::PortalShellBase, which represents a set of portals in a specific geometry arrangement. The returned object lifetime is managed by the returning node.

Parameters

options	The global construction options
gctx	The geometry context for construction (usually nominal)
logger	The logger to use for output during construction

Returns

Reference to portal shell containing connected portals for this node

Implemented in Acts::Experimental::Blueprint, Acts::Experimental::CuboidContainerBlueprintNode, Acts::Experimental::CylinderContainerBlueprintNode, Acts::Experimental::GeometryIdentifierBlueprintNode, Acts::Experimental::MaterialDesignatorBlueprintNode, and Acts::Experimental::StaticBlueprintNode.

depth()

std::size_t Acts::Experimental::BlueprintNode::depth

(

)

const

Return the depth of this node in the blueprint tree.

A depth of zero means this node does not have a parent.

Returns

The depth of this node

finalize()

virtual void Acts::Experimental::BlueprintNode::finalize ( const BlueprintOptions & options, const GeometryContext & gctx, TrackingVolume & parent, const Logger & logger = Acts::getDummyLogger() )

pure virtual

This method is called during the finalize phase.

This phase handles:

• Registering portals into their final volumes
• Registering volumes into their parents
• Creating navigation policies
• (In future) Handle geometry identification assignment

At the end of this phase, each node will have transferred any temporary resources created during the build, that need to be retained, into the final Acts::TrackingGeometry, and can be safely destroyed.

Note

The parent for volumes, portals, etc to be registered in is passed in as an argument, rather than being implicitly determined from the parent node. This is done so that nodes can remove themselves from the final volume hierarchy, like container nodes or the Acts::Experimental::MaterialDesignatorBlueprintNode.

Parameters

options	The global construction options
gctx	The geometry context for construction (usually nominal)
parent	The parent volume to register in
logger	The logger to use for output during construction

Implemented in Acts::Experimental::Blueprint, Acts::Experimental::ContainerBlueprintNode, Acts::Experimental::GeometryIdentifierBlueprintNode, Acts::Experimental::MaterialDesignatorBlueprintNode, and Acts::Experimental::StaticBlueprintNode.

graphviz()

void Acts::Experimental::BlueprintNode::graphviz

(

std::ostream &

os

)

const

Print the node tree starting from this node to graphviz format.

Parameters

os	The stream to print to

indent()

std::string Acts::Experimental::BlueprintNode::indent ( ) const

protected

An indentation depending on the depth of this node.

Returns

The indentation string

name()

virtual const std::string & Acts::Experimental::BlueprintNode::name ( ) const

pure virtual

Get the name of this node.

Returns

Reference to the node name string

Implemented in Acts::Experimental::Blueprint, Acts::Experimental::ContainerBlueprintNode, Acts::Experimental::GeometryIdentifierBlueprintNode, Acts::Experimental::LayerBlueprintNode, Acts::Experimental::MaterialDesignatorBlueprintNode, and Acts::Experimental::StaticBlueprintNode.

prefix()

std::string Acts::Experimental::BlueprintNode::prefix ( ) const

protected

Printing helper returning a prefix including an indent depending on the depth.

Returns

The prefix string

setDepth()

void Acts::Experimental::BlueprintNode::setDepth ( std::size_t depth )

protected

Set the depth to depth and update children recursively.

Parameters

depth

New depth value to set

toStream()

virtual void Acts::Experimental::BlueprintNode::toStream ( std::ostream & os ) const

protectedvirtual

Virtual method to determine stream representation.

Parameters

os	Output stream to write to

Note

This method is called by the stream operator.

Reimplemented in Acts::Experimental::MaterialDesignatorBlueprintNode.

withGeometryIdentifier()

GeometryIdentifierBlueprintNode & Acts::Experimental::BlueprintNode::withGeometryIdentifier

(

const std::function< void(GeometryIdentifierBlueprintNode &geometryIdentifier)> &

callback = {}

)

Convenience method for creating a Acts::Experimental::GeometryIdentifierBlueprintNode.

Parameters

callback

An optional callback that receives the node as an argument

Returns

Reference to the newly created geometry identifier blueprint node