cattsunami.core.autoframe

cattsunami.core.autoframe#

Home of the AutoFrame classes which facillitate the generation of initial and final frames for NEB calculations.

Classes#

`AutoFrame`	Base class to hold functions that are shared across the reaction types.
`AutoFrameDissociation`	Base class to hold functions that are shared across the reaction types.
`AutoFrameTransfer`	Base class to hold functions that are shared across the reaction types.
`AutoFrameDesorption`	Base class to hold functions that are shared across the reaction types.

Functions#

`interpolate_and_correct_frames`(initial, final, ...)	Given the initial and final frames, perform the following:
`get_shortest_path`(initial, final)	Find the shortest path for all atoms about pbc and reorient the final frame so the
`traverse_adsorbate_transfer`(reaction, initial, final, ...)	Traverse reactant 1, reactant 2, product 1 and product 2 in a depth first search of
`traverse_adsorbate_dissociation`(reaction, initial, ...)	Traverse reactant 1, product 1 and product 2 in a depth first search of
`traverse_adsorbate_desorption`(reaction, initial, ...)	Traverse reactant 1 and product 1 in a depth first search of
`get_product2_idx`(reaction, edge_list_final, ...)	For dissociation only. Use the information about the initial edge list and final edge
`traverse_adsorbate_general`(traversal_rxt, slab_len, ...)	Perform the traversal to reposition atoms so that the distance along bonds is
`unwrap_atoms`(initial, final, reaction, map_idx)	Make corrections to the final frame so it is no longer wrapped around the cell,
`interpolate`(initial_frame, final_frame, num_frames)	Interpolate between the initial and final frames starting with a linear interpolation
`is_edge_list_respected`(frame, edge_list)	Check to see that the expected adsorbate-adsorbate edges are found and no additional
`reorder_edge_list`(edge_list, mapping)	For the final edge list, apply the mapping so the edges correspond to the correctly
`is_adsorbate_adsorbed`(adsorbate_slab_config)	Check to see if the adsorbate is adsorbed on the surface.

Module Contents#

class cattsunami.core.autoframe.AutoFrame#

Base class to hold functions that are shared across the reaction types.

reorder_adsorbate(frame: ase.Atoms, idx_mapping: dict)#

Given the adsorbate mapping, reorder the adsorbate atoms in the final frame so that they match the initial frame to facillitate proper interpolation.

Parameters:

frame (ase.Atoms) – the atoms object for which the adsorbate will be reordered
idx_mapping (dict) – the index mapping to reorder things

Returns:

the reordered adsorbate-slab configuration

Return type:

ase.Atoms

only_keep_unique_systems(systems, energies)#

Remove duplicate systems from systems and energies.

Parameters:

systems (list[ase.Atoms]) – the systems to remove duplicates from
energies (list[float]) – the energies to remove duplicates from

Returns:

the systems with duplicates removed list[float]: the energies with duplicates removed

Return type:

list[ase.Atoms]

get_most_proximate_symmetric_group(initial: ase.Atoms, frame: ase.Atoms)#

For cases where the adsorbate has symmetry and the leaving group could be different atoms / sets of atoms, determine which one make the most sense given the geometry of the initial and final frames. This is done by minimizing the total distance traveled by all atoms from initial to final frame.

Parameters:

initial (ase.Atoms) – the initial adsorbate-surface configuration
frame (ase.Atoms) – the final adsorbate-surface configuration being considered.

Returns:

the mapping to be used which specifies the most apt leaving group int: the index of the mapping to be used

Return type:

dict

are_all_adsorbate_atoms_overlapping(adsorbate1: ase.Atoms, adsorbate2: ase.Atoms)#

Test to see if all the adsorbate atoms are intersecting to find unique structures. Systems where they are overlapping are considered the same.

Parameters:

adsorbate1 (ase.Atoms) – just the adsorbate atoms of a structure that is being compared
adsorbate2 (ase.Atoms) – just the adsorbate atoms of the other structure that is being compared

Returns:

