Interpret

Submodule with freestanding functions yielding Molecule or Graph instances from Cartesian coordinate data (and optionally bond order data).

Bond discretization

In the discretization of fractional bond orders to classic integer internal bond types (e.g. single, double, etc.), there are two options. You can choose to round bond orders to the nearest integer, but this is particularly error prone for particularly weakly-bound metal ligands (around 0.5) and aromatic bonds (around 1.5). For instance, two adjacent aromatic bonds that both show a fractional bond order around 1.5 may be randomly rounded up or down depending on the bond order generation method or its particular conformation. This can cause unexpected ranking inequivalency / equivalency artifacts. If you expect there to be conjugated systems or transition metals in your set of interpreted molecules, discretizing bond orders in this fashion is currently disadvised.

It can instead be preferable to discretize bond orders in a purely binary manner, i.e. bond orders are interpreted as a single bond if the fractional bond order is is more than or equal to 0.5. Double bond stereocenters (i.e. in organic molecules E/Z stereocenters) are still interpreted from coordinate information despite the main bond type discretized to a single bond.

class scine_molassembler.interpret.BondDiscretization

Specifies the algorithm used to discretize floating-point bond orders into discrete bond types.

Members:

Binary : All bond orders >= 0.5 are considered single bonds

RoundToNearest : Round bond orders to nearest integer

Binary = <BondDiscretization.Binary: 0>

RoundToNearest = <BondDiscretization.RoundToNearest: 1>

__init__(self: scine_molassembler.interpret.BondDiscretization, value: int) → None

property name

property value

class scine_molassembler.interpret.ComponentMap

Represents a map from an atom collection to the component molecules

class ComponentIndexPair

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: scine_molassembler.interpret.ComponentMap.ComponentIndexPair, arg0: int, arg1: int) -> None

2. __init__(self: scine_molassembler.interpret.ComponentMap.ComponentIndexPair) -> None

property atom_index

property component

__init__(self: scine_molassembler.interpret.ComponentMap, arg0: List[int]) → None

apply(*args, **kwargs)

Overloaded function.

1. apply(self: scine_molassembler.interpret.ComponentMap, index: int) -> scine_molassembler.interpret.ComponentMap.ComponentIndexPair

   Returns an object like a named tuple of the component and new index after transformation by the map

   >>> m = interpret.ComponentMap([0, 1, 1, 0, 1])
   >>> m.apply(0)
   (component=0, atom_index=0)
   

2. apply(self: scine_molassembler.interpret.ComponentMap, atom_collection: Scine::Utils::AtomCollection) -> List[Scine::Utils::AtomCollection]

   Splits an atom collection just like an interpret split the positions into multiple molecules

   param atom_collection

   The atom collection to split

   rtype

   List of atom collections

invert(*args, **kwargs)

Overloaded function.

1. invert(self: scine_molassembler.interpret.ComponentMap, pair: scine_molassembler.interpret.ComponentMap.ComponentIndexPair) -> int

   Invert a ComponentIndexPair to the original index

   >>> m = interpret.ComponentMap([0, 1, 1, 0, 1])
   >>> pair = m.apply(0)
   >>> m.invert(pair)
   0
   >>> assert all([m.invert(m.apply(a)) == a for a in range(len(m))])
   

2. invert(self: scine_molassembler.interpret.ComponentMap, component: int, atom_index: int) -> int

Two-arg component and atom index inversion convenience function

3. invert(self: scine_molassembler.interpret.ComponentMap, component_index_tuple: Tuple[int, int]) -> int

component and atom index tuple inversion convenience function

4. invert(self: scine_molassembler.interpret.ComponentMap) -> List[List[int]]

   Inverts the component mapping.

   Allows direct determination of the original index of a component’s atom within the coordinate set used in interpretation.

   returns

   A nested list that contains the original indices for each component.

   >>> m = interpret.ComponentMap([0, 1, 1, 0, 1]) # 0->0, 1->1, 2->1, etc.
   >>> m.invert()
   [[0, 3], [1, 2, 4]]
   

class scine_molassembler.interpret.GraphsResult

Result type of a graph interpret call.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

property component_map

Mapping of atom indices from the original positional information to which molecule it is now part.

property graphs

Individual graphs found in the 3D information.

Return type

List of Graph

class scine_molassembler.interpret.MoleculesResult

Result type of a molecule interpret call.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

property component_map

Mapping of atom indices from the original positional information to which molecule it is now part.

property molecules

Individual molecules found in the 3D information.

Return type

List of Molecule

scine_molassembler.interpret.bad_haptic_ligand_bonds(atom_collection: Scine::Utils::AtomCollection, bond_collection: Scine::Utils::BondOrderCollection) → List[scine_molassembler.FalsePositive]

Suggest false positive haptic ligand bonds

Generates a plane of best fit for each haptic ligand in the interpreted graphs. If the angle of the normal of this plane to the axis defined by the central atom and the site centroid is more than 30 degrees, tries to name a single bond whose removal improves the interpretation.

Returns

a list of FalsePositive objects

Note

Suggested bonds can disconnect haptic sites. When making changes to a bond order matrix based on suggestions from this function, apply them one at a time based on the highest probability received. Additionally, if multiple bonds must be removed to make a haptic ligand geometrically reasonable, you will need to iteratively call this function and alter suggested bond orders.

scine_molassembler.interpret.graphs(atom_collection: Scine::Utils::AtomCollection, bond_orders: Scine::Utils::BondOrderCollection, discretization: scine_molassembler.interpret.BondDiscretization) → scine_molassembler.interpret.GraphsResult

Interpret graphs from element types, positional information and bond orders

