ccu.workflows.scan

This module defines the bond scan workflow.

Example

Relaxation using an ASE Optimizer

import logging

from ase.build import molecule
from ase.calculators.emt import EMT
from ccu.workflows.calculation import run_molecular_bond_scan

logging.basicConfig(level=logging.DEBUG)

atoms = molecule("CO2")
atoms.calc = EMT()
run_calculation(atoms, opt=opt, fmax=0.01, steps=10)
class ccu.workflows.scan.BondScanParams(a0: int, a1: int, mask: list[bool] | None = None, indices: list[int] | None = None, fix: float = 0.0, bond_lims: tuple[float, float] = (0.7, 4.0))[source]

Bases: NamedTuple

Parameters for modifying bond scans.

a0, a1, mask, indices, and fix map to the parameters in set_distance`(). bond_lims specifies the minimum and maximum bond lengths for the bond scan. The endpoint may be excluded if the scan step does not evenly divide the difference between the minimum and maximum bond lengths.

Create new instance of BondScanParams(a0, a1, mask, indices, fix, bond_lims)

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {'bond_lims': (0.7, 4.0), 'fix': 0.0, 'indices': None, 'mask': None}
_fields = ('a0', 'a1', 'mask', 'indices', 'fix', 'bond_lims')
classmethod _make(iterable)

Make a new BondScanParams object from a sequence or iterable

_replace(**kwds)

Return a new BondScanParams object replacing specified fields with new values

a0: int

Alias for field number 0

a1: int

Alias for field number 1

bond_lims: tuple[float, float]

Alias for field number 5

fix: float

Alias for field number 4

indices: list[int] | None

Alias for field number 3

mask: list[bool] | None

Alias for field number 2

ccu.workflows.scan._remove_existing_bond_lengths(filename: Path, a0: int, a1: int, bond_lengths: list[float], scan_step: float) → tuple[list[float], list[Atoms]][source]
ccu.workflows.scan.get_bond_scan_parameters(atoms: Atoms, *, cutoffs: list[float] | None = None) → list[BondScanParams][source]

Determine all bonded pairs and corresponding bond scan parameters.

Parameters:

  • atoms – An Atoms object.

  • cutoffs – A list of cutoff radii used to determine which atoms are bonded.

Returns:

A list of bond modification parameters suitable for the bonds parameter of run_molecular_bond_scans().

Warns:

UserWarning – Bonded atoms are not bond-separable.

Notes

Two atoms in a molecule are bond-separable if the distance between them can be increased without affecting the bond lengths of any other bonds in the molecule. In graph theory terms, this means that both atoms are articulation points in the graph representation of the molecule.

Bond scan parameters are defined to preferentially fix the more bonded atom in the bond.

Example: Stretch an intramolecular bond while preserving other bond lengths

>>> from ccu.adsorption.adsorbates import get_adsorbate
>>> from ccu.workflows.scan import get_bond_scan_parameters

>>> hcooh = get_adsorbate("HCOOH")
>>> bp = get_bond_scan_parameters(hcooh)[0]

# This atom should move together with bp.a1

>>> moving = next(a for a in bp.indices if a not in (bp.a0, bp.a1))
>>> d1 = hcooh.get_distance(bp.a0, bp.a1)
>>> d2 = hcooh.get_distance(bp.a1, moving)
>>> hcooh.set_distance(bp.a0, bp.a1, d1 * 2, indices=bp.indices)
>>> hcooh.get_distance(bp.a0, bp.a1) == d1 * 2
True
>>> d2 == hcooh.get_distance(bp.a1, moving)
True
ccu.workflows.scan.run_molecular_bond_scans(atoms: Atoms, calc: Calculator, *, bond_scan_params: list[tuple] | list[BondScanParams] | None = None, scan_step: float = 0.1, write_traj: bool = True, traj_template: str = 'scan_{}_{}.traj') → dict[tuple[int, int], list[Atoms]][source]

Run linear scan calculations for molecular bonds.

Parameters:

  • atoms – An Atoms object for which a hookean constraint is to be parametrized.

  • calc – A preconfigured ASE calculator to use to run the bond scans.

  • bond_scan_params – A list of bond scan parameters specifying which and how bonds will be linearly scanned. Bond scan parameters can be specified as a plain tuple or a BondScanParams instance. If the former, they will be converted into the latter. Defaults to None in which bond scan parameters will be automatically generated using get_bond_scan_parameters().

  • scan_step – The step size (in Angstroms) to use for the linear scan calculations. Defaults to 0.1.

  • write_traj – Whether or not to write trajectory files for each bond scan containing the images for which energies are calculated. Defaults to True.

  • traj_template – A format string to be used to name the trajectory files of each linear scan. The format string must accept two fields, which correspond to the atomic indices of the atoms in the bond for which the linear bond scan is being performed. Defaults to "scan_{}_{}.traj".

Note

This function can resume from a previous call if write_traj=True and the same traj_template string is used. In that case, calculations for bond separations that differ by less than one-tenth of the step size of an existing image will be skipped.

Returns:

A dictionary mapping atomic indices to lists, each atom in the list being the image of a completed step in the linear bond scan specified by the atomic indices.