Enumerates the atom and bond self-mappings (automorphism group) of a molecular graph. More...

#include <AutomorphismGroupSearch.hpp>

Public Types
typedef std::shared_ptr< AutomorphismGroupSearch >	SharedPointer
	A reference-counted smart pointer [SHPTR] for dynamically allocated `AutomorphismGroupSearch` instances. More...

typedef SubstructureSearch::MappingIterator	MappingIterator
	A mutable random access iterator used to iterate over the stored Chem::AtomBondMapping objects. More...

typedef SubstructureSearch::ConstMappingIterator	ConstMappingIterator
	A constant random access iterator used to iterate over the stored `const` Chem::AtomBondMapping objects. More...

typedef std::function< bool(const MolecularGraph &, const AtomBondMapping &)>	MappingCallbackFunction
	Type of the callback function invoked for every found mapping. More...

Public Member Functions
	AutomorphismGroupSearch (unsigned int atom_flags=DEF_ATOM_PROPERTY_FLAGS, unsigned int bond_flags=DEF_BOND_PROPERTY_FLAGS)
	Constructs and initializes the `AutomorphismGroupSearch` instance for the specified atom and bond properties. More...

	AutomorphismGroupSearch (const AutomorphismGroupSearch &)=delete

AutomorphismGroupSearch &	operator= (const AutomorphismGroupSearch &)=delete

void	setAtomPropertyFlags (unsigned int flags)
	Specifies the atomic properties considered for atom matching during automorphism search. More...

unsigned int	getAtomPropertyFlags () const
	Returns the atomic properties currently considered for atom matching. More...

void	setBondPropertyFlags (unsigned int flags)
	Specifies the bond properties considered for bond matching during automorphism search. More...

unsigned int	getBondPropertyFlags () const
	Returns the bond properties currently considered for bond matching. More...

void	includeIdentityMapping (bool include)
	Specifies whether the identity mapping shall be included in the search results. More...

bool	identityMappingIncluded () const
	Tells whether the identity mapping is included in the search results. More...

bool	findMappings (const MolecularGraph &molgraph)
	Searches for the possible atom/bond mappings in the automorphism group of the molecular graph molgraph. More...

void	stopSearch ()
	Aborts a currently running findMappings() call. More...

std::size_t	getNumMappings () const
	Returns the number of atom/bond mappings that were recorded in the last call to findMappings(). More...

AtomBondMapping &	getMapping (std::size_t idx)
	Returns a non-`const` reference to the stored atom/bond mapping object at index idx. More...

const AtomBondMapping &	getMapping (std::size_t idx) const
	Returns a `const` reference to the stored atom/bond mapping object at index idx. More...

MappingIterator	getMappingsBegin ()
	Returns a mutable iterator pointing to the beginning of the stored Chem::AtomBondMapping objects. More...

ConstMappingIterator	getMappingsBegin () const
	Returns a constant iterator pointing to the beginning of the stored `const` Chem::AtomBondMapping objects. More...

MappingIterator	getMappingsEnd ()
	Returns a mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects. More...

ConstMappingIterator	getMappingsEnd () const
	Returns a constant iterator pointing to the end of the stored `const` Chem::AtomBondMapping objects. More...

MappingIterator	begin ()
	Returns a mutable iterator pointing to the beginning of the stored Chem::AtomBondMapping objects. More...

ConstMappingIterator	begin () const
	Returns a constant iterator pointing to the beginning of the stored `const` Chem::AtomBondMapping objects. More...

MappingIterator	end ()
	Returns a mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects. More...

ConstMappingIterator	end () const
	Returns a constant iterator pointing to the end of the stored `const` Chem::AtomBondMapping objects. More...

void	setMaxNumMappings (std::size_t max_num_mappings)
	Allows to specify a limit on the number of stored atom/bond mappings. More...

std::size_t	getMaxNumMappings () const
	Returns the specified limit on the number of stored atom/bond mappings. More...

void	addAtomMappingConstraint (std::size_t atom1_idx, std::size_t atom2_idx)
	Adds a constraint on the allowed atom mappings. More...

