Standard interface to geometry navigation for a track for testing on CPU. More...

#include <GeoTrackInterface.hh>

Public Types
Type aliases
using	Initializer_t = GeoTrackInitializer

using	real_type = RealType

using	Real3 = Array< real_type, 3 >

Public Member Functions
virtual	~GeoTrackInterface ()=0
	Default virtual destructor.

virtual GeoTrackInterface &	operator= (Initializer_t const &init)=0
	Initialize the state.

virtual ImplVolumeId	impl_volume_id () const =0
	Get the implementation volume ID.

virtual bool	failed () const =0
	Whether the last operation resulted in an error.

Physical state
virtual Real3 const &	pos () const =0
	Return the physical position in the global coordinate system.

virtual Real3 const &	dir () const =0
	Return the direction in the global coordinate system.

Canonical volume state
Precondition The geo status cannot be `GeoStatus::invalid`
virtual VolumeId	volume_id () const =0
	Get the canonical volume ID in the current impl volume.

virtual VolumeInstanceId	volume_instance_id () const =0
	Get the physical volume ID in the current cell.

virtual VolumeLevelId	volume_level () const =0
	Get the distance from root volume in the geometry hierarchy.

virtual void	volume_instance_id (Span< VolumeInstanceId > levels) const =0
	Get the volume instance ID for all levels.

virtual bool	is_outside () const =0
	Whether the track is outside the valid geometry region.

Surface state
virtual bool	is_on_boundary () const =0
	Whether the track is exactly on a surface.

virtual Real3	normal () const =0
	Calculate the normal vector on the current surface.

virtual GeoStatus	geo_status () const
	Derive the geometry state from the existing state flags.

Straight-line movement and boundary crossing
Propagation	find_next_step ()
	Find the distance to the next boundary (infinite max).

virtual Propagation	find_next_step (real_type max_step)=0
	Find the distance to the next boundary, up to and including a step.

virtual void	move_internal (real_type step)=0
	Move within the volume.

virtual void	move_to_boundary ()=0
	Move to the boundary in preparation for crossing it.

virtual void	cross_boundary ()=0
	Cross from one side of the current surface to the other.

Locally bounded movement
virtual real_type	find_safety ()=0
	Find the safety distance at the current position.

virtual real_type	find_safety (real_type max_step)=0
	Find the safety at the current position, up to a maximum step distance.

virtual void	set_dir (Real3 const &newdir)=0
	Change direction.

virtual void	move_internal (Real3 const &pos)=0
	Move within the volume to a specific point.

Protected Member Functions
	GeoTrackInterface (GeoTrackInterface const &)=default

GeoTrackInterface &	operator= (GeoTrackInterface const &)=default

	GeoTrackInterface (GeoTrackInterface &&)=default

GeoTrackInterface &	operator= (GeoTrackInterface &&)=default

Detailed Description

template<class RealType = ::celeritas::real_type>
class celeritas::GeoTrackInterface< RealType >

Standard interface to geometry navigation for a track for testing on CPU.

Template Parameters

RealType Floating point precision

Note: This class is for illustrative and testing purposes only (see celeritas::test::WrappedGeoTrackView) and is not used during the main Celeritas execution. The geometry there is determined by the CELERITAS_CORE_GEO configuration variable and defined as a type alias celeritas::CoreGeoTrackView .

Initialization is performed via the assignment operator using a GeoTrackInitializer.

Initialization may fail, leaving the track with an "error" status.
Some implementations allow initialization on a boundary, leaving the track in an "outgoing from boundary" state (i.e., the next step is into the volume the track initializes inside).
Some implementations allow initialization to succeed but be in an unphysical part of the geometry (e.g., ORANGE exterior volume). In this case, the canonical volume ID will be null, indicating no corresponding user-defined geometry region.

Tracking to and across volumes along a straight line requires a specific sequence of calls.

Locate the boundary crossing along the current direction with find_next_step.
Move within the current volume, not crossing a boundary, via move_internal or move_to_boundary.
If on a boundary, normal can be used to calculate the current surface normal, but its dot product with the track direction may not be meaningful. Use geo_status to determine whether the track is incident to or outgoing from the boundary.
If incident into the boundary, change volumes ("relocate") with cross_boundary. The post-crossing status can be error, boundary_out, or invalid. Some geometries represent the exterior as a null canonical VolumeId, and some as an invalid state.

Note: The free function is_on_boundary will be true of the geo status both before and after the call to cross_boundary, and the surface normal can be calculated in both cases.

