1. yaff – YAFF - Yet another force field

1.1. yaff.atselect – The ATSELECT language

The ATSELECT language

The ATSELECT language is a single-line language that can be used to define atom types in Yaff, or to construct a list of atoms in a system that match an ATSELECT rule.

yaff.atselect.check_name(name)

Raise a ValueError if the given ffatype or scope name is invalid.

Arugments:

name
The name to be checked.

A name is invalid …

  • if it has length zero,
  • if it contains any of :%=<>@()&|!, or
  • if it starts with a digit [0-9].

These rules make sure that the ffatype and scope names do not conflict with the ATSELECT language.

yaff.atselect.find_first(s, subs, start=0, end=None)

Find the first occurence of a set of substrings in s

Arguments:

s
The string that must be searched for the patterns in the subs list.
subs
A list of patterns.

Optional arguments:

start
Only start searching at this index in the string s.
end
When given, no subs occuring after end are mathcing.
yaff.atselect.lex_find(s, sub, start=0, end=None)

find sub in s that is not enclosed in brackets

yaff.atselect.lex_split(s, splitter)

Split the string at the given character, ignoring characters in brackets

This routine also checks if the number of opening and closing brackets match, and that there is no character in the string that is preceeded by more closing than opening brackets.

yaff.atselect.atsel_compile(s)

Compiles an ATSELECT line into a boolean function

Argument:

s
a string with one ATSELECT line. Before this line is processed, all whitespace (including newline) charachters are removed.

Returns:

rule
A function that takes two arguments: system and i, where system is a System instance and i is an atom index. The function returns True if the atom matches the ATSELECT line in the string s.
yaff.atselect.iter_matches(dm0, dm1, allowed, threshold=0.001, error_sq_fn=None, overlapping=True)

Iterate over all possible renumberings of system 1 that are present in system 0.

Parameters:
  • dm0 (np.ndarray, shape=(n0, n0)) – A reference distance matrix (or analogeous object).
  • dm1 (np.ndarray, shape=(n1, n1), n1 <= n0) – A distance matrix of the system to be reordered.
  • allowed (list (length n1) of lists of integer indexes) – For each element in system 1, the allowed corresponding indexes in system 0. This can be based on corresponding chemical elements, atom types, etc. The more specific, the more efficient this function becomes.
  • threshold (float) – An allowed deviation (L2-norm) between the distance matrix of the reference and the reordered system 1.
  • error_sq_fn (function taking two arguments) – When not given, the squared difference is computed as error measure when comparing two distance matrix elements (dm0 versus dm1). This can be replaced by any user-provided squared error function.
  • overlapping (bool) – When set to False, the algorithm excludes matches that are permutations of previous matches or that have a partial overlap with any previous match.
Yields:

match (tuple) – All possible renumberings of elements in system 1 that match with (a subset of) system 0. All elements of the tuple are integers.

1.2. yaff.log – Screen logger

Screen logger

This module holds the main screen loging object of Yaff. The log object is an instance off the ScreenLog class in the module molmod.log. The logger also comes with a timer infrastructure, which is also implemented in the molmod.log module.

1.3. yaff.system – Representation of a molecular systems

Representation of a molecular systems

class yaff.system.System(numbers, pos, scopes=None, scope_ids=None, ffatypes=None, ffatype_ids=None, bonds=None, rvecs=None, charges=None, radii=None, valence_charges=None, dipoles=None, radii2=None, masses=None)

Bases: object

Initialize a System object.

Arguments:

numbers
A numpy array with atomic numbers
pos
A numpy array (N,3) with atomic coordinates in Bohr.

Optional arguments:

scopes
A list with scope names
scope_ids
A list of scope indexes that links each atom with an element of the scopes list. If this argument is not present, while scopes is given, it is assumed that scopes contains a scope name for every atom, i.e. that it is a list with length natom. In that case, it will be converted automatically to a scopes list with only unique name together with a corresponding scope_ids array.
ffatypes
A list of labels of the force field atom types.
ffatype_ids
A list of atom type indexes that links each atom with an element of the list ffatypes. If this argument is not present, while ffatypes is given, it is assumed that ffatypes contains an atom type for every element, i.e. that it is a list with length natom. In that case, it will be converted automatically to a short ffatypes list with only unique elements (within each scope) together with a corresponding ffatype_ids array.
bonds
a numpy array (B,2) with atom indexes (counting starts from zero) to define the chemical bonds.
rvecs
An array whose rows are the unit cell vectors. At most three rows are allowed, each containing three Cartesian coordinates.
charges
An array of atomic charges
radii

An array of atomic radii, \(R_{A,c}\), that determine shape of the atomic charge distribution:

\[\rho_{A,c}(\mathbf{r}) = \frac{q_A}{\pi^{3/2}R_{A,c}^3} \exp\left( -\frac{|r - \mathbf{R}_A|^2}{R_{A,c}^2} \right)\]
valence_charges
In case a point-core + distribute valence charge is used, this vector contains the valence charges. The core charges can be computed by subtracting the valence charges from the net charges.
dipoles
An array of atomic dipoles
radii2

An array of atomic radii, \(R_{A,d}\), that determine shape of the atomic dipole distribution:

\[\rho_{A,d}(\mathbf{r}) = -2\frac{\mathbf{d}_A \cdot (\mathbf{r} - \mathbf{R}_A)}{ \sqrt{\pi} R_{A,d}^5 }\exp\left( -\frac{|r - \mathbf{R}_A|^2}{R_{A,d}^2} \right)\]
masses
The atomic masses (in atomic units, i.e. m_e)

