Models a molecule as a graph (connectivity of atoms) and a list of stereopermutators. More...

#include <Molecule.h>

Inheritance diagram for Scine::Molassembler::Molecule:

Data Structures
struct	Impl

struct	unsafe_tag_t

Public Member Functions
Special member functions
	Molecule (Molecule &&other) noexcept
	Default-constructor creates a hydrogen molecule (H2). More...

Molecule &	operator= (Molecule &&rhs) noexcept
	Default-constructor creates a hydrogen molecule (H2). More...

	Molecule (const Molecule &other)
	Default-constructor creates a hydrogen molecule (H2). More...

Molecule &	operator= (const Molecule &rhs)
	Default-constructor creates a hydrogen molecule (H2). More...

	~Molecule () final
	Default-constructor creates a hydrogen molecule (H2). More...

	Molecule () noexcept
	Default-constructor creates a hydrogen molecule (H2). More...

	Molecule (Utils::ElementType element) noexcept
	Single-element molecule constructor. More...

	Molecule (Utils::ElementType a, Utils::ElementType b, BondType bondType=BondType::Single) noexcept
	Construct a minimal molecule from two element types and a mutual bond type. More...

	Molecule (Graph graph)
	Constructs from connectivity alone, inferring the stereopermutators from graph. More...

	Molecule (Graph graph, const AngstromPositions &positions, const boost::optional< std::vector< BondIndex > > &bondStereopermutatorCandidatesOptional=boost::none)
	Construct from connectivity and positions. More...

	Molecule (Graph graph, const AngstromPositions &positions, const boost::optional< std::vector< BondIndex > > &bondStereopermutatorCandidatesOptional, const PeriodicBoundaryDuplicates &boundaries)
	Default-constructor creates a hydrogen molecule (H2). More...

	Molecule (Graph graph, StereopermutatorList stereopermutators, boost::optional< AtomEnvironmentComponents > canonicalComponentsOption=boost::none)
	Construct a molecule from underlying data fragments. More...

Modifiers
AtomIndex	addAtom (Utils::ElementType elementType, AtomIndex adjacentTo, BondType bondType=BondType::Single) final
	Adds an atom by attaching it to an existing atom. More...

BondIndex	addBond (AtomIndex a, AtomIndex b, BondType bondType=BondType::Single) final
	Adds a bond between two existing atoms. More...

const BondStereopermutator &	addPermutator (const BondIndex &bond, BondStereopermutator::Alignment alignment=BondStereopermutator::Alignment::Eclipsed)
	Add a new BondStereopermutator to the molecule. More...

void	applyPermutation (const std::vector< AtomIndex > &permutation)
	Applies an index permutation to the Molecule state. More...

void	assignStereopermutator (AtomIndex a, const boost::optional< unsigned > &assignmentOption)
	Sets the stereopermutator assignment at a particular atom. More...

void	assignStereopermutator (const BondIndex &edge, const boost::optional< unsigned > &assignmentOption)
	Sets the stereopermutator assignment on a bond. More...

void	assignStereopermutatorRandomly (AtomIndex a, Random::Engine &engine=randomnessEngine())
	Assigns a stereopermutator stereopermutation at random. More...

void	assignStereopermutatorRandomly (const BondIndex &e, Random::Engine &engine=randomnessEngine())
	Assigns a bond stereopermutator to a random assignment. More...

std::vector< AtomIndex >	canonicalize (AtomEnvironmentComponents componentBitmask=AtomEnvironmentComponents::All)
	Transform the molecule to a canonical form. Invalidates all atom and bond indices. More...

void	removeAtom (AtomIndex a) final
	Removes an atom from the graph, including bonds to it. More...

void	removeBond (AtomIndex a, AtomIndex b)
	Removes a bond from the graph. More...

void	removeBond (const BondIndex &bond) final

bool	removePermutator (const BondIndex &bond)
	Removes the BondStereopermutator on a specified edge, if present. More...

bool	setBondType (AtomIndex a, AtomIndex b, BondType bondType) final
	Changes a bond type. Returns whether the bond already existed. More...

void	setElementType (AtomIndex a, Utils::ElementType elementType) final
	Changes an existing atom's element type. More...

void	setShapeAtAtom (AtomIndex a, Shapes::Shape shape)
	Sets the local shape at an atom index. More...

void	thermalizeStereopermutator (AtomIndex a, bool thermalization=true)
	Change the thermalization of an atom stereopermutator. More...

