Analysis

Analysis functions common enough to be included in the main package.

Analysis functions for surface chemistry of diatomic molecules.

close_approach_condition(x::AbstractArray, indices::Vector{Int}, simulation::AbstractSimulation; threshold = 1.5u"Å")

Evaluate true if the diatomic bond length is below `threshold`.

com_velocity_condition(x::AbstractArray, indices::Vector{Int}, simulation::AbstractSimulation; surface_normal::AbstractVector=[0,0,1])

Evaluates true if the centre of mass velocity vector of the diatomic molecule points to the surface.

get_desorption_frame(trajectory::AbstractVector, diatomic_indices::Vector{Int}, simulation::AbstractSimulation; surface_normal::Vector=[0, 0, 1], surface_distance_threshold=5.0 * u"Å", fallback_distance_threshold = 1.5u"Å")

Determines the index in a trajectory where surface desorption begins.

This is evaluated using two conditions:

1. In the trajectory, the diatomic must be surface_distance_threshold or further away from the highest other atom. (In surface_normal direction).

2. Desorption begins at the turning point of the centre of mass velocity component along surface_normal, indicating overall movement away from the surface.

If the second condition is never reached (can happen for particularly quick desorptions), the fallback_distance_threshold is used to find the last point where the diatomic bond length is above the given value and saves from that point onwards.

surface_distance_condition(x::AbstractArray, indices::Vector{Int}, simulation::AbstractSimulation; surface_distance_threshold=5.0*u"Å")

Checks that the diatomic molecule is at least `surface_distance_threshold` away from the highest substrate atom in the simulation.

transform_U(config::Matrix, index1::Int, index2::Int, sim::Simulation)

Builds diatomic Cartesian to internal coordinate transformation matrix as described in the SI of 10.1021/jacsau.0c00066

classical_rotation_energy(J::Union{Int, CartesianIndex}, config::Any, ind1::Union{Int, CartesianIndex}, ind2::Union{Int, CartesianIndex}, sim::Simulation)

Classical rotation energy of a rigid diatomic rotor in Hartree

classical_translational_energy(config::Any, ind1::Union{Int, CartesianIndex}, ind2::Union{Int, CartesianIndex}, sim::Simulation)

Returns the classical translational energy in Hartree

harmonic_vibration_energy(ν::Union{Int, CartesianIndex}, k::Float, ind1::Union{Int, CartesianIndex}=1, ind2::Union{Int, CartesianIndex}=2, sim::Simulation)

Vibrational energy of a harmonic oscillator with the force constant k and vibrational level ν.

apply_output_functions(sol::FakeSolution, output_functions; savetime::Bool=true)

Evaluates output functions on a DifferentialEquations.jl solution object or fake solution object generated using a defined Simulation and a DynamicsVariables type.

Basically equivalent to running run_dynamics() with the same output functions, but without doing the dynamics simulation again.

apply_output_functions(sim<:AbstractSimulation, u_type::AbstractVector, t_type::AbstractVector, output_functions; savetime::Bool=true)

Evaluates output functions on a defined Simulation, a DynamicsVariables type output and a time-type output.

Basically equivalent to running run_dynamics() with the same output functions, but without doing the dynamics simulation again.

These analysis functions contain some postprocessing code to associate positions of adsorbate molecules on a surface slab with high-symmetry locations on the surface slab.

Base definitions for fcc metal surface facets are included, but there are options to expand this further.

This code only works for 2D positions in X and Y, so the surface needs to lie in the XY plane.

classify_every_frame(
    trajectory,
    cell::PeriodicCell,
    slab::SlabStructure,
    fractional::Bool = false,
    snap_to_site::Float64 = 0.03,
)

Classifies the adsorption site of adsorbate atoms for every frame in a trajectory.

Arguments

• trajectory: Vector{DynamicsVariables type} of structures to classify.
• cell::PeriodicCell: The periodic cell representation of the simulation.
• slab::SlabStructure: Slab structure object containing adsorbate atom indices, supercell size, and symmetry site information.
• fractional::Bool = false: If true, uses fractional coordinates for site matching; otherwise, uses Cartesian coordinates.
• snap_to_site::Float64 = 0.03: Distance tolerance for assigning a position to a high-symmetry site.

Returns

• A vector of vectors, where each inner vector contains the classified site (as a Symbol) for an adsorbate atom at one frame.

Notes

• Each adsorbate atom is assigned to a symmetry site or :other for each trajectory frame.
• Positions are wrapped back into the primitive cell before site classification.
• Uses positions_to_category to perform the categorization for each atom in each frame.

positions_to_category(position, categories, cell::PeriodicCell; fractional::Bool = false, snap_to_site::Float64 = 0.03)

Classifies a given 2D position according to its proximity to high-symmetry surface sites.

Arguments

• position: A 2-element (or longer, only first 2D used) vector representing the coordinates to classify.
• categories: A dictionary mapping site names (as Symbols) to lists of site coordinates.
• cell::PeriodicCell: The surface unit cell used to calculate distances and perform coordinate transformations.
• fractional::Bool = false: Whether to use fractional coordinates to determine distances to sites. If true, position is mapped directly to the sites; if false, converts to fractional using cell.
• snap_to_site::Float64 = 0.03: The distance tolerance (in the same units as position/cell) for snapping to a given site category.

Returns

• The key of the closest site category (from categories) if within snap_to_site of any defined site. If not within this range or outside the cell, returns :other.

Notes

• Positions are always truncated to 2D before classification.
• If the position is not inside the periodic cell, returns :other.
• Site assignment is based on the minimum Euclidean distance to any site in each category.