Subgraph-isomorphism search of a query molecular graph against a target molecular graph, implemented after the VF2 algorithm. More...

Inheritance diagram for CDPL.Chem.SubstructureSearch:

Public Member Functions
None	__init__ ()
	Constructs and initializes a `SubstructureSearch` instance.

None	__init__ (MolecularGraph query)
	Constructs and initializes a `SubstructureSearch` instance for the specified query structure. More...

int	getObjectID ()
	Returns the numeric identifier (ID) of the wrapped C++ class instance. More...

None	setAtomMatchExpressionFunction (AtomMatchExpressionPtrAtomFunctor func)
	Installs a function that resolves the atom-level Chem.MatchExpression for a query atom. More...

None	setBondMatchExpressionFunction (BondMatchExpressionPtrBondFunctor func)
	Installs a function that resolves the bond-level Chem.MatchExpression for a query bond. More...

None	setMolecularGraphMatchExpressionFunction (MolGraphMatchExpressionPtrMolGraphFunctor func)
	Installs a function that resolves the graph-level Chem.MatchExpression for the query molecular graph. More...

bool	mappingExists (MolecularGraph target)
	Tells whether the query structure matches a substructure of the specified target molecular graph. More...

bool	findMappings (MolecularGraph target)
	Searches for all possible atom/bond mappings of the query structure to substructures of the specified target molecular graph. More...

None	stopSearch ()
	Aborts the currently running subgraph mapping search. More...

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

AtomBondMapping	getMapping (int idx)
	Returns a reference to the stored atom/bond mapping object at index idx. More...

None	uniqueMappingsOnly (bool unique)
	Allows to specify whether or not to store only unique atom/bond mappings. More...

bool	uniqueMappingsOnly ()
	Tells whether duplicate atom/bond mappings are discarded. More...

int	getMaxNumMappings ()
	Returns the specified limit on the number of stored atom/bond mappings. More...

None	setMaxNumMappings (int max_num_mappings)
	Allows to specify a limit on the number of stored atom/bond mappings. More...

None	clearAtomMappingConstraints ()
	Clears all previously defined query to target atom mapping constraints. More...

None	addAtomMappingConstraint (int query_atom_idx, int target_atom_idx)
	Adds a constraint on the allowed mappings between query and target structure atoms. More...

None	clearBondMappingConstraints ()
	Clears all previously defined query to target bond mapping constraints. More...

None	addBondMappingConstraint (int query_bond_idx, int target_bond_idx)
	Adds a constraint on the allowed mappings between query and target structure bonds. More...

None	setQuery (MolecularGraph query)
	Allows to specify a new query structure. More...

AtomBondMapping	__getitem__ (int idx)

int	__len__ ()

bool	__nonzero__ (MolecularGraph self)

bool	__bool__ (MolecularGraph self)

Properties
	objectID = property(getObjectID)

	numMappings = property(getNumMappings)

	uniqueMappings = property(uniqueMappingsOnly, uniqueMappingsOnly)

	maxNumMappings = property(getMaxNumMappings, setMaxNumMappings)

Detailed Description

Subgraph-isomorphism search of a query molecular graph against a target molecular graph, implemented after the VF2 algorithm.

Successive calls to setQuery() and findMappings() (or mappingExists() for a yes/no answer) produce all atom/bond mapping solutions; mappings are retrieved through the getMapping*() / begin()-end() iterator pair. Per-atom, per-bond and per-molecular graph match-expression accessor functions can be installed to extend equivalence beyond pure topology (the defaults pull expressions from the Chem.AtomProperty / Chem.BondProperty / Chem.MolecularGraphProperty objects). Result accumulation is bounded by setMaxNumMappings() and uniqueMappingsOnly(); the search can also be aborted from a callback via stopSearch().

See also: [VFLIB2]

Constructor & Destructor Documentation

◆ init()

None CDPL.Chem.SubstructureSearch.__init__ ( MolecularGraph query )

Constructs and initializes a SubstructureSearch instance for the specified query structure.

Parameters

query A molecular graph that represents the query structure.

