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

bind/python/iguana_ex_python_00_run_functions.py

@@ -42,15 +42,16 @@
 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 you can put your config file(s) where you want
+# - for this example, we use a YAML file installed alongside iguana (copied from `./config/config.yaml`)
+config_file = iguana.ConfigFileReader.GetConfigInstallationPrefix() + '/examples/config.yaml'
+# print the file name (so you can open it to see)
+print(f'CONFIG FILE: {config_file}')
+# use this configuration for all algorithms in the sequence
+seq.SetConfigFileForEachAlgorithm(config_file)
+# alternatively: use this configuration for the algorithm that needs it
+# seq.Get("clas12::EventBuilderFilter").SetConfigFile(config_file)
 
 # start the algorithms
 seq.Start(banks)

bind/python/iguana_ex_python_01_action_functions.py

@@ -51,13 +51,16 @@
 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 you can put your config file(s) where you want
+# - for this example, we use a YAML file installed alongside iguana (copied from `./config/config.yaml`)
+config_file = iguana.ConfigFileReader.GetConfigInstallationPrefix() + '/examples/config.yaml'
+# print the file name (so you can open it to see)
+print(f'CONFIG FILE: {config_file}')
+# use this configuration for each algorithm
+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 = iguana.ConfigFileReader.GetConfigInstallationPrefix() + '/examples/config.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

@@ -243,7 +243,10 @@ 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
+- 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
 
 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.
 

examples/config/config.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,16 @@ 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 you can put your config file(s) where you want
+  // - for this example, we use a YAML file installed alongside iguana (copied from `./config/config.yaml`)
+  auto config_file = iguana::ConfigFileReader::GetConfigInstallationPrefix() + "/examples/config.yaml";
+  // print the file name (so you can open it to see)
+  fmt::println("CONFIG FILE: {}", config_file);
+  // use this configuration for all algorithms in the sequence
+  seq.SetConfigFileForEachAlgorithm(config_file);
+  // alternatively: use this configuration for the algorithm that needs it
+  // seq.Get("clas12::EventBuilderFilter")->SetConfigFile(config_file);
 
   // start the algorithms
   seq.Start(banks);

examples/iguana_ex_cpp_00_run_functions_with_banks.cc

@@ -50,16 +50,17 @@ int main(int argc, char** argv)
   iguana::clas12::EventBuilderFilter algo_eventbuilder_filter; // filter by Event Builder PID (a filter algorithm)
   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 you can put your config file(s) where you want
+  // - for this example, we use a YAML file installed alongside iguana (copied from `./config/config.yaml`)
+  auto config_file = iguana::ConfigFileReader::GetConfigInstallationPrefix() + "/examples/config.yaml";
+  // print the file name (so you can open it to see)
+  fmt::println("CONFIG FILE: {}", config_file);
+  // use this configuration for each algorithm
+  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,16 @@ 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 you can put your config file(s) where you want
+  // - for this example, we use a YAML file installed alongside iguana (copied from `./config/config.yaml`)
+  auto config_file = iguana::ConfigFileReader::GetConfigInstallationPrefix() + "/examples/config.yaml";
+  // print the file name (so you can open it to see)
+  fmt::println("CONFIG FILE: {}", config_file);
+  // use this configuration for each algorithm
+  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,8 @@ 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});
+  auto config_file = iguana::ConfigFileReader::GetConfigInstallationPrefix() + "/examples/config.yaml";
+  algo_eventbuilder_filter.SetConfigFile(config_file);
   algo_eventbuilder_filter.Start();
 
   // enable interactive mode

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);
-  }
 }

src/iguana/algorithms/Algorithm.h

@@ -8,6 +8,7 @@
 
 #include "AlgorithmBoilerplate.h"
 #include "iguana/bankdefs/BankDefs.h"
+#include "iguana/services/Deprecated.h"
 #include "iguana/services/RCDBReader.h"
 #include "iguana/services/YAMLReader.h"
 #include <iguana/services/GlobalParam.h>
@@ -119,30 +120,30 @@ namespace iguana {
           else
             m_log->Error("Option '{}' must be a string or a Logger::Level", key);
         }
+        // make sure the key hasn't been renamed or deprecated
+        iguana::deprecated::CheckSetOptionKey(m_class_name, key);
+        // add it to the cache
         m_option_cache[key] = val;
         return val;
       }
 
       /// Get the value of a scalar option
-      /// @param key the unique key name of this option, for caching; if empty, the option will not be cached
-      /// @param node_path the `YAML::Node` identifier path to search for this option in the config files; if empty, it will just use `key`
+      /// @param node_path the `YAML::Node` identifier path to search for this option in the config files
       /// @returns the scalar option
       template <typename OPTION_TYPE>