void	clearAtomMappingConstraints ()
	Clears all previously defined atom mapping constraints. More...

void	addBondMappingConstraint (std::size_t bond1_idx, std::size_t bond2_idx)
	Adds a constraint on the allowed bond mappings. More...

void	clearBondMappingConstraints ()
	Clears all previously defined bond mapping constraints. More...

void	setFoundMappingCallback (const MappingCallbackFunction &func)
	Sets a callback function that is invoked for every atom/bond mapping found during findMappings(). More...

const MappingCallbackFunction &	getFoundMappingCallback () const
	Returns the currently installed callback function invoked for every found atom/bond mapping. More...

Static Public Attributes
static constexpr unsigned int	DEF_ATOM_PROPERTY_FLAGS
	Specifies the default set of atomic properties considered for atom matching. More...

static constexpr unsigned int	DEF_BOND_PROPERTY_FLAGS
	Specifies the default set of bond properties considered for bond matching. More...

Detailed Description

Enumerates the atom and bond self-mappings (automorphism group) of a molecular graph.

The automorphism group of a molecular graph is the set of self-mappings (atom permutations and the induced bond permutations) that preserve the molecular graph structure under the configured atom and bond mapping constraints. Atom and bond matching is configurable via bit masks composed by a bitwise-OR combination of the constants defined in namespace Chem::AtomPropertyFlag and Chem::BondPropertyFlag that are set using the methods setAtomPropertyFlags() and setBondPropertyFlags(), respectively. Found mappings are recorded as Chem::AtomBondMapping objects that can be accessed via index through the method getMapping() or iteration using the iterator pair returned by the methods begin() and end(). The method setFoundMappingCallback() allows to register a user-defined callback function that gets invoked whenever a new mapping has been found. The maximum number of stored solutions can be bounded by setMaxNumMappings() and stopSearch() allows an immediate abort of the search process. Furthermore, query ↔ target atom and bond mappings can be restricted to user-defined subsets by the methods addAtomMappingConstraint() and addBondMappingConstraint(), respectively.

Member Typedef Documentation

◆ SharedPointer

typedef std::shared_ptr<AutomorphismGroupSearch> CDPL::Chem::AutomorphismGroupSearch::SharedPointer

A reference-counted smart pointer [SHPTR] for dynamically allocated AutomorphismGroupSearch instances.

◆ MappingIterator

typedef SubstructureSearch::MappingIterator CDPL::Chem::AutomorphismGroupSearch::MappingIterator

A mutable random access iterator used to iterate over the stored Chem::AtomBondMapping objects.

◆ ConstMappingIterator

typedef SubstructureSearch::ConstMappingIterator CDPL::Chem::AutomorphismGroupSearch::ConstMappingIterator

A constant random access iterator used to iterate over the stored const Chem::AtomBondMapping objects.

◆ MappingCallbackFunction

typedef std::function<bool(const MolecularGraph&, const AtomBondMapping&)> CDPL::Chem::AutomorphismGroupSearch::MappingCallbackFunction

Type of the callback function invoked for every found mapping.

Returning false discards the mapping.

Constructor & Destructor Documentation

◆ AutomorphismGroupSearch() [1/2]

CDPL::Chem::AutomorphismGroupSearch::AutomorphismGroupSearch	(	unsigned int	atom_flags = `DEF_ATOM_PROPERTY_FLAGS`,
		unsigned int	bond_flags = `DEF_BOND_PROPERTY_FLAGS`
	)

Constructs and initializes the AutomorphismGroupSearch instance for the specified atom and bond properties.

Parameters

atom_flags	Bitwise-OR combination of Chem::AtomPropertyFlag values specifying atomic properties considered for atom matching.
bond_flags	Bitwise-OR combination of Chem::BondPropertyFlag values specifying bond properties considered for bond matching.

◆ AutomorphismGroupSearch() [2/2]

CDPL::Chem::AutomorphismGroupSearch::AutomorphismGroupSearch ( const AutomorphismGroupSearch & )

delete

Member Function Documentation

◆ operator=()