Graph information interface
bool	adjacent (AtomIndex a, AtomIndex b) const final

boost::optional< BondIndex >	bond (AtomIndex a, AtomIndex b) const final

BondType	bondType (const BondIndex &edge) const final

bool	canRemove (AtomIndex a) const final

bool	canRemove (const BondIndex &edge) const final

const Cycles &	cycles () const final

unsigned	degree (AtomIndex a) const final

Utils::ElementType	elementType (AtomIndex a) const final

AtomIndex	V () const final

unsigned	E () const final

Information
boost::optional < AtomEnvironmentComponents >	canonicalComponents () const
	Get which components of the graph have been used in canonicalization. More...

boost::optional< Shapes::Shape >	inferShape (AtomIndex index, const RankingInformation &ranking) const
	Determines what the local shape at a non-terminal atom ought to be based on the underlying graph. More...

std::string	dumpGraphviz () const
	Returns a graphivz string representation of the molecule. More...

const Graph &	graph () const
	Provides read-only access to the graph representation. More...

std::size_t	hash () const
	Hash function for the molecule. More...

const StereopermutatorList &	stereopermutators () const
	Provides read-only access to the list of stereopermutators. More...

StereopermutatorList	inferStereopermutatorsFromPositions (const AngstromPositions &angstromWrapper, const boost::optional< std::vector< BondIndex > > &explicitBondStereopermutatorCandidatesOption=boost::none) const
	Generates stereopermutators from connectivity and positional information. More...

std::string	str () const
	Returns a command-line interface information string.

RankingInformation	rankPriority (AtomIndex a, const std::vector< AtomIndex > &excludeAdjacent={}, const boost::optional< AngstromPositions > &positionsOption=boost::none) const
	Rank substituents of an atom. More...

Comparison
bool	canonicalCompare (const Molecule &other, AtomEnvironmentComponents componentBitmask=AtomEnvironmentComponents::All) const
	Modular comparison of this Molecule with another, assuming that both are in a canonical form. More...

boost::optional< std::vector < AtomIndex > >	modularIsomorphism (const Molecule &other, AtomEnvironmentComponents componentBitmask) const
	Modular comparison of this Molecule with another. More...

Operators
bool	operator== (const Molecule &other) const
	Equality operator, performs most strict equality comparison. More...

bool	operator!= (const Molecule &other) const
	Inverts Molecule::operator ==.

Modification
Information

Static Public Member Functions
Static functions
static Utils::AtomCollection	applyCanonicalizationMap (const std::vector< AtomIndex > &canonicalizationIndexMap, const Utils::AtomCollection &atomCollection)
	Applies a canonicalization index mapping to an atom collection. More...

Private Attributes
std::unique_ptr< Impl >	pImpl_

Unsafe, no propagation on mutation interface. Here be dragons!
static constexpr unsafe_tag_t	unsafe_tag {}

StereopermutatorList &	stereopermutators (unsafe_tag_t)

Graph &	graph (unsafe_tag_t)

void	propagate (unsafe_tag_t)

Detailed Description

Models a molecule as a graph (connectivity of atoms) and a list of stereopermutators.

This class models chemical molecules as a combination of a graph and a list of stereopermutators.

In the graph, vertices additionally store an element type (and thus represent atoms) and edges store a discretized bond type (and therefore represent bonds).

Stereopermutators represent the absolute configuration at an atom or bond in an abstract fashion and do not store coordinate information.

Note

You may be surprised to see that all basic editing of Molecules, even if it seems to concern the graph only, happens in this class interface. That is because a graph edit may affect rankings at any stereopermutators in the molecule due to the algorithm by which substituents are ranked. This means that for every tiny edit, all stereopermutator substituents are re-ranked and chiral state, if present, is propagated through a possible ranking change. For that, the list of stereopermutators is required, which is accessible only in this class.

Some explanation is required to qualify the complexity guarantees. It is assumed that graphs are sparse, i.e. the average number of substituents at any atom does not grow with the number of atoms in the graph. Any function linear in the number of an atom's substituents is therefore of constant complexity. The variables used in the complexity notations are:

V = number of atoms/vertices
E = number of bonds/edges
A = number of atom stereopermutators
B = number of bond stereopermutators

The notations used are the Bachmann-Landau notations:

\(O\) implies that the function grows asymptotically no faster than
\(\Theta\) implies that the function grow asymptotically as fast as
\(\Omega\) implies that the function grows asympotically at least as fast as (Knuth definition)

