kim_tools.ase package

Submodules

kim_tools.ase.core module

Helper routines for KIM Tests and Verification Checks

exception kim_tools.ase.core.KIMASEError(msg)

Bases: Exception

kim_tools.ase.core.remove_species_not_supported_by_ASE(species)

Remove any species from the 'species' list that are not supported by ASE

kim_tools.ase.core.randomize_species(atoms, species, seed=13)

Given an ASE 'atoms' object, set random element for each atom selected from the list of available 'species' in a way that ensures all are represented with the same probabilities.

kim_tools.ase.core.fractional_coords_transformation(cell)

Given a set of cell vectors, this will return a transformation matrix T that can be used to multiply any arbitrary position to get its fractional coordinates in the basis of those cell vectors.

kim_tools.ase.core.atom_outside_cell_along_nonperiodic_dim(T, atom_coord, pbc, tol=1e-12)

Given a transformation matrix to apply to an atomic position to get its fractional position in the basis of some cell vectors and the corresponding boundary conditions, determine if the atom is outside of the cell along any non-periodic directions (measured using tolerance 'tol'). This is relevant when using an SM from a simulator such as LAMMPS that performs spatial decomposition -- atoms that leave the box along non-periodic dimensions are likely to become "lost."

kim_tools.ase.core.randomize_positions(atoms, pert_amp, seed=13)

