Context Managers

Various context managers for manipulating molecules.

Index

`as_array.AsArray`(mol)	A context manager for temporary interconverting between PLAMS molecules and NumPy arrays.
`mol_split_cm.SplitMol`(mol, bond_list[, cap_type])	A context manager for temporary splitting a single molecule into multiple components.
`remove_atoms_cm.RemoveAtoms`(mol, atoms)	A context manager for temporary removing a set of atoms from a molecule.

API

class CAT.attachment.as_array.AsArray(mol)[source]

A context manager for temporary interconverting between PLAMS molecules and NumPy arrays.

Examples

>>> from scm.plams import Molecule

# Create a H2 example molecule
>>> h1 = Atom(symbol='H', coords=(0.0, 0.0, 0.0))
>>> h2 = Atom(symbol='H', coords=(1.0, 0.0, 0.0))
>>> mol = Molecule()
>>> mol.add_atom(h1)
>>> mol.add_atom(h2)

>>> print(mol)  
  Atoms:
    1         H      0.000000      0.000000      0.000000
    2         H      1.000000      0.000000      0.000000


# Example: Translate the molecule along the Cartesian Z-axis by 5 Angstroem
>>> with AsArray(mol) as xyz:
...     xyz[:, 2] += 5

>>> print(mol)  
  Atoms:
    1         H      0.000000      0.000000      5.000000
    2         H      1.000000      0.000000      5.000000

Parameters: mol (plams.Molecule or Iterable [plams.Atom]) – An iterable consisting of PLAMS atoms. See AsArray.mol.

mol

A PLAMS molecule or a sequence of PLAMS atoms.

Type: plams.Molecule or Sequence [plams.Atom]

_xyz

A 2D array with the Cartesian coordinates of mol. Empty by default; this value is set internally by the AsArray.__enter__() method.

Type: \(n*3\) numpy.ndarray [float], optional

class CAT.attachment.mol_split_cm.SplitMol(mol, bond_list, cap_type='H')[source]

A context manager for temporary splitting a single molecule into multiple components.

The context manager splits the provided molecule into multiple components, capping all broken bonds in the process. The exact amount of fragments depends on the number of specified bonds.

These moleculair fragments are returned upon opening the context manager and merged back into the initial molecule once the context manager is closed. While opened, the initial molecule is cleared of all atoms and bonds, while the same hapens to the moleculair fragments upon closing.

Examples

>>> from scm.plams import Molecule, Bond, from_smiles

>>> mol: Molecule = from_smiles('CC')  # Ethane
>>> bond: Bond = mol[1, 2]

# A backup of all bonds and atoms
>>> bonds_backup = mol.bonds.copy()
>>> atoms_backup = mol.atoms.copy()

# The context manager is opened; the bond is removed and the molecule is fragmented
>>> with SplitMol(mol, bond) as fragment_tuple:
...     for fragment in fragment_tuple:
...         fancy_operation(fragment)  
...
...     print(
...         mol.bonds == bonds_backup,
...         mol.atoms == atoms_backup,
...         bond in mol.bonds
...     )
False False False

# The context manager is closed; all atoms and bonds have been restored
>>> print(
...     mol.bonds == bonds_backup,
...     mol.atoms == atoms_backup,
...     bond in mol.bonds
... )
True True True

Parameters

mol (plams.Molecule) – A PLAMS molecule. See SplitMol.mol.
bond_list (plams.Bond or Iterable [plams.Bond]) – An iterable consisting of PLAMS bonds. All bonds must be part of mol. See SplitMol.bonds.
cap_type (str, int or plams.Atom) – An atomic number or symbol of the atom type used for capping the to-be split molecule. See SplitMol.cap_type.

mol

A PLAMS molecule.

Type: plams.Molecule

bonds

A set of PLAMS bonds.

Type: set [plams.Bond]

cap_type

An atomic symbol of the atom type used for capping the to-be split molecule.

Type: str

_at_pairs

A list of dictionaries. Each dictionary contains two atoms as keys (see SplitMol.bond_list) and their respective capping atom as values. Used for reassembling SplitMol.mol once the context manager is closed. Set internally by SplitMol.__enter__().

Type: list [dict [plams.Atom, plams.Atom]], optional

_vars_backup

A backup of all instance variables of SplitMol.mol. Set internally by SplitMol.__enter__().

Type: dict [str, Any], optional

_tmp_mol_list

A list of PLAMS molecules obtained by splitting SplitMol.mol. Set internally by SplitMol.__enter__().

Type: tuple [plams.Molecule], optional

Raises: MoleculeError – Raised when one attempts to access or manipulate the instance variables of SplitMol.mol when the context manager is opened.

class CAT.attachment.remove_atoms_cm.RemoveAtoms(mol, atoms)[source]

A context manager for temporary removing a set of atoms from a molecule.

The relative ordering of the to-be removed atoms (and matching bonds), as specified in atoms, is preserved during the removal and reattachment process. Note that reattaching will (re-)append the removed atoms/bonds, a process which is thus likelly to affect the absolute ordering of atoms/bonds within the entire molecule.

Examples

>>> from scm.plams import Molecule, Atom, from_smiles

>>> mol: Molecule = from_smiles('CO')
>>> atom1: Atom = mol[1]
>>> atom2: Atom = mol[2]

>>> atom_set = {atom1, atom2}
>>> with RemoveAtoms(mol, atom_set):
...     print(atom1 in mol, atom2 in mol)
False False

>>> print(atom1 in mol, atom2 in mol)
True True

Parameters

mol (plams.Molecule) – A PLAMS molecule. See RemoveAtoms.mol.
atoms (plams.Atom or Iterable [plams.Atom]) – A PLAMS atom or an iterable consisting of unique PLAMS atoms. All supplied atoms should belong to mol. See RemoveAtoms.atoms.

mol

A PLAMS molecule.

Type: plams.Molecule

atoms

A sequence of PLAMS atoms belonging to RemoveAtoms.mol. Setting a value will convert it into a sequence of atoms.

Type: Sequence [plams.Atom]

_bonds

A ordered dictionary of PLAMS bonds connected to one or more atoms in RemoveAtoms.atoms. All values are None, the dictionary serving as an improvised OrderedSet. Set to None until RemoveAtoms.__enter__() is called.

Type: OrderedDict [plams.Bond, None]