#include <Algorithm.h>

Detailed Description

Base class for all algorithms to inherit from.

This is the base class for all algorithms. It provides common members, such as a logger instance and options data structure. Algorithm implementations must:

inherit from this base class
override the methods Algorithm::Start, Algorithm::Run and Algorithm::Stop

See existing algorithms for examples.

Definition at line 67 of file Algorithm.h.

Public Member Functions
	Algorithm (std::string_view name)
hipo::banklist::size_type	GetBankIndex (hipo::banklist &banks, std::string const &bank_name) const noexcept(false)
std::unique_ptr< YAMLReader > const &	GetConfig () const
hipo::bank	GetCreatedBank (std::string const &bank_name="") const noexcept(false)
hipo::banklist::size_type	GetCreatedBankIndex (hipo::banklist &banks) const noexcept(false)
std::string	GetCreatedBankName () const noexcept(false)
std::vector< std::string >	GetCreatedBankNames () const noexcept(false)
hipo::schema	GetCreatedBankSchema (std::string const &bank_name="") const noexcept(false)
unsigned int	GetCreatedBankVariant () const
template<typename OPTION_TYPE>
OPTION_TYPE	GetOptionScalar (YAMLReader::node_path_t node_path={}) const
template<typename OPTION_TYPE>
std::set< OPTION_TYPE >	GetOptionSet (YAMLReader::node_path_t node_path={}) const
template<typename OPTION_TYPE>
std::vector< OPTION_TYPE >	GetOptionVector (YAMLReader::node_path_t node_path={}) const
std::unique_ptr< RCDBReader > &	GetRCDBReader ()
virtual bool	Run (hipo::banklist &banks) const final
	Run Function: Process an event's hipo::banklist
void	SetConfig (std::unique_ptr< YAMLReader > &&yaml_config)
void	SetConfigDirectory (std::string const &name)
void	SetConfigFile (std::string const &name)
void	SetName (std::string_view name)
template<typename OPTION_TYPE>
OPTION_TYPE	SetOption (std::string const &key, const OPTION_TYPE val)
	Set an option specified by the user.
virtual void	Start () final
	Start Function: Initialize this algorithm before any events are processed, with the intent to process either hipo::bank objects or bank rows, rather than full hipo::banklist objects
virtual void	Start (hipo::banklist &banks) final
	Start Function: Initialize this algorithm before any events are processed, with the intent to process hipo::banklist objects
virtual void	Stop () final
	Stop Function: Finalize this algorithm after all events are processed.
Public Member Functions inherited from iguana::Object
	Object (std::string_view name="", Logger::Level lev=Logger::DEFAULT_LEVEL)
std::unique_ptr< Logger > &	GetLog ()
std::string	GetName () const
std::unique_ptr< Logger > &	Log ()
void	SetLogLevel (Logger::Level const lev)
void	SetLogLevel (std::string_view lev)
void	SetName (std::string_view name)

Protected Member Functions
hipo::schema	CreateBank (hipo::banklist &banks, hipo::banklist::size_type &bank_idx, std::string const &bank_name) noexcept(false)
hipo::bank &	GetBank (hipo::banklist &banks, hipo::banklist::size_type const idx, std::string const &expected_bank_name="") const noexcept(false)
void	ShowBank (hipo::bank const &bank, std::string_view message="", Logger::Level const level=Logger::trace) const
void	ShowBanks (hipo::banklist const &banks, std::string_view message="", Logger::Level const level=Logger::trace) const
void	StartRCDBReader ()
	Instantiate the RCDBReader instance for this algorithm.
void	ThrowSinceRenamed (std::string const &new_name, std::string const &version) const noexcept(false)

Protected Attributes
std::string	m_class_name
	Class name of this algorithm.
unsigned int	m_created_bank_variant {0}
std::string	m_default_config_file
	Default configuration file name.
std::mutex	m_mutex
	A mutex for this algorithm.
std::unique_ptr< RCDBReader >	m_rcdb
	RCDB reader.
bool	m_rows_only
	If true, algorithm can only operate on bank rows; Algorithm::GetBank, and therefore Algorithm::Run, cannot be called.
std::string	o_user_config_dir
std::string	o_user_config_file
Protected Attributes inherited from iguana::Object
std::unique_ptr< Logger >	m_log
	Logger instance for this object
