riigid.library package

riigid.library.misc module

A collection of miscellaneous functions.

riigid.library.misc.copy_docstring(take_from_fct)[source]

A decorator to copy the docstring of one function to a different function.

Parameters:

take_from_fct – The function, whose docstring shall be copied

Return type:

The decorator

Examples

>>> def fun1():
>>>     '''
>>>     This function has a docstring!
>>>     '''
>>>     return 1
>>>
>>> @copy_docstring(fun1)
>>> def fun2():
>>>     return 2
>>>
>>> help(fun2)
Help on function fun2 in module __main__:
fun2()
This function has a docstring!
riigid.library.misc.get_atoms_indices_by_height(all_atoms, middle_height, above=True, direction='z')[source]

The indices of atoms above/below middle_height are returned.

A useful function to find the indices of an fragment or to set up a new fragment.

above=True: Atoms above middle_height are considered and their indices in all_atoms are returned.

above=False: Atoms below middle_height are considered and their indices in all_atoms are returned.

Parameters:

  • all_atoms (ase.atoms.Atoms) – The full Atoms object

  • middle_height (number) – The height used to separate atoms; [Å]

  • above (Bool, default: True) – See explanation given above

  • direction ('x','y' or 'z', default: 'z') – The direction used to separate the atoms

Returns:

List containing indices of all atoms above/below middle_height

Return type:

list

Raises:

ValueError – If the given input value for the ‘direction’ parameter is not known.

riigid.library.misc.get_indices_of_atoms1_in_atoms2(atoms1, atoms2, cutoff=0.0001)[source]

Find the indices of the (the atoms of) atoms1 inside the atoms2 object.

In the typical use of this function, atoms1 are the atoms of a fragment, while atoms2 are the atoms of the full structure.

To determine the indices, atoms are considered identical, if they are of the same species and the distance between them is less than cutoff.

Parameters:

  • atoms1 (ase.atoms.Atoms) – The atoms, whose indices are searched

  • atoms2 (ase.atoms.Atoms) – The atoms, where atoms1 is searched in

  • cutoff (number, default: 1e-4) – Atoms closer than cutoff, which are of the same species, are considered identical

Returns:

  • list of int – The list of indices; Normally this should be of the same length as atoms1

  • bool – Was the search successful? If not all atoms were found (the returned list is shorter than len(atoms1)), this is set to False (In this case, the returned list is useless, but still returned for compatibility reasons). If all atoms have been found once (the returned list is of length len(atoms1)), this is set to True.

Raises:

RuntimeError – If some atoms have been found more than once, an exception is raised. This indicates an ill-defined Atoms object.

riigid.library.misc.redirect_stdout_to_file(filename)[source]

Decorator to redirect standard output (stdout) to a file during the execution of a function.

Parameters:

filename (str) – The name of the file to which stdout will be redirected.

Returns:

A decorator that takes a function and returns a wrapped function with stdout redirected.

Return type:

callable

riigid.library.rotation module

A collection of functions related to the rotation of fragments in RIIGID.

They are stored here, in a separate file, because they may also be useful somewhere else than just inside the Fragment class.

riigid.library.rotation.angle_between_vectors(v1, v2)[source]

Calculates the angle (in °) between two vectors in 3D.

Parameters:

  • v1 (list of length 3 or numpy.ndarray of shape (3,)) – The two vectors

  • v2 (list of length 3 or numpy.ndarray of shape (3,)) – The two vectors

Returns:

The angle between the two vectors; [°]

Return type:

number between 0 and 180

riigid.library.rotation.angles_between_principal_axes_and_xyz(mat_inertia)[source]

Calculate angles between x,y,z-axis and principal axes of inertia.

Takes the inertia matrix of a fragment, calculates the principal axes of inertia (eigenvectors) and then calculates the angles (in °) between these principal axes and the space-fixed x,y,z- axis. Can be used to identify the current rotation/orientation of the fragment, even in non-rigid (e.g. VASP) geometry optimizations.

Parameters:

mat_inertia (numpy.ndarray of shape (3,3)) – The inertia matrix of the fragment

Returns:

Matrix containing angels (in °) between principal axes and the x,y,z- axis; The element [i,j] of this matrix is the angle between principle axis j and axis i (i=0 means x, 1=y, 2=z); [°]

Return type:

numpy.ndarray of shape (3,3)

riigid.library.rotation.get_normal_vector_fragment(fragment)[source]

Find and return the (normalized) vector normal to a planar (non-linear) fragment.

The normal vector is calculated by looking for two atoms that form a near 90 ° angle (for numeric stability) and then calculating the normalized cross-product of these two vectors. The resulting vector is normal to the planar molecule.

The normal vector is obviously not unique, there are two possible directions. This function uses the following convention: If the normal vector has a nonzero z-component, then choose it to be positive. Otherwise, if it has a nonzero y-component, then choose this y-component to be positive. Otherwise choose the x-component to be positive.

Note

DO NOT USE THIS FUNCTION WITH A NON-PLANAR OR A LINEAR FRAGMENT!

Parameters:

fragment (riigid.Fragment) – The planar, non-linear fragment whose normal vector shall be calculated

Returns:

The normal vector

Return type:

numpy.ndarray of shape (3,)

Raises:

ValueError – If the normal vector search resulted in a zero-vector.

riigid.library.rotation.rotmat(axis, angle)[source]

Create 3x3 rotation matrix for the rotation around axis by angle.

Parameters:

  • axis (list of length 3 or numpy.ndarray of shape (3,)) – The rotation axis

  • angle (number) – The rotation angle; [°]

Returns:

The rotation matrix

Return type:

numpy.ndarray of shape (3,3)

References

Cole, Ian R. (2015). Modelling CPV. Loughborough University. Thesis. https://hdl.handle.net/2134/18050

riigid.library.rotation.signed_angle_between_vectors(v1, v2, axis)[source]

Calculates the “signed” angle (in °) between two vectors in 3D.

v1 and v2 have to be normal to axis. The angle is right-hand measured around axis, from v1 to v2

Parameters:

  • v1 (list of length 3 or numpy.ndarray of shape (3,)) – The two vectors and the axis

  • v2 (list of length 3 or numpy.ndarray of shape (3,)) – The two vectors and the axis

  • axis (list of length 3 or numpy.ndarray of shape (3,)) – The two vectors and the axis

Returns:

The angle between the two vectors; [°]

Return type:

number between 0 and 360