fix!: standardize config param names for Algorithm::SetOption

bind/python/iguana_ex_python_00_run_functions.py

@@ -42,15 +42,14 @@
 seq.Add('clas12::rga::MomentumCorrection') # momentum corrections (a transformer algorithm)
 # seq.PrintSequence()
 
-# set log levels
-# NOTE: this can also be done in a config file
-seq.SetOption('clas12::EventBuilderFilter', 'log', 'info')
-seq.SetOption('clas12::SectorFinder', 'log', 'info')
-seq.SetOption('clas12::rga::MomentumCorrection', 'log', 'info')
-
-# set algorithm options
-# NOTE: this can also be done in a config file, but setting options here OVERRIDES config file settings
-seq.SetOption('clas12::EventBuilderFilter', 'pids', [11, 211, -211])
+# configure algorithms with a custom YAML file
+# - in practice, specify the path(s) to your preferred configuration file(s); see documentation
+#   on 'How to Configure Algorithms' for details, and alternative methods for algorithm configuration
+# - in this example, the file is from the source-code path `./config/examples/`, which was copied to
+#   the installation subdirectory `etc/iguana/`, within the default configuration-file search path
+seq.SetConfigFileForEachAlgorithm("examples/config_for_examples.yaml")
+# alternatively: use this configuration for the algorithm that needs it
+# seq.Get("clas12::EventBuilderFilter").SetConfigFile("examples/config_for_examples.yaml")
 
 # start the algorithms
 seq.Start(banks)

bind/python/iguana_ex_python_01_action_functions.py

@@ -51,13 +51,15 @@
 algo_sector_finder       = iguana.clas12.SectorFinder() # get the sector for each particle (a creator algorithm)
 algo_momentum_correction = iguana.clas12.rga.MomentumCorrection() # momentum corrections (a transformer algorithm)
 
-# set log levels
-algo_eventbuilder_filter.SetOption('log', 'info')
-algo_sector_finder.SetOption('log', 'info')
-algo_momentum_correction.SetOption('log', 'info')
-
-# set algorithm options
-algo_eventbuilder_filter.SetOption('pids',  [11, 211, -211])
+# configure algorithms with a custom YAML file
+# - in practice, specify the path(s) to your preferred configuration file(s); see documentation
+#   on 'How to Configure Algorithms' for details, and alternative methods for algorithm configuration
+# - in this example, the file is from the source-code path `./config/examples/`, which was copied to
+#   the installation subdirectory `etc/iguana/`, within the default configuration-file search path
+config_file = "examples/config_for_examples.yaml"
+algo_eventbuilder_filter.SetConfigFile(config_file)
+algo_sector_finder.SetConfigFile(config_file)
+algo_momentum_correction.SetConfigFile(config_file)
 
 # start the algorithms
 algo_eventbuilder_filter.Start()

bind/python/iguana_ex_python_hipopy.py

@@ -44,13 +44,11 @@
 algo_sector_finder       = iguana.clas12.SectorFinder() # get the sector for each particle (a creator algorithm)
 algo_momentum_correction = iguana.clas12.rga.MomentumCorrection() # momentum corrections (a transformer algorithm)
 
-# set log levels
-algo_eventbuilder_filter.SetOption('log',   'info')
-algo_sector_finder.SetOption('log', 'info')
-algo_momentum_correction.SetOption('log',   'info')
-
-# set algorithm options
-algo_eventbuilder_filter.SetOption('pids',  [11, 211, -211])
+# configure algorithms with a custom YAML file
+config_file = "examples/config_for_examples.yaml"
+algo_eventbuilder_filter.SetConfigFile(config_file)
+algo_sector_finder.SetConfigFile(config_file)
+algo_momentum_correction.SetConfigFile(config_file)
 
 # start the algorithms
 algo_eventbuilder_filter.Start()

doc/doxygen/mainpage.md

@@ -5,11 +5,12 @@ This documentation shows how to use the Iguana algorithms. For more documentatio
 
 - **Tip:** To toggle between light and dark mode for this webpage, click the button in the top-right corner, next to the search box.
 