True if all adsorbate atoms are overlapping (structure is a match): False if one or more of the adsorbate atoms do not overlap

Return type:

(bool)

class cattsunami.core.autoframe.AutoFrameDissociation(reaction: fairchem.applications.cattsunami.core.Reaction, reactant_system: ase.Atoms, product1_systems: list, product1_energies: list, product2_systems: list, product2_energies: list, r_product1_max: float | None = None, r_product2_max: float | None = None, r_product2_min: float | None = None)#

Bases: AutoFrame

Base class to hold functions that are shared across the reaction types.

reaction#

reactant1_systems#

get_neb_frames(calculator, n_frames: int = 5, n_pdt1_sites: int = 5, n_pdt2_sites: int = 5, fmax: float = 0.05, steps: int = 200)#

Propose final frames for NEB calculations. Perform a relaxation on the final frame using the calculator provided. Interpolate between the initial and final frames for a proposed reaction trajectory. Correct the trajectory if there is any atomic overlap.

Parameters:

calculator – an ase compatible calculator to be used to relax the final frame.
n_frames (int) – the number of frames per reaction trajectory
n_pdt1_sites (int) – The number of product 1 sites to consider
n_pdt2_sites (int) – The number of product 2 sites to consider. Note this is multiplicative with n_pdt1_sites (i.e. if n_pdt1_sites = 2 and n_pdt2_sites = 3 then a total of 6 final frames will be proposed)
fmax (float) – force convergence criterion for final frame optimization
steps (int) – step number termination criterion for final frame optimization

Returns:

the initial reaction coordinates

Return type:

list[lists]

get_best_sites_for_product1(n_sites: int = 5)#

Wrapper to find product 1 placements to be considered for the final frame of the NEB.

Parameters:

n_sites (int) – The number of sites for product 1 to consider. Notice this is multiplicative with product 2 sites (i.e. if 2 is specified here and 3 there) then a total of 6 initial and final frames will be considered.

Returns:

the lowest energy, proximate placements of product: 1 to be used in the final NEB frames

Return type:

(list[ase.Atoms])

get_best_unique_sites_for_product2(product1: ase.Atoms, n_sites: int = 5)#

Wrapper to find product 2 placements to be considered for the final frame of the NEB.

Parameters:

product1 (ase.Atoms) – The atoms object of the product 1 placement that will be considered in this function to search for product 1 + product 2 combinations for the final frame.
n_sites (int) – The number of sites for product 1 to consider. Notice this is multiplicative with product 2 sites (i.e. if 2 is specified here and 3 there) then a total of 6 initial and final frames will be considered.

Returns:

the lowest energy, proximate placements of product: 2 to be used in the final NEB frames

Return type:

(list[ase.Atoms])

get_sites_within_r(center_coordinate: numpy.ndarray, all_systems: list, all_system_energies: list, all_systems_binding_idx: int, allowed_radius_max: float, allowed_radius_min: float, n_sites: int = 5)#

Get the n lowest energy, sites of the systems within r. For now n is 5 or < 5 if there are fewer than 5 unique sites within r.

Parameters:

center_coordinate (np.ndarray) – the coordinate about which r should be centered.
all_systems (list) – the list of all systems to be assessed for their uniqueness and proximity to the center coordinate.
all_systems_binding_idx (int) – the idx of the adsorbate atom that is bound in all_systems
allowed_radius_max (float) – the outer radius about center_coordinate in which the adsorbate must lie to be considered.
allowed_radius_min (float) – the inner radius about center_coordinate which the adsorbate must lie outside of to be considered.
n_sites (int) – the number of unique sites in r that will be chosen.

Returns:

list of systems identified as candidates.

Return type:

(list[ase.Atoms])

class cattsunami.core.autoframe.AutoFrameTransfer(reaction: fairchem.applications.cattsunami.core.Reaction, reactant1_systems: list, reactant2_systems: list, reactant1_energies: list, reactant2_energies: list, product1_systems: list, product1_energies: list, product2_systems: list, product2_energies: list, r_traverse_max: float, r_react_max: float, r_react_min: float)#

