feat!: Run function enhancements

.github/workflows/ci.yml

@@ -232,6 +232,9 @@ jobs:
       - name: test example iguana_ex_cpp_00_run_functions.cc
         run: stdbuf -o0 iguana_ex_cpp_00_run_functions test_data.hipo ${{ env.num_events }} | tee equivalence.00.cpp.txt
         if: ${{ matrix.id == 'cpp' || matrix.id == 'python' }}
+      - name: test example iguana_ex_cpp_00_run_functions_with_banks.cc
+        run: stdbuf -o0 iguana_ex_cpp_00_run_functions_with_banks test_data.hipo ${{ env.num_events }}
+        if: ${{ matrix.id == 'cpp' || matrix.id == 'python' }}
       - name: test example iguana_ex_cpp_01_action_functions.cc
         run: stdbuf -o0 iguana_ex_cpp_01_action_functions test_data.hipo ${{ env.num_events }} | tee equivalence.01.cpp.txt
         if: ${{ matrix.id == 'cpp' || matrix.id == 'python' }}

.gitignore

@@ -21,6 +21,7 @@ chameleon-tree
 # overrides
 !doc/gen/logo.png
 !doc/gen/logo_small.png
+!doc/gen/mermaid/*.png
 
 # misc. artifacts
 .DS_Store

bind/python/iguana_ex_python_00_run_functions.py

@@ -55,11 +55,14 @@
 # start the algorithms
 seq.Start(banks)
 
+# get the name of newly created banks (if you don't want to look them up in the documentation)
+sector_finder_bank_name = seq.GetCreatedBankName("clas12::SectorFinder");
+
 # get bank index, for each bank we want to use after Iguana algorithms run
 # NOTE: new banks from creator algorithms are initialized by `Start`
 b_config   = hipo.getBanklistIndex(banks, 'RUN::config')
 b_particle = hipo.getBanklistIndex(banks, 'REC::Particle')
-b_sector   = hipo.getBanklistIndex(banks, 'REC::Particle::Sector') # new created bank
+b_sector   = hipo.getBanklistIndex(banks, sector_finder_bank_name) # new created bank
 
 # run the algorithm sequence on each event
 iEvent = 0

doc/gen/Doxyfile.in

@@ -285,14 +285,18 @@ TAB_SIZE               = 4
 
 ALIASES =
 # algorithm properties
-ALIASES += brief_algo="@brief **%Algorithm:** "
-ALIASES += begin_doc_algo{2|}="\par %Algorithm Name:^^&emsp;&emsp;&emsp;`%\1`\xrefitem algo \"Algorithm Type:\" \"List of all Algorithms\" \2 \par %Algorithm Inputs and Outputs:^^<table>"
-ALIASES += input_banks{1}="<tr><td>**Input Banks**</td><td>`\1`</td></tr>"
-ALIASES += output_banks{1}="<tr><td>**Output Banks**</td><td>`\1`</td></tr>"
-ALIASES += end_doc="</table>"
+ALIASES += algo_brief{1}="@brief **%Algorithm:** \1^^@xrefitem algo \"\" \"List of Algorithms\" \1^^@link_to_run_ftn"
+ALIASES += algo_type_filter="@par Type: Filter^^This algorithm will filter input bank(s).^^"
+ALIASES += algo_type_transformer="@par Type: Transformer^^This algorithm will change values within input bank(s).^^"
+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.^^^^"
 # configuration options
 ALIASES += begin_doc_config{1}="\par Configuration Options:^^YAML configuration, which includes the default option values:^^@include \1/Config.yaml ^^Table of options and descriptions:^^<table><tr><th>Name</th><th>Type</th><th>Description</th></tr>"
 ALIASES += config_param{3|}="<tr><td>`\1`</td><td>`\2`</td><td>\3</td></tr>"
+ALIASES += end_doc="</table>^^"
+# run functions
+ALIASES += run_function="@brief **Run Function:** Process an event's `hipo::bank` objects^^^^The parameter list explains which banks are input (\"in\"), output (\"out\"), or both (\"in,out\").^^"
+ALIASES += link_to_run_ftn="@par Input and Output Banks:^^See @link ::Run `Run` function(s) for the banks @endlink that are processed by this algorithm.^^"
+ALIASES += run_function_returns_true="@returns `true`, _i.e._, this `%Run` function does not provide an event-level filter"
 # action functions
 ALIASES += action_function{1}="\xrefitem action \"Function Type\" \"List of all Action Functions\" \1 \brief **Action Function:** "
 ALIASES += when_to_call{1}="@note This function should be called **\1**"
@@ -307,7 +311,6 @@ ALIASES += doxygen_on="@endcond"
 ALIASES += latex{1}="@f$\1@f$"
 # misc
 ALIASES += spacer="&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"
-ALIASES += creator_note="This algorithm creates a new bank and its definition is found within the \link src/iguana/bankdefs/iguana.json **Iguana Bank Definitions JSON File** \endlink<ul><li>For guidance on how to read this JSON file, [see documentation on created banks](#mainpageCreatedBanks).</li><li>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.</li></ul>"
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For
@@ -713,7 +716,7 @@ SORT_MEMBER_DOCS       = YES
 # this will also influence the order of the classes in the class list.
 # The default value is: NO.
 
-SORT_BRIEF_DOCS        = NO
+SORT_BRIEF_DOCS        = YES
 
 # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
 # (brief and detailed) documentation of class members so that constructors and
@@ -732,7 +735,7 @@ SORT_MEMBERS_CTORS_1ST = NO
 # appear in their defined order.
 # The default value is: NO.
 
-SORT_GROUP_NAMES       = NO
+SORT_GROUP_NAMES       = YES
 
 # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
 # fully-qualified names, including namespaces. If set to NO, the class list will
@@ -970,6 +973,7 @@ WARN_LOGFILE           =
 INPUT                  = @top_srcdir@/src/ \
                          @top_builddir@/src/iguana/algorithms \
                          @top_builddir@/src/iguana/bankdefs \
+                         @top_builddir@/src/iguana/bankdefs/BankDefs.md \
                          @top_srcdir@/bind/ \
                          @top_srcdir@/doc/gen/ \
                          @top_srcdir@/doc/gen/mainpage.md \
@@ -1086,7 +1090,8 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = @top_srcdir@/doc/gen/logo.png
+IMAGE_PATH             = @top_srcdir@/doc/gen/logo.png \
+                         @top_srcdir@/doc/gen/mermaid/flowchart_usage.png
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -2545,7 +2550,7 @@ COLLABORATION_GRAPH    = NO
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-GROUP_GRAPHS           = YES
+GROUP_GRAPHS           = NO
 
 # If the UML_LOOK tag is set to YES, doxygen will generate inheritance and
 # collaboration diagrams in a style similar to the OMG's Unified Modeling