Given an ASE 'atoms' object, displace all atomic coordinates by a random amount in the range [-pert_amp, pert_amp] along each dimension. Note that all atomic coordinates must be inside of the corresponding cell along non-periodic dimensions. As each atom is looped over, we continue generating perturbations until the displaced position is inside of the cell along any non-periodic directions (displacing outside the cell along periodic dimensions is allowed, although it's up to the calling function to wrap the positions if they need to be).

kim_tools.ase.core.get_isolated_energy_per_atom(model, symbol, initial_separation=1.0, max_separation=15.0, separation_neg_exponent=4, quit_early_after_convergence=True, energy_tolerance=1e-12)

Construct a non-periodic cell containing a single atom and compute its energy. It tries to iteratively finetune the atomic separation for a dimer up to a specified precision (separation_neg_exponent). If between two successive phases the energy difference is less than energy_tolerance, it stops early, i.e. if 4.0x and 4.00x are within energy_tolerance, it stops at 4.00x. All separations are in Angstroms.

Parameters:

  • model (Union[str, Calculator]) -- KIM model or ASE calculator to use for calculations

  • symbol (str) -- Chemical symbol

  • initial_separation (float) -- Initial separation for dimer calculations

  • max_separation (float) -- maximum separation for dimer calculations

  • separation_neg_exponent (float) -- Number of decimal places to refine the separation

  • quit_early_after_convergence (bool) -- Whether to stop early if energy converges

  • energy_tolerance (float) -- Energy difference tolerance for convergence check

Return type:

float

Returns:

The isolated energy per atom for the requested chemical symbol

kim_tools.ase.core.rescale_to_get_nonzero_energy(atoms, isolated_energy_per_atom, etol)

If the given configuration has a potential energy, relative to the sum of the isolated energy corresponding to each atom present, smaller in magnitude than 'etol' (presumably because the distance between atoms is too large), rescale it making it smaller. The 'isolated_energy_per_atom' arg should be a dict containing an entry for each atomic species present in the atoms object (additional entries are ignored).

kim_tools.ase.core.check_if_atoms_interacting_energy(model, symbols, etol)

First, get the energy of a single isolated atom of each species given in 'symbols'. Then, construct a dimer consisting of these two species and try to decrease its bond length until a discernible difference in the energy (from the sum of the isolated energy of each species) is detected. The 'symbols' arg should be a list or tuple of length 2 indicating which species pair to check, e.g. to check if Al interacts with Al, one should specify ['Al', 'Al'].

kim_tools.ase.core.check_if_atoms_interacting_force(model, symbols, ftol)

Construct a dimer and try to decrease its bond length until the force acting on each atom is larger than 'ftol' in magnitude. The 'symbols' arg should be a list or tuple of length 2 indicating which species pair to check, e.g. to check if Al interacts with Al, one should specify ['Al', 'Al'].

kim_tools.ase.core.check_if_atoms_interacting(model, symbols, check_energy=True, etol=1e-06, check_force=True, ftol=0.001)

Check to see whether non-trivial energy and/or forces can be detected using the current model. The 'symbols' arg should be a list or tuple of length 2 indicating which species pair to check, e.g. to check if Al interacts with Al, one should specify ['Al', 'Al'].

kim_tools.ase.core.rescale_to_get_nonzero_forces(atoms, ftol)

If the given configuration has force components which are all smaller in absolute value than 'ftol' (presumably because the distance between atoms is too large), rescale it to be smaller until the largest force component in absolute value is greater than or equal to 'ftol'. In a perfect crystal, the crystal is rescaled until the atoms on the surface reach the minimum value (internal atoms padded with another atoms around them will have zero force). Note that any periodicity is turned off for the rescaling and then restored at the end.

kim_tools.ase.core.perturb_until_all_forces_sizeable(atoms, pert_amp, minfact=0.1, maxfact=5.0, max_iter=1000)

Keep perturbing atoms in the ASE 'atoms' object until all force components on each atom have an absolute value of least 'minfact' times the largest (in absolute value) component across all force vectors coming in. Note that all atomic coordinates must be inside of the corresponding cell along non-periodic dimensions. Perturbations leading to a force component on any atom that is larger than 'maxfact' times the largest force component coming in are rejected. Perturbations leading to atoms outside of the span across x, y, and z of the atomic positions coming in or outside of the simulation cell along non-periodic directions are also rejected. The process repeats until max_iter iterations have been reached, at which point an exception is raised.

kim_tools.ase.core.get_model_species_minimum_cutoff(model, species, xtol=1e-08, etol_coarse=1e-06, etol_fine=1e-15, max_bisect_iters=1000, max_upper_cutoff_bracket=20.0)

Given a model and a list of species, construct all permutations of dimers and compute their energy-cutoff i.e the distance at which their interaction becomes non-trivial. Return the smallest such distance among all pairs of species. This method calls get_model_energy_cutoff

Return type:

float

kim_tools.ase.core.get_model_energy_cutoff(model, symbols, xtol=1e-08, etol_coarse=1e-06, etol_fine=1e-15, max_bisect_iters=1000, max_upper_cutoff_bracket=20.0)

Compute the distance at which energy interactions become non-trival for a given model and a species pair it supports. This is done by constructing a dimer composed of these species in a large finite box, increasing the separation if necessary until the total potential energy is within 'etol_fine' of the sum of the corresponding isolated energies, and then shrinking the separation until the energy differs from that value by more than 'etol_coarse'. Using these two separations to bound the search range, bisection is used to refine in order to locate the cutoff. The 'symbols' arg should be a list or tuple of length 2 indicating which species pair to check, e.g. to get the energy cutoff of Al with Al, one should specify ['Al', 'Al'].

This function is based on the content of the DimerContinuityC1__VC_303890932454_002 Verification Check in OpenKIM [1-3].

Return type:

float

[1] Tadmor E. Verification Check of Dimer C1 Continuity v002. OpenKIM; 2018.

doi:10.25950/43d2c6d5

[2] Tadmor EB, Elliott RS, Sethna JP, Miller RE, Becker CA. The potential of

atomistic simulations and the Knowledgebase of Interatomic Models. JOM. 2011;63(7):17. doi:10.1007/s11837-011-0102-6

[3] Elliott RS, Tadmor EB. Knowledgebase of Interatomic Models (KIM) Application

Programming Interface (API). OpenKIM; 2011. doi:10.25950/ff8f563a

kim_tools.ase.core.generate_fcc_compute_energy(model, species, alat, seed=13)

Construct an FCC lattice large enough to accommodate all species, evaluate its energy, and return the energy and size of the supercell.

Parameters:

  • model (Union[str, Calculator]) -- The model name or calculator object.

  • species (list) -- List of atomic species to be incorporated into the FCC lattice.

  • alat (float) -- The lattice constant for the FCC lattice.

  • seed (Optional[int]) -- Optional random seed for reproducibility during species randomization.

Returns:

  • The total potential energy of the lattice.

  • The number of unit cells along each side of the supercell.

Return type:

A tuple containing

kim_tools.ase.core.fcc_atoms_in_supercell(n_cells_per_side)

Compute the number of atoms in an FCC supercell.

This function calculates the total number of atoms in a Face-Centered Cubic (FCC) supercell based on the number of unit cells along each side. In an FCC structure, each unit cell contains 4 atoms.

Parameters:

n_cells_per_side (int) -- Number of unit cells along each side of the supercell. This represents the size of the supercell.

Return type:

int

Returns:

The total number of atoms in the FCC supercell.

kim_tools.ase.core.local_edge_detection(x, y)

Computes the Local Edge Detection (LED) values for the x-y curve. The algorithm helps to identify discontinuities or abrupt changes in the curve.

Based on the paper: A. Gelb and E. Tadmor, "Local edge detection for non-linear signals," Journal of Scientific Computing, 28:279-306, 2006.

Parameters:

  • x (list) -- A list of x-values representing the independent variable of the curve.

  • y (list) -- A list of y-values representing the dependent variable of the curve.

Return type:

list

Returns:

A list of LED values of strength of discontinuities in the x-y curve.

Notes

The LED[i] corresponds to the X[i+2]

kim_tools.ase.core.filter_good_alat(alats, energies, ncells, leds, min_cutoff, etol=[0.05, 500.0], led_tol=1.0)

Filter a good lattice constant (alat) based on the given criteria.

This function filters out a valid alat value from the provided lists of alats, energies, number of cells, and LED values. The filtering is done based on several conditions including the energy bounds, LED tolerance, and minimum cutoff distance.

Parameters:

  • alats (list) -- A list of lattice parameters (alat).

  • energies (list) -- A list of energy-per-atom values corresponding to each alat. Used to compute the total energy of the FCC structure for filtering.

  • ncells (list) -- A list of the number of cells corresponding to each alat. Used to compute the number of atoms for filtering by energy.

  • leds (list) -- A list of LED values corresponding to each alat. Note that leds[i] corresponds to alats[i+2]

  • min_cutoff (float) -- The minimum cutoff distance for the model-species combination. This is used to filter alats.

  • etol (list) -- A list containing the minimum and maximum energy-per-atom bounds for filtering. Default is [5e-2, 5e2].

  • led_tol (float) -- The maximum LED value for filtering. Default is 1.0.

Returns:

A dictionary containing the filtered alat value and related properties:

  • 'good_alat': The filtered alat value.

  • 'min_led': The minimum LED value found.

  • 'good_ncells': The number of cells corresponding to the selected alat.

Return type:

dict

Notes

The following conditions are applied to filter the valid alat: - 0.2 * min_cutoff < alat < 0.8 * min_cutoff - etol[0] < |energy-per-atom| < etol[1] - |LED| < led_tol - 0 < |LED| < min_led

kim_tools.ase.core.find_working_configuration_FCC(model, species, energy_bound=[0.05, 500.0], led_tol=1.0, seed=13)

Find an FCC configuration for a model and species with energy and LED constraints.

This function constructs an FCC configuration for the specified species and model, and filters the configurations based on energy-per-atom and smoothness of the energy-alat relation. The energy values must lie within the specified bounds, and the local edge detection (LED) must be below the given tolerance.

Parameters:

  • model (Union[str, Calculator]) -- The model name or calculator object used to compute the energies of the configurations.

  • species (list) -- atomic species to be incorporated into the FCC structure.

  • energy_bound (list) -- A list of two values specifying the minimum and maximum energy-per-atom bounds for filtering. Default is [5e-2, 5e2].

  • led_tol (float) -- The tolerance for local edge detection filtering. Default is 1.0.

  • seed (Optional[int]) -- An optional random seed for reproducibility.

Returns:

A dictionary containing the working FCC configuration, including the

optimal lattice constant, number of cells per side, and the corresponding LED value.

Return type:

dict

Notes

  • The function first computes the minimum cutoff distance for the species pair.

  • It then attempts different lattice constants and filters the configurations based on energy-per-atom and LED values.

  • Only configurations that meet the energy and LED criteria are retained.

Module contents