feat: example subclass algorithm (#422)

Author: c-dilks

CODEOWNERS

@@ -21,6 +21,7 @@ src/iguana/algorithms/clas12/rga/FiducialFilterPass1/* @Gregtom3
 src/iguana/algorithms/clas12/rga/FiducialFilterPass2/* @tbhayward
 src/iguana/algorithms/clas12/rga/MomentumCorrection/* @RichCap @c-dilks
 src/iguana/algorithms/example/ExampleAlgorithm/* @c-dilks
+src/iguana/algorithms/example/ExampleSubclassAlgorithm/* @c-dilks
 src/iguana/algorithms/physics/Depolarization/* @c-dilks
 src/iguana/algorithms/physics/DihadronKinematics/* @c-dilks
 src/iguana/algorithms/physics/InclusiveKinematics/* @c-dilks

src/iguana/algorithms/example/ExampleAlgorithm/README.md

@@ -40,5 +40,9 @@ Once you have generated your new algorithm:
 > errors, and will allow you to _see_ the documentation before it's deployed
 > online.
 
+> [!TIP]
+> If you are writing an algorithm that is very similar to another algorithm, consider inheriting from it;
+> see [`ExampleSubclassAlgorithm`](../ExampleSubclassAlgorithm) for an example.
+
 > [!TIP]
 > Enable debugging symbols when building by setting the Iguana build option `buildtype` to `debug`.

src/iguana/algorithms/example/ExampleSubclassAlgorithm/Action.yaml

@@ -0,0 +1,4 @@
+algorithm:
+  name: 'example::ExampleSubclassAlgorithm'
+include:
+  - '../../clas12/rga/FiducialFilterPass1/Action.yaml' # include these action functions

src/iguana/algorithms/example/ExampleSubclassAlgorithm/Algorithm.cc

@@ -0,0 +1,4 @@
+#include "Algorithm.h"
+namespace iguana::example {
+  REGISTER_IGUANA_ALGORITHM(ExampleSubclassAlgorithm);
+}

src/iguana/algorithms/example/ExampleSubclassAlgorithm/Algorithm.h

@@ -0,0 +1,21 @@
+#pragma once
+
+#include "iguana/algorithms/clas12/rga/FiducialFilterPass1/Algorithm.h"
+
+namespace iguana::example {
+
+  /// @algo_brief{example demonstrating inheritance from another algorithm}
+  /// @algo_type_filter
+  class ExampleSubclassAlgorithm : public clas12::rga::FiducialFilterPass1
+  {
+      // use `DEFINE_IGUANA_SUBALGORITHM` rather than the usual `DEFINE_IGUANA_ALGORITHM`;
+      // include the base-class algorithm as an argument
+      DEFINE_IGUANA_SUBALGORITHM(ExampleSubclassAlgorithm, example::ExampleSubclassAlgorithm, clas12::rga::FiducialFilterPass1)
+
+    public:
+
+      // make sure base-class specialized `Run` functions (overloads) are not shadowed by any `Run` function overrides here
+      using clas12::rga::FiducialFilterPass1::Run;
+  };
+
+}

src/iguana/algorithms/example/ExampleSubclassAlgorithm/Config.yaml

@@ -0,0 +1,13 @@
+example::ExampleSubclassAlgorithm:
+
+  ###################################################################################
+  # NOTE: config is the same as `rga::FiducialFilterPass1`, but with value changes
+  ###################################################################################
+
+  # cut levels for PCAL homogeneous cuts; one of 'loose', 'medium', or 'tight'
+  pcal_electron_cut_level: tight # for electrons and positrons
+  pcal_photon_cut_level: tight # for photons
+
+  # enable/disable certain cuts for more fine-grained control
+  enable_pcal_cuts: 1
+  enable_dc_cuts: 1

src/iguana/algorithms/meson.build

@@ -28,6 +28,14 @@ algo_dict = [
     'has_action_yaml': false,
     'test_args': {'banks': [ 'REC::Particle' ]},
   },
+  {
+    'name': 'example::ExampleSubclassAlgorithm',
+    'has_validator': false,
+    'test_args': {
+      'banks': [ 'REC::Particle', 'RUN::config', 'REC::Traj', 'REC::Calorimeter' ],
+      'prerequisites': [ 'clas12::CalorimeterLinker', 'clas12::TrajLinker' ],
+    },
+  },
   {
     'name': 'clas12::EventBuilderFilter',
     'has_validator': false,