-      OPTION_TYPE GetOptionScalar(std::string const& key, YAMLReader::node_path_t node_path = {}) const;
+      OPTION_TYPE GetOptionScalar(YAMLReader::node_path_t node_path = {}) const;
 
       /// Get the value of a vector option
-      /// @param key the unique key name of this option, for caching; if empty, the option will not be cached
-      /// @param node_path the `YAML::Node` identifier path to search for this option in the config files; if empty, it will just use `key`
+      /// @param node_path the `YAML::Node` identifier path to search for this option in the config files
       /// @returns the vector option
       template <typename OPTION_TYPE>
-      std::vector<OPTION_TYPE> GetOptionVector(std::string const& key, YAMLReader::node_path_t node_path = {}) const;
+      std::vector<OPTION_TYPE> GetOptionVector(YAMLReader::node_path_t node_path = {}) const;
 
       /// Get the value of a vector option, and convert it to `std::set`
-      /// @param key the unique key name of this option
-      /// @param node_path the `YAML::Node` identifier path to search for this option in the config files; if empty, it will just use `key`
+      /// @param node_path the `YAML::Node` identifier path to search for this option in the config files
       /// @returns the vector option converted to `std::set`
       template <typename OPTION_TYPE>
-      std::set<OPTION_TYPE> GetOptionSet(std::string const& key, YAMLReader::node_path_t node_path = {}) const;
+      std::set<OPTION_TYPE> GetOptionSet(YAMLReader::node_path_t node_path = {}) const;
 
       /// Set the name of this algorithm
       /// @param name the new name
@@ -248,12 +249,6 @@ namespace iguana {
       /// @param level the log level
       void ShowBank(hipo::bank const& bank, std::string_view message = "", Logger::Level const level = Logger::trace) const;
 
-      /// Get an option from the option cache
-      /// @param key the key name associated with this option
-      /// @returns the option value, if found (using `std::optional`)
-      template <typename OPTION_TYPE>
-      std::optional<OPTION_TYPE> GetCachedOption(std::string const& key) const;
-
       /// Throw a runtime exception since this algorithm has been renamed.
       /// Guidance will be printed for the user.
       /// @param new_name the new name of the algorithm
@@ -262,10 +257,11 @@ namespace iguana {
 
     private: // methods
 
-      /// Prepend `node_path` with the full algorithm name. If `node_path` is empty, set it to `{key}`.
-      /// @param key the key name for this option
-      /// @param node_path the `YAMLReader::node_path_t` to prepend
-      void CompleteOptionNodePath(std::string const& key, YAMLReader::node_path_t& node_path) const;
+      /// Get an option from the option cache
+      /// @param key the key name associated with this option
+      /// @returns the option value, if found (using `std::optional`)
+      template <typename OPTION_TYPE>
+      std::optional<OPTION_TYPE> GetCachedOption(std::string const& key) const;
 
       // PrintOptionValue: overloaded for different value types
       void PrintOptionValue(std::string const& key, int const& val, Logger::Level const level = Logger::debug, std::string_view prefix = "OPTION") const;

src/iguana/algorithms/AlgorithmSequence.h

@@ -119,6 +119,15 @@ namespace iguana {
         Get<Algorithm>(algo_instance_name)->SetOption(key, val);
       }
 
+      /// @brief Set an algorithm log level
+      /// @see `Logger::Level` for available levels
+      /// @param algo_instance_name the algorithm instance name
+      /// @param lev the log level name
+      void SetLogLevel(std::string const& algo_instance_name, std::string const& lev)
+      {
+        Get<Algorithm>(algo_instance_name)->SetLogLevel(lev);
+      }
+
       /// Set the name of this sequence
       /// @param name the new name
       void SetName(std::string_view name);

src/iguana/algorithms/clas12/EventBuilderFilter/Algorithm.cc

@@ -9,8 +9,8 @@ namespace iguana::clas12 {
 
     // define options, their default values, and cache them
     ParseYAMLConfig();
-    o_particle_bank = GetOptionScalar<std::string>("particle_bank");
-    o_pids          = GetOptionSet<int>("pids");
+    o_particle_bank = GetOptionScalar<std::string>({"particle_bank"});
+    o_pids          = GetOptionSet<int>({"pids"});
 
     // get expected bank indices
     b_particle = GetBankIndex(banks, o_particle_bank);

src/iguana/algorithms/clas12/MatchParticleProximity/Algorithm.cc

@@ -9,8 +9,8 @@ namespace iguana::clas12 {
   {
     // parse config file
     ParseYAMLConfig();
-    o_bank_a = GetOptionScalar<std::string>("bank_a");
-    o_bank_b = GetOptionScalar<std::string>("bank_b");
+    o_bank_a = GetOptionScalar<std::string>({"bank_a"});
+    o_bank_b = GetOptionScalar<std::string>({"bank_b"});
 
     // banklist indices
     b_bank_a = GetBankIndex(banks, o_bank_a);