std::string	m_name
	The name of this object.

Inheritance diagram for iguana::Algorithm:

Constructor & Destructor Documentation

◆ Algorithm()

iguana::Algorithm::Algorithm ( std::string_view name )

inline

Parameters

name	the unique name for a derived class instance

Definition at line 73 of file Algorithm.h.

◆ ~Algorithm()

virtual iguana::Algorithm::~Algorithm ( )

inlinevirtual

Definition at line 80 of file Algorithm.h.

Member Function Documentation

◆ CreateBank()

hipo::schema iguana::Algorithm::CreateBank	(	hipo::banklist &	banks,
		hipo::banklist::size_type &	bank_idx,
		std::string const &	bank_name )

protected

Create a new bank and push it to the bank list. The bank must be defined in src/iguana/bankdefs/iguana.json.

Parameters

[out]	banks	the hipo::banklist onto which the new bank will be pushed
[out]	bank_idx	will be set to the hipo::banklist index of the new bank
[in]	bank_name	the new bank name

Returns: the bank's schema

◆ GetBank()

hipo::bank & iguana::Algorithm::GetBank	(	hipo::banklist &	banks,
		hipo::banklist::size_type const	idx,
		std::string const &	expected_bank_name = "" ) const

protected

Get the reference to a bank from a hipo::banklist; optionally checks if the bank name matches the expectation

Parameters

banks	the hipo::banklist from which to get the specified bank
idx	the index of banks of the specified bank
expected_bank_name	if specified, checks that the specified bank has this name

Returns: a reference to the bank

◆ GetBankIndex()

hipo::banklist::size_type iguana::Algorithm::GetBankIndex	(	hipo::banklist &	banks,
		std::string const &	bank_name ) const

Get the index of a bank in a hipo::banklist; throws an exception if the bank is not found

Parameters

banks	the list of banks this algorithm will use
bank_name	the name of the bank

Returns: the hipo::banklist index of the bank

See also: tools::GetBankIndex for a function that is independent of algorithm; GetCreatedBankIndex, a convenience method for Iguana-created banks

◆ GetConfig()

std::unique_ptr< YAMLReader > const & iguana::Algorithm::GetConfig ( ) const

Get a reference to this algorithm's configuration (YAMLReader)

Returns: the configuration

◆ GetCreatedBank()

hipo::bank iguana::Algorithm::GetCreatedBank ( std::string const & bank_name = "" ) const

Get a bank created by a creator-type algorithm. The bank must be defined in src/iguana/bankdefs/iguana.json. Use this function if you intend to use specialized Run(hipo::bank&, ...) functions, where one of its parameters is a (reference to) a created bank.

Parameters

[in] bank_name the created bank name, which is only needed if the algorithm creates more than one bank

Returns: the new bank

◆ GetCreatedBankIndex()

hipo::banklist::size_type iguana::Algorithm::GetCreatedBankIndex ( hipo::banklist & banks ) const

Get the index of an Iguana-created bank in a hipo::banklist; throws an exception if the bank is not found, or if the algorithm creates more than one bank

Parameters

banks the list of banks this algorithm will use

Returns: the hipo::banklist index of the bank

See also: GetBankIndex for a more general method

◆ GetCreatedBankName()

std::string iguana::Algorithm::GetCreatedBankName ( ) const

Get the created bank name, for creator-type algorithms which create only one new bank

See also: Algorithm::GetCreatedBankNames for algorithms which create more than one new bank

Returns: the new bank name

◆ GetCreatedBankNames()

std::vector< std::string > iguana::Algorithm::GetCreatedBankNames ( ) const

Get the list of created bank names, for creator-type algorithms

See also: Algorithm::GetCreatedBankName for algorithms which create only one bank

Returns: the list of new bank names

◆ GetCreatedBankSchema()

hipo::schema iguana::Algorithm::GetCreatedBankSchema ( std::string const & bank_name = "" ) const

Get a bank schema created by a creator-type algorithm. The bank must be defined in src/iguana/bankdefs/iguana.json.

See also: Algorithm::GetCreatedBank

Parameters

[in] bank_name the created bank name, which is only needed if the algorithm creates more than one bank

