.. _cpp-Config:

**********************************************************
Config.hpp
**********************************************************
.. default-domain:: cpp
.. default-role:: cpp:expr

.. py:currentmodule:: mod
.. cpp:namespace:: mod

.. _libmod-config:

This file defines configuration options for the library, e.g., for
changing the number of threads available for the ILP solver, or for
completely switching to another ILP solver.
Many of the options control verbosity of algorithms or which data to
output when printing figures.

.. enum-struct:: LabelType

    Selector for which type of label to use in algorithms.

    .. enumerator:: String

        Vertices and edges are considered to be labelled with
        character strings. If only first-order terms are present,
        then strings are generated as a serialisation of the term.
    .. enumerator:: Term

        Vertices and edges are considered to be labelled with
        first-order terms. If only strings are present, then first-order
        terms are generated by parsing the strings. This may result
        in an :cpp:class:`TermParsingError` if a string can not be parsed.
.. enum-struct:: LabelRelation

    Selector for which type of labelled morphism to use in an algorithm.

    .. enumerator:: Isomorphism

        Strings are considered isomorphic when they are equal.
        Terms are considered isomorphic when their most general unifier
        is a renaming.
    .. enumerator:: Specialisation

        A term :math:`t_2` is more special than, or isomorphic to, a term :math:`t_1` if there is a substitution
        which can be applied to :math:`t_1` to make the terms equal.
        This relation means that the right-hand side of a comparison is the more specialised term.
    .. enumerator:: Unification

        Strings unify if they are equal, i.e., the same as with :cpp:any:`Isomorphism`.
        Terms unify if a most general unifier (MGU) exists. The found MGU
        is used for substitution in some algorithms.
.. class:: LabelSettings

    A class simply for grouping label settings.

    .. function:: LabelSettings(LabelType type, LabelRelation relation)

        Construct label settings that only uses the vertex and edge labels.
    .. function:: LabelSettings(LabelType type, LabelRelation relation, LabelRelation stereoRelation)

        Construct label settings that include both vertex and edge labels, and stereo information.
    .. function:: LabelSettings(LabelType type, LabelRelation relation, bool withStereo, LabelRelation stereoRelation)
    .. function:: friend bool operator==(LabelSettings a, LabelSettings b)
                  friend bool operator!=(LabelSettings a, LabelSettings b)
    .. function:: friend std::ostream &operator<<(std::ostream &s, const LabelSettings &ls)
    .. member:: LabelType type
    .. member:: LabelRelation relation
    .. member:: bool withStereo
    .. member:: LabelRelation stereoRelation
..  enum-struct:: IsomorphismPolicy

    For some functions there is a choice of how to handle given arguments
    where two different objects may be isomorphic. Most notably the case is with graphs (:class:`graph::Graph`).

    .. enumerator:: Check

        Objects are checked for isomorphism as needed and exceptions are thrown when different objects are isomorphic.
        If in doubt, use this.
    .. enumerator:: TrustMe

        No checks are performed and the function trusts the caller to have performed the equivalent isomorphism checks.
        Only use this when you are completely sure that no exceptions would have been thrown if using :enumerator:`Check`.

        .. warning:: Generally the library has undefined behaviour if you use this option
            but an exception would have been thrown with :enumerator:`Check`.
.. enum-struct:: SmilesClassPolicy

    When loading SMILES strings, the class labels can be recorded and mapped into the corresponding
    vertices of the loaded graph. This policy dictates what should happen when the same class label
    is written on multiple atoms.

    .. enumerator:: NoneOnDuplicate

        If a class label is duplicated, then no labels are mapped to vertices.
    .. enumerator:: ThrowOnDuplicate

        If a class label is duplicated, throw a :class:`InputError`.
    .. enumerator:: MapUnique

        Map all class labels that are unique to vertices.
.. function:: std::vector<std::string> getAvailableILPSolvers()

    :returns: a list of solver names for which bindings are available in the current installation.
        It will be a subsequnce of
        ``CPLEX``, ``CBC-CLP``,
        depending on how the library was installated.
        The default solver is the first entry returned.

.. function:: Config &getConfig()

    :returns: the singleton :cpp:class:`Config` instance used by the library.


Class ``template<typename T> ConfigSetting``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: template<typename T> ConfigSetting
    

    Holds a single option of type :cpp:any:`T`.

Synopsis
^^^^^^^^

.. code-block:: c++
    
    template<typename T>
    struct ConfigSetting {
        ConfigSetting(T value, const std::string &name) : value(value), name(name) {}
        void set(T value) {
            this->value = value;
        };
        T get() const {
            return value;
        }
        T &operator()() {
            return value;
        }
        const std::string &getName() const {
            return name;
        }
    private:
        T value;
        const std::string name;
    };

Details
^^^^^^^

.. cpp:namespace-push:: template<typename T> ConfigSetting

.. function:: void set(T value)

    Sets the configuration value.

.. function:: T get() const

    :returns: The configuration value.

.. function: T &operator()()

    Access the value.


.. cpp:namespace-pop::


Class ``Config``
--------------------------------------------------------------------------------------------------------------------------------

.. class:: Config
    

    Holds all configuration settings.