Movement to a nearby but arbitrary point can be done inside a "safety" distance:

Locate the closest point on the boundary in any direction with find_safety.
Change the direction with set_dir. (Note that this will always invalidate the linear "next step".)
Move to a point with move_internal.

Neither accessors nor mutators should be called in an invalid state. It is allowable but potentially dangerous to call accessors in an error state.

Member Function Documentation

◆ cross_boundary()

template<class RealType = ::celeritas::real_type>

virtual void celeritas::GeoTrackInterface< RealType >::cross_boundary ( )

pure virtual

Cross from one side of the current surface to the other.

Changes the logical state when on the boundary, updating to the next volume.

Precondition: geo_status() is GeoStatus::boundary_inc .

Postcondition: geo_status() is GeoStatus::boundary_out , or GeoStatus::error if the new volume could not be found.

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ dir()

template<class RealType = ::celeritas::real_type>

virtual Real3 const & celeritas::GeoTrackInterface< RealType >::dir ( ) const

pure virtual

Return the direction in the global coordinate system.

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ failed()

template<class RealType = ::celeritas::real_type>

virtual bool celeritas::GeoTrackInterface< RealType >::failed ( ) const

pure virtual

Whether the last operation resulted in an error.

Deprecated:: check geo_status for GeoStatus::error instead.

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ find_next_step() [1/2]

template<class RealType = ::celeritas::real_type>

Propagation celeritas::GeoTrackInterface< RealType >::find_next_step ( )

inline

Find the distance to the next boundary (infinite max).

Determines the distance to the next boundary (i.e., a different implementation volume) along the track's current direction.

Deprecated:: Provide a physically reasonable upper bound to the distance to reduce search cost and avoid a redundant method.

◆ find_next_step() [2/2]

template<class RealType = ::celeritas::real_type>

virtual Propagation celeritas::GeoTrackInterface< RealType >::find_next_step ( real_type max_step )

pure virtual

Find the distance to the next boundary, up to and including a step.

Determines the distance to the next boundary along the track's current direction, up to a given distance. Queries may be more efficient for small distances.

Precondition: geo_status() is not GeoStatus::boundary_inc .

Postcondition: The returned distance is in the range (0, max_step] .

Implemented in celeritas::test::WrappedGeoTrackView< GTV >.

◆ find_safety() [1/2]

template<class RealType = ::celeritas::real_type>

virtual real_type celeritas::GeoTrackInterface< RealType >::find_safety ( )

pure virtual

Find the safety distance at the current position.

Determines the distance to the nearest boundary in any direction (i.e., the radius of the maximally inscribed sphere).

deprecated: use find_safety(inf)

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ find_safety() [2/2]

template<class RealType = ::celeritas::real_type>

virtual real_type celeritas::GeoTrackInterface< RealType >::find_safety ( real_type max_step )

pure virtual

Find the safety at the current position, up to a maximum step distance.

The resulting safety should be no larger than the maximum step.

Precondition: is_on_boundary(geo.geo_status()) must be false

Implemented in celeritas::test::WrappedGeoTrackView< GTV >.

◆ geo_status()

template<class RealType = ::celeritas::real_type>

virtual GeoStatus celeritas::GeoTrackInterface< RealType >::geo_status ( ) const

inlinevirtual

Derive the geometry state from the existing state flags.

This is a shim for geometry implementations that do not natively track the full GeoStatus. When on a boundary, it assumes the normal vector is oriented "outward" from the current volume. The dot product of the track direction and the surface normal determines whether the track is incident to the boundary (positive: headed outward from the volume) or incident (negative: headed into the volume).

Reimplemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ impl_volume_id()

template<class RealType = ::celeritas::real_type>

virtual ImplVolumeId celeritas::GeoTrackInterface< RealType >::impl_volume_id ( ) const

pure virtual

Get the implementation volume ID.

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ is_on_boundary()

template<class RealType = ::celeritas::real_type>

virtual bool celeritas::GeoTrackInterface< RealType >::is_on_boundary ( ) const

pure virtual

Whether the track is exactly on a surface.

Returns true if a track is exactly on the boundary of a volume, capable of changing to another volume without altering the physical position.

Deprecated:: use is_on_boundary(geo.geo_status())

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ is_outside()

template<class RealType = ::celeritas::real_type>

virtual bool celeritas::GeoTrackInterface< RealType >::is_outside ( ) const

pure virtual

Whether the track is outside the valid geometry region.

Returns true if the track has left the world (or started outside the outermost known volume).

Deprecated:: Check geo.geo_status() is not invalid and evaluate is_outside(geo.volume_id())

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ move_internal() [1/2]

template<class RealType = ::celeritas::real_type>

virtual void celeritas::GeoTrackInterface< RealType >::move_internal ( Real3 const & pos )

pure virtual

Move within the volume to a specific point.

Changes the physical position of the geometry state without altering the logical state (i.e., it must remain within the current volume).

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ move_internal() [2/2]

template<class RealType = ::celeritas::real_type>

virtual void celeritas::GeoTrackInterface< RealType >::move_internal ( real_type step )

pure virtual

Move within the volume.

Changes the physical position of the geometry state without altering the logical state (i.e., it must remain within the current volume).

Precondition: The given step must be less than or equal to the previous find_next_step result and can only be equal if the endpoint is not on a boundary.

Implemented in celeritas::test::WrappedGeoTrackView< GTV >.

◆ move_to_boundary()

template<class RealType = ::celeritas::real_type>

virtual void celeritas::GeoTrackInterface< RealType >::move_to_boundary ( )

pure virtual

Move to the boundary in preparation for crossing it.

Moves the track to the boundary of the current volume along the current direction, updating its logical state to indicate that it is on the boundary of the current volume.

Precondition: geo_status() is not GeoStatus::boundary_inc .

Postcondition: geo_status() is GeoStatus::boundary_inc .

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ normal()

template<class RealType = ::celeritas::real_type>

virtual Real3 celeritas::GeoTrackInterface< RealType >::normal ( ) const

pure virtual

Calculate the normal vector on the current surface.

Returns a global-coordinate direction perpendicular to the volume at the local point when on a boundary. The sign of the surface normal is implementation-dependent; it may change based on the track state (previous volume, direction, surface sign) or geometry construction.

Precondition: is_on_boundary(geo.geo_status()) must be true

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ operator=()

template<class RealType = ::celeritas::real_type>

virtual GeoTrackInterface & celeritas::GeoTrackInterface< RealType >::operator= ( Initializer_t const & init )

pure virtual

Initialize the state.

Takes a GeoTrackInitializer object to locate the point in the geometry hierarchy.

Postcondition: geo_status() is never GeoStatus::boundary_inc : the result is interior (placed inside a volume), boundary_out (placed on a boundary with direction heading away from it), or error (volume not found).

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ pos()

template<class RealType = ::celeritas::real_type>

virtual Real3 const & celeritas::GeoTrackInterface< RealType >::pos ( ) const

pure virtual

Return the physical position in the global coordinate system.

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ set_dir()

template<class RealType = ::celeritas::real_type>

virtual void celeritas::GeoTrackInterface< RealType >::set_dir ( Real3 const & newdir )

pure virtual

Change direction.

Changes the direction of the track (in global coordinate system).

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ volume_id()

template<class RealType = ::celeritas::real_type>

virtual VolumeId celeritas::GeoTrackInterface< RealType >::volume_id ( ) const

pure virtual

Get the canonical volume ID in the current impl volume.

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ volume_instance_id() [1/2]

template<class RealType = ::celeritas::real_type>

virtual VolumeInstanceId celeritas::GeoTrackInterface< RealType >::volume_instance_id ( ) const

pure virtual

Get the physical volume ID in the current cell.

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ volume_instance_id() [2/2]

template<class RealType = ::celeritas::real_type>

virtual void celeritas::GeoTrackInterface< RealType >::volume_instance_id ( Span< VolumeInstanceId > levels ) const

pure virtual

Get the volume instance ID for all levels.

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

◆ volume_level()

template<class RealType = ::celeritas::real_type>

virtual VolumeLevelId celeritas::GeoTrackInterface< RealType >::volume_level ( ) const

pure virtual

Get the distance from root volume in the geometry hierarchy.

Implemented in celeritas::test::CheckedGeoTrackView, and celeritas::test::WrappedGeoTrackView< GTV >.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ cross_boundary()

◆ dir()

◆ failed()

◆ find_next_step() [1/2]

◆ find_next_step() [2/2]

◆ find_safety() [1/2]

◆ find_safety() [2/2]

◆ geo_status()

◆ impl_volume_id()

◆ is_on_boundary()

◆ is_outside()

◆ move_internal() [1/2]

◆ move_internal() [2/2]

◆ move_to_boundary()

◆ normal()

◆ operator=()

◆ pos()

◆ set_dir()

◆ volume_id()

◆ volume_instance_id() [1/2]

◆ volume_instance_id() [2/2]

◆ volume_level()