Several attributes are derived from the (optional) arguments:

  • cell contains the rvecs attribute and is an instance of the Cell class.
  • neighs1, neighs2 and neighs3 are dictionaries derived from bonds that contain atoms that are separated 1, 2 and 3 bonds from a given atom, respectively. This means that i in system.neighs3[j] is True if there are three bonds between atoms i and j.
natom

The number of atoms

nffatype

The number of atom types

nbond

The number of bonds

classmethod from_file(*fns, **user_kwargs)

Construct a new System instance from one or more files

Arguments:

fn1, fn2, …
A list of filenames that are read in order. Information in later files overrides information in earlier files.

Optional arguments:

Any argument from the default constructor __init__. These must be given with keywords.

Supported file formats

.xyz
Standard Cartesian coordinates file (in angstroms). Atomic positions and atomic numbers are read from this file. If the title consists of 3, 6 or 9 numbers, each group of three numbers is interpreted as a cell vector (in angstroms). A guess of the bonds will be made based on inter-atomic distances.
.psf
Atom types and bonds are read from this file
.chk
Internal text-based checkpoint format. It just contains a dictionary with the constructor arguments.
classmethod from_hdf5(f)

Create a system from an HDF5 file/group containing a system group

Arguments:

f
An open h5.File object with a system group. The system group must at least contain a numbers and pos dataset.
to_file(fn)

Write the system to a file

Arguments:

fn
The file to write to.

Supported formats are:

chk
Internal human-readable checkpoint format. This format includes all the information of a system object. All data are stored in atomic units.
h5
Internal binary checkpoint format. This format includes all the information of a system object. All data are stored in atomic units.
xyz
A simple file with atomic positions and elements. Coordinates are written in Angstroms.
to_hdf5(f)

Write the system to a HDF5 file.

Arguments:

f
A Writable h5.File object.
get_scope(index)

Return the of the scope (string) of atom with given index

get_ffatype(index)

Return the of the ffatype (string) of atom with given index

get_indexes(rule)

Return the atom indexes that match the filter rule

rule can be a function that accepts two arguments: system and an atom index and that returns True of the atom with index i is of a given type. On the other hand rule can be an ATSELECT string that defines the atoms of interest.

A list of atom indexes is returned.

iter_bonds()

Iterate over all bonds.

iter_angles()

Iterative over all possible valence angles.

This routine is based on the attribute bonds.

iter_dihedrals()

Iterative over all possible dihedral angles.

This routine is based on the attribute bonds.

iter_oops()

Iterative over all possible oop patterns.”

This routine is based on the attribute bonds.

detect_bonds(exceptions=None)

Initialize the bonds attribute based on inter-atomic distances

Optional argument:

exceptions:
Specify custom threshold for certain pairs of elements. This must be a dictionary with ((num0, num1), threshold) as items.

For each pair of elements, a distance threshold is used to detect bonded atoms. The distance threshold is based on a database of known bond lengths. If the database does not contain a record for the given element pair, the threshold is based on the sum of covalent radii.

detect_ffatypes(rules)

Initialize the ffatypes attribute based on ATSELECT rules.

Argument:

rules
A list of (ffatype, rule) pairs that will be used to initialize the attributes self.ffatypes and self.ffatype_ids.

If the system already has FF atom types, they will be overwritten.

set_standard_masses()

Initialize the masses attribute based on the atomic numbers.

align_cell(lcs=None, swap=True)

Align the unit cell with respect to the Cartesian Axes frame

Optional Arguments:

lcs

The linear combinations of the unit cell that must get aligned. This is a 2x3 array, where each row represents a linear combination of cell vectors. The first row is for alignment with the x-axis, second for the z-axis. The default value is:

np.array([
    [1, 0, 0],
    [0, 0, 1],
])
swap
By default, the first alignment is done with the z-axis, then with the x-axis. The order is reversed when swap is set to False.

The alignment of the first linear combination is always perfect. The alignment of the second linear combination is restricted to a plane. The cell is always made right-handed. The coordinates are also rotated with respect to the origin, but never inverted.

The attributes of the system are modified in-place. Note that this method only works on 3D periodic systems.

supercell(*reps)

Return a supercell of the system.

Arguments:

reps
An array with repetitions, which must have the same number of elements as the number of cell vectors.

If this method is called with a non-periodic system, a TypeError is raised.

remove_duplicate(threshold=0.1)

Return a system object in which the duplicate atoms and bonds are removed.

Optional argument:

threshold
The minimum distance between two atoms that are supposed to be different.

When it makes sense, properties of overlapping atoms are averaged out. In other cases, the atom with the lowest index in a cluster of overlapping atoms defines the new value of a property.

subsystem(indexes)

Return a System instance in which only the given atom are retained.

cut_bonds(indexes)

Remove all bonds of a fragment with the remainder of the system;

Arguments:

indexes
The atom indexes in the fragment
iter_matches(other, overlapping=True)

Yield all renumberings of atoms that map the given system on the current.

Parameters:
  • other (yaff.System) – Another system with the same number of atoms (and chemical formula), or less atoms.
  • overlapping (bool) – When set to False, the returned matches are guaranteed to be mutually exclusive. The result may not be unique when partially overlapping matches would exist. Use with care.
  • graph distance is used to perform the mapping, so bonds must be defined in (The) –
  • current and the given system. (the) –

1.4. yaff.version – Do not edit this file, versioning is governed by git describe --tags and setup.py.

Do not edit this file, versioning is governed by git describe --tags and setup.py.