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

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

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]