AutomorphismGroupSearch& CDPL::Chem::AutomorphismGroupSearch::operator= ( const AutomorphismGroupSearch & )

delete

◆ setAtomPropertyFlags()

void CDPL::Chem::AutomorphismGroupSearch::setAtomPropertyFlags ( unsigned int flags )

Specifies the atomic properties considered for atom matching during automorphism search.

Parameters

flags The new bitwise-OR combination of corresponding Chem::AtomPropertyFlag values.

◆ getAtomPropertyFlags()

unsigned int CDPL::Chem::AutomorphismGroupSearch::getAtomPropertyFlags ( ) const

Returns the atomic properties currently considered for atom matching.

Returns: The currently set bitwise-OR combination of corresponding Chem::AtomPropertyFlag values.

◆ setBondPropertyFlags()

void CDPL::Chem::AutomorphismGroupSearch::setBondPropertyFlags ( unsigned int flags )

Specifies the bond properties considered for bond matching during automorphism search.

Parameters

flags The new bitwise-OR combination of corresponding Chem::BondPropertyFlag values.

◆ getBondPropertyFlags()

unsigned int CDPL::Chem::AutomorphismGroupSearch::getBondPropertyFlags ( ) const

Returns the bond properties currently considered for bond matching.

Returns: The currently set bitwise-OR combination of corresponding Chem::BondPropertyFlag values.

◆ includeIdentityMapping()

void CDPL::Chem::AutomorphismGroupSearch::includeIdentityMapping ( bool include )

Specifies whether the identity mapping shall be included in the search results.

Parameters

include If true, the identity mapping is also reported.

◆ identityMappingIncluded()

bool CDPL::Chem::AutomorphismGroupSearch::identityMappingIncluded ( ) const

Tells whether the identity mapping is included in the search results.

Returns: true if the identity mapping is included, and false otherwise.

◆ findMappings()

bool CDPL::Chem::AutomorphismGroupSearch::findMappings ( const MolecularGraph & molgraph )

Searches for the possible atom/bond mappings in the automorphism group of the molecular graph molgraph.

The method will store all found mappings up to the maximum number of recorded mappings specified by setMaxNumMappings().

Parameters

molgraph The molecular graph that has to be searched for automorphisms.

Returns: true if any mappings of the specified molecular graph have been found, and false otherwise.

Note: Any atom/bond mappings that were recorded in a previous call to findMappings() will be discarded.

◆ stopSearch()

void CDPL::Chem::AutomorphismGroupSearch::stopSearch ( )

Aborts a currently running findMappings() call.

Intended to be invoked from within the callback installed via setFoundMappingCallback() to stop the automorphism enumeration early.

◆ getNumMappings()

std::size_t CDPL::Chem::AutomorphismGroupSearch::getNumMappings ( ) const

Returns the number of atom/bond mappings that were recorded in the last call to findMappings().

Returns: The number of atom/bond mappings that were recorded in the last call to findMappings().

◆ getMapping() [1/2]

AtomBondMapping& CDPL::Chem::AutomorphismGroupSearch::getMapping ( std::size_t idx )

Returns a non-const reference to the stored atom/bond mapping object at index idx.

Parameters

idx	The zero-based index of the atom/bond mapping object to return.

Returns: A non-const reference to the Chem::AtomBondMapping object at index idx.

Exceptions

Base::IndexError if idx is not in the range [0, getNumMappings()).

◆ getMapping() [2/2]

const AtomBondMapping& CDPL::Chem::AutomorphismGroupSearch::getMapping ( std::size_t idx ) const

Returns a const reference to the stored atom/bond mapping object at index idx.

Parameters

idx	The zero-based index of the atom/bond mapping object to return.

Returns: A const reference to the Chem::AtomBondMapping object at index idx.

Exceptions

Base::IndexError if idx is not in the range [0, getNumMappings()).

◆ getMappingsBegin() [1/2]

MappingIterator CDPL::Chem::AutomorphismGroupSearch::getMappingsBegin ( )

Returns a mutable iterator pointing to the beginning of the stored Chem::AtomBondMapping objects.