Returns: the new bank schema

◆ GetCreatedBankVariant()

unsigned int iguana::Algorithm::GetCreatedBankVariant ( ) const

Returns: the variant number of a created bank

See also: tools::GetBankIndex for details

◆ GetOptionScalar()

template<typename OPTION_TYPE>

OPTION_TYPE iguana::Algorithm::GetOptionScalar ( YAMLReader::node_path_t node_path = {} ) const

Get the value of a scalar option

Parameters

node_path the YAML::Node identifier path to search for this option in the config files

Returns: the scalar option

◆ GetOptionSet()

template<typename OPTION_TYPE>

std::set< OPTION_TYPE > iguana::Algorithm::GetOptionSet ( YAMLReader::node_path_t node_path = {} ) const

Get the value of a vector option, and convert it to std::set

Parameters

node_path the YAML::Node identifier path to search for this option in the config files

Returns: the vector option converted to std::set

◆ GetOptionVector()

template<typename OPTION_TYPE>

std::vector< OPTION_TYPE > iguana::Algorithm::GetOptionVector ( YAMLReader::node_path_t node_path = {} ) const

Get the value of a vector option

Parameters

node_path the YAML::Node identifier path to search for this option in the config files

Returns: the vector option

◆ GetRCDBReader()

std::unique_ptr< RCDBReader > & iguana::Algorithm::GetRCDBReader ( )

Returns: the RCDB reader instance

◆ Run()

virtual bool iguana::Algorithm::Run ( hipo::banklist & banks ) const

finalvirtual

Run Function: Process an event's hipo::banklist

Parameters

banks the list of banks to process

Returns: a boolean value, which is typically used to decide whether or not to continue analyzing an event, i.e., it can be used as an event-level filter; not all algorithms use or need this feature; see the algorithm's more specialized Run functions, which have hipo::bank parameters

See also: Specialized Run function(s) above/below; they take individual hipo::bank objects as parameters, and their documentation explains which banks are used by this algorithm and how.

◆ SetConfig()

void iguana::Algorithm::SetConfig ( std::unique_ptr< YAMLReader > && yaml_config )

Set a custom YAMLReader to use for this algorithm

Parameters

yaml_config the custom YAMLReader instance

◆ SetConfigDirectory()

void iguana::Algorithm::SetConfigDirectory ( std::string const & name )

Set a custom configuration file directory for this algorithm

See also: Algorithm::SetConfigFile

Parameters

name	the directory name

◆ SetConfigFile()

void iguana::Algorithm::SetConfigFile ( std::string const & name )

Set a custom configuration file for this algorithm

See also: Algorithm::SetConfigDirectory

Parameters

name	the configuration file name

◆ SetName()

void iguana::Algorithm::SetName ( std::string_view name )

Set the name of this algorithm

Parameters

name	the new name

◆ SetOption()

template<typename OPTION_TYPE>

OPTION_TYPE iguana::Algorithm::SetOption	(	std::string const &	key,
		const OPTION_TYPE	val )

inline

Set an option specified by the user.

The key is the "path" within the YAML configuration file; for example, consider the following YAML file:

clas12::Example:
  strictness: 1
  forward_tagger:
    radius: [8.5, 15.5]

To set strictness, use "strictness"
To set radius, which is nested under forward_tagger, use "forward_tagger/radius"
see YAMLReader::NodePath2String for details on how a YAML node path is converted to such a string

If the option name is "log", the log level of the Logger owned by this algorithm will be changed to the specified value.

Parameters

key	the name of the option
val	the value to set

Returns: the value that has been set (if needed, e.g., when val is an rvalue)

Definition at line 133 of file Algorithm.h.

◆ ShowBank()

void iguana::Algorithm::ShowBank	(	hipo::bank const &	bank,
		std::string_view	message = "",
		Logger::Level const	level = Logger::trace ) const

protected

Dump a single bank

Parameters

bank	the bank to show
message	if specified, print a header message
level	the log level

◆ ShowBanks()

void iguana::Algorithm::ShowBanks	(	hipo::banklist const &	banks,
		std::string_view	message = "",
		Logger::Level const	level = Logger::trace ) const

protected

Dump all banks in a hipo::banklist

Parameters

banks	the banks to show
message	if specified, print a header message
level	the log level