Bases: AutoFrame

Base class to hold functions that are shared across the reaction types.

reaction#

r_traverse_max#

r_react_max#

r_react_min#

get_neb_frames(calculator, n_frames: int = 10, n_initial_frames: int = 5, n_final_frames_per_initial: int = 5, fmax: float = 0.05, steps: int = 200)#

Propose final frames for NEB calculations. Perform a relaxation on the final frame using the calculator provided. Linearly interpolate between the initial and final frames for a proposed reaction trajectory. Correct the trajectory if there is any atomic overlap.

Parameters:

calculator – an ase compatible calculator to be used to relax the initial and final frames.
n_frames (int) – the number of frames per reaction trajectory
n_initial_frames (int) – The number of initial frames to consider
n_final_frames_per_initial (int) – The number of final frames per inital frame to consider
fmax (float) – force convergence criterion for final frame optimization
steps (int) – step number termination criterion for final frame optimization

Returns:

the initial reaction coordinates

Return type:

list[lists]

get_system_pairs_initial()#

Get the initial frames for the NEB. This is done by finding the closest pair of systems from systems1 and systems2 for which the interstitial distance between all adsorbate atoms is less than rmax and greater than rmin.

Returns:

the initial frames for the NEB list[float]: the pseudo energies of the initial frames (i.e just the sum of the

individual adsorption energies)

Return type:

list[ase.Atoms]

get_system_pairs_final(system1_coord, system2_coord)#

Get the final frames for the NEB. This is done by finding the closest pair of systems from systems1 and systems2 for which the distance traversed by the adsorbate from the initial frame to the final frame is less than rmax and the minimum interstitial distance between the two products in greater than rmin.

Returns:: the initial frames for the NEB list[float]: the pseudo energies of the initial frames
Return type:: list[ase.Atoms]

class cattsunami.core.autoframe.AutoFrameDesorption(reaction: fairchem.applications.cattsunami.core.Reaction, reactant_systems: list, reactant_energies: list, z_desorption: float)#

Bases: AutoFrame

Base class to hold functions that are shared across the reaction types.

z_desorption#

reaction#

get_neb_frames(calculator, n_frames: int = 5, n_systems: int = 5, fmax: float = 0.05, steps: int = 200)#

Propose final frames for NEB calculations. Perform a relaxation on the final frame using the calculator provided. Linearly interpolate between the initial and final frames for a proposed reaction trajectory. Correct the trajectory if there is any atomic overlap.

Parameters:

calculator – an ase compatible calculator to be used to relax the final frame.
n_frames (int) – the number of frames per reaction trajectory
n_pdt1_sites (int) – The number of product 1 sites to consider
n_pdt2_sites (int) – The number of product 2 sites to consider. Note this is multiplicative with n_pdt1_sites (i.e. if n_pdt1_sites = 2 and n_pdt2_sites = 3 then a total of 6 final frames will be proposed)
fmax (float) – force convergence criterion for final frame optimization
steps (int) – step number termination criterion for final frame optimization

Returns:

the initial reaction coordinates

Return type:

list[lists]

cattsunami.core.autoframe.interpolate_and_correct_frames(initial: ase.Atoms, final: ase.Atoms, n_frames: int, reaction: fairchem.applications.cattsunami.core.Reaction, map_idx: int)#

Given the initial and final frames, perform the following: (1) Unwrap the final frame if it is wrapped around the cell (2) Interpolate between the initial and final frames

Parameters:

initial (ase.Atoms) – the initial frame of the NEB
final (ase.Atoms) – the proposed final frame of the NEB
n_frames (int) – The desired number of frames for the NEB (not including initial and final)
reaction (Reaction) – the reaction object which provides pertinent info
map_idx (int) – the index of the mapping to use for the final frame

cattsunami.core.autoframe.get_shortest_path(initial: ase.Atoms, final: ase.Atoms)#

