Adjust and document optical surface traversal

doc/implementation/optical-physics/surface.rst

@@ -14,11 +14,7 @@ properties.
 
 .. doxygenenum:: celeritas::optical::SurfacePhysicsOrder
 
-During surface crossing, tracks maintain a "within-surface state" that stores
-the current layer and direction, decoupling the geometry state from the
-material state.
-
-.. doxygenclass:: celeritas::optical::SurfaceTraversalView
+.. doxygenclass:: celeritas::optical::SurfacePhysicsView
 
 .. _surface_boundary_init:
 

src/celeritas/inp/OpticalPhysics.hh

@@ -489,11 +489,6 @@ struct DielectricInteraction
 //---------------------------------------------------------------------------//
 /*!
  * Surface roughness description.
- *
- * \todo Future work will allow the of use multiple surface
- * paints/wrappings managed by different models. \c PhysSurfaceId will pair
- * a \c SurfaceId with a \c PhysSurfaceId that defines paint/wrapping
- * combinations.
  */
 struct RoughnessModels
 {

src/celeritas/optical/Types.hh

@@ -6,6 +6,7 @@
 //---------------------------------------------------------------------------//
 #pragma once
 
+#include "corecel/Macros.hh"
 #include "celeritas/Types.hh"
 
 namespace celeritas
@@ -16,9 +17,11 @@ namespace celeritas
 namespace optical
 {
 
-//! Opaque index into subsurface track position, in range [0, num subsurface
-//! interfaces + 1]
-using SurfaceTrackPosition = OpaqueId<struct SurfaceTrackPosition_>;
+//! Opaque index of sub-surface interface
+using LocalSurfaceId = OpaqueId<struct LocalSurface_, unsigned short int>;
+
+//! Opaque index of sub-surface material region
+using LocalPositionId = OpaqueId<struct LocalMat_, unsigned short int>;
 
 }  // namespace optical
 
@@ -51,7 +54,7 @@ enum class SurfacePhysicsOrder
 };
 
 //! Traversal direction of a sub-subsurface