Constructor & Destructor Documentation

Scine::Molassembler::Molecule::Molecule ( Molecule && other )

noexcept

Default-constructor creates a hydrogen molecule (H2).

Complexity \(\Theta(1)\)

Scine::Molassembler::Molecule::Molecule ( const Molecule & other )

Default-constructor creates a hydrogen molecule (H2).

Complexity \(\Theta(1)\)

Scine::Molassembler::Molecule::~Molecule ( )

final

Default-constructor creates a hydrogen molecule (H2).

Complexity \(\Theta(1)\)

Scine::Molassembler::Molecule::Molecule ( )

noexcept

Default-constructor creates a hydrogen molecule (H2).

Complexity \(\Theta(1)\)

Scine::Molassembler::Molecule::Molecule ( Utils::ElementType element )

noexcept

Single-element molecule constructor.

Complexity \(\Theta(1)\)

Scine::Molassembler::Molecule::Molecule	(	Utils::ElementType	a,
		Utils::ElementType	b,
		BondType	bondType = `BondType::Single`
	)

noexcept

Construct a minimal molecule from two element types and a mutual bond type.

Complexity \(\Theta(1)\)

Scine::Molassembler::Molecule::Molecule ( Graph graph )

explicit

Constructs from connectivity alone, inferring the stereopermutators from graph.

Constructs a molecule from connectivity alone. Local shapes and stereopermutators are inferred from the graph alone.

Complexity \(O(V + E)\) in rankings and stereopermutator instantiations

Exceptions

std::logic_error If the supplied graph has multiple connected components or there are less than 2 atoms

Scine::Molassembler::Molecule::Molecule	(	Graph	graph,
		const AngstromPositions &	positions,
		const boost::optional< std::vector< BondIndex > > &	bondStereopermutatorCandidatesOptional = `boost::none`
	)

Construct from connectivity and positions.

Construct an instance from a constituting graph and positional information. Local shapes are deduced from positional information. Stereopermutators are inferred from the graph and assigned using the supplied positional information.

Complexity \(O(V + B)\) where \(B\) is the number of candidate bonds for bond stereopermutators

Parameters

graph	The graph from which to construct the molecule
positions	Atom positions to use for the classification of shapes and interpretation of stereopermutators
bondStereopermutatorCandidatesOptional	If boost::none, all bonds are candidates for BondStereopermutator. Otherwise, only the specified bonds are checked for BondStereopermutators.

Exceptions

std::logic_error If the supplied graph has multiple connected components or there are less than 2 atoms

Scine::Molassembler::Molecule::Molecule	(	Graph	graph,
		const AngstromPositions &	positions,
		const boost::optional< std::vector< BondIndex > > &	bondStereopermutatorCandidatesOptional,
		const PeriodicBoundaryDuplicates &	boundaries
	)

Default-constructor creates a hydrogen molecule (H2).

Complexity \(\Theta(1)\)

Scine::Molassembler::Molecule::Molecule	(	Graph	graph,
		StereopermutatorList	stereopermutators,
		boost::optional< AtomEnvironmentComponents >	canonicalComponentsOption = `boost::none`
	)

Construct a molecule from underlying data fragments.

Complexity \(\Theta(1)\)

Exceptions

std::logic_error If the supplied graph has multiple connected components or there are less than 2 atoms

Warning: This function is not intended for library consumers. It is used internally in implementation details.

Member Function Documentation

AtomIndex Scine::Molassembler::Molecule::addAtom	(	Utils::ElementType	elementType,
		AtomIndex	adjacentTo,
		BondType	bondType = `BondType::Single`
	)

finalvirtual

Adds an atom by attaching it to an existing atom.

Adds a new atom, attaching it to an existing atom by a specified bond type.

Complexity Factorial in size of the new shape at adjacentTo and linear in re-rankings and propagations of non-terminal positions

Parameters

elementType	The element type of the new atom
adjacentTo	The atom to which the new atom is to be attached
bondType	The bond type with which the new atom is to be attached

Exceptions

std::out_of_range If adjacentTo is invalid, i.e. >= V()

Note: Any molecular edit causes a full re-rank at each non-terminal atom, and can lead to changes in the list of stereopermutators. Stereopermutators may disappear, change their assignment and number of assignments, or new stereopermutators can appear as a consequence of the most minor edit. For procedural safety, consider iterators to StereopermutatorList members and any stereopermutator state stored external to a Molecule instance and its members invalidated.

