Molassembler  3.0.0
Molecule graph and conformer library
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Scine::Molassembler::Molecule Class Referencefinal

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...
 
Moleculeoperator= (Molecule &&rhs) noexcept
 Default-constructor creates a hydrogen molecule (H2). More...
 
 Molecule (const Molecule &other)
 Default-constructor creates a hydrogen molecule (H2). More...
 
Moleculeoperator= (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 BondStereopermutatoraddPermutator (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< AtomIndexcanonicalize (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< BondIndexbond (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 Cyclescycles () 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::ShapeinferShape (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 Graphgraph () const
 Provides read-only access to the graph representation. More...
 
std::size_t hash () const
 Hash function for the molecule. More...
 
const StereopermutatorListstereopermutators () 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< ImplpImpl_
 

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

static constexpr unsafe_tag_t unsafe_tag {}
 
StereopermutatorListstereopermutators (unsafe_tag_t)
 
Graphgraph (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_errorIf 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
graphThe graph from which to construct the molecule
positionsAtom positions to use for the classification of shapes and interpretation of stereopermutators
bondStereopermutatorCandidatesOptionalIf boost::none, all bonds are candidates for BondStereopermutator. Otherwise, only the specified bonds are checked for BondStereopermutators.
Exceptions
std::logic_errorIf 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_errorIf 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
elementTypeThe element type of the new atom
adjacentToThe atom to which the new atom is to be attached
bondTypeThe bond type with which the new atom is to be attached
Exceptions
std::out_of_rangeIf 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
aThe first atom index
bThe second atom index
bondTypeThe bond type with which to connect a and b.
Exceptions
std::out_of_rangeIf either atom index is invalid, i.e. >= V()
std::logic_errorIf 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
Ifthere 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
canonicalizationIndexMapIndex mapping received from a molecule canonicalization operation
atomCollectionthe 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
permutationA 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
aThe atom index at which a stereopermutator is to be assigned.
assignmentOptionThe 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_rangeIf 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
edgeThe edge at which a stereopermutator is to be assigned.
assignmentOptionThe 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_rangeIf 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
aThe atom index at which the atom stereopermutator is to be assigned randomly
engineThe PRNG engine to use for random assignment. Defaults to the library-global random number generator engine
Exceptions
std::out_of_rangeIf 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
eThe bond index at which to randomly assign a bond stereopermutator
engineThe 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_rangeIf 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
otherThe other canonical molecule to compare against
componentBitmaskThe 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_errorIf 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
componentBitmaskThe 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_errorIf 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
indexThe atom index where the local shape should be determined
rankingThe 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_rangeIf the supplied atomic index is >= V()
std::logic_errorIf 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
angstromWrapperWrapped positions in angstrom length units
explicitBondStereopermutatorCandidatesOptionPermits 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_rangeif 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
otherThe other molecule to compare against
componentBitmaskComponents 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
aThe atom whose substituents are to be ranked
excludeAdjacentA list of substituent atom indices that should be excluded from ranking
positionsOptionPositional 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_rangeIf 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_rangeIf the supplied index is invalid, i.e. >= V()
std::logic_errorIf 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_rangeIf the supplied bond index is invalid, i.e. either atom index >= V() or the specified bond does not exist.
std::logic_errorIf 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
aThe first index of the bond whose type should be changed
bThe second index of the bond whose type should be changed
bondTypeThe new bond type
Returns
If the bond already existed.
Exceptions
out_of_rangeIf a or b are invalid, i.e. >= V()
std::logic_errorIf 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
aThe atom index of the atom whose element type is to be changed
elementTypeThe new element type
Exceptions
std::out_of_rangeIf 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_rangeif the supplied atomic index is invalid
std::logic_errorif 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_rangeif 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: