Loading...
Searching...
No Matches
Configuration
Core

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

Collaboration diagram for Configuration:

## Classes

class | seqan3::configuration< configs_t >
| Collection of elements to configure an algorithm. More...
struct | seqan3::pipeable_config_element
| Adds pipe interface to configuration elements. More...

## Variables

template<typename config1_t, typename config2_t>
constexpr bool | seqan3::is_config_element_combineable_v = detail::config_element_pipeable_with<config1_t, config2_t>
| Helper variable template to test if a configuration element is combineable with another configuration element or configuration.

## Tuple interface

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

## Detailed Description

Provides core functionality used to configure configurations.

See also
  Core

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.

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <seqan3/core/configuration/configuration.hpp>
#include <seqan3/core/configuration/pipeable_config_element.hpp>
enum struct my_id : int
{
bar_id,
foo_id
};
class bar : private seqan3::pipeable_config_element
{
public:
bar() = default;
bar(bar const &) = default;
bar(bar &&) = default;
bar & operator=(bar const &) = default;
bar & operator=(bar &&) = default;
~bar() = default;
static constexpr my_id id{my_id::bar_id};
};
template <typename t>
struct foo : private seqan3::pipeable_config_element
{
public:
foo() = default;
foo(foo const &) = default;
foo(foo &&) = default;
foo & operator=(foo const &) = default;
foo & operator=(foo &&) = default;
~foo() = default;
static constexpr my_id id{my_id::foo_id};
};
template <typename t>
foo(t) -> foo<t>;
configuration.hpp
Provides seqan3::configuration and utility functions.
pipeable_config_element.hpp
Provides seqan3::pipeable_config_element.
seqan3::pipeable_config_element
Adds pipe interface to configuration elements.
Definition pipeable_config_element.hpp:29

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.

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <seqan3/core/configuration/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
std::array

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.

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <seqan3/alignment/configuration/align_config_band.hpp>
#include <seqan3/alignment/configuration/align_config_method.hpp>
#include <seqan3/core/configuration/configuration.hpp>
#include <seqan3/core/configuration/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::method_global{}
| seqan3::align_cfg::band_fixed_size{seqan3::align_cfg::lower_diagonal{-4},
seqan3::align_cfg::upper_diagonal{4}};
}
align_config_band.hpp
Provides seqan3::detail::align_config_band.
align_config_method.hpp
Provides global and local alignment configurations.
seqan3::align_cfg::band_fixed_size
Configuration element for setting a fixed size band.
Definition align_config_band.hpp:60
seqan3::align_cfg::method_global
Sets the global alignment method.
Definition align_config_method.hpp:119
seqan3::configuration
Collection of elements to configure an algorithm.
Definition configuration.hpp:42
seqan3::align_cfg::lower_diagonal
A strong type representing the lower diagonal of the seqan3::align_cfg::band_fixed_size.
Definition align_config_band.hpp:28
seqan3::align_cfg::upper_diagonal
A strong type representing the upper diagonal of the seqan3::align_cfg::band_fixed_size.
Definition align_config_band.hpp:39