-| Quick Links ||
-| --- | --- |
-| @spacer [List of All Algorithms](#algo) @spacer | @spacer [List of Algorithms Organized by Run Group, <i>etc</i>.](#algo_namespaces) @spacer |
-| @spacer [List of Action Functions](#action) @spacer | @spacer [Configuring Algorithms](#mainpageConfiguring) @spacer |
-| @spacer [Banks Created by Iguana](#created_banks) @spacer | @spacer [Examples of Code](#mainpageExample) @spacer |
+| Quick Links                                               |                                                                                            |
+| ---                                                       | ---                                                                                        |
+| @spacer [List of All Algorithms](#algo) @spacer           | @spacer [List of Algorithms Organized by Run Group, <i>etc</i>.](#algo_namespaces) @spacer |
+| @spacer [List of Action Functions](#action) @spacer       | @spacer [How to Configure Algorithms](#mainpageConfiguring) @spacer                        |
+| @spacer [Banks Created by Iguana](#created_banks) @spacer | @spacer [How to Run Algorithms](#mainpageRunning) @spacer                                  |
+|                                                           | @spacer [Examples of Code](#mainpageExample) @spacer                                       |
 
 <br><hr>
 
@@ -243,7 +244,11 @@ Many algorithms are configurable. An algorithm's configuration parameters and th
 
 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 @link iguana::Algorithm::SetOption @endlink to configure an algorithm more directly, which may require recompilation, depending on how you use Iguana algorithms
+    - this is the preferred method for configuration
+- use @link iguana::Algorithm::SetOption @endlink to configure an algorithm more directly, however:
+    - this may require recompilation, depending on how you use Iguana algorithms
+    - some options cannot be set this way, in particular, options that depend on data, such as a run number-dependent vertex cut
+    - using the YAML file is preferred in general (whereas @link iguana::Algorithm::SetOption @endlink is useful for algorithm Validators)
 
 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.
 
@@ -276,13 +281,15 @@ physics::AlgorithmB
     reptileA: gecko
     reptileB: tuatara
 ```
-Custom YAML file, with some changes such as widening `AlgorithmA`'s `cuts`:
+Custom YAML file, with some changes such as widening `AlgorithmA`'s `cuts`, and controlling the log levels:
 ```yaml
 ### custom YAML file
 physics::AlgorithmA
+  log: info # set the log level for this algorithm
   cuts: [-2, 2]
 
 physics::AlgorithmB
+  log: debug # set the log level for this algorithm
   valueA: 5
   valueB: 0.14
   reptiles:

examples/config/examples/config_for_examples.yaml

@@ -0,0 +1,9 @@
+clas12::EventBuilderFilter:
+  log: info # set the log level
+  pids: [ 11, 211, -211, 22 ] # customize the list of PDGs to filter for
+
+clas12::SectorFinder:
+  log: info
+
+clas12::rga::MomentumCorrection:
+  log: info

examples/iguana_ex_cpp_00_run_functions.cc

@@ -47,15 +47,14 @@ int main(int argc, char** argv)
   seq.Add("clas12::rga::MomentumCorrection"); // momentum corrections (a transformer algorithm)
   // seq.PrintSequence();
 
-  // set log levels
-  // NOTE: this can also be done in a config file
-  seq.SetOption("clas12::EventBuilderFilter", "log", "info");
-  seq.SetOption("clas12::SectorFinder", "log", "info");
-  seq.SetOption("clas12::rga::MomentumCorrection", "log", "info");
-
-  // set algorithm options
-  // NOTE: this can also be done in a config file, but setting options here OVERRIDES config file settings
-  seq.SetOption<std::vector<int>>("clas12::EventBuilderFilter", "pids", {11, 211, -211});
+  // configure algorithms with a custom YAML file
+  // - in practice, specify the path(s) to your preferred configuration file(s); see documentation
+  //   on 'How to Configure Algorithms' for details, and alternative methods for algorithm configuration
+  // - in this example, the file is from the source-code path `./config/examples/`, which was copied to
+  //   the installation subdirectory `etc/iguana/`, within the default configuration-file search path
+  seq.SetConfigFileForEachAlgorithm("examples/config_for_examples.yaml");
+  // alternatively: use this configuration for the algorithm that needs it
+  // seq.Get("clas12::EventBuilderFilter")->SetConfigFile("examples/config_for_examples.yaml");
 
   // start the algorithms
   seq.Start(banks);

examples/iguana_ex_cpp_00_run_functions_with_banks.cc

@@ -51,15 +51,15 @@ int main(int argc, char** argv)
   iguana::clas12::SectorFinder algo_sector_finder; // get the sector for each particle (a creator algorithm)
   iguana::clas12::rga::MomentumCorrection algo_momentum_correction; // momentum corrections (a transformer algorithm)
 
-  // set log levels
-  // NOTE: this can also be done in a config file
-  algo_eventbuilder_filter.SetOption("log", "info");
-  algo_sector_finder.SetOption("log", "info");
-  algo_momentum_correction.SetOption("log", "info");
-
-  // set algorithm options
-  // NOTE: this can also be done in a config file, but setting options here OVERRIDES config file settings
-  algo_eventbuilder_filter.SetOption<std::vector<int>>("pids", {11, 211, -211});
+  // configure algorithms with a custom YAML file
+  // - in practice, specify the path(s) to your preferred configuration file(s); see documentation
+  //   on 'How to Configure Algorithms' for details, and alternative methods for algorithm configuration
+  // - in this example, the file is from the source-code path `./config/examples/`, which was copied to
+  //   the installation subdirectory `etc/iguana/`, within the default configuration-file search path
+  std::string config_file = "examples/config_for_examples.yaml";
+  algo_eventbuilder_filter.SetConfigFile(config_file);
+  algo_sector_finder.SetConfigFile(config_file);
+  algo_momentum_correction.SetConfigFile(config_file);
 
   // start the algorithms
   algo_eventbuilder_filter.Start();

examples/iguana_ex_cpp_01_action_functions.cc

@@ -57,14 +57,15 @@ int main(int argc, char** argv)
   iguana::clas12::SectorFinder algo_sector_finder; // get the sector for each particle (a creator algorithm)
   iguana::clas12::rga::MomentumCorrection algo_momentum_correction; // momentum corrections (a transformer algorithm)
 
-  // set log levels
-  algo_eventbuilder_filter.SetOption("log", "info");
-  algo_sector_finder.SetOption("log", "info");
-  algo_momentum_correction.SetOption("log", "info");
-
-  // set algorithm options
-  // NOTE: this can also be done in a config file
-  algo_eventbuilder_filter.SetOption<std::vector<int>>("pids", {11, 211, -211});
+  // configure algorithms with a custom YAML file
+  // - in practice, specify the path(s) to your preferred configuration file(s); see documentation
+  //   on 'How to Configure Algorithms' for details, and alternative methods for algorithm configuration
+  // - in this example, the file is from the source-code path `./config/examples/`, which was copied to
+  //   the installation subdirectory `etc/iguana/`, within the default configuration-file search path
+  std::string config_file = "examples/config_for_examples.yaml";
+  algo_eventbuilder_filter.SetConfigFile(config_file);
+  algo_sector_finder.SetConfigFile(config_file);
+  algo_momentum_correction.SetConfigFile(config_file);
 
   // start the algorithms
   algo_eventbuilder_filter.Start();

examples/iguana_ex_cpp_dataframes.cc

@@ -33,7 +33,7 @@ int main(int argc, char** argv)
 
   // iguana algorithms
   iguana::clas12::EventBuilderFilter algo_eventbuilder_filter;
-  algo_eventbuilder_filter.SetOption<std::vector<int>>("pids", {11, 211, -211});
+  algo_eventbuilder_filter.SetConfigFile("examples/config_for_examples.yaml");
   algo_eventbuilder_filter.Start();
 
   // enable interactive mode

examples/meson.build

@@ -1,6 +1,6 @@
 # install config files
 example_config_files_prefix = project_etcdir / 'examples'
-install_subdir('config', install_dir: example_config_files_prefix, strip_directory: true)
+install_subdir('config' / 'examples', install_dir: example_config_files_prefix, strip_directory: true)
 
 # example source information
 example_sources = {

src/iguana/algorithms/Algorithm.cc

@@ -31,58 +31,60 @@ namespace iguana {
   ///////////////////////////////////////////////////////////////////////////////
 
   template <typename OPTION_TYPE>
-  OPTION_TYPE Algorithm::GetOptionScalar(std::string const& key, YAMLReader::node_path_t node_path) const
+  OPTION_TYPE Algorithm::GetOptionScalar(YAMLReader::node_path_t node_path) const
   {
-    CompleteOptionNodePath(key, node_path);
+    auto key = YAMLReader::NodePath2String(node_path);
     auto opt = GetCachedOption<OPTION_TYPE>(key);
+    node_path.push_front(m_class_name);
     if(!opt.has_value()) {
       opt = m_yaml_config->GetScalar<OPTION_TYPE>(node_path);
     }
     if(!opt.has_value()) {
-      m_log->Error("Failed to `GetOptionScalar` for key {:?}", key);
+      m_log->Error("Failed to `GetOptionScalar` for parameter {:?}", key);
       throw std::runtime_error("config file parsing issue");
     }
     PrintOptionValue(key, opt.value());
     return opt.value();
   }
-  template int Algorithm::GetOptionScalar(std::string const& key, YAMLReader::node_path_t node_path) const;
-  template double Algorithm::GetOptionScalar(std::string const& key, YAMLReader::node_path_t node_path) const;
-  template std::string Algorithm::GetOptionScalar(std::string const& key, YAMLReader::node_path_t node_path) const;
+  template int Algorithm::GetOptionScalar(YAMLReader::node_path_t node_path) const;
+  template double Algorithm::GetOptionScalar(YAMLReader::node_path_t node_path) const;
+  template std::string Algorithm::GetOptionScalar(YAMLReader::node_path_t node_path) const;
 
   ///////////////////////////////////////////////////////////////////////////////
 
   template <typename OPTION_TYPE>
-  std::vector<OPTION_TYPE> Algorithm::GetOptionVector(std::string const& key, YAMLReader::node_path_t node_path) const
+  std::vector<OPTION_TYPE> Algorithm::GetOptionVector(YAMLReader::node_path_t node_path) const
   {
-    CompleteOptionNodePath(key, node_path);
+    auto key = YAMLReader::NodePath2String(node_path);
     auto opt = GetCachedOption<std::vector<OPTION_TYPE>>(key);
+    node_path.push_front(m_class_name);
     if(!opt.has_value()) {
       opt = m_yaml_config->GetVector<OPTION_TYPE>(node_path);
     }
     if(!opt.has_value()) {
-      m_log->Error("Failed to `GetOptionVector` for key {:?}", key);
+      m_log->Error("Failed to `GetOptionVector` for parameter {:?}", key);
       throw std::runtime_error("config file parsing issue");
     }
     PrintOptionValue(key, opt.value());
     return opt.value();
   }
-  template std::vector<int> Algorithm::GetOptionVector(std::string const& key, YAMLReader::node_path_t node_path) const;
-  template std::vector<double> Algorithm::GetOptionVector(std::string const& key, YAMLReader::node_path_t node_path) const;
-  template std::vector<std::string> Algorithm::GetOptionVector(std::string const& key, YAMLReader::node_path_t node_path) const;
+  template std::vector<int> Algorithm::GetOptionVector(YAMLReader::node_path_t node_path) const;
+  template std::vector<double> Algorithm::GetOptionVector(YAMLReader::node_path_t node_path) const;
+  template std::vector<std::string> Algorithm::GetOptionVector(YAMLReader::node_path_t node_path) const;
 
   ///////////////////////////////////////////////////////////////////////////////
 
   template <typename OPTION_TYPE>
-  std::set<OPTION_TYPE> Algorithm::GetOptionSet(std::string const& key, YAMLReader::node_path_t node_path) const
+  std::set<OPTION_TYPE> Algorithm::GetOptionSet(YAMLReader::node_path_t node_path) const
   {
-    auto val_vec = GetOptionVector<OPTION_TYPE>(key, node_path);
+    auto val_vec = GetOptionVector<OPTION_TYPE>(node_path);
     std::set<OPTION_TYPE> val_set;
     std::copy(val_vec.begin(), val_vec.end(), std::inserter(val_set, val_set.end()));
     return val_set;
   }
-  template std::set<int> Algorithm::GetOptionSet(std::string const& key, YAMLReader::node_path_t node_path) const;
-  template std::set<double> Algorithm::GetOptionSet(std::string const& key, YAMLReader::node_path_t node_path) const;
-  template std::set<std::string> Algorithm::GetOptionSet(std::string const& key, YAMLReader::node_path_t node_path) const;
+  template std::set<int> Algorithm::GetOptionSet(YAMLReader::node_path_t node_path) const;
+  template std::set<double> Algorithm::GetOptionSet(YAMLReader::node_path_t node_path) const;
+  template std::set<std::string> Algorithm::GetOptionSet(YAMLReader::node_path_t node_path) const;
 
   ///////////////////////////////////////////////////////////////////////////////
 
@@ -430,12 +432,4 @@ namespace iguana {
     throw std::runtime_error("algorithm has been renamed");
   }
 
-  ///////////////////////////////////////////////////////////////////////////////
-
-  void Algorithm::CompleteOptionNodePath(std::string const& key, YAMLReader::node_path_t& node_path) const
-  {
-    if(node_path.empty())
-      node_path.push_front(key);
-    node_path.push_front(m_class_name);
-  }
 }