Attempts to interpret (possibly multiple) graphs from element types, positional information and a bond order collection. Bond orders are discretized into bond types. Connected components within the space are identified and individually instantiated into graphs.

Parameters

• atom_collection – Element types and positional information in Bohr units

• bond_orders – Fractional bond orders

• discretization – How bond fractional orders are to be discretized

Raises

ValueError – If the number of particles in the atom collection and bond order collections do not match

scine_molassembler.interpret.molecules(*args, **kwargs)

Overloaded function.

1. molecules(atom_collection: Scine::Utils::AtomCollection, bond_orders: Scine::Utils::BondOrderCollection, discretization: scine_molassembler.interpret.BondDiscretization, stereopermutator_bond_order_threshold: Optional[float] = 1.4) -> scine_molassembler.interpret.MoleculesResult

   Interpret molecules from element types, positional information and bond orders

   Attempts to interpret (possibly multiple) Molecules from element types, positional information and a bond order collection. Bond orders are discretized into bond types. Connected components within the space are identified and individually instantiated into Molecules. The instantiation of BondStereopermutators in the Molecules can be limited to edges whose bond order exceeds a particular value.

   param atom_collection

   Element types and positional information in Bohr units

   param bond_orders

   Fractional bond orders

   param discretization

   How bond fractional orders are to be discretized

   param stereopermutator_bond_order_threshold

   If specified, limits the instantiation of BondStereopermutators onto edges whose fractional bond orders exceed the provided threshold. If None, BondStereopermutators are instantiated at all bonds.

   raises ValueError

   If the number of particles in the atom collection and bond order collections do not match

   >>> import scine_utilities as utils
   >>> import numpy as np
   >>> elements = [utils.ElementType.H] * 4
   >>> positions = np.array([[0.0, 0.0, 0.0], [0.0, 0.71, 0.0], [2.0, 2.0, 2.0], [2.0, 2.71, 2.0]])
   >>> atoms = utils.AtomCollection(elements, positions)
   >>> bond_orders = utils.BondOrderCollection(4)
   >>> bond_orders.set_order(0, 1, 1.0)
   >>> bond_orders.set_order(2, 3, 1.0)
   >>> discretization = interpret.BondDiscretization.RoundToNearest
   >>> result = interpret.molecules(atoms, bond_orders, discretization)
   >>> assert len(result.molecules) == 2
   >>> hydrogen = Molecule()
   >>> assert all([m == hydrogen for m in result.molecules])
   >>> result.component_map
   [0, 0, 1, 1]
   

2. molecules(atom_collection: Scine::Utils::AtomCollection, discretization: scine_molassembler.interpret.BondDiscretization, stereopermutator_bond_order_threshold: Optional[float] = 1.4) -> scine_molassembler.interpret.MoleculesResult

   Interpret molecules from element types and positional information. Bond orders are calculated with UFF parameters.

   Attempts to interpret (possibly multiple) Molecules from element types and positional information. Bond orders are calculated from atom-pairwise spatial distances by Utils::BondDetector. The bond orders are then discretized into bond types. Connected components within the space are identified and individually instantiated into Molecules. The instantiation behavior of BondStereopermutators in the Molecules can be limited to edges whose bond order exceeds a particular value.

   param atom_collection

   Element types and positional information in Bohr units

   param discretization

   How bond fractional orders are to be discretized

   param stereopermutator_bond_order_threshold

   If specified, limits the instantiation of BondStereopermutators onto edges whose fractional bond orders exceed the provided threshold. If None, BondStereopermutators are instantiated at all bonds.

3. molecules(atom_collection: Scine::Utils::AtomCollection, bond_orders: Scine::Utils::BondOrderCollection, uninteresting_atoms: Set[int], ghost_atom_map: Dict[int, int], discretization: scine_molassembler.interpret.BondDiscretization, stereopermutator_bond_order_threshold: Optional[float] = 1.4) -> scine_molassembler.interpret.MoleculesResult

   Interpret molecules of a periodic system

   Attempts to interpret (possibly multiple) Molecules in a periodic system. The bond orders are discretized into bond types. Connected components within the space are identified and individually instantiated into Molecules. The instantiation behavior of BondStereopermutators in the Molecules can be limited to edges whose bond order exceeds a particular value.

   param atom_collection

   Element types and positional information in Bohr units with ghost atoms

   param bond_orders

   Bond orders including extra bonds to ghost atoms

   param uninteresting_atoms

   List of atoms for which to skip shape classification and stereopermutator instantiation

   param ghost_atom_map

   Map from ghost atom indices to their base atom indices

   param discretization

   How bond fractional orders are to be discretized

   param stereopermutator_bond_order_threshold

   If specified, limits the instantiation of BondStereopermutators onto edges whose fractional bond orders exceed the provided threshold. If None, BondStereopermutators are instantiated at all bonds.

   raises ValueError

   If the number of particles in the atom collection and bond order collections do not match

   Warning

   Ranking across periodic boundaries is incorrect

   Note

   Any molecules interpreted with uninteresting atoms cannot be passed to conformer generation routines

scine_molassembler.interpret.remove_false_positives(atoms: Scine::Utils::AtomCollection, bonds: Scine::Utils::BondOrderCollection) → Scine::Utils::BondOrderCollection

Iteratively removes bonds reported by false positive detection functions

scine_molassembler.interpret.uncertain_bonds(atom_collection: Scine::Utils::AtomCollection, bond_collection: Scine::Utils::BondOrderCollection) → List[scine_molassembler.FalsePositive]

Lists bonds with uncertain shape classifications at both ends

Returns

a list of FalsePositive objects

Warning

Do not alter both bonds if there is a bond pair that have overlapping indices. If suggested bonds overlap, remove only that bond with the higher probability