Implements Scine::Molassembler::GraphInterface.

BondIndex Scine::Molassembler::Molecule::addBond	(	AtomIndex	a,
		AtomIndex	b,
		BondType	bondType = `BondType::Single`
	)

finalvirtual

Adds a bond between two existing atoms.

Adds a bond between two already-existing atoms.

Complexity Factorial in size of the larger new shape at either end of the bond and linear in re-rankings and propagations of non-terminal positions

Parameters

a	The first atom index
b	The second atom index
bondType	The bond type with which to connect a and b.

Exceptions

std::out_of_range	If either atom index is invalid, i.e. >= V()
std::logic_error	If the atom indices match or the edge already exists.

Note: Any molecular edit causes a full re-rank at each non-terminal atom, and can lead to changes in the list of stereopermutators. Stereopermutators may disappear, change their assignment and number of assignments, or new stereopermutators can appear as a consequence of the most minor edit. For procedural safety, consider iterators to StereopermutatorList members and any stereopermutator state stored external to a Molecule instance and its members invalidated.

Implements Scine::Molassembler::GraphInterface.

const BondStereopermutator& Scine::Molassembler::Molecule::addPermutator	(	const BondIndex &	bond,
		BondStereopermutator::Alignment	alignment = `BondStereopermutator::Alignment::Eclipsed`
	)

Add a new BondStereopermutator to the molecule.

Returns: A reference to the added stereopermutator

Exceptions

If	there is already a bond stereopermutator present

static Utils::AtomCollection Scine::Molassembler::Molecule::applyCanonicalizationMap	(	const std::vector< AtomIndex > &	canonicalizationIndexMap,
		const Utils::AtomCollection &	atomCollection
	)

static

Applies a canonicalization index mapping to an atom collection.

Parameters

canonicalizationIndexMap	Index mapping received from a molecule canonicalization operation
atomCollection	the atom collection to permute

Returns: A permuted atom collection

void Scine::Molassembler::Molecule::applyPermutation ( const std::vector< AtomIndex > & permutation )

Applies an index permutation to the Molecule state.

Complexity \(\Theta(V + A + B)\)

Parameters

permutation A vertex permutation

void Scine::Molassembler::Molecule::assignStereopermutator	(	AtomIndex	a,
		const boost::optional< unsigned > &	assignmentOption
	)

Sets the stereopermutator assignment at a particular atom.

This sets the stereopermutator assignment at a specific atom index. For this, a stereopermutator must be instantiated and contained in the StereopermutatorList returned by stereopermutators(). The supplied assignment must be either boost::none or smaller than stereopermutatorPtr->numAssignments().

Complexity \(O(V)\) re-rankings and state propagations

Parameters

a	The atom index at which a stereopermutator is to be assigned.
assignmentOption	The new assignment. The special value boost::none makes the stereopermutator indeterminate. Any indeterminate atom stereopermutators in a molecule at conformation-generation will be assigned with a probability according to their sterepermutation's relative statistical occurence.

Exceptions

std::out_of_range If the atom index is invalid, i.e. >= V(), there is no stereopermutator at this position or the assignment index is invalid.

Note: Any molecular edit causes a full re-rank at each non-terminal atom, and can lead to changes in the list of stereopermutators. Stereopermutators may disappear, change their assignment and number of assignments, or new stereopermutators can appear as a consequence of the most minor edit. For procedural safety, consider iterators to StereopermutatorList members and any stereopermutator state stored external to a Molecule instance and its members invalidated.

void Scine::Molassembler::Molecule::assignStereopermutator	(	const BondIndex &	edge,
		const boost::optional< unsigned > &	assignmentOption
	)

Sets the stereopermutator assignment on a bond.

This sets the stereopermutator assignment at a specific bond index. For this, a stereopermutator must be instantiated and contained in the StereopermutatorList returned by stereopermutators(). The supplied assignment must be either boost::none or smaller than stereopermutatorPtr->numAssignments().

Complexity \(O(V)\) re-rankings and state propagations

Parameters

edge	The edge at which a stereopermutator is to be assigned.
assignmentOption	The new assignment. The special value boost::none makes the stereopermutator indeterminate. Any indeterminate bond stereopermutators in a molecule at conformation-generation will be assigned randomly.

Exceptions

