Interfaces

These classes manage access to geometric information throughout the codebase. They work in tandem with celeritas::GeantGeoParams to associate volume identifiers with Geant4 runtime data structures.

class VolumeParams

Define and manage a hierarchy of volumes and instances thereof.

See the introduction to the Geometry API section for a detailed description of volumes in the detector geometry description. This class abstracts the graph of user-defined volumes, relating nodes (VolumeId, aka logical volume) to edges (VolumeInstanceId, aka physical volume) and providing the means to determine the path (isomorphic to a VolumeUniqueInstanceId, aka touchable history) of a track state. The root of the graph is the world volume, and the level of a volume in the path is the distance to the root: zero for the root volume, one for its direct child, etc. The maximum value of the level in any path is one less than num_volume_levels : an array of VolumeId with that size can represent any path.

In conjunction with GeantGeoParams, this class allows conversion between the Celeritas geometry implementation and the Geant4 geometry navigation.

class SurfaceParams : public celeritas::ParamsDataInterface<SurfaceParamsData>

Map volumetric geometry information to surface IDs.

See the introduction to the Geometry API section for a detailed description of surfaces in the detector geometry description.

The specification of surfaces using volume relationships is required by volume-based geometries such as Geant4 and VecGeom 1, so it is not currently possible to define different properties for the different faces of a volume unless those faces are surrounded by distinct geometric volumes. Since ORANGE and VecGeom 2 support true surface definitions, a future extension will allow the user to attach surface properties to, for example, different sides of a cube.

class GeoParamsInterface

Interface class for accessing host geometry metadata.

This class is implemented by OrangeParams to allow navigation with the ORANGE geometry implementation, VecgeomParams for using VecGeom, and GeantGeoParams for testing with the Geant4-provided navigator.

Subclassed by celeritas::GeantGeoParams, celeritas::OrangeParams, celeritas::VecgeomParams

A few helper functions can be used to build collections (see Data model) of ImplVolumeId for runtime tracking (used internally by fields, physics, etc.).

template<class T, class G, class F>
inline Collection<T, Ownership::value, MemSpace::host, ImplVolumeId> celeritas::build_volume_collection(G const &geo, F &&fill_value)

Create a “collection” that maps from ImplVolumeId to a value.

This builds collections for runtime execution using a GeoTrackView’s impl_volume_id() call, which requires less indirection than volume_id() .

Given a geometry (which is allowed to be GeoParamsInterface ), a function

T(*)(VolumeId) 

will be called for every ImplVolumeId in the geometry that corresponds to a canonical volume. The resulting value will be assigned to the collection.

template<class T>
class VolumeMapFiller

Helper class to fill a volume collection from a map.

Example:

host_data.detector
    = build_volume_collection<DetectorId>(geo, VolumeMapFiller{det_ids});

Runtime usage

A geometry “track view” is the key class used to access and/or modify a geometry state. (See Data model for more discussion of views and states.) Most states are a combination of physical properties (position, direction) and logical properties (volume path, surface, surface side).

The track view provides access to the thread-local state.

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

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

Initialization is performed via the assignment operator using a GeoTrackInitializer.

• An ephemeral failed flag can be set if initialization encountered an error, which is usually due to the user geometry definition.

• Depending on geometry implementation, the track may have a valid geometry state but is outside the physically relevant region: is_outside will be set.

• Otherwise, the track’s geometry state is valid for access.

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.

• If on a boundary, change volumes (“relocate”) with cross_boundary. This may cause the particle to leave the geometry, or result in an error that will set the failed flag.

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.

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 .

Note

The flag is_on_boundary will be true both before and after the call to cross_boundary, and the surface normal can be calculated in both cases.

Template Parameters:

RealType – Floating point precision

Physical state

Return the physical position in the global coordinate system

virtual Real3 const &pos() const = 0

Return the direction in the global coordinate system.

virtual Real3 const &dir() const = 0

Return the direction in the global coordinate system.

Canonical volume state

Get the canonical volume ID in the current impl volume

virtual VolumeId volume_id() const = 0

Get the physical volume ID in the current cell.

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.

Surface state

virtual bool is_on_boundary() const = 0

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.

virtual Real3 normal() const = 0

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.

Straight-line movement and boundary crossing

virtual Propagation find_next_step() = 0

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.

virtual Propagation find_next_step(real_type max_step) = 0

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.

virtual void move_internal(real_type step) = 0

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).

Pre:

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.

virtual void move_to_boundary() = 0

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.

virtual void cross_boundary() = 0

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

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

Locally bounded movement

virtual real_type find_safety() = 0

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).

virtual real_type find_safety(real_type max_step) = 0

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

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

virtual void set_dir(Real3 const &newdir) = 0

Change direction.

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

virtual void move_internal(Real3 const &pos) = 0

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).

Public Functions

virtual ~GeoTrackInterface() = 0

Default virtual destructor.

virtual GeoTrackInterface &operator=(Initializer_t const &init) = 0

Initialize the state.

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

virtual ImplVolumeId impl_volume_id() const = 0

Get the implementation volume ID.

virtual bool is_outside() const = 0

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).

virtual bool failed() const = 0

Whether the last operation resulted in an error.