You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 11, 2026. It is now read-only.
ALIASES += algo_type_filter="@par Type: Filter^^This algorithm will filter input bank(s).^^"
290
290
ALIASES += algo_type_transformer="@par Type: Transformer^^This algorithm will change values within input bank(s).^^"
291
291
ALIASES += algo_type_creator="@par Type: Creator^^^^- This algorithm creates new bank(s); \ref created_banks \"click here for a description of all created banks\".^^- See also the return value type of this algorithm's action functions, which may be `struct`s with the same set of variables as the created bank.^^^^"
@@ -2550,7 +2550,7 @@ COLLABORATION_GRAPH = NO
2550
2550
# The default value is: YES.
2551
2551
# This tag requires that the tag HAVE_DOT is set to YES.
2552
2552
2553
-
GROUP_GRAPHS = YES
2553
+
GROUP_GRAPHS = NO
2554
2554
2555
2555
# If the UML_LOOK tag is set to YES, doxygen will generate inheritance and
2556
2556
# collaboration diagrams in a style similar to the OMG's Unified Modeling
5. In the event loop, Run the algorithm for each event:
47
50
- if using Common Functions, either:
48
-
- call specialized `Run` functions, which act on individual `hipo::bank` objects, or
49
-
- call `Run(hipo::banklist&)` if you use `hipo::banklist`
50
-
- call the Action Function(s) otherwise
51
+
- call specialized `Run` functions, which act on individual `hipo::bank` objects and are unique for each algorithm; users of `clas12root` versions _newer_ than `1.8.6` should use this
52
+
- call @link iguana::Algorithm::Run(hipo::banklist&) const `Run(hipo::banklist&)`@endlink if you use `hipo::banklist`
53
+
- call the [Action Function(s)](#action) otherwise
51
54
6. Proceed with your analysis
52
55
- if you called a `Run` function, banks will be filtered, transformed, and/or created
53
56
- if you called Action Functions, you will need to handle their output yourself
54
57
- in either case, see [guidance on how to run algorithms](#mainpageRunning) for more details
55
-
7. After your event loop, stop each algorithm by calling `Stop()`
58
+
7. After your event loop, stop each algorithm by calling @link iguana::Algorithm::Stop() `Stop()`@endlink
56
59
57
60
Please let the maintainers know if your use case is not covered in any examples or if you need any help.
58
61
62
+
@anchor mainpageFlowchart
63
+
### Flowchart for Usage
64
+
59
65
Here is a flowchart, illustrating the above:
60
66
61
-
<imgsrc="./flowchart_usage.png"width=100%/>
67
+
<imgsrc="./flowchart_usage.png"width=60%/>
62
68
63
69
<br><hr>
64
70
@@ -70,9 +76,9 @@ An Iguana algorithm is a function that maps input HIPO bank data to output data.
70
76
71
77
| Type | Description | Example |
72
78
| --- | --- | --- |
73
-
|**Filter**| Filters rows of a bank based on a Boolean condition |`iguana::clas12::FiducialFilter`: filter particles with fiducial cuts |
74
-
|**Transformer**| Transform (mutate) elements of a bank |`iguana::clas12::MomentumCorrection`: correct particle momenta |
75
-
|**Creator**| Create a new bank |`iguana::physics::InclusiveKinematics`: calculate inclusive kinematics @latex{x}, @latex{Q^2}, _etc_. |
79
+
|**Filter**| Filters rows of a bank based on a Boolean condition |@linkiguana::clas12::FiducialFilter@endlink: filter particles with fiducial cuts |
80
+
|**Transformer**| Transform (mutate) elements of a bank |@linkiguana::clas12::MomentumCorrection@endlink: correct particle momenta |
81
+
|**Creator**| Create a new bank |@linkiguana::physics::InclusiveKinematics@endlink: calculate inclusive kinematics @latex{x}, @latex{Q^2}, _etc_. |
76
82
77
83
The available algorithms are:
78
84
@@ -85,7 +91,7 @@ The available algorithms are:
85
91
@anchor mainpageRunning
86
92
## How to Run Algorithms
87
93
88
-
Algorithms may be run using either:
94
+
Algorithms may be run using one of the following; see [the usage flowchart](#mainpageFlowchart) for help deciding what to do.
89
95
90
96
-[Common Functions](#mainpageCommon): for users of the [**the HIPO API**](https://github.com/gavalian/hipo), which is likely the case if you are using C++, _e.g._, via `clas12root`
91
97
-[Action Functions](#mainpageAction): for all other users
@@ -102,22 +108,30 @@ All algorithms have the following **Common Functions**, which may be used in ana
102
108
103
109
| Common Functions ||
104
110
| --- | --- |
105
-
|`Start(hipo::banklist&)`| To be called before event processing |
106
-
|`Run(hipo::banklist&)`| To be called for every event |
107
-
|`Stop()`| To be called after event processing |
108
-
109
-
The algorithms are implemented in C++ classes which inherit from the base class `iguana::Algorithm`; these three class methods are overridden in each algorithm.
110
-
111
-
The `Run(hipo::banklist&)` function should be called on every event; the general consequence, that is, how the user should handle the algorithm's results, depends on the
111
+
|`Start`| To be called before event processing |
112
+
|`Run`| To be called for every event |
113
+
|`Stop`| To be called after event processing |
114
+
115
+
- for `Start`:
116
+
- call @link iguana::Algorithm::Start() `Start()`@endlink if you will be using individual `hipo::bank` objects (_e.g._, if you are using `clas12root`)
117
+
- call @link iguana::Algorithm::Start(hipo::banklist&) `Start(hipo::banklist&)`@endlink if you use `hipo::banklist`
118
+
-**Tip:**`hipo::banklist` users may use @link iguana::AlgorithmSequence `AlgorithmSequence`@endlink to help run a _sequence_ of algorithms
119
+
- for `Run`:
120
+
- call specialized `Run` functions, which act on individual `hipo::bank` objects and are unique for each algorithm; users of `clas12root` versions _newer_ than `1.8.6` should use this
121
+
- call @link iguana::Algorithm::Run(hipo::banklist&) const `Run(hipo::banklist&)`@endlink if you use `hipo::banklist`
122
+
- the `Stop` function is the same for either case
123
+
124
+
The `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
112
125
algorithm type:
113
126
114
127
<table>
115
128
<tr> <th>Type</th> <th>How to handle the results</th> </tr>
116
129
<tr> <td>**Filter**</td> <td>
117
-
The involved banks will be filtered.
118
-
To iterate over _filtered_ bank rows, use the function `hipo::bank::getRowList`,
119
-
rather than iterating from `0` up to `hipo::bank::getRows()`; for example, given a
120
-
bank object named `particle_bank`:
130
+
The involved banks will be filtered. To iterate over _filtered_ bank rows, use
131
+
the function `hipo::bank::getRowList`, rather than iterating from `0` up to
132
+
`hipo::bank::getRows()`.
133
+
<br>
134
+
For example, given a bank object named `particle_bank`:
the relevant bank elements changed. For example, momentum correction algorithms
135
-
typically change the particle momentum components.
147
+
The transformed `hipo::bank` will simply have the relevant bank elements changed.
148
+
<br>
149
+
For example, momentum correction algorithms typically change the particle momentum components.
136
150
</td> </tr>
137
151
<tr> <td>**Creator**</td> <td>
138
-
Creator-type algorithms will simply create a new `hipo::bank` object, appending
152
+
Creator-type algorithms will create a new `hipo::bank` object, appending
139
153
it to the end of the input `hipo::banklist`.
140
154
<ul>
141
155
<li>[Click here for descriptions of all created banks](#created_banks)</li>
@@ -154,6 +168,8 @@ Internally, `Run(hipo::banklist&)` calls Action Functions, which are described i
154
168
@anchor mainpageAction
155
169
### Action Functions
156
170
171
+
@todo**Unfortunately, some algorithms are not yet fully supported by action functions, but we can try to add support upon request.**
172
+
157
173
The action functions do the _real_ work of the algorithm, and are meant to be
158
174
easily callable from _any_ analysis, even if HIPO banks are not directly used.
159
175
These functions are unique to each algorithm, so view the algorithm
@@ -191,8 +207,8 @@ To maximize compatibility with user analysis code, these functions are overloade
191
207
Finally, it is important to note _when_ to call action functions in the analysis code. For example, some action functions should be
192
208
called _once_ every event, while others should be called for every particle of the `REC::Particle` bank. Some algorithms
193
209
have _both_ of these types of functions, for example:
194
-
-`iguana::clas12::ZVertexFilter::PrepareEvent`, which must be called first, at the beginning of an event's analysis
195
-
-`iguana::clas12::ZVertexFilter::Filter`, which must be called on every particle, using the _output_ of `PrepareEvent` in one of its input parameters
210
+
-@linkiguana::clas12::ZVertexFilter::PrepareEvent@endlink, which must be called first, at the beginning of an event's analysis
211
+
-@linkiguana::clas12::ZVertexFilter::Filter@endlink, which must be called on every particle, using the _output_ of `PrepareEvent` in one of its input parameters
196
212
197
213
It is highly recommended to read an algorithm's documentation carefully before using it, _especially_ if you use action functions.
198
214
@@ -209,7 +225,7 @@ Many algorithms are configurable. An algorithm's configuration parameters and th
209
225
210
226
Iguana provides a few ways to configure algorithms; in general, you may either:
211
227
- use YAML for configuration that gets applied at runtime, _i.e._, no need to recompile
212
-
- use `iguana::Algorithm::SetOption` to configure an algorithm more directly, which may require recompilation, depending on how you use Iguana algorithms
228
+
- use @linkiguana::Algorithm::SetOption@endlink to configure an algorithm more directly, which may require recompilation, depending on how you use Iguana algorithms
213
229
214
230
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.
215
231
@@ -257,8 +273,8 @@ physics::AlgorithmB
257
273
```
258
274
259
275
Once you have a YAML file, you just need to tell each algorithm to use it:
260
-
- use `iguana::Algorithm::SetConfigFile` on each algorithm
261
-
- if you use `iguana::AlgorithmSequence`, use `iguana::AlgorithmSequence::SetConfigFileForEachAlgorithm` to use this file for each algorithm in the algorithm sequence
276
+
- use @link iguana::Algorithm::SetConfigFile @endlink on each algorithm
277
+
- if you use @link iguana::AlgorithmSequence @endlink, use @link iguana::AlgorithmSequence::SetConfigFileForEachAlgorithm @endlink to use this file for each algorithm in the algorithm sequence
262
278
263
279
### Option 2: Copy the default directory, and modify
264
280
@@ -279,4 +295,4 @@ setenv IGUANA_CONFIG_PATH `pwd`/my_iguana_config:$IGUANA_CONFIG_PATH # tcsh or
279
295
The algorithms will then search `my_iguana_config` for the configuration before searching the default paths. You may add multiple paths, if needed.
280
296
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`. Note that `source this_iguana.sh` will _overwrite_`$IGUANA_CONFIG_PATH`.
281
297
282
-
2. Use `iguana::Algorithm::SetConfigDirectory`instead of prepending `$IGUANA_CONFIG_PATH` (and if you use an algorithm sequence, use `iguana::AlgorithmSequence::SetConfigDirectoryForEachAlgorithm`)
298
+
2. Use @linkiguana::Algorithm::SetConfigDirectory@endlinkinstead of prepending `$IGUANA_CONFIG_PATH` (and if you use an algorithm sequence, use @linkiguana::AlgorithmSequence::SetConfigDirectoryForEachAlgorithm@endlink)
0 commit comments