std::out_of_range If the BondIndex is invalid (i.e. either atom index >= V()), there is no bond stereopermutator at the supplied edge or the assignment index is invalid.

Note: Any molecular edit causes a full re-rank at each non-terminal atom, and can lead to changes in the list of stereopermutators. Stereopermutators may disappear, change their assignment and number of assignments, or new stereopermutators can appear as a consequence of the most minor edit. For procedural safety, consider iterators to StereopermutatorList members and any stereopermutator state stored external to a Molecule instance and its members invalidated.

void Scine::Molassembler::Molecule::assignStereopermutatorRandomly	(	AtomIndex	a,
		Random::Engine &	engine = `randomnessEngine()`
	)

Assigns a stereopermutator stereopermutation at random.

This sets the stereopermutator assignment at a specific index, taking relative statistical occurence weights of each stereopermutation into account.

Complexity \(O(V)\) re-rankings and state propagations

Parameters

a	The atom index at which the atom stereopermutator is to be assigned randomly
engine	The PRNG engine to use for random assignment. Defaults to the library-global random number generator engine

Exceptions

std::out_of_range If the atom index is invalid (i.e. is >= V()) or there is no atom stereopermutator at this bond index.

Note: Any molecular edit causes a full re-rank at each non-terminal atom, and can lead to changes in the list of stereopermutators. Stereopermutators may disappear, change their assignment and number of assignments, or new stereopermutators can appear as a consequence of the most minor edit. For procedural safety, consider iterators to StereopermutatorList members and any stereopermutator state stored external to a Molecule instance and its members invalidated.; This function advances the state of the global PRNG by default if the default argument for engine is chosen.

void Scine::Molassembler::Molecule::assignStereopermutatorRandomly	(	const BondIndex &	e,
		Random::Engine &	engine = `randomnessEngine()`
	)

Assigns a bond stereopermutator to a random assignment.

Parameters

e	The bond index at which to randomly assign a bond stereopermutator
engine	The PRNG engine to use for random assignment. Defaults to the library-global random number generator engine

Complexity \(O(V)\) re-rankings and state propagations

Exceptions

std::out_of_range If the bond index is invalid (i.e. either atom index is >= V()) or there is no bond stereopermutator at this bond index.

Note: Any molecular edit causes a full re-rank at each non-terminal atom, and can lead to changes in the list of stereopermutators. Stereopermutators may disappear, change their assignment and number of assignments, or new stereopermutators can appear as a consequence of the most minor edit. For procedural safety, consider iterators to StereopermutatorList members and any stereopermutator state stored external to a Molecule instance and its members invalidated.; This function advances the state of the global PRNG by default if the default argument for engine is chosen.

bool Scine::Molassembler::Molecule::canonicalCompare	(	const Molecule &	other,
		AtomEnvironmentComponents	componentBitmask = `AtomEnvironmentComponents::All`
	)		const

Modular comparison of this Molecule with another, assuming that both are in a canonical form.

Complexity \(O(V)\)

Parameters

other	The other canonical molecule to compare against
componentBitmask	The components of an atom's environment to include in the comparison. You should use the same componentBitmask as when canonicalizing the molecules you are comparing here. It may be possible to use a bitmask with fewer components, but certainly not one with more. May not be None.

Returns: Whether the molecules are identical (i.e. a special case of isomorphism in which the vertex mapping is an identity permutation)

Exceptions

std::logic_error If componentBitmask contains more components than have been used to canonicalize this molecule instance or other.

boost::optional<AtomEnvironmentComponents> Scine::Molassembler::Molecule::canonicalComponents ( ) const

Get which components of the graph have been used in canonicalization.

Complexity \(\Theta(1)\)

std::vector<AtomIndex> Scine::Molassembler::Molecule::canonicalize ( AtomEnvironmentComponents componentBitmask = AtomEnvironmentComponents::All )

Transform the molecule to a canonical form. Invalidates all atom and bond indices.

Complexity Theoretically the algorithm falls into the exponential class, but for typical molecules much faster.

Parameters

componentBitmask The components of the molecular graph to include in the canonicalization procedure.

Warning: This invalidates all atom indices and bond indices and any references to constituting members of the molecule.

Note: Use Molecule::canonicalCompare to compare instances of canonicalized molecules. If you are using the default value for componentBitmask, Molecule::operator == has a shortcut for fully canonical molecules.

Postcondition: A call to canonicalComponents() yields components supplied here.