-enum class SubsurfaceDirection : bool
+enum class LocalDirection : bool
 {
     reverse = false,
     forward = true
@@ -103,7 +106,7 @@ char const* to_cstring(ReflectionMode);
 char const* to_cstring(WlsDistribution);
 
 //! Convert sub-surface direction to a sign (+1/-1 for forward/reverse resp.)
-CELER_FORCEINLINE_FUNCTION int to_signed_offset(SubsurfaceDirection d)
+CELER_CONSTEXPR_FUNCTION int to_signed_offset(LocalDirection d)
 {
     return 2 * static_cast<int>(d) - 1;
 }

src/celeritas/optical/surface/SurfacePhysicsData.hh

@@ -20,25 +20,23 @@ namespace optical
 /*!
  * Storage for physics data of a geometric surface.
  *
- * The \c subsurface_materials indexes into the \c
- * SurfacePhysicsParamsData::subsurface_materials and represents a list of
- * interstitial optical materials that make up a geometric surface. The \c
- * subsurface_interfaces represents the physics surfaces that separate the
- * optical materials that make up a geometric surface.
+ * See \c SurfacePhysicsView for documentation.
  *
- * By convention, \c subsurface_interfaces[0] separates the pre-volume and the
- * first subsurface material, while the last interface separates the last
- * subsurface material and the post-volume.
+ * - \c interstitial_mats indexes into \c SurfacePhysicsParamsData::opt_mat_ids
+ * - \c local_surface_ids give \c PhysSurfaceId for models
+ * - physical surfaces map to models is done by \c model_maps
  */
-struct SurfaceRecord
+struct SurfacePhysicsRecord
 {
-    ItemMap<SurfaceTrackPosition, OpaqueId<OptMatId>> subsurface_materials;
-    ItemMap<SurfaceTrackPosition, PhysSurfaceId> subsurface_interfaces;
+    //! Indirection to a stored optical mat ID (interstitial 0 = LPId{1})
+    ItemRange<OptMatId> interstitial_mat_ids;
+    //! Physics surface ID from the forward-oriented local surface ID
+    ItemMap<LocalSurfaceId, PhysSurfaceId> local_surface_ids;
 
     //! Whether data is assigned
     explicit CELER_FUNCTION operator bool() const
     {
-        return subsurface_materials.size() + 1 == subsurface_interfaces.size();
+        return interstitial_mat_ids.size() + 1 == local_surface_ids.size();
     }
 };
 
@@ -92,10 +90,12 @@ struct SurfacePhysicsParamsData
     SurfacePhysicsParamsScalars scalars;
 
     //! Optical surface model data
-
-    GeoSurfaceItems<SurfaceRecord> surfaces;
+    GeoSurfaceItems<SurfacePhysicsRecord> surfaces;
     SurfaceStepModelMaps model_maps;
-    Items<OptMatId> subsurface_materials;
+
+    //// BACKEND STORAGE ////
+
+    Items<OptMatId> opt_mat_ids;
 
     //! Whether data is assigned
     explicit CELER_FUNCTION operator bool() const
@@ -111,7 +111,7 @@ struct SurfacePhysicsParamsData
         CELER_EXPECT(other);
         scalars = other.scalars;
         surfaces = other.surfaces;
-        subsurface_materials = other.subsurface_materials;
+        opt_mat_ids = other.opt_mat_ids;
         for (auto step : range(SurfacePhysicsOrder::size_))
         {
             model_maps[step] = other.model_maps[step];
@@ -136,16 +136,16 @@ struct SurfacePhysicsStateData
     //!@{
     //! \name Constant state for a single boundary crossing
     StateItems<SurfaceId> surface;
-    StateItems<SubsurfaceDirection> surface_orientation;
+    StateItems<LocalDirection> surface_orientation;
     StateItems<Real3> global_normal;
     StateItems<OptMatId> pre_volume_material;
     StateItems<OptMatId> post_volume_material;
     //!@}
 
     //!@{
     //! \name Mutable state for a single boundary crossing
-    StateItems<SurfaceTrackPosition> surface_position;
-    StateItems<SubsurfaceDirection> track_direction;
+    StateItems<LocalPositionId> local_position;
+    StateItems<LocalDirection> local_direction;
     StateItems<Real3> facet_normal;
     StateItems<ReflectivityAction> reflectivity_action;
     //!@}
@@ -154,8 +154,8 @@ struct SurfacePhysicsStateData
     explicit CELER_FUNCTION operator bool() const
     {
         return !surface.empty() && surface.size() == surface_orientation.size()
-               && surface.size() == surface_position.size()
-               && surface.size() == track_direction.size()
+               && surface.size() == local_position.size()
+               && surface.size() == local_direction.size()
                && surface.size() == pre_volume_material.size()
                && surface.size() == post_volume_material.size()
                && surface.size() == global_normal.size()
@@ -175,8 +175,8 @@ struct SurfacePhysicsStateData
         surface = other.surface;
         surface_orientation = other.surface_orientation;
         global_normal = other.global_normal;
-        surface_position = other.surface_position;
-        track_direction = other.track_direction;
+        local_position = other.local_position;
+        local_direction = other.local_direction;
         pre_volume_material = other.pre_volume_material;
         post_volume_material = other.post_volume_material;
         facet_normal = other.facet_normal;
@@ -199,8 +199,8 @@ resize(SurfacePhysicsStateData<Ownership::value, M>* state, size_type size)
     resize(&state->surface, size);
     resize(&state->surface_orientation, size);
     resize(&state->global_normal, size);
-    resize(&state->surface_position, size);
-    resize(&state->track_direction, size);
+    resize(&state->local_position, size);
+    resize(&state->local_direction, size);
     resize(&state->pre_volume_material, size);
     resize(&state->post_volume_material, size);
     resize(&state->facet_normal, size);

src/celeritas/optical/surface/SurfacePhysicsParams.cc

@@ -109,7 +109,7 @@ void SurfacePhysicsParams::build_surfaces(
     CELER_EXPECT(!interstitial_materials.empty());
 
     auto build_surface = make_builder(&data.surfaces);
-    auto build_material = make_builder(&data.subsurface_materials);
+    auto build_material = make_builder(&data.opt_mat_ids);
 
     PhysSurfaceId next_phys_surface{0};
     for (auto const& materials : interstitial_materials)
@@ -120,7 +120,7 @@ void SurfacePhysicsParams::build_surfaces(
         next_phys_surface
             = PhysSurfaceId(phys_surface_start.get() + materials.size() + 1);
 
-        build_surface.push_back(SurfaceRecord{
+        build_surface.push_back(SurfacePhysicsRecord{
             build_material.insert_back(materials.begin(), materials.end()),
             range(phys_surface_start, next_phys_surface)});
     }

src/celeritas/optical/surface/SurfacePhysicsTrackView.hh

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
 //---------------------------------------------------------------------------//
 //! \file celeritas/optical/surface/SurfacePhysicsTrackView.hh
+//! \sa celeritas/optical/SurfacePhysics.test.cc
 //---------------------------------------------------------------------------//
 #pragma once
 
@@ -24,9 +25,13 @@ namespace optical
  * Optical surface physics data for a track.
  *
  * Tracks maintain a position while traversing the interstitial materials of an
- * optical surface. This class provides transformations from this position
- * based on the surface orientation and traversal direction to access relevant
- * material and interface data in storage.
+ * optical surface.
+ * This class provides transformations from this position based on the surface
+ * orientation (pre/post volume when the crossing began) and traversal
+ * direction (current state) to access relevant material and interface data in
+ * storage.
+ *
+ * See \c SurfacePhysicsView, \c SurfaceTraversalView .
  */
 class SurfacePhysicsTrackView
 {
@@ -40,7 +45,7 @@ class SurfacePhysicsTrackView
     struct Initializer
     {
         SurfaceId surface{};
-        SubsurfaceDirection orientation;
+        LocalDirection orientation;
         Real3 global_normal{0, 0, 0};
         OptMatId pre_volume_material{};
         OptMatId post_volume_material{};
@@ -105,7 +110,7 @@ class SurfacePhysicsTrackView
     TrackSlotId const track_id_;
 
     // Get material at the given track position
-    inline CELER_FUNCTION OptMatId material(SurfaceTrackPosition) const;
+    inline CELER_FUNCTION OptMatId material(LocalPositionId) const;
 };
 
 //---------------------------------------------------------------------------//
@@ -302,11 +307,9 @@ SurfacePhysicsTrackView::scalars() const
 /*!
  * Get material at given track position.
  */
-CELER_FUNCTION OptMatId
-SurfacePhysicsTrackView::material(SurfaceTrackPosition pos) const
+CELER_FUNCTION OptMatId SurfacePhysicsTrackView::material(LocalPositionId pos) const
 {
-    auto pos_range
-        = range(SurfaceTrackPosition{this->traversal().num_positions()});
+    auto pos_range = range(LocalPositionId{this->traversal().num_local_pos()});
     CELER_EXPECT(pos < pos_range.size());
 
     if (pos == pos_range.front())

src/celeritas/optical/surface/SurfacePhysicsUtils.hh

@@ -33,6 +33,19 @@ is_entering_surface(Real3 const& dir, Real3 const& normal)
     return dot_product(dir, normal) < 0;
 }
 
+//---------------------------------------------------------------------------//
+/*!
+ * Get the local surface ID given the current local material and direction.
+ */
+inline CELER_FUNCTION LocalSurfaceId local_surf_id(LocalPositionId pos,
+                                                   LocalDirection dir)
+{
+    CELER_EXPECT(
+        pos && (pos > LocalPositionId{0} || dir == LocalDirection::forward));
+    return id_cast<LocalSurfaceId>(static_cast<int>(pos.unchecked_get())
+                                   + static_cast<int>(dir) - 1);
+}
+
 //---------------------------------------------------------------------------//
 /*!
  * Get the next track surface position in the given direction.
@@ -41,24 +54,21 @@ is_entering_surface(Real3 const& dir, Real3 const& normal)
  * Uses unsigned underflow when moving reverse (dir = -1) while on a
  * pre-surface (pos = 0) to wrap to an invalid position value.
  */
-CELER_FORCEINLINE_FUNCTION SurfaceTrackPosition
-next_subsurface_position(SurfaceTrackPosition pos, SubsurfaceDirection dir)
+inline CELER_FUNCTION LocalPositionId next_local_pos_id(LocalPositionId pos,
+                                                        LocalDirection dir)
 {
     CELER_EXPECT(pos);
-    return SurfaceTrackPosition{
-        pos.unchecked_get()
-        + static_cast<SurfaceTrackPosition::size_type>(to_signed_offset(dir))};
+    return LocalPositionId(pos.unchecked_get() + to_signed_offset(dir));
 }
 
 //---------------------------------------------------------------------------//
 /*!
  * Calculate subsurface direction from a track's geometry direction.
  */
-inline CELER_FUNCTION SubsurfaceDirection
+inline CELER_FUNCTION LocalDirection
 calc_subsurface_direction(Real3 const& geo_dir, Real3 const& normal)
 {
-    return static_cast<SubsurfaceDirection>(
-        is_entering_surface(geo_dir, normal));
+    return static_cast<LocalDirection>(is_entering_surface(geo_dir, normal));
 }
 
 //---------------------------------------------------------------------------//