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 ofVolumeIdwith 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
OrangeParamsto allow navigation with the ORANGE geometry implementation,VecgeomParamsfor using VecGeom, andGeantGeoParamsfor 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 thanvolume_id().Given a geometry (which is allowed to be
GeoParamsInterface), a functionwill be called for everyT(*)(VolumeId)
ImplVolumeIdin 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
failedflag 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_outsidewill 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_internalormove_to_boundary.If on a boundary,
normalcan 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 thefailedflag.
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_GEOconfiguration variable and defined as a type aliasceleritas::CoreGeoTrackView.Note
The flag
is_on_boundarywill be true both before and after the call tocross_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
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.
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
stepmust be less than or equal to the previousfind_next_stepresult 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.
Public Functions
-
virtual ~GeoTrackInterface() = 0¶
Default virtual destructor.
-
virtual GeoTrackInterface &operator=(Initializer_t const &init) = 0¶
Initialize the state.
Takes a
GeoTrackInitializerobject 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.