Returns: A mutable iterator pointing to the beginning of the stored Chem::AtomBondMapping objects.

◆ getMappingsBegin() [2/2]

ConstMappingIterator CDPL::Chem::AutomorphismGroupSearch::getMappingsBegin ( ) const

Returns a constant iterator pointing to the beginning of the stored const Chem::AtomBondMapping objects.

Returns: A constant iterator pointing to the beginning of the stored const Chem::AtomBondMapping objects.

◆ getMappingsEnd() [1/2]

MappingIterator CDPL::Chem::AutomorphismGroupSearch::getMappingsEnd ( )

Returns a mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects.

Returns: A mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects.

◆ getMappingsEnd() [2/2]

ConstMappingIterator CDPL::Chem::AutomorphismGroupSearch::getMappingsEnd ( ) const

Returns a constant iterator pointing to the end of the stored const Chem::AtomBondMapping objects.

Returns: A constant iterator pointing to the end of the stored const Chem::AtomBondMapping objects.

◆ begin() [1/2]

MappingIterator CDPL::Chem::AutomorphismGroupSearch::begin ( )

Returns a mutable iterator pointing to the beginning of the stored Chem::AtomBondMapping objects.

Returns: A mutable iterator pointing to the beginning of the stored Chem::AtomBondMapping objects.

◆ begin() [2/2]

ConstMappingIterator CDPL::Chem::AutomorphismGroupSearch::begin ( ) const

Returns a constant iterator pointing to the beginning of the stored const Chem::AtomBondMapping objects.

Returns: A constant iterator pointing to the beginning of the stored const Chem::AtomBondMapping objects.

◆ end() [1/2]

MappingIterator CDPL::Chem::AutomorphismGroupSearch::end ( )

Returns a mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects.

Returns: A mutable iterator pointing to the end of the stored Chem::AtomBondMapping objects.

◆ end() [2/2]

ConstMappingIterator CDPL::Chem::AutomorphismGroupSearch::end ( ) const

Returns a constant iterator pointing to the end of the stored const Chem::AtomBondMapping objects.

Returns: A constant iterator pointing to the end of the stored const Chem::AtomBondMapping objects.

◆ setMaxNumMappings()

void CDPL::Chem::AutomorphismGroupSearch::setMaxNumMappings ( std::size_t max_num_mappings )

Allows to specify a limit on the number of stored atom/bond mappings.

In a call to findMappings() the automorphism search will terminate as soon as the specified maximum number of stored atom/bond mappings has been reached. A previously set limit on the number of mappings can be disabled by providing zero for the value of max_num_mappings.

Parameters

max_num_mappings The maximum number of atom/bond mappings to store.

Note: By default, no limit is imposed on the number of stored mappings.

◆ getMaxNumMappings()

std::size_t CDPL::Chem::AutomorphismGroupSearch::getMaxNumMappings ( ) const

Returns the specified limit on the number of stored atom/bond mappings.

Returns: The specified maximum number of stored atom/bond mappings.

See also: setMaxNumMappings(), findMappings()

◆ addAtomMappingConstraint()

void CDPL::Chem::AutomorphismGroupSearch::addAtomMappingConstraint	(	std::size_t	atom1_idx,
		std::size_t	atom2_idx
	)

Adds a constraint on the allowed atom mappings.

By default, an atom can be mapped to any valid other atom. When this method gets called for a particular atom pair (specified by atom1_idx and atom2_idx), a future search will report only those solutions which feature the specified mapping of the two atoms. Multiple calls to addAtomMappingConstraint() for a particular atom enlarges the set of valid mapping solutions.

Parameters

atom1_idx	The index of the first atom.
atom2_idx	The index of the second atom.

◆ clearAtomMappingConstraints()

void CDPL::Chem::AutomorphismGroupSearch::clearAtomMappingConstraints ( )

Clears all previously defined atom mapping constraints.

See also: addAtomMappingConstraint()

◆ addBondMappingConstraint()