◆ Start() [1/2]

virtual void iguana::Algorithm::Start ( )

finalvirtual

Start Function: Initialize this algorithm before any events are processed, with the intent to process either hipo::bank objects or bank rows, rather than full hipo::banklist objects

Use this method if you intend to use:

Specialized Run functions with hipo::bank objects
action functions, instead of Algorithm::Run.

◆ Start() [2/2]

virtual void iguana::Algorithm::Start ( hipo::banklist & banks )

finalvirtual

Start Function: Initialize this algorithm before any events are processed, with the intent to process hipo::banklist objects

Use this method if you intend to use:

Algorithm::Run with hipo::banklist objects

Parameters

banks the list of banks this algorithm will use, so that Algorithm::Run can cache the indices of the banks that it needs

◆ Stop()

virtual void iguana::Algorithm::Stop ( )

finalvirtual

Stop Function: Finalize this algorithm after all events are processed.

Call this when you are done with an algorithm.

◆ ThrowSinceRenamed()

void iguana::Algorithm::ThrowSinceRenamed	(	std::string const &	new_name,
		std::string const &	version ) const

protected

Throw a runtime exception since this algorithm has been renamed. Guidance will be printed for the user.

Parameters

new_name	the new name of the algorithm
version	the first software version where this change applies

Member Data Documentation

◆ m_class_name

std::string iguana::Algorithm::m_class_name

protected

Class name of this algorithm.

Definition at line 317 of file Algorithm.h.

◆ m_created_bank_variant

unsigned int iguana::Algorithm::m_created_bank_variant {0}

protected

Unique created-bank variant number, to handle the case where a user creates duplicate banks, e.g., with two creator algorithm instances that are configured differently

Definition at line 338 of file Algorithm.h.

◆ m_default_config_file

std::string iguana::Algorithm::m_default_config_file

protected

Default configuration file name.

Definition at line 323 of file Algorithm.h.

◆ m_mutex

std::mutex iguana::Algorithm::m_mutex

mutableprotected

A mutex for this algorithm.

Definition at line 334 of file Algorithm.h.

◆ m_rcdb

std::unique_ptr<RCDBReader> iguana::Algorithm::m_rcdb

protected

RCDB reader.

Definition at line 341 of file Algorithm.h.

◆ m_rows_only

bool iguana::Algorithm::m_rows_only

protected

If true, algorithm can only operate on bank rows; Algorithm::GetBank, and therefore Algorithm::Run, cannot be called.

Definition at line 320 of file Algorithm.h.

◆ o_user_config_dir

std::string iguana::Algorithm::o_user_config_dir

protected

User's configuration file directory. Set it with Algorithm::SetConfigDirectory

Definition at line 331 of file Algorithm.h.

◆ o_user_config_file

std::string iguana::Algorithm::o_user_config_file

protected

User's configuration file name, which may override the default configuration file, m_default_config_file. Set it with Algorithm::SetConfigFile

Definition at line 327 of file Algorithm.h.

The documentation for this class was generated from the following file:

/__w/iguana/iguana/iguana_src/src/iguana/algorithms/Algorithm.h

Detailed Description

Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ Algorithm()

◆ ~Algorithm()

Member Function Documentation

◆ CreateBank()

◆ GetBank()

◆ GetBankIndex()

◆ GetConfig()

◆ GetCreatedBank()

◆ GetCreatedBankIndex()

◆ GetCreatedBankName()

◆ GetCreatedBankNames()

◆ GetCreatedBankSchema()

◆ GetCreatedBankVariant()

◆ GetOptionScalar()

◆ GetOptionSet()

◆ GetOptionVector()

◆ GetRCDBReader()

◆ Run()

◆ SetConfig()

◆ SetConfigDirectory()

◆ SetConfigFile()

◆ SetName()

◆ SetOption()

◆ ShowBank()

◆ ShowBanks()

◆ Start() [1/2]

◆ Start() [2/2]

◆ Stop()

◆ ThrowSinceRenamed()

Member Data Documentation

◆ m_class_name

◆ m_created_bank_variant

◆ m_default_config_file

◆ m_mutex

◆ m_rcdb

◆ m_rows_only

◆ o_user_config_dir

◆ o_user_config_file