Few fixes and improvements

- Fix Doxygen build error
- Add `scintillation_by_particle()` boolean in `ScintillationData` to
  verify which sampling method should be used; Improve documentation
- Use CELER_NOT_IMPLEMENTED whenever scintillation particle data is
  passed to the scintillation pre-generator and generator.
- Improve test

src/celeritas/io/ImportParameters.hh

@@ -119,7 +119,7 @@ struct ImportTransParameters
 
 //---------------------------------------------------------------------------//
 /*!
- * \TODO: Placeholder for optical parameter data.
+ * TODO: Placeholder for optical parameter data.
  * See \c G4OpticalParameters .
  */
 struct ImportOpticalParameters

src/celeritas/optical/ScintillationData.hh

@@ -87,6 +87,11 @@ struct ParticleScintillationSpectrum
  * Data characterizing the scintillation spectrum for all particles and
  * materials.
  *
+ * Sampling using material-only data or particle- and material-dependent data
+ * are mutually exclusive. Therefore, either \c materials or \c particles are
+ * loaded at the beginning of the simulation, but *never* both at the same
+ * time. The \c scintillation_by_particle() function can be used to check that.
+ *
  * - \c matid_to_optmatid returns an \c OpticalMaterialId given a
  *   \c MaterialId
  * - \c pid_to_scintpid returns a \c ScintillationParticleId given a
@@ -144,6 +149,12 @@ struct ScintillationData
                && num_materials == matid_to_optmatid.size();
     }
 
+    //! Whether sampling must happen by particle type
+    CELER_FUNCTION bool scintillation_by_particle() const
+    {
+        return !particles.empty();
+    }
+
     //! Retrieve spectrum index for a given optical particle and material ids
     ParticleScintSpectrumId
     spectrum_index(ScintillationParticleId pid, OpticalMaterialId mat_id) const

src/celeritas/optical/ScintillationGenerator.hh

@@ -118,13 +118,16 @@ template<class Generator>
 CELER_FUNCTION Span<OpticalPrimary>
 ScintillationGenerator::operator()(Generator& rng)
 {
+    if (shared_.scintillation_by_particle())
+    {
+        // TODO: implement sampling for particles
+        CELER_NOT_IMPLEMENTED("scintillation by particle type");
+    }
+
     // Loop for generating scintillation photons
     size_type num_generated{0};
     auto const& mat_spectrum = shared_.materials[dist_.material];
 
-    // TODO: implement sampling for particles
-    // TODO: in Geant4 components are not necessary
-
     // Material sampling
     for (auto sid : mat_spectrum.components)
     {

src/celeritas/optical/ScintillationPreGenerator.hh

@@ -59,7 +59,7 @@ class ScintillationPreGenerator
     inline CELER_FUNCTION OpticalDistributionData operator()(Generator& rng);
 
   private:
-    ParticleTrackView const& particle_view_;
+    units::ElementaryCharge charge_;
     real_type step_len_;
     OpticalMaterialId mat_id_;
     NativeCRef<ScintillationData> const& shared_;
@@ -78,7 +78,7 @@ inline CELER_FUNCTION ScintillationPreGenerator::ScintillationPreGenerator(
     OpticalMaterialId material,
     NativeCRef<ScintillationData> const& shared,
     OpticalPreGenStepData const& step_data)
-    : particle_view_(particle_view)
+    : charge_(particle_view.charge())
     , step_len_(sim_view.step_length())
     , mat_id_(material)
     , shared_(shared)
@@ -99,7 +99,12 @@ template<class Generator>
 inline CELER_FUNCTION OpticalDistributionData
 ScintillationPreGenerator::operator()(Generator& rng)
 {
-    // TODO: implement sampling for particles
+    if (shared_.scintillation_by_particle())
+    {
+        // TODO: implement sampling for particles
+        CELER_NOT_IMPLEMENTED("scintillation by particle type");
+    }
+
     auto const& material = shared_.materials[mat_id_];
     CELER_EXPECT(material);
 
@@ -124,7 +129,7 @@ ScintillationPreGenerator::operator()(Generator& rng)
     if (result.num_photons > 0)
     {
         // Assign remaining data
-        result.charge = particle_view_.charge();
+        result.charge = charge_;
         result.material = mat_id_;
         result.step_length = step_len_;
         result.time = step_.time;

test/celeritas/optical/Scintillation.test.cc

@@ -139,6 +139,8 @@ TEST_F(ScintillationTest, material_scint_params)
 {
     auto const params = this->build_scintillation_params();
     auto const& data = params->host_ref();
+    EXPECT_FALSE(data.scintillation_by_particle());
+
     auto const opt_matid = data.matid_to_optmatid[MaterialId{0}];
 
     EXPECT_EQ(1, data.num_materials);
@@ -192,6 +194,8 @@ TEST_F(ScintillationTest, particle_scint_params)
     auto const params = this->build_scintillation_params(
         /* scint_by_particle = */ true);
     auto const& data = params->host_ref();
+    EXPECT_TRUE(data.scintillation_by_particle());
+
     auto const opt_matid = data.matid_to_optmatid[MaterialId{0}];
     auto const scint_pid = data.pid_to_scintpid[ParticleId{0}];
 
@@ -255,6 +259,7 @@ TEST_F(ScintillationTest, pre_generator)
 {
     auto const params = this->build_scintillation_params();
     auto const& data = params->host_ref();
+    EXPECT_FALSE(data.scintillation_by_particle());
 
     // The particle's energy is necessary for the particle track view but is
     // irrelevant for the test since what matters is the energy deposition,
@@ -266,14 +271,14 @@ TEST_F(ScintillationTest, pre_generator)
         data,
         this->build_pregen_step());
 
-    auto result = generate(this->rng());
+    auto const result = generate(this->rng());
     EXPECT_EQ(4, result.num_photons);
     EXPECT_REAL_EQ(0, result.time);
     EXPECT_REAL_EQ(1, result.step_length);
     EXPECT_EQ(-1, result.charge.value());
     EXPECT_EQ(0, result.material.get());
 
-    auto expected_step = this->build_pregen_step();
+    auto const expected_step = this->build_pregen_step();
     for (auto p : range(StepPoint::size_))
     {
         EXPECT_EQ(expected_step.points[p].speed.value(),
@@ -287,6 +292,8 @@ TEST_F(ScintillationTest, basic)
 {
     auto const params = this->build_scintillation_params();
     auto const& data = params->host_ref();
+    EXPECT_FALSE(data.scintillation_by_particle());
+
     auto const opt_matid = data.matid_to_optmatid[MaterialId{0}];
 
     // Pre-generate optical distribution data