Enumerates the atom/bond automorphisms 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 atom/bond mapping objects. More...

typedef SubstructureSearch::ConstMappingIterator	ConstMappingIterator
	A constant random access iterator used to iterate over the stored atom/bond mapping objects. More...

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

Public Member Functions
	AutomorphismGroupSearch (unsigned int atom_flags=DEF_ATOM_PROPERTY_FLAGS, unsigned int bond_flags=DEF_BOND_PROPERTY_FLAGS)
	Constructs and initializes a `AutomorphismGroupSearch` instance. 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 given molecular graph. 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 atom/bond mapping objects. More...

ConstMappingIterator	getMappingsBegin () const
	Returns a constant iterator pointing to the beginning of the stored atom/bond mapping objects. More...

MappingIterator	getMappingsEnd ()
	Returns a mutable iterator pointing to the end of the stored atom/bond mapping objects. More...

ConstMappingIterator	getMappingsEnd () const
	Returns a constant iterator pointing to the end of the stored atom/bond mapping objects. More...

MappingIterator	begin ()
	Returns a mutable iterator pointing to the beginning of the stored atom/bond mapping objects. More...

ConstMappingIterator	begin () const
	Returns a constant iterator pointing to the beginning of the stored atom/bond mapping objects. More...

MappingIterator	end ()
	Returns a mutable iterator pointing to the end of the stored atom/bond mapping objects. More...

ConstMappingIterator	end () const
	Returns a constant iterator pointing to the end of the stored atom/bond mapping 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 that is invoked for every atom/bond mapping found during findMappings(). More...

const MappingCallbackFunction &	getFoundMappingCallback () const
	Returns the currently installed found-mapping callback. 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/bond automorphisms 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 property flags. Atom and bond matching is configurable via the Chem::AtomPropertyFlag and Chem::BondPropertyFlag bit masks. Found mappings are stored as Chem::AtomBondMapping objects and can be iterated or accessed by index.

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 atom/bond mapping objects.

◆ ConstMappingIterator

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

A constant random access iterator used to iterate over the stored atom/bond mapping objects.

◆ MappingCallbackFunction

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

Type of the callback invoked for every found mapping (return false to abort the search).

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 a AutomorphismGroupSearch instance.

Parameters

atom_flags	The bitwise-OR combination of Chem::AtomPropertyFlag values considered for atom matching.
bond_flags	The bitwise-OR combination of Chem::BondPropertyFlag values 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 Chem::AtomPropertyFlag values.

◆ getAtomPropertyFlags()

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

Returns the atomic properties currently considered for atom matching.

Returns: The bitwise-OR combination of 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 Chem::BondPropertyFlag values.

◆ getBondPropertyFlags()

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

Returns the bond properties currently considered for bond matching.

Returns: The bitwise-OR combination of 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 given molecular graph.

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 atom/bond mapping object at index idx.

Exceptions

Base::IndexError if no mappings are available or idx is not in the range [0, getNumMappings() - 1].

◆ 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 atom/bond mapping object at index idx.

Exceptions

Base::IndexError if no mappings are available or idx is not in the range [0, getNumMappings() - 1].

◆ getMappingsBegin() [1/2]

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

Returns a mutable iterator pointing to the beginning of the stored atom/bond mapping objects.

Returns: A mutable iterator pointing to the beginning of the stored atom/bond mapping objects.

◆ getMappingsBegin() [2/2]

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

Returns a constant iterator pointing to the beginning of the stored atom/bond mapping objects.

Returns: A constant iterator pointing to the beginning of the stored atom/bond mapping objects.

◆ getMappingsEnd() [1/2]

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

Returns a mutable iterator pointing to the end of the stored atom/bond mapping objects.

Returns: A mutable iterator pointing to the end of the stored atom/bond mapping objects.

◆ getMappingsEnd() [2/2]

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

Returns a constant iterator pointing to the end of the stored atom/bond mapping objects.

Returns: A constant iterator pointing to the end of the stored atom/bond mapping objects.

◆ begin() [1/2]

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

Returns a mutable iterator pointing to the beginning of the stored atom/bond mapping objects.

Returns: A mutable iterator pointing to the beginning of the stored atom/bond mapping objects.

◆ begin() [2/2]

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

Returns a constant iterator pointing to the beginning of the stored atom/bond mapping objects.

Returns: A constant iterator pointing to the beginning of the stored atom/bond mapping objects.

◆ end() [1/2]

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

Returns a mutable iterator pointing to the end of the stored atom/bond mapping objects.

Returns: A mutable iterator pointing to the end of the stored atom/bond mapping objects.

◆ end() [2/2]

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

Returns a constant iterator pointing to the end of the stored atom/bond mapping objects.

Returns: A constant iterator pointing to the end of the stored atom/bond mapping 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 that is invoked for every atom/bond mapping found during findMappings().

Returning false from the callback aborts the search (equivalent to calling stopSearch()).

Parameters

func	The new found-mapping callback.

◆ getFoundMappingCallback()

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

Returns the currently installed found-mapping callback.

Returns: A const reference to the found-mapping callback.

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