Returns: Permutation mapping from old indices to new:
auto indexMapping = mol.canonicalize();

AtomIndex newIndex = indexMapping.at(oldIndex);

You can use this to update invalidated indices.

std::string Scine::Molassembler::Molecule::dumpGraphviz ( ) const

Returns a graphivz string representation of the molecule.

Complexity \(\Theta(V + E + A + B)\)

Creates a graphviz representation of a molecule that can be written into a dotfile and processed with graphviz's dot binary to create an image of the molecular graph.

Includes tooltip information on stereopermutators when hovering over individual nodes.

const Graph& Scine::Molassembler::Molecule::graph ( ) const

Provides read-only access to the graph representation.

Complexity \(\Theta(1)\)

std::size_t Scine::Molassembler::Molecule::hash ( ) const

Hash function for the molecule.

Convolutional hash including only the currently canonical components.

Warning: Remember that comparing hashes is not a viable alternative for comparing molecules. If molecules have different hashes, they are certainly different, but even if their hashes match, they are not definitively the same due to the reduction of information.; Do not compare hashes between molecules with different values of canonicalComponents().

Exceptions

std::logic_error If the molecule is acanonical, i.e. canonicalComponents() is None

Returns: A convolutional hash of the currently canonical components.

boost::optional<Shapes::Shape> Scine::Molassembler::Molecule::inferShape	(	AtomIndex	index,
		const RankingInformation &	ranking
	)		const

Determines what the local shape at a non-terminal atom ought to be based on the underlying graph.

Complexity \(\Theta(1)\) currently since only basic VSEPR is implemented

Returns the expected shape name at a non-terminal atom by inference from graph information only.

Can be extended to apply various levels of theory to determine the shape based on various information contained in the graph, such as ligand field theory.

Parameters

index	The atom index where the local shape should be determined
ranking	The ranking of all substituents at the supplied index. See rankPriority()

Returns: A local shape (of the appropriate size to fit the number of ligand sites) which may or may not be the shape with the lowest energy.

Exceptions

std::out_of_range	If the supplied atomic index is >= V()
std::logic_error	If the supplied atom is terminal or if the amount of ligand sites exceeds the size of the largest defined shape.

Note: Currently applies VSEPR if the element type at the supplied index is not a transition metal, and returns the first shape of appropriate size otherwise.

StereopermutatorList Scine::Molassembler::Molecule::inferStereopermutatorsFromPositions	(	const AngstromPositions &	angstromWrapper,
		const boost::optional< std::vector< BondIndex > > &	explicitBondStereopermutatorCandidatesOption = `boost::none`
	)		const

Generates stereopermutators from connectivity and positional information.

Positions are an important source of information for stereopermutators as they will alleviate graph-based shape-determination errors and allow for the determination of stereopermutator assignments through spatial fitting.

Complexity \(\Theta(S!)\) where \(S\) is the largest shape size fitted

Parameters

angstromWrapper	Wrapped positions in angstrom length units
explicitBondStereopermutatorCandidatesOption	Permits the specification of a limited set of bonds on which BondStereopermutator instantiation is attempted. In Interpret.h, for instance, you can choose not to instantiate BondStereopermutators below a fractional bond order threshold to avoid spurious frozen dihedrals. By default, all bonds are candidates.

Exceptions

std::out_of_range if a BondIndex in explicitBondStereopermutatorCandidatesOption does not reference an existing bond (irrelevant if left default).

boost::optional<std::vector<AtomIndex> > Scine::Molassembler::Molecule::modularIsomorphism	(	const Molecule &	other,
		AtomEnvironmentComponents	componentBitmask
	)		const

Modular comparison of this Molecule with another.

This permits detailed specification of which elements of the molecular information you want to use in the comparison.

At each atom position, a hash is computed that encompasses all local information that is specified to be used in componentsBitmask. This hash is then used during graph isomorphism calculation to avoid finding an isomorphism that does not consider the specified factors.

Complexity \(O(V_1 \cdot V_2)\)

Parameters

other	The other molecule to compare against
componentBitmask	Components of an atom's environment to include in isomorphism tests. May not be None.

Returns: None if the molecules are not isomorphic. Returns an index mapping from this to other if the molecules are isomorphic.