void CDPL::Chem::AutomorphismGroupSearch::addBondMappingConstraint	(	std::size_t	bond1_idx,
		std::size_t	bond2_idx
	)

Adds a constraint on the allowed bond mappings.

By default, an bond can be mapped to any valid other bond. When this method gets called for a particular bond pair (specified by bond1_idx and bond2_idx), a future search will report only those solutions which feature the specified mapping of the two bonds. Multiple calls to addBondMappingConstraint() for a particular bond enlarges the set of valid mapping solutions.

Parameters

bond1_idx	The index of the first bond.
bond2_idx	The index of the second bond.

◆ clearBondMappingConstraints()

void CDPL::Chem::AutomorphismGroupSearch::clearBondMappingConstraints ( )

Clears all previously defined bond mapping constraints.

See also: addBondMappingConstraint()

◆ setFoundMappingCallback()

void CDPL::Chem::AutomorphismGroupSearch::setFoundMappingCallback ( const MappingCallbackFunction & func )

Sets a callback function that is invoked for every atom/bond mapping found during findMappings().

Returning false from the function discards the found mapping (will not be part of the search results).

Parameters

func	The new callback function.

◆ getFoundMappingCallback()

const MappingCallbackFunction& CDPL::Chem::AutomorphismGroupSearch::getFoundMappingCallback ( ) const

Returns the currently installed callback function invoked for every found atom/bond mapping.

Returns: A const reference to the installed callback function.

Member Data Documentation

◆ DEF_ATOM_PROPERTY_FLAGS

constexpr unsigned int CDPL::Chem::AutomorphismGroupSearch::DEF_ATOM_PROPERTY_FLAGS

staticconstexpr

Initial value:

=
                AtomPropertyFlag::TYPE | AtomPropertyFlag::ISOTOPE |
                AtomPropertyFlag::H_COUNT | AtomPropertyFlag::FORMAL_CHARGE |
                AtomPropertyFlag::CONFIGURATION | AtomPropertyFlag::AROMATICITY |
                AtomPropertyFlag::EXPLICIT_BOND_COUNT | AtomPropertyFlag::HYBRIDIZATION_STATE

Specifies the default set of atomic properties considered for atom matching.

◆ DEF_BOND_PROPERTY_FLAGS

constexpr unsigned int CDPL::Chem::AutomorphismGroupSearch::DEF_BOND_PROPERTY_FLAGS

staticconstexpr

Initial value:

=
                BondPropertyFlag::ORDER | BondPropertyFlag::TOPOLOGY |
                BondPropertyFlag::AROMATICITY | BondPropertyFlag::CONFIGURATION

Specifies the default set of bond properties considered for bond matching.

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

AutomorphismGroupSearch.hpp

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ SharedPointer

◆ MappingIterator

◆ ConstMappingIterator

◆ MappingCallbackFunction

Constructor & Destructor Documentation

◆ AutomorphismGroupSearch() [1/2]

◆ AutomorphismGroupSearch() [2/2]

Member Function Documentation

◆ operator=()

◆ setAtomPropertyFlags()

◆ getAtomPropertyFlags()

◆ setBondPropertyFlags()

◆ getBondPropertyFlags()

◆ includeIdentityMapping()

◆ identityMappingIncluded()

◆ findMappings()

◆ stopSearch()

◆ getNumMappings()

◆ getMapping() [1/2]

◆ getMapping() [2/2]

◆ getMappingsBegin() [1/2]

◆ getMappingsBegin() [2/2]

◆ getMappingsEnd() [1/2]

◆ getMappingsEnd() [2/2]

◆ begin() [1/2]

◆ begin() [2/2]

◆ end() [1/2]

◆ end() [2/2]

◆ setMaxNumMappings()

◆ getMaxNumMappings()

◆ addAtomMappingConstraint()

◆ clearAtomMappingConstraints()

◆ addBondMappingConstraint()

◆ clearBondMappingConstraints()

◆ setFoundMappingCallback()

◆ getFoundMappingCallback()

Member Data Documentation

◆ DEF_ATOM_PROPERTY_FLAGS

◆ DEF_BOND_PROPERTY_FLAGS