Find the shortest path for all atoms about pbc and reorient the final frame so the atoms align with this shortest path. This allows us to perform a linear interpolation that does not interpolate jumps across pbc.

Parameters:

initial (ase.Atoms) – the initial frame of the NEB
final (ase.Atoms) – the proposed final frame of the NEB to be corrected

Returns:

the corrected final frame (ase.Atoms): the initial frame tiled (3,3,1), which is used it later steps (ase.Atoms): the final frame tiled (3,3,1), which is used it later steps

Return type:

(ase.Atoms)

cattsunami.core.autoframe.traverse_adsorbate_transfer(reaction: fairchem.applications.cattsunami.core.Reaction, initial: ase.Atoms, final: ase.Atoms, initial_tiled: ase.Atoms, final_tiled: ase.Atoms, edge_list_final: list)#

Traverse reactant 1, reactant 2, product 1 and product 2 in a depth first search of the bond graph. Unwrap the atoms to minimize the distance over the bonds. This ensures that when we perform the linear interpolation, the adsorbate moves as a single moity and avoids accidental bond breaking events over pbc.

Parameters:

reaction (Reaction) – the reaction object which provides pertinent info
initial (ase.Atoms) – the initial frame of the NEB
final (ase.Atoms) – the proposed final frame of the NEB to be corrected
initial_tiled (ase.Atoms) – the initial frame tiled (3,3,1)
final_tiled (ase.Atoms) – the final frame tiled (3,3,1)
edge_list_final (list) – the edge list of the final frame corrected with mapping idx changes

Returns:

the corrected initial frame (ase.Atoms): the corrected final frame

Return type:

(ase.Atoms)

cattsunami.core.autoframe.traverse_adsorbate_dissociation(reaction: fairchem.applications.cattsunami.core.Reaction, initial: ase.Atoms, final: ase.Atoms, initial_tiled: ase.Atoms, final_tiled: ase.Atoms, edge_list_final: int)#

Traverse reactant 1, product 1 and product 2 in a depth first search of the bond graph. Unwrap the atoms to minimize the distance over the bonds. This ensures that when we perform the linear interpolation, the adsorbate moves as a single moity and avoids accidental bond breaking events over pbc.

Parameters:

reaction (Reaction) – the reaction object which provides pertinent info
initial (ase.Atoms) – the initial frame of the NEB
final (ase.Atoms) – the proposed final frame of the NEB to be corrected
initial_tiled (ase.Atoms) – the initial frame tiled (3,3,1)
final_tiled (ase.Atoms) – the final frame tiled (3,3,1)
edge_list_final (list) – the edge list of the final frame corrected with mapping idx changes

Returns:

the corrected initial frame (ase.Atoms): the corrected final frame

Return type:

(ase.Atoms)

cattsunami.core.autoframe.traverse_adsorbate_desorption(reaction: fairchem.applications.cattsunami.core.Reaction, initial: ase.Atoms, final: ase.Atoms, initial_tiled: ase.Atoms, final_tiled: ase.Atoms)#

Traverse reactant 1 and product 1 in a depth first search of the bond graph. Unwrap the atoms to minimize the distance over the bonds. This ensures that when we perform the linear interpolation, the adsorbate moves as a single moity and avoids accidental bond breaking events over pbc.

Parameters:

reaction (Reaction) – the reaction object which provides pertinent info
initial (ase.Atoms) – the initial frame of the NEB
final (ase.Atoms) – the proposed final frame of the NEB to be corrected
initial_tiled (ase.Atoms) – the initial frame tiled (3,3,1)
final_tiled (ase.Atoms) – the final frame tiled (3,3,1)
edge_list_final (list) – the edge list of the final frame corrected with mapping idx changes

Returns:

the corrected initial frame (ase.Atoms): the corrected final frame

Return type:

(ase.Atoms)

cattsunami.core.autoframe.get_product2_idx(reaction: fairchem.applications.cattsunami.core.Reaction, edge_list_final: list, traversal_rxt1_final: list)#