Note: The number of stereopermutations that a stereopermutator has is considered part of the shape ComparisonOptions.; If you choose to discard bond order checking, this merely deactivates bond order hashing and a post-isomorphism-search bond order re-check. Bond order information - if present in the molecule prior to calling this function - is also present in stereopermutator ranking information and hence can influence the number of stereopermutations and the currently set stereopermutation index. This can lead to unexpected but logically consistent comparison behavior.; This function forwards to canonicalCompare if compentBitmask matches the canonical components of both molecules involved.

Molecule& Scine::Molassembler::Molecule::operator= ( Molecule && rhs )

noexcept

Default-constructor creates a hydrogen molecule (H2).

Complexity \(\Theta(1)\)

Molecule& Scine::Molassembler::Molecule::operator= ( const Molecule & rhs )

Default-constructor creates a hydrogen molecule (H2).

Complexity \(\Theta(1)\)

bool Scine::Molassembler::Molecule::operator== ( const Molecule & other ) const

Equality operator, performs most strict equality comparison.

If both molecule instances are fully canonical, calls canonicalCompare(). Otherwise calls modularIsomorphism().

Implemented as

if(
  canonicalComponents() == AtomEnvironmentComponents::All
  && other.canonicalComponents() == AtomEnvironmentComponents::All
) {
  return canonicalCompare(other, AtomEnvironmentComponents::All);
}
return modularIsomorphism(other, AtomEnvironmentComponents::All);

RankingInformation Scine::Molassembler::Molecule::rankPriority	(	AtomIndex	a,
		const std::vector< AtomIndex > &	excludeAdjacent = `{}`,
		const boost::optional< AngstromPositions > &	positionsOption = `boost::none`
	)		const

Rank substituents of an atom.

Performs a ranking algorithm that attempts to differentiate branches extending at each substituent atom (haptic ligands are not considered a single unit, rather their component atoms are all individual substituents).

Groups substituents into ligands (these are not the same since haptic ligands exist) and ranks those too.

Complexity Theoretically unclear, but for typical cases constant time.

Parameters

a	The atom whose substituents are to be ranked
excludeAdjacent	A list of substituent atom indices that should be excluded from ranking
positionsOption	Positional information can be used to determine auxiliary stereopermutator assignments that arise in the ranking algorithm and may have different sub-rankings than at the same position in the molecule considered on its own. It is preferable to supply this if positional information is present!

Exceptions

std::out_of_range If the supplied atom index is i.e. >= V()

Returns: a RankingInformation instance that contains all gathered information.

void Scine::Molassembler::Molecule::removeAtom ( AtomIndex a )

finalvirtual

Removes an atom from the graph, including bonds to it.

Removes an atom from the molecular graph, including bonds to the atom, after checking that removing it is safe, i.e. the removal does not disconnect the graph.

Complexity \(O(V + A + B)\) stereopermutator updates, re-rankings and propagations

Exceptions

std::out_of_range	If the supplied index is invalid, i.e. >= V()
std::logic_error	If removing the atom disconnects the graph or removes the final atom.

Warning: Invalidates all atom indices due to renumbering

Note: Any molecular edit causes a full re-rank at each non-terminal atom, and can lead to changes in the list of stereopermutators. Stereopermutators may disappear, change their assignment and number of assignments, or new stereopermutators can appear as a consequence of the most minor edit. For procedural safety, consider iterators to StereopermutatorList members and any stereopermutator state stored external to a Molecule instance and its members invalidated.

Implements Scine::Molassembler::GraphInterface.

void Scine::Molassembler::Molecule::removeBond	(	AtomIndex	a,
		AtomIndex	b
	)

Removes a bond from the graph.

Removes a bond after checking if removing that bond is safe, i.e. does not disconnect the graph. An example of bonds that can always be removed are ring-closing bonds, since they never disconnect the molecular graph.

Complexity \(O(V + A + B)\) stereopermutator updates, re-rankings and propagations

Exceptions

std::out_of_range	If the supplied bond index is invalid, i.e. either atom index >= V() or the specified bond does not exist.
std::logic_error	If graph().canRemove() returns false.

Note: It is not safe to remove a bond just because one of the involved atoms is terminal, since that atom would then be disconnected from the rest of the molecule. This function merely removes a bond from the graph. It is, however, considered safe to remove the terminal vertex, which involves removing the bond to it.; Any molecular edit causes a full re-rank at each non-terminal atom, and can lead to changes in the list of stereopermutators. Stereopermutators may disappear, change their assignment and number of assignments, or new stereopermutators can appear as a consequence of the most minor edit. For procedural safety, consider iterators to StereopermutatorList members and any stereopermutator state stored external to a Molecule instance and its members invalidated.