Member Function Documentation

◆ getObjectID()

int CDPL.Chem.SubstructureSearch.getObjectID ( )

Returns the numeric identifier (ID) of the wrapped C++ class instance.

Different Python SubstructureSearch instances may reference the same underlying C++ class instance. The commonly used Python expression a is not b thus cannot tell reliably whether the two SubstructureSearch instances a and b reference different C++ objects. The numeric identifier returned by this method allows to correctly implement such an identity test via the simple expression a.getObjectID() != b.getObjectID().

Returns: The numeric ID of the internally referenced C++ class instance.

◆ setAtomMatchExpressionFunction()

None CDPL.Chem.SubstructureSearch.setAtomMatchExpressionFunction ( AtomMatchExpressionPtrAtomFunctor func )

Installs a function that resolves the atom-level Chem.MatchExpression for a query atom.

Parameters

func	The accessor function to use.

◆ setBondMatchExpressionFunction()

None CDPL.Chem.SubstructureSearch.setBondMatchExpressionFunction ( BondMatchExpressionPtrBondFunctor func )

Installs a function that resolves the bond-level Chem.MatchExpression for a query bond.

Parameters

func	The accessor function to use.

◆ setMolecularGraphMatchExpressionFunction()

None CDPL.Chem.SubstructureSearch.setMolecularGraphMatchExpressionFunction ( MolGraphMatchExpressionPtrMolGraphFunctor func )

Installs a function that resolves the graph-level Chem.MatchExpression for the query molecular graph.

Parameters

func	The accessor function to use.

◆ mappingExists()

bool CDPL.Chem.SubstructureSearch.mappingExists ( MolecularGraph target )

Tells whether the query structure matches a substructure of the specified target molecular graph.

The method does not store any atom/bond mappings between the query and target structure - it just tells if a complete mapping of the query is possible. If you need access to the atom/bond mappings, use findMappings() instead.

Parameters

target The molecular graph that has to be searched for a match of the query structure.

Returns: True if the query matches a substructure of the target molecular graph, and False otherwise.

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

◆ findMappings()

bool CDPL.Chem.SubstructureSearch.findMappings ( MolecularGraph target )

Searches for all possible atom/bond mappings of the query structure to substructures of the specified target molecular graph.

The method will store all found subgraph mapping solutions up to the maximum number of recorded mappings specified by setMaxNumMappings(). If only unique mappings have to be stored (see uniqueMappingsOnly(bool unique)), any duplicates of previously found mappings will be discarded.

Parameters

target The molecular graph that has to be searched for matches of the query structure.

Returns: True if the query matches at least one substructure of the specified target molecular graph, and False otherwise.

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

◆ stopSearch()

None CDPL.Chem.SubstructureSearch.stopSearch ( )

Aborts the currently running subgraph mapping search.

Intended to be invoked from a callback (typically a match-expression evaluator) running on the same thread as findMappings(); once flagged, findMappings() returns at the next loop boundary.

◆ getNumMappings()

int CDPL.Chem.SubstructureSearch.getNumMappings ( )

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()

AtomBondMapping CDPL.Chem.SubstructureSearch.getMapping ( int idx )

Returns a 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 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].

◆ uniqueMappingsOnly() [1/2]

None CDPL.Chem.SubstructureSearch.uniqueMappingsOnly ( bool unique )

Allows to specify whether or not to store only unique atom/bond mappings.

A mapping of the query pattern to a substructure of the target molecular graph is considered to be unique if it differs from all previously found mappings by at least one atom or bond. If the unique argument is True, and a newly discovered mapping covers the same atoms and bonds of the target (including all permutations) as a mapping that was found earlier in the search process, it is considered as a duplicate and will be discarded.

Parameters

unique If True, only unique mappings will be stored, and all found mappings otherwise.

Note: By default, duplicate mappings are not discarded.

◆ uniqueMappingsOnly() [2/2]

bool CDPL.Chem.SubstructureSearch.uniqueMappingsOnly ( )

Tells whether duplicate atom/bond mappings are discarded.