### 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:

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <seqan3/alignment/configuration/align_config_band.hpp>
#include <seqan3/alignment/configuration/align_config_gap_cost_affine.hpp>
#include <seqan3/core/configuration/configuration.hpp>
#include <seqan3/core/configuration/pipeable_config_element.hpp>
#include <seqan3/core/debug_stream.hpp>
int main()
{
using seqan3::get;
seqan3::configuration my_cfg =
seqan3::align_cfg::gap_cost_affine{seqan3::align_cfg::open_score{-10}, seqan3::align_cfg::extension_score{-1}}
| seqan3::align_cfg::band_fixed_size{seqan3::align_cfg::lower_diagonal{-4},
seqan3::align_cfg::upper_diagonal{4}};
// my_cfg is now of type configuration<gap_cost_affine, band_fixed_size>
seqan3::debug_stream << get<1>(my_cfg).lower_diagonal << '\n'; // prints -4
seqan3::debug_stream << get<seqan3::align_cfg::band_fixed_size>(my_cfg).upper_diagonal << '\n'; // prints 4
seqan3::debug_stream << get<seqan3::align_cfg::gap_cost_affine>(my_cfg).extension_score << '\n'; // prints -1
}
align_config_gap_cost_affine.hpp
Provides seqan3::align_config::gap_cost_affine.
seqan3::align_cfg::gap_cost_affine
A configuration element for the affine gap cost scheme.
Definition align_config_gap_cost_affine.hpp:72
debug_stream.hpp
Provides seqan3::debug_stream and related types.
seqan3::debug_stream
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition debug_stream.hpp:38
seqan3::get
constexpr auto const & get(configuration< configs_t... > const &config) noexcept
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition configuration.hpp:412
seqan3::align_cfg::extension_score
A strong type of underlying type int32_t that represents the score (usually negative) of any characte...
Definition align_config_gap_cost_affine.hpp:48
seqan3::align_cfg::open_score
A strong type of underlying type int32_t that represents a score (usually negative) that is incurred ...
Definition align_config_gap_cost_affine.hpp:31

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::get_or interface. Using this interface one can call get with a specific configuration element. If this configuration element or a specialisation of it is already stored inside of the configuration, the respective element is returned. Otherwise, the passed argument will be returned as the alternative.

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <seqan3/core/configuration/configuration.hpp>
#include <seqan3/core/configuration/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 : private seqan3::pipeable_config_element
{
public:
float value{};
bar() = default;
bar(bar const &) = default;
bar(bar &&) = default;
bar & operator=(bar const &) = default;
bar & operator=(bar &&) = default;
~bar() = default;
bar(float v) : value{v}
{}
static constexpr my_id id{my_id::bar_id};
};
template <typename t>
class foo : private seqan3::pipeable_config_element
{
public:
t value{};
foo() = default;
foo(foo const &) = default;
foo(foo &&) = default;
foo & operator=(foo const &) = default;
foo & operator=(foo &&) = default;
~foo() = default;
foo(t v) : value{std::move(v)}
{}
static constexpr my_id id{my_id::foo_id};
};
template <typename t>
foo(t) -> foo<t>;
int main()
{
seqan3::configuration my_cfg{foo{1}}; // Only foo<int> is present.
seqan3::debug_stream << my_cfg.get_or(foo{std::string{"hello"}}).value << '\n'; // finds foo<int> -> prints: 1
seqan3::debug_stream << my_cfg.get_or(bar{2.4}).value << '\n'; // bar not present -> prints: 2.4
}
std::string
seqan3::configuration::get_or
constexpr decltype(auto) get_or(alternative_t &&alternative) &noexcept
Returns the stored configuration element if present otherwise the given alternative.
Definition configuration.hpp:117

## Function Documentation

## get()

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

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

related

Returns the stored element.

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.

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <seqan3/alignment/configuration/align_config_band.hpp>
#include <seqan3/alignment/configuration/align_config_gap_cost_affine.hpp>
#include <seqan3/core/configuration/configuration.hpp>
#include <seqan3/core/configuration/pipeable_config_element.hpp>
#include <seqan3/core/debug_stream.hpp>
int main()
{
using seqan3::get;
seqan3::configuration my_cfg =
seqan3::align_cfg::gap_cost_affine{seqan3::align_cfg::open_score{-10}, seqan3::align_cfg::extension_score{-1}}
| seqan3::align_cfg::band_fixed_size{seqan3::align_cfg::lower_diagonal{-4},
seqan3::align_cfg::upper_diagonal{4}};
// my_cfg is now of type configuration<gap_cost_affine, band_fixed_size>
seqan3::debug_stream << get<1>(my_cfg).lower_diagonal << '\n'; // prints -4
seqan3::debug_stream << get<seqan3::align_cfg::band_fixed_size>(my_cfg).upper_diagonal << '\n'; // prints 4
seqan3::debug_stream << get<seqan3::align_cfg::gap_cost_affine>(my_cfg).extension_score << '\n'; // prints -1
}

### Exception

no-throw guarantee.

### Complexity

Constant time.

## Variable Documentation

## is_config_element_combineable_v

template<typename config1_t, typename config2_t>

bool seqan3::is_config_element_combineable_v = detail::config_element_pipeable_with<config1_t, config2_t>

inline constexpr

Helper variable template to test if a configuration element is combineable with another configuration element or configuration.

Template Parameters

  config1_t | Either the type of a configuration element or a configuration.
  config2_t | Either the type of a configuration element or a configuration.

This helper variable template checks if config1_t fulfills the concept requirements seqan3::detail::config_element_pipeable_with config2_t. If config2_t is a seqan3::configuration, the check will be expanded to every configuration element contained in the configuration type. Only if config1_t is combineable with every element stored inside of the given configuration, this helper variable template evaluates to true, otherwise false. If config1_t is a seqan3::configuration the same applies in combination with the configuration element config2_t. If both config1_t and config2_t are seqan3::configuration types, then the cartesian product between the configuration elements of the first configuration and the second configuration are tested.

This entity is not part of the SeqAn API. Do not rely on it in your applications. This entity is exposition only!

Hide me