void Scine::Molassembler::Molecule::removeBond ( const BondIndex & bond )

finalvirtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Implements Scine::Molassembler::GraphInterface.

bool Scine::Molassembler::Molecule::removePermutator ( const BondIndex & bond )

Removes the BondStereopermutator on a specified edge, if present.

Returns: Whether a permutator was deleted

bool Scine::Molassembler::Molecule::setBondType	(	AtomIndex	a,
		AtomIndex	b,
		BondType	bondType
	)

finalvirtual

Changes a bond type. Returns whether the bond already existed.

Changes the bond type between two atom indices. If the bond does not exist yet, adds the bond.

Complexity \(\Theta(V)\) re-rankings and propagations

Parameters

a	The first index of the bond whose type should be changed
b	The second index of the bond whose type should be changed
bondType	The new bond type

Returns: If the bond already existed.

Exceptions

out_of_range	If a or b are invalid, i.e. >= V()
std::logic_error	If bondType is specified as BondType::Eta. The representation of bonding to haptic ligands and its dynamism is handled internally.

Note: Any molecular edit causes a full re-rank at each non-terminal atom, and can lead to changes in the list of stereopermutators. Stereopermutators may disappear, change their assignment and number of assignments, or new stereopermutators can appear as a consequence of the most minor edit. For procedural safety, consider iterators to StereopermutatorList members and any stereopermutator state stored external to a Molecule instance and its members invalidated.

Implements Scine::Molassembler::GraphInterface.

void Scine::Molassembler::Molecule::setElementType	(	AtomIndex	a,
		Utils::ElementType	elementType
	)

finalvirtual

Changes an existing atom's element type.

Changes the element type of an existing atom.

Complexity \(\Theta(V)\) re-rankings and propagations

Parameters

a	The atom index of the atom whose element type is to be changed
elementType	The new element type

Exceptions

std::out_of_range If a is invalid >= V()

Note: Any molecular edit causes a full re-rank at each non-terminal atom, and can lead to changes in the list of stereopermutators. Stereopermutators may disappear, change their assignment and number of assignments, or new stereopermutators can appear as a consequence of the most minor edit. For procedural safety, consider iterators to StereopermutatorList members and any stereopermutator state stored external to a Molecule instance and its members invalidated.

Implements Scine::Molassembler::GraphInterface.

void Scine::Molassembler::Molecule::setShapeAtAtom	(	AtomIndex	a,
		Shapes::Shape	shape
	)

Sets the local shape at an atom index.

This sets the local shape at a specific atom index. There are a number of cases that this function treats differently, besides faulty arguments: If there is already a AtomStereopermutator instantiated at this atom index, its underlying shape is altered. If there is no AtomStereopermutator at this index, one is instantiated. In all cases, new or modified stereopermutators are default-assigned if there is only one possible assignment.

Complexity \(\Theta(V)\) re-rankings and propagations

Exceptions

std::out_of_range	if the supplied atomic index is invalid
std::logic_error	if the provided shape is a different size than that of the existing AtomStereopermutator

Note: Any molecular edit causes a full re-rank at each non-terminal atom, and can lead to changes in the list of stereopermutators. Stereopermutators may disappear, change their assignment and number of assignments, or new stereopermutators can appear as a consequence of the most minor edit. For procedural safety, consider iterators to StereopermutatorList members and any stereopermutator state stored external to a Molecule instance and its members invalidated.

const StereopermutatorList& Scine::Molassembler::Molecule::stereopermutators ( ) const

Provides read-only access to the list of stereopermutators.

Complexity \(\Theta(1)\)

void Scine::Molassembler::Molecule::thermalizeStereopermutator	(	AtomIndex	a,
		bool	thermalization = `true`
	)

Change the thermalization of an atom stereopermutator.

Enables or disables the thermalization of the stereopermutations of an atom stereopermutator. When enabled, a stereopermutator is no longer a stereocenter and has only a single assignment. In conformer generation, a particular stereopermutation is chosen at random.

Exceptions

std::out_of_range if the supplied atom index is invalid or there is no atom stereopermutator at that atom

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

Molassembler/Molecule.h

Data Structures

Public Member Functions

Static Public Member Functions

Private Attributes

Unsafe, no propagation on mutation interface. Here be dragons!

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation