Provides core functionality used to configure algorithms. More...

Collaboration diagram for Algorithm:

Classes
class	seqan3::configuration< configs_t >
	Collection of elements to configure an algorithm. More...

struct	seqan3::pipeable_config_element< derived_t, value_t >
	Adds pipe interface to configuration elements. More...

Tuple interface
template<template< typename ... > class query_t, typename ... configs_t>
constexpr auto &	get (configuration< configs_t... > &config) noexcept
	Returns the stored element. More...

Detailed Description

Provides core functionality used to configure algorithms.

In SeqAn there are many algorithms, e.g. alignment or search algorithms, that can be configured through many different settings and policies that alter the execution of the respective algorithm. These configurations can be orthogonal or might be mutually exclusive and can make interfaces very difficult to use. This module provides a basic system to manage the configurations of algorithms using a unified interface.

Usage

The basis of any algorithm configuration are configuration elements. These are objects that handle a specific setting and must satisfy the seqan3::detail::config_element. The following snippet demonstrates a basic setup for such configuration elements.

#include <seqan3/core/algorithm/configuration.hpp>
#include <seqan3/core/algorithm/pipeable_config_element.hpp>
 
enum struct my_id : int
{
    bar_id,
    foo_id
};
 
struct bar : public seqan3::pipeable_config_element<bar, float>
{
    static constexpr my_id id{my_id::bar_id};
};
 
template <typename t>
struct foo : public seqan3::pipeable_config_element<foo<t>, t>
{
    static constexpr my_id id{my_id::foo_id};
};
 
template <typename t>
foo(t) -> foo<t>;

Here, two classes with the name bar and foo are created. They can be normal or template classes and must inherit from seqan3::pipeable_config_element and contain a member with the name value to satisfy the respective concept. The separate value member is used for a proper encapsulation from the actual setting parameter. For example the alignment algorithms require a scoring scheme, but the scoring scheme itself should not be pipeable with other settings.

In addition an enum type was defined that will be used later to allow for compatibility checks when combining settings in a configuration object. This enum assigns every configuration element a unique id. To provide compatibility checks the seqan3::detail::compatibility_table must be overloaded for the specific algorithm configuration.

#include <seqan3/core/algorithm/configuration.hpp>
 
enum struct my_id : int
{
    bar_id,
    foo_id
};
 
namespace seqan3::detail
{
template <>
inline constexpr std::array<std::array<int, 2>, 2> compatibility_table<my_id>
{
    {
        {0, 1},
        {1, 0}
    }
};
} // namespace seqan3::detail

The type for the configuration element ids is used to overload the bool table. In the example above, both elements can be combined with each other but not with themselves, to avoid inconsistent settings.

Combining Configurations

To enable easy creation of algorithm settings the seqan3::configuration supports a pipeable interface for the different configuration elements which are added through the seqan3::pipeable_config_element base class. The following snippet demonstrates how bar and foo can be combined.

#include <seqan3/alignment/band/static_band.hpp>
#include <seqan3/alignment/configuration/align_config_band.hpp>
#include <seqan3/alignment/configuration/align_config_mode.hpp>
#include <seqan3/core/algorithm/configuration.hpp>
#include <seqan3/core/algorithm/pipeable_config_element.hpp>
 
int main()
{
    // Here we use the global and banded alignment configurations to show how they can be combined.
    seqan3::configuration my_cfg = seqan3::align_cfg::mode{seqan3::global_alignment} |
                                   seqan3::align_cfg::band{seqan3::static_band{seqan3::lower_bound{-4},
                                                                               seqan3::upper_bound{4}}};
}

Access the data

The configuration inherits from a std::tuple and exposes a tuple like interface using the standard position-based and type-based get interfaces. The get interface was extended to also support template template types as input template parameters to query the correct element:

#include <seqan3/alignment/band/static_band.hpp>
#include <seqan3/alignment/configuration/align_config_band.hpp>
#include <seqan3/alignment/configuration/align_config_gap.hpp>
#include <seqan3/alignment/scoring/gap_scheme.hpp>
#include <seqan3/core/algorithm/configuration.hpp>
#include <seqan3/core/algorithm/pipeable_config_element.hpp>
#include <seqan3/core/debug_stream.hpp>
 