For dissociation only. Use the information about the initial edge list and final edge list to determine which atom in product 2 lost a bond in the reaction and use this as the binding index for traversal in traverse_adsorbate_dissociation.

Parameters:

reaction (Reaction) – the reaction object which provides pertinent info
edge_list_final (list) – the edge list of the final frame corrected with mapping idx changes
traversal_rxt1_final (list) – the traversal of reactant 1 for the final frame

Returns:

the binding index of product 2

Return type:

(int)

cattsunami.core.autoframe.traverse_adsorbate_general(traversal_rxt, slab_len: int, starting_node_idx: int, equivalent_idx_factors: numpy.ndarray, frame: ase.Atoms, frame_tiled: ase.Atoms)#

Perform the traversal to reposition atoms so that the distance along bonds is minimized.

Parameters:

traversal_rxt (list) – the traversal of the adsorbate to be traversed. It is the list of edges ordered by depth first search.
slab_len (int) – the number of atoms in the slab
starting_node_idx (int) – the index of the atom to start the traversal from
equivalent_idx_factors (np.ndarray) – the values to add to the untiled index which gives equivalent indices (i.e. copies of that atom in the tiled system)
frame (ase.Atoms) – the frame to be corrected
frame_tiled (ase.Atoms) – the tiled (3,3,1) version of the frame which will be corrected

Returns:

the corrected frame

Return type:

(ase.Atoms)

cattsunami.core.autoframe.unwrap_atoms(initial: ase.Atoms, final: ase.Atoms, reaction: fairchem.applications.cattsunami.core.Reaction, map_idx: int)#

Make corrections to the final frame so it is no longer wrapped around the cell, if it has jumpped over the pbc. Ensure that for each adsorbate moity, absolute bond distances for all edges that exist in the initial and final frames are minimize regardles of cell location. This enforces the traversal of the adsorbates happens along the same path, which is not necessarily the minimum distance path for each atom. Changes are made in place.

Parameters:

initial (ase.Atoms) – the initial atoms object to which the final atoms should be proximate
final (ase.Atoms) – the final atoms object to be corrected
reaction (Reaction) – the reaction object which provides pertinent info
map_idx (int) – the index of the mapping to use for the final frame

cattsunami.core.autoframe.interpolate(initial_frame: ase.Atoms, final_frame: ase.Atoms, num_frames: int)#

Interpolate between the initial and final frames starting with a linear interpolation along the atom-wise vectors from initial to final. Then iteratively correct the positions so atomic overlap is avoided/ reduced. When iteratively updating, the positions of adjacent frames are considered to avoid large jumps in the trajectory.

Parameters:

initial_frame (ase.Atoms) – the initial frame which will be interpolated from
final_frame (ase.Atoms) – the final frame which will be interpolated to
num_frames (int) – the number of frames to be interpolated between the initial

Returns:

the interpolated frames

Return type:

(list[ase.Atoms])

cattsunami.core.autoframe.is_edge_list_respected(frame: ase.Atoms, edge_list: list)#

Check to see that the expected adsorbate-adsorbate edges are found and no additional edges exist between the adsorbate atoms.

Parameters:

frame (ase.Atoms) – the atoms object for which edges will be checked. This must comply with ocp tagging conventions.
edge_list (list[tuples]) – The expected edges

cattsunami.core.autoframe.reorder_edge_list(edge_list: list, mapping: dict)#

For the final edge list, apply the mapping so the edges correspond to the correctly concatenated object.

Parameters:

edge_list (list[tuples]) – the final edgelist
mapping – the mapping so the final atoms concatenated have indices that correctly map to the initial atoms.

cattsunami.core.autoframe.is_adsorbate_adsorbed(adsorbate_slab_config: ase.Atoms)#

Check to see if the adsorbate is adsorbed on the surface.

Parameters:: adsorbate_slab_config (ase.Atoms) – the combined adsorbate and slab configuration with adsorbate atoms tagged as 2s and surface atoms tagged as 1s.
Returns:: True if the adsorbate is adsorbed, False otherwise.
Return type:: (bool)