+
## Iguana: Implementation Guardian of Analysis Algorithms
@@ -16,7 +16,6 @@ Iguana is not a framework for _reading_ data, rather it is a set of algorithms t
### For Users
1. [**Iguana User's Guide**](https://jeffersonlab.github.io/iguana/doxygen)
1. [Setup Guide - how to build and install Iguana](doc/setup.md)
-1. [Configuring the Algorithms](doc/configuration.md)
1. [Troubleshooting](doc/troubleshooting.md)
#### Language Bindings
@@ -24,7 +23,6 @@ Iguana is not a framework for _reading_ data, rather it is a set of algorithms t
1. [All others: see the Iguana User's guide](https://jeffersonlab.github.io/iguana/doxygen)
### For Developers
-1. [Design Notes](doc/design.md)
1. [Developing a new Algorithm](src/iguana/algorithms/example/ExampleAlgorithm/README.md)
1. [Algorithm Tests and Validators](doc/testing.md)
1. [Repository Maintenance](doc/maintenance.md)
diff --git a/bind/python/iguana_ex_python_00_run_functions.py b/bind/python/iguana_ex_python_00_run_functions.py
index f958303a..adab8591 100755
--- a/bind/python/iguana_ex_python_00_run_functions.py
+++ b/bind/python/iguana_ex_python_00_run_functions.py
@@ -27,6 +27,7 @@
"REC::Calorimeter",
"REC::Track",
"REC::Scintillator"])
+b_particle = hipo.getBanklistIndex(banks, "REC::Particle")
seq = iguana.AlgorithmSequence('pyiguana')
seq.Add('clas12::EventBuilderFilter')
@@ -47,9 +48,9 @@ def prettyPrint(message, bank):
seq.Start(banks)
while(reader.next(banks) and (numEvents==0 or iEvent < numEvents)):
iEvent += 1
- prettyPrint("BEFORE", banks[1])
+ prettyPrint("BEFORE", banks[b_particle])
seq.Run(banks)
- prettyPrint("AFTER", banks[1])
+ prettyPrint("AFTER", banks[b_particle])
seq.Stop()
diff --git a/bind/python/iguana_ex_python_01_action_functions.py b/bind/python/iguana_ex_python_01_action_functions.py
index 34eebcda..25a816ef 100755
--- a/bind/python/iguana_ex_python_01_action_functions.py
+++ b/bind/python/iguana_ex_python_01_action_functions.py
@@ -27,6 +27,9 @@
reader = hipo.reader(inFile)
banks = reader.getBanks(["REC::Particle", "RUN::config"]);
+b_particle = hipo.getBanklistIndex(banks, "REC::Particle")
+b_config = hipo.getBanklistIndex(banks, "RUN::config")
+
algo_eventbuilder_filter = iguana.clas12.EventBuilderFilter()
algo_momentum_correction = iguana.clas12.MomentumCorrection()
@@ -41,8 +44,8 @@
while(reader.next(banks) and (numEvents==0 or iEvent < numEvents)):
iEvent += 1
- particleBank = banks[0]
- configBank = banks[1]
+ particleBank = banks[b_particle]
+ configBank = banks[b_config]
particleBank.show()
for row in particleBank.getRowList():
diff --git a/doc/configuration.md b/doc/configuration.md
deleted file mode 100644
index 9592ff69..00000000
--- a/doc/configuration.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# Configuring the Algorithms
-
-Most of the algorithms are configurable using a YAML configuration file. If you are using Iguana for your analysis, you likely want to customize the algorithm configurations.
-
-The default configuration is installed in the `etc/` subdirectory of the Iguana installation. If you have set the Iguana environment variables using, _e.g._ `source this_iguana.sh`, or if you are using the version of Iguana installed on `ifarm`, you will have the environment variable `$IGUANA_CONFIG_PATH` set to include this `etc/` directory.
-
-There are a few ways to configure the algorithms; see the sections below for the options
-
-> [!IMPORTANT]
-> While algorithm developers are encouraged _not_ to make breaking changes to their algorithms or configuration, in some cases certain changes cannot be prevented. Thus if you have your own algorithm configurations, you may want to keep up-to-date on any changes of the algorithm. We will try to announce all breaking changes in the Iguana release notes.
-
-> [!NOTE]
-> If the Iguana installation is relocated, the environment variable `$IGUANA_CONFIG_PATH` _must_ be used at runtime.
-
-## Option 1: Copy the default directory, and modify
-
-First, copy the default configuration directory to your work area, or to your analysis code source tree; we'll call the copied directory `my_iguana_config`, as an example. If `$IGUANA_CONFIG_PATH` is the default configuration directory (_i.e._ you have not set or modified this variable yourself), you may run:
-```bash
-cp -r $IGUANA_CONFIG_PATH my_iguana_config
-```
-
-You may then freely modify any configuration file within `my_iguana_config/`. To use this directory in your algorithms, you may do any one of the following:
-
-1. Since `$IGUANA_CONFIG_PATH` allows multiple paths, delimited by colons (`:`), prepend `my_iguana_config/` to `$IGUANA_CONFIG_PATH`; the safest way is to use an absolute path:
-```bash
-export IGUANA_CONFIG_PATH=`pwd`/my_iguana_config:$IGUANA_CONFIG_PATH # bash or zsh
-setenv IGUANA_CONFIG_PATH `pwd`/my_iguana_config:$IGUANA_CONFIG_PATH # tcsh or csh
-```
-The algorithms will then search `my_iguana_config` for the configuration before searching the default paths. You may add multiple paths, if needed.
-Paths which appear first in `$IGUANA_CONFIG_PATH` will be prioritized when the algorithm searches for configuration parameters; this behavior is similar to that of `$PATH` or `$LD_LIBRARY_PATH`.
-
-2. Use `Algorithm::SetConfigDirectory` instead of prepending `$IGUANA_CONFIG_PATH`.
-
-## Option 2: Write your own YAML file
-
-Make a new YAML file, containing just the options you want to override; use `Algorithm::SetConfigFile` to use this file for each algorithm.
-See existing algorithms' configuration, and just copy what you need into your own YAML file; be mindful of the indentation, and that the top-level set of YAML nodes are the algorithm names. For example:
-
-Algorithm default configuration files:
-```yaml
-### default configuration file 1
-physics::AlgorithmA
- cuts: [-1, 1]
-```
-```yaml
-### default configuration file 2
-physics::AlgorithmB
- value: 3
-```
-Custom YAML file, widening `AlgorithmA`'s `cuts` and increasing `AlgorithmB`'s `value`:
-```yaml
-### custom YAML file
-physics::AlgorithmA
- cuts: [-2, 2]
-
-physics::AlgorithmB
- value: 5
-```
diff --git a/doc/design.md b/doc/design.md
deleted file mode 100644
index 478feb62..00000000
--- a/doc/design.md
+++ /dev/null
@@ -1,142 +0,0 @@
-# Design
-
-## Graphs
-
-### Class Diagram
-
-```mermaid
-flowchart LR
- classDef cls fill:#88ff88,color:black
- classDef algo fill:#ff8888,color:black
- classDef other fill:#ff88ff,color:black
-
- subgraph services
- Logger:::cls
- Object:::cls
- end
-
- subgraph algorithms
- Algorithm:::cls
- FiducialCuts:::algo
- MomentumCorrection:::algo
- AlgorithmSequence:::algo
- bindings(language| Name | Type | Description |
|---|---|---|
| `\1` | `\2` | \3 |
-This documentation shows how to use the Iguana algorithms.
+This documentation shows how to use the Iguana algorithms. For more documentation, see the [**Documentation Front Page**](https://github.com/JeffersonLab/iguana/blob/main/README.md)
-For more documentation, see
-- [**Documentation Front Page**](https://github.com/JeffersonLab/iguana/blob/main/README.md)
+| Quick Links ||
+| --- | --- |
+| @spacer [List of Algorithms](#algo) @spacer | @spacer [Examples of Code](#secExample) @spacer |
+| @spacer [List of Action Functions](#action) @spacer | @spacer [Configuring Algorithms](#secConfiguring) @spacer |
-## Example Code in C++, Python, and Fortran
+| **Filter** | Remove rows of a bank based on some `bool` condition |
| **Transformer** | Transform (mutate) elements of a bank |
| **Creator** | Create a new bank |
+@anchor secCommon +### Common Functions -### Algorithm Common Functions: for HIPO C++ Users +All algorithms have the following **Common Functions**, which may be used in analysis code that uses [**the HIPO API**](https://github.com/gavalian/hipo). These functions act on `hipo::bank` objects, and are designed to be called at certain points in an analysis of HIPO data: -All algorithms have the following functions, which may be used in analysis code -that uses [**the HIPO C++ API**](https://github.com/gavalian/hipo); for -analysis code that does not, skip to the **Action Functions** section. +| Common Functions || +| --- | --- | +| `iguana::Algorithm::Start` | To be called before event processing | +| `iguana::Algorithm::Run` | To be called for every event | +| `iguana::Algorithm::Stop` | To be called after event processing | + +The algorithms are implemented in C++ classes which inherit from the base class `iguana::Algorithm`; these three class methods are overridden in each algorithm. + +The `iguana::Algorithm::Run` function should be called on every event; the general consequence, that is, how the user should handle the algorithm's results, depends on the +algorithm type:
| `iguana::Algorithm::Start` | Run before event processing |
| `iguana::Algorithm::Run` | Run for every event |
| `iguana::Algorithm::Stop` | Run after event processing |
| Type | How to handle the results |
|---|---|
| **Filter** | +The involved banks will be filtered. +To iterate over _filtered_ bank rows, use the function `hipo::bank::getRowList`, +rather than iterating from `0` up to `hipo::bank::getRows()`; for example, given a +bank object named `particle_bank`: +```cpp +for(auto const& row : particle_bank.getRowList()) { + // loops over only the rows which pass the filter +} +``` +```cpp +for(int row = 0; row < particle_bank.getRows(); row++) { + // loops over ALL rows, regardless of whether they pass the filter +} +``` + |
| **Transformer** | +The transformed `hipo::bank` will simply have +the relevant bank elements changed. For example, momentum correction algorithms +typically change the particle momentum components. + |
| **Creator** | +Creator-type algorithms will simply create a new `hipo::bank` object, appending +it to the end of the input `hipo::banklist`. An initial version is created upon calling +`iguana::Algorithm::Start`, so that you may begin to reference it; it is helpful to +use `hipo::getBanklistIndex` (see [the examples for details](#secExample)). + |
+@anchor secAction +### Action Functions The action functions do the _real_ work of the algorithm, and are meant to be easily callable from _any_ analysis, even if HIPO banks are not directly used. These functions are unique to each algorithm, so view the algorithm documentation for details, or browse the full list: -- \ref action "List of all Action Functions" - -The action functions have types that correspond to the algorithm types. -Furthermore, some action functions can only be useful if all of the rows of a -bank are included in its inputs, which motivates the following additional -classification: -
| **Scalar** | -All inputs and outputs are scalar quantities (single values). -This type of function may be used on a single bank row. - |
| **Vector** | -All inputs and outputs are vector quantities (lists of values). -This type of action function needs values from all of the bank rows. - |
| **Mixed** | -Inputs and outputs are scalar or vector quantities. - |
+ +
+@anchor secConfiguring +## How to Configure Algorithms + +Many algorithms are configurable. An algorithm's configuration parameters and their default values are found in the algorithm's documentation. + +Iguana provides a few ways to configure algorithms; in general, you may either: +- use YAML for configuration that gets applied at runtime, _i.e._, no need to recompile +- use `iguana::Algorithm::SetOption` to configure an algorithm more directly, which may require recompilation, depending on how you use Iguana algorithms + +The default configuration YAML files are installed in the `etc/` subdirectory of the Iguana installation. If you have set the Iguana environment variables using, _e.g._ `source this_iguana.sh`, or if you are using the version of Iguana installed on `ifarm`, you will have the environment variable `$IGUANA_CONFIG_PATH` set to include this `etc/` directory. + +There are a few ways to configure the algorithms with YAML; see the sections below for the options + +@important +While algorithm developers are encouraged _not_ to make breaking changes to their algorithms or configuration, in some cases certain changes cannot be prevented. Thus if you have your own algorithm configurations, keep up-to-date on any changes of the algorithm. We will try to announce all breaking changes in the Iguana release notes. + +### Option 1: Write your own YAML file + +Start your own YAML file by first copying the default YAML configurations from each algorithm that you want to use. See [algorithm documentation](#algo) or the `Config.yaml` files installed in `$IGUANA_CONFIG_PATH` for the algorithms' default YAML configurations. +- Be mindful of indentation in your YAML file + - The top level (no indentation) contains the algorithm names + - Under each algorithm name is its configuration (one indentation level) + - Further indentation levels or lists of configurations may be used within; see each algorithm's documentation for more information +- Note that _excluding_ a configuration option in your YAML file means that the default value will be used. + +For example, suppose you want to use algorithms which have the following YAML configurations: +```yaml +### default configuration file 1 +physics::AlgorithmA + cuts: [-1, 1] +``` +```yaml +### default configuration file 2 +physics::AlgorithmB + valueA: 3 + valueB: 0.14 + reptiles: + reptileA: gecko + reptileB: tuatara +``` +Custom YAML file, with some changes such as widening `AlgorithmA`'s `cuts`: +```yaml +### custom YAML file +physics::AlgorithmA + cuts: [-2, 2] + +physics::AlgorithmB + valueA: 5 + valueB: 0.14 + reptiles: + reptileA: alligator + reptileB: caiman +``` + +Once you have a YAML file, you just need to tell each algorithm to use it: +- use `iguana::Algorithm::SetConfigFile` on each algorithm +- if you use `iguana::AlgorithmSequence`, use `iguana::AlgorithmSequence::SetConfigFileForEachAlgorithm` to use this file for each algorithm in the algorithm sequence + +### Option 2: Copy the default directory, and modify + +First, copy the default configuration directory to your work area, or to your analysis source code; we'll call the copied directory `my_iguana_config`, as an example. If `$IGUANA_CONFIG_PATH` is the default configuration directory (_i.e._ you have not set or modified this variable yourself), you may run: +```bash +cp -rv $IGUANA_CONFIG_PATH my_iguana_config +``` + +You may then freely modify any configuration file within `my_iguana_config/`. + +To use this directory in your algorithms, you may do any one of the following: + +1. Since `$IGUANA_CONFIG_PATH` allows multiple paths, delimited by colons (`:`), prepend `my_iguana_config/` to `$IGUANA_CONFIG_PATH`; the safest way is to use an absolute path: +```bash +export IGUANA_CONFIG_PATH=`pwd`/my_iguana_config:$IGUANA_CONFIG_PATH # bash or zsh +setenv IGUANA_CONFIG_PATH `pwd`/my_iguana_config:$IGUANA_CONFIG_PATH # tcsh or csh +``` +The algorithms will then search `my_iguana_config` for the configuration before searching the default paths. You may add multiple paths, if needed. +Paths which appear first in `$IGUANA_CONFIG_PATH` will be prioritized when the algorithm searches for configuration parameters; this behavior is similar to that of `$PATH` or `$LD_LIBRARY_PATH`. + +2. Use `iguana::Algorithm::SetConfigDirectory` instead of prepending `$IGUANA_CONFIG_PATH` (and if you use an algorithm sequence, use `iguana::AlgorithmSequence::SetConfigDirectoryForEachAlgorithm`) diff --git a/examples/iguana_ex_cpp_00_run_functions.cc b/examples/iguana_ex_cpp_00_run_functions.cc index 8444bf43..6de33b85 100644 --- a/examples/iguana_ex_cpp_00_run_functions.cc +++ b/examples/iguana_ex_cpp_00_run_functions.cc @@ -37,20 +37,24 @@ int main(int argc, char** argv) // read input file hipo::reader reader(inFileName,{0}); - // set banks + // set list of banks to be read hipo::banklist banks = reader.getBanks({"RUN::config", "REC::Particle", "REC::Calorimeter", "REC::Track", "REC::Scintillator"}); - enum banks_enum { b_config, - b_particle }; // TODO: users shouldn't have to do this + + // get bank index, for each bank we want to use after Iguana algorithms run + auto b_particle = hipo::getBanklistIndex(banks, "REC::Particle"); // iguana algorithm sequence iguana::AlgorithmSequence seq; seq.Add("clas12::EventBuilderFilter"); // filter by Event Builder PID seq.Add("clas12::SectorFinder"); // get the sector for each particle seq.Add("clas12::MomentumCorrection"); // momentum corrections + // TODO: + // - getRowList for filter + // - add a creator algo // set log levels seq.SetOption("clas12::EventBuilderFilter", "log", "debug"); diff --git a/examples/iguana_ex_cpp_01_action_functions.cc b/examples/iguana_ex_cpp_01_action_functions.cc index 57e2094a..15f7959b 100644 --- a/examples/iguana_ex_cpp_01_action_functions.cc +++ b/examples/iguana_ex_cpp_01_action_functions.cc @@ -11,6 +11,10 @@ /// NUM_EVENTS the number of events to analyze; /// set to zero to analyze all events /// ``` +/// +/// @note while this example _does_ use `hipo::bank` objects to read HIPO data, it demonstrates +/// using action functions called with the data _from_ these banks. +/// /// @end_doc_example #include