int main()
{
    using seqan3::get;
 
    seqan3::configuration my_cfg = seqan3::align_cfg::gap{seqan3::gap_scheme{seqan3::gap_score{-1},
                                                                             seqan3::gap_open_score{-10}}} |
                                   seqan3::align_cfg::band{seqan3::static_band{seqan3::lower_bound{-4},
                                                                               seqan3::upper_bound{4}}};
    // my_cfg is now of type configuration<gap, band>
 
    seqan3::debug_stream << get<1>(my_cfg).value.lower_bound                          << '\n';  // prints -4
    seqan3::debug_stream << get<seqan3::align_cfg::band>(my_cfg).value.upper_bound    << '\n';  // prints 4
    seqan3::debug_stream << get<seqan3::align_cfg::gap>(my_cfg).value.get_gap_score() << '\n';  // prints -1
}

The get interface returns a reference to the stored configuration element. In some cases, e.g. the implementor of the actual algorithm, one wants to have an easy access to the actual value of the setting. Since, the configuration must not contain all possible configuration elements the seqan3::configuration provides a seqan3::configuration::value_or interface, which provides direct access to the value of the respective configuration element or uses a default value if the queried type is not contained in the configuration.

#include <seqan3/core/algorithm/configuration.hpp>
#include <seqan3/core/algorithm/pipeable_config_element.hpp>
#include <seqan3/core/debug_stream.hpp>
 
// Initial setup used in the actual example:
enum struct my_id : int
{
    bar_id,
    foo_id
};
 
struct bar : public seqan3::pipeable_config_element<bar, float>
{
    static constexpr my_id id{my_id::bar_id};
};
 
template <typename t>
struct foo : public seqan3::pipeable_config_element<foo<t>, t>
{
    static constexpr my_id id{my_id::foo_id};
};
 
template <typename t>
foo(t) -> foo<t>;
 
int main()
{
    seqan3::configuration my_cfg{bar{1.3}};
    seqan3::debug_stream << my_cfg.value_or<bar>("not there") << '\n';  // prints: 1.3
    seqan3::debug_stream << my_cfg.value_or<foo>("not there") << '\n';  // prints: not there
}

Function Documentation

◆ get()

template<template< typename ... > class query_t, typename ... configs_t>

constexpr auto & get ( configuration< configs_t... > & config )

Template Parameters

query_t A template template.

Parameters

[in] config The configuration to get the element for.

Extends the position-based and type based get interface for the configuration type, with a version that also accepts template-template types (types that are itself templates), such that the exact template definition must not be known.

Example

The following snippet demonstrates the various versions of get that can be used.

#include <seqan3/alignment/band/static_band.hpp>
#include <seqan3/alignment/configuration/align_config_band.hpp>
#include <seqan3/alignment/configuration/align_config_gap.hpp>
#include <seqan3/alignment/scoring/gap_scheme.hpp>
#include <seqan3/core/algorithm/configuration.hpp>
#include <seqan3/core/algorithm/pipeable_config_element.hpp>
#include <seqan3/core/debug_stream.hpp>
 
int main()
{
    using seqan3::get;
 
    seqan3::configuration my_cfg = seqan3::align_cfg::gap{seqan3::gap_scheme{seqan3::gap_score{-1},
                                                                             seqan3::gap_open_score{-10}}} |
                                   seqan3::align_cfg::band{seqan3::static_band{seqan3::lower_bound{-4},
                                                                               seqan3::upper_bound{4}}};
    // my_cfg is now of type configuration<gap, band>
 
    seqan3::debug_stream << get<1>(my_cfg).value.lower_bound                          << '\n';  // prints -4
    seqan3::debug_stream << get<seqan3::align_cfg::band>(my_cfg).value.upper_bound    << '\n';  // prints 4
    seqan3::debug_stream << get<seqan3::align_cfg::gap>(my_cfg).value.get_gap_score() << '\n';  // prints -1
}

Exception

no-throw guarantee.

Complexity

Constant time.

Classes

Tuple interface