Returns: True if duplicate mappings are discarded, and False otherwise.

See also: uniqueMappingsOnly(bool unique)

◆ getMaxNumMappings()

int CDPL.Chem.SubstructureSearch.getMaxNumMappings ( )

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()

◆ setMaxNumMappings()

None CDPL.Chem.SubstructureSearch.setMaxNumMappings ( int max_num_mappings )

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

In a call to findMappings() the substructure 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.

◆ clearAtomMappingConstraints()

None CDPL.Chem.SubstructureSearch.clearAtomMappingConstraints ( )

Clears all previously defined query to target atom mapping constraints.

See also: addAtomMappingConstraint()

◆ addAtomMappingConstraint()

None CDPL.Chem.SubstructureSearch.addAtomMappingConstraint	(	int	query_atom_idx,
		int	target_atom_idx
	)

Adds a constraint on the allowed mappings between query and target structure atoms.

By default, an atom of the query structure is free to match any suitable target structure atom. When this method gets called for a particular query/target atom pair (specified by query_atom_idx and target_atom_idx), future substructure searches will find only those subgraph mapping solutions (if any) where the given query atom maps to the specified target structure atom. Multiple calls to addAtomMappingConstraint() for the same query atom have an additive effect and allow to restrict the valid query atom mappings not only to a single but also a larger set of target structure atoms.

Parameters

query_atom_idx	The index of the query structure atom.
target_atom_idx	The index of the target structure atom that has to be matched by the query atom.

◆ clearBondMappingConstraints()

None CDPL.Chem.SubstructureSearch.clearBondMappingConstraints ( )

Clears all previously defined query to target bond mapping constraints.

See also: addBondMappingConstraint()

◆ addBondMappingConstraint()

None CDPL.Chem.SubstructureSearch.addBondMappingConstraint	(	int	query_bond_idx,
		int	target_bond_idx
	)

Adds a constraint on the allowed mappings between query and target structure bonds.

By default, a bond of the query structure is free to match any suitable target structure bond. When this method gets called for a particular query/target bond pair (specified by query_bond_idx and target_bond_idx), future substructure searches will find only those subgraph mapping solutions (if any) where the given query bond maps to the specified target structure bond. Multiple calls to addBondMappingConstraint() for the same query bond have an additive effect and allow to restrict the valid query bond mappings not only to a single but also a larger set of target structure bonds.

Parameters

query_bond_idx	The index of the query structure bond.
target_bond_idx	The index of the target structure bond that has to be matched by the query bond.

◆ setQuery()

None CDPL.Chem.SubstructureSearch.setQuery ( MolecularGraph query )

Allows to specify a new query structure.

Parameters

query A molecular graph that represents the query structure.

◆ getitem()

AtomBondMapping CDPL.Chem.SubstructureSearch.__getitem__ ( int idx )

Parameters

idx

Returns

◆ len()

int CDPL.Chem.SubstructureSearch.__len__ ( )

Returns

◆ nonzero()

bool CDPL.Chem.SubstructureSearch.__nonzero__ ( MolecularGraph self )

Parameters

arg1

Returns

◆ bool()

bool CDPL.Chem.SubstructureSearch.__bool__ ( MolecularGraph self )

Parameters

arg1

Returns

Public Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ getObjectID()

◆ setAtomMatchExpressionFunction()

◆ setBondMatchExpressionFunction()

◆ setMolecularGraphMatchExpressionFunction()

◆ mappingExists()

◆ findMappings()

◆ stopSearch()

◆ getNumMappings()

◆ getMapping()

◆ uniqueMappingsOnly() [1/2]

◆ uniqueMappingsOnly() [2/2]

◆ getMaxNumMappings()

◆ setMaxNumMappings()

◆ clearAtomMappingConstraints()

◆ addAtomMappingConstraint()

◆ clearBondMappingConstraints()

◆ addBondMappingConstraint()

◆ setQuery()

◆ __getitem__()

◆ __len__()

◆ __nonzero__()

◆ __bool__()

◆ init()

◆ getitem()

◆ len()

◆ nonzero()

◆ bool()