From afedf1ad58ead75f78d6e8ba76082545bbe6fd9b Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Fri, 17 Nov 2023 18:54:18 -0500
Subject: [PATCH] doc: write about algo design

---
 README.md     |  2 ++
 doc/design.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)

diff --git a/README.md b/README.md
index 37bcec8c..78349895 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
 
 Prototype design
 
+See [design notes](doc/design.md)
+
 ## Dependencies
 
 Dependencies likely available in your package manager:
diff --git a/doc/design.md b/doc/design.md
index 44af1b87..c98c4c66 100644
--- a/doc/design.md
+++ b/doc/design.md
@@ -62,3 +62,60 @@ flowchart LR
     MomentumCorrection       -.-> Algorithm
     MomentumCorrectionConfig -.-> AlgorithmConfig
 ```
+
+## Algorithm Design
+
+Base class `Algorithm` has virtual methods:
+- `Start`: runs before any event processing
+    - configuration
+    - set up data structures
+- `Run`: runs on every event
+    - input and output are a set of banks (`std::unordered_map< std::string, hipo::bank>`)
+    - runs the algorithm for a given event's bank(s)
+    - should be thread-safe, _e.g._, no modification of instance members
+    - usage:
+        - called on every event in an event loop
+        - part of a lambda for a data frame transformation
+    - analyses that operate on bank rows rather than full banks require exposure
+      of some function that does the _primary_ action of the algorithm
+        - useful to have
+        - wide variety of function signatures, so not easy to generalize and therefore not required
+- `Stop`: runs after event processing
+    - cleanup, if needed
+
+Algorithm usage options for users:
+- Instantiate and run algorithms as they are
+    - No need for `Iguana` instance
+    - Algorithms do not depend on `Iguana`, just on services
+    - All algorithms are available in a separate shared library
+    - Drawback: language bindings are not planned at the algorithm level
+- Use `Iguana`
+    - `Iguana` will only instantiate the algorithms the user intends to use, owning
+      an instance of each
+    - User runs the algorithms using `Iguana` "sugar"
+    - Language bindings can be made available at this level
+
+### Algorithm Types
+
+#### Filter
+- return an input bank with some rows masked (or removed)
+    - masking preferred to preserve bank linking
+    - options for masking a row:
+        - zero all elements
+        - add a boolean item to the _end_ of the schema to store whether a row is masked
+- public `bool Cut(float...)` function
+    - expose the _primary_ action of the algorithm for users that operate on bank rows
+    - not required, since difficult to generalize at the `Algorithm` (or `Iguana`) level
+    - similar to `chanser`'s RG-A criteria implementations
+
+#### Transformer
+- return an input bank with some elements modified
+- public `Transorm(...)` function that exposes the _primary_ algorithm action would be useful,
+  but not required
+
+#### Creator
+- return a new bank with a new schema
+- many reconstruction algorithms are creators
+
+#### Hybrid
+- any combination of the above