matscipy.calculators.mcfm.qm_cluster_tools package

Modules

matscipy.calculators.mcfm.qm_cluster_tools.base_qm_cluster_tool

matscipy.calculators.mcfm.qm_cluster_tools.qm_clustering_tool

matscipy.calculators.mcfm.qm_cluster_tools.qm_flagging_tool

matscipy.calculators.mcfm.qm_cluster_tools.base_qm_cluster_tool module

class matscipy.calculators.mcfm.qm_cluster_tools.base_qm_cluster_tool.BaseQMClusterTool(mediator)

Bases: object

Class that hold all the functions common to qm clustering objects

__init__(mediator)

Class that hold all the functions common to qm clustering objects

Parameters:

mediator (matscipy.calculators.mcfm.QMCluster) – class responsible for managing the QM clusters in the simulation

find_neighbours(atoms, index)

Find the neighbours of atom i using self.neighbour_list returns a list of [heavy_neighbours, hydrogen_neighbours]

Parameters:

  • atoms (ase.Atoms object) – structure in which it is necessary to find the neighbours

  • index (int) – atomic index

Returns:

  • list – non-hydrogen neighbours

  • list – hydrogen neighbours

hydrogenate_cluster(atoms, cluster)

Add neigoburing hydrogens to a cluster composed of heavy ions The input should be a set representing heavy ions in a cluster This functions operates on sets

Parameters:

  • atoms (ase.Atoms object) – structure in which it is necessary to find the neighbours

  • cluster (ase.Atoms object) – sub-structure of the larger struct that needs its dangling bonds hydrogenated

Returns:

The original cluster but now hydrogenated

Return type:

ase.Atoms

matscipy.calculators.mcfm.qm_cluster_tools.qm_clustering_tools module

class matscipy.calculators.mcfm.qm_cluster_tools.qm_clustering_tool.QMClusteringTool(mediator=None, double_bonded_atoms_list=[])

Bases: BaseQMClusterTool

This class is responsible for carving and hydrogenating a qm cluster

__init__(mediator=None, double_bonded_atoms_list=[])

This class is responsible for carving and hydrogenating a qm cluster

Parameters:

  • mediator (matscipy.calculators.mcfm.QMCluster) – class responsible for managing the QM clusters in the simulation

  • double_bonded_atoms_list (list) – list of doubly bonded atoms, needed for double hydrogenation.

create_buffer_region(atoms, qm_atoms_list, buffer_hops=10)

GIven a list of active QM atoms, returns a list containing buffer atoms indices

Parameters:

  • atoms (ase.Atoms) – whole structure

  • qm_atoms_list (list of ints (atomic indexes)) – List of atoms in the inner QM region

  • buffer_hops (int) – Expand the cluster by this many neighbour hops to create the buffer

Returns:

  • list of ints (atomic indexes) – buffer_list: List of atoms in the buffer region

  • list of ints (atomic indexes) – terminal_atoms: List of atoms from the buffer region that are on the verge of it

  • list of ints (atomic indexes) – cutoff_atoms_list: List of atoms that are not in the buffer but are bonded to the atoms in the buffer.

carve_cluster(atoms, core_qm_list, buffer_hops=10)

Create a cluster with the list as core atoms, returns an ase.Atoms object

Parameters:

  • atoms (ase.Atoms) – whole structure

  • core_qm_list (list of ints (atomic indexes)) – Indexes of atoms in the core QM region

  • buffer_hops (int) – Expand the cluster by this many neighbour hops to create the buffer

Returns:

atoms object representing the QM cluster including the inner region and the buffer

Return type:

ase.Atoms

hydrogenate_dangling_bonds(terminal_atoms_list, cutoff_atoms_list, atomic_cluster, atoms)

Change atoms that were cut-off into hydrogens

Parameters:

  • terminal_atoms_list (list of ints (atomic indexes)) – last atoms in the buffer region, bonded to the atoms not in the buffer

  • cutoff_atoms_list (list of ints (atomic indexes)) – atoms to be changed into hydrogen, first atoms not in the buffer

  • atomic_cluster (ase.Atoms) – QM region structure (with core and buffer atoms)

  • atoms (ase.Atoms) – whole structure

replace_single_bond(terminal_atom_index, cutoff_atom_index, atomic_cluster, atoms, atomic_positions)

Replace a cut-off atom with a single hydrogen

Parameters:

  • terminal_atoms_list (list of ints (atomic indexes)) – last atoms in the buffer region, bonded to the atoms not in the buffer

  • cutoff_atoms_list (list of ints (atomic indexes)) – atoms to be changed into hydrogen, first atoms not in the buffer

  • atomic_cluster (ase.Atoms) – QM region structure (with core and buffer atoms)

  • atoms (ase.Atoms) – whole structure

  • atomic_positions (np.array) – Positions of atoms in the whole structure (copy of the atoms.positions)

replace_double_bond(terminal_atom_index, cutoff_atom_index, atomic_cluster, atoms, atomic_positions)

Replace a cut-off atom with two hydrogens

Parameters:

  • terminal_atoms_list (list of ints (atomic indexes)) – last atoms in the buffer region, bonded to the atoms not in the buffer

  • cutoff_atoms_list (list of ints (atomic indexes)) – atoms to be changed into hydrogen, first atoms not in the buffer

  • atomic_cluster (ase.Atoms) – QM region structure (with core and buffer atoms)

  • atoms (ase.Atoms) – whole structure

  • atomic_positions (np.array) – Positions of atoms in the whole structure (copy of the atoms.positions)

include_special_atom(specialAtomIndex, atoms, buffer_list, terminal_atoms_list, cutoff_atoms_list)

Add a special atom to the buffer and update indexes. In case a group of special atoms are specified (special molecule), If one of these atoms is in the buffer regios, the rest are also added to it.

Parameters:

  • specialAtomIndex (int (atomic index)) – Add a specified atoms to the buffer

  • atoms (ase.Atoms) – whole structure

  • buffer_list (list of ints (atomic indexes)) – List of atoms in the buffer region

  • terminal_atoms_list (list of ints (atomic indexes)) – last atoms in the buffer region, bonded to the atoms not in the buffer

  • cutoff_atoms_list (list of ints (atomic indexes)) – atoms to be changed into hydrogen, first atoms not in the buffer

complete_aromatic_rings(atoms, buffer_list, terminal_atoms_list, cutoff_atoms_list, total_supplementary_terminal_atoms)

Check if a terminal atom is not connected ot two atoms at once If it is, add it. This deals with aromatic ring structures

Parameters:

  • atoms (ase.Atoms) – whole structure

  • buffer_list (list of ints (atomic indexes)) – List of atoms in the buffer region

  • terminal_atoms_list (list of ints (atomic indexes)) – last atoms in the buffer region, bonded to the atoms not in the buffer

  • cutoff_atoms_list (list of ints (atomic indexes)) – atoms to be changed into hydrogen, first atoms not in the buffer

  • total_supplementary_terminal_atoms (NONE) – atoms added to the buffer to make clusters more physical. Example: last atom in the aromnatic ring

Returns:

Return True if any atoms were added

Return type:

bool

create_cluster_from_marks(atoms, select_list)

Return an ase.Atoms object containing selected atoms from a larger structure

Parameters:

  • atoms (ase.Atoms) – whole structure

  • select_list (list of ints (atomic indexes)) – List of atoms to include in the new structure

Returns:

Structure composed of selected atoms

Return type:

ase.Atoms

print_message(message, limit=100)

Print a message if the calculators verbosity level is above the given threshold

Parameters:

  • message (str) – The message to be printed

  • limit (int) – the verbosity threshold for this mesage

find_neighbours(atoms, index)

Find the neighbours of atom i using self.neighbour_list returns a list of [heavy_neighbours, hydrogen_neighbours]

Parameters:

  • atoms (ase.Atoms object) – structure in which it is necessary to find the neighbours

  • index (int) – atomic index

Returns:

  • list – non-hydrogen neighbours

  • list – hydrogen neighbours

hydrogenate_cluster(atoms, cluster)

Add neigoburing hydrogens to a cluster composed of heavy ions The input should be a set representing heavy ions in a cluster This functions operates on sets

Parameters:

  • atoms (ase.Atoms object) – structure in which it is necessary to find the neighbours

  • cluster (ase.Atoms object) – sub-structure of the larger struct that needs its dangling bonds hydrogenated

Returns:

The original cluster but now hydrogenated

Return type:

ase.Atoms

matscipy.calculators.mcfm.qm_cluster_tools.qm_flagging_tool module

class matscipy.calculators.mcfm.qm_cluster_tools.qm_flagging_tool.QMFlaggingTool(mediator=None, qm_flag_potential_energies=None, small_cluster_hops=3, only_heavy=False, ema_parameter=0.1, energy_cap=None, energy_increase=1)

Bases: BaseQMClusterTool

This class is responsible for flagging atoms that move out of their equilibrium

__init__(mediator=None, qm_flag_potential_energies=None, small_cluster_hops=3, only_heavy=False, ema_parameter=0.1, energy_cap=None, energy_increase=1)

This class is responsible for flagging atoms that move out of their equilibrium

Parameters:

  • mediator (matscipy.calculators.mcfm.QMCluster) – class responsible for managing the QM clusters in the simulation

  • qm_flag_potential_energies (np.array) –

    threshholds for flagging indivual atoms. The diensions are (nAtoms, 2) where:

    column 1: threshold to enter the QM regios column 2: threshold to stay the QM region

  • small_cluster_hops (int) – Each flagged atom and atoms around it within small_cluster_hops neighbour hops will generate a single cluster, clusters are later joined.

  • only_heavy (bool) – If True, only consider non-hydrogen atoms in cluster expansion. Hydrogens are added later

  • ema_parameter (float) – parameter lambda in the exponential mean average calculation

  • energy_cap (float) – if not None, cap potential energy per atom at this value

  • energy_increase (int) – Multiplier for potential energy per atom, used to scale it for convininece

get_energized_list(atoms, data_array, property_str, hysteretic_tolerance)

Produce a list of atoms that are ot be flagged as a QM region based on the properties given in the array according to the tolerance given.

Parameters:

  • atoms (ase.Atoms) – Whole structure

  • data_array (array) – an array of per atom data providing information

  • property_str (str) – name of th property so that it can be stored in atoms.properties.

  • hysteretic_tolerance (array) –

    Threshholds for flagging indivual atoms. The diensions are (nAtoms, 2) where:

    column 1: threshold to enter the QM regios column 2: threshold to stay the QM region

Returns:

List of flagged atoms

Return type:

list

create_cluster_around_atom(atoms, atom_id, hydrogenate=False)

Carve a cluster around the atom with atom_id This function operates on sets and returns a set

Parameters:

  • atoms (ase.Atoms) – Whole structure

  • atom_id (int) – Atomic index

  • hydrogenate (bool) – If true, hydrogenate the resulting structure

Returns:

atoms in the new cluster

Return type:

list

join_clusters(verbose=False)

This function will join the clusters if they overlap Input is an array of sets each representing individual small cluster

Parameters:

verbose (bool) – Print messages during calculation

expand_cluster(special_atoms_list)

Include extra atoms in the cluster.

If one of the special atoms is included in one of the clusters, add all other special atoms to this cluster

Parameters:

special_atoms_list (list) – list of the special atoms

update_qm_region(atoms, potential_energies=None)

Update the QM region while the simulation is running

Parameters:

  • atoms (ase.Atoms) – whole structure

  • potential_energies (array) – Potential energy per atom

Returns:

list of individual clusters as lists of atoms

Return type:

list of lists of ints

find_neighbours(atoms, index)

Find the neighbours of atom i using self.neighbour_list returns a list of [heavy_neighbours, hydrogen_neighbours]

Parameters:

  • atoms (ase.Atoms object) – structure in which it is necessary to find the neighbours

  • index (int) – atomic index

Returns:

  • list – non-hydrogen neighbours

  • list – hydrogen neighbours

hydrogenate_cluster(atoms, cluster)

Add neigoburing hydrogens to a cluster composed of heavy ions The input should be a set representing heavy ions in a cluster This functions operates on sets

Parameters:

  • atoms (ase.Atoms object) – structure in which it is necessary to find the neighbours

  • cluster (ase.Atoms object) – sub-structure of the larger struct that needs its dangling bonds hydrogenated

Returns:

The original cluster but now hydrogenated

Return type:

ase.Atoms

matscipy.calculators.mcfm.qm_cluster_tools.qm_flagging_tool.exponential_moving_average(oldset, newset=None, ema_parameter=0.1)

Apply the exponential moving average to the given array

Parameters:

  • oldset (array) – old values

  • newset (array) – new data set

  • ema_parameter (float) – parameter lambda

matscipy.calculators.mcfm.qm_cluster_tools.qm_flagging_tool.update_avg_property_per_atom(atoms, data_array, property_str, ema_parameter)

Update the per atom property using running avarages and store it in atoms.properties[property_str]

Parameters:

  • atoms (ase.Atoms) – structure that need updated values

  • data_array (array) – data that need to be attached to atoms

  • property_str (str) – key for structure properties dictionary

  • ema_parameter (float) – Coefficient for the Exponential Moving Average