arc.species.vectors

A module for manipulating vectors

arc.species.vectors.apply_rodrigues_rotation(coords, axis_origin, axis_unit, angle_rad, indices)[source]

Rotate atoms at indices around an axis using Rodrigues’ formula.

Modifies coords in-place and returns it.

Parameters:

  • coords – list of (x, y, z) tuples representing all atom positions.

  • axis_origin – a point on the rotation axis (e.g., coords of the near-side pivot).

  • axis_unit – unit vector along the rotation axis.

  • angle_rad – rotation angle in radians (positive = right-hand rule around axis_unit).

  • indices – 0-indexed atom indices to rotate.

Returns:

The same coords list with rotated atoms.

Return type:

list

arc.species.vectors.calculate_angle(coords, atoms, index=0, units='degs')[source]

Calculate an angle.

Parameters:

  • coords (list, tuple, dict) – The array-format or tuple-format coordinates, or the xyz dict.

  • atoms (list) – The 3 atoms defining the angle.

  • index (int, optional) – Whether atoms is 0-indexed or 1-indexed (values are 0 or 1).

  • units (str, optional) – The desired units, either ‘rads’ for radians, or ‘degs’ for degrees.

Raises:

  • VectorsError – If index is out of range, or atoms is of wrong length or has repeating indices.

  • TypeError – If coords is of wrong type.

Returns: float

The angle.

arc.species.vectors.calculate_dihedral_angle(coords, torsion, index=0, units='degs')[source]

Calculate a dihedral angle.

Parameters:

  • coords (list, tuple, dict) – The array-format or tuple-format coordinates, or the xyz dict.

  • torsion (list) – The 4 atoms defining the dihedral angle.

  • index (int, optional) – Whether torsion is 0-indexed or 1-indexed (values are 0 or 1).

  • units (str, optional) – The desired units, either ‘rads’ for radians, or ‘degs’ for degrees.

Raises:

  • VectorsError – If index is out of range, or torsion is of wrong length or has repeating indices.

  • TypeError – If coords is of wrong type.

Returns: float

The dihedral angle in a 0-360 degrees range.

arc.species.vectors.calculate_distance(coords, atoms, index=0)[source]

Calculate a distance.

Parameters:

  • coords (list, tuple, dict) – The array-format or tuple-format coordinates, or the xyz dict.

  • atoms (list) – The 2 atoms to calculate defining the vector for which the length will be calculated.

  • index (int, optional) – Whether atoms is 0-indexed or 1-indexed (values are 0 or 1).

Raises:

  • VectorsError – If index is out of range, or atoms is of wrong length or has repeating indices.

  • TypeError – If coords is of wrong type.

Returns: float

The distance in the coords units.

arc.species.vectors.calculate_param(coords, atoms, index=0)[source]

Calculate a distance / angle / dihedral angle parameter. Default units (deg for angles) are used.

Parameters:

  • coords (list, tuple, dict) – The array-format or tuple-format coordinates, or the xyz dict.

  • atoms (list) – The 2 atoms to calculate defining the vector for which the length will be calculated.

  • index (int, optional) – Whether atoms is 0-indexed or 1-indexed (values are 0 or 1).

Returns: float

The calculated parameter.

arc.species.vectors.get_angle(v1, v2, units='rads')[source]

Calculate the angle between two vectors.

Parameters:

  • v1 (list) – Vector 1.

  • v2 (list) – Vector 2.

  • units (str, optional) – The desired units, either ‘rads’ for radians, or ‘degs’ for degrees.

Raises:

VectorsError – If v1 and v2 are of different lengths.

Returns: float

The angle between v1 and v2 in the desired units.

arc.species.vectors.get_delta_angle(a1, a2)[source]

Get the difference between two (dihedral or regular) angles.

Examples::

3 - 1 = 2 1 - 3 = 2 1- 359 = 2

Parameters:

  • a1 (float) – Angle 1 in degrees.

  • a2 (float) – Angle 2 in degrees.

Returns: float

The difference between the angles in degrees.

arc.species.vectors.get_dihedral(v1, v2, v3, units='degs', tol=1e-08)[source]

Calculate the dihedral angle between three vectors. v2 connects between v1 and v3.

Parameters:

  • v1 (list) – Vector 1.

  • v2 (list) – Vector 2.

  • v3 (list) – Vector 3.

  • units (str, optional) – The desired units, either ‘rads’ for radians, or ‘degs’ for degrees.

  • tol (float, optional) – The tolerance for zero-length vectors.

Raises:

VectorsError – If either v1 or v2 have lengths different from three.

Returns: float

The dihedral angle between v1 and v2 in the desired units.

arc.species.vectors.get_lp_vector(label, mol, xyz, pivot)[source]

Get a vector from the pivotal atom in the molecule towards its lone electron pair (lp). The approach is to reverse the average of the three unit vectors between the pivotal atom and its neighbors.

Parameters:

  • label (str) – The species’ label.

  • mol (Molecule) – The 2D graph representation of the molecule.

  • xyz (dict) – The 3D coordinates of the molecule with the same atom order as in mol.

  • pivot (int) – The 0-index of the pivotal atom of interest.

Raises:

VectorsError – If the lp vector cannot be attained.

Returns: list

A unit vector pointing from the pivotal (nitrogen) atom towards its lone electron pairs orbital.

arc.species.vectors.get_normal(v1, v2)[source]

Calculate a normal vector using cross multiplication.

Parameters:

  • v1 (list) – Vector 1.

  • v2 (list) – Vector 2.

Returns: list

A normal unit vector to v1 and v2.

arc.species.vectors.get_perpendicular_axes(vector, tol=1e-08)[source]

Get the two unit vectors that complete a right-handed orthonormal frame with a given direction.

Writing e_x for the unit vector along vector, the returned e_y and e_z satisfy e_x x e_y = e_z. Their common phase about e_x is arbitrary: it is fixed by get_perpendicular_unit_vector(), so it is reproducible for a given input but carries no meaning of its own. Angles measured against the returned pair therefore retain their cyclic order about e_x while their absolute values do not.

Parameters:

  • vector (list) – The vector defining the first axis of the frame. Need not be normalized.

  • tol (float, optional) – The minimal accepted length of vector.

Raises:

VectorsError – If vector is not of length three, is not finite, is shorter than tol, or is long enough for its squared length to overflow.

Returns: tuple

The e_y and e_z unit vectors.

arc.species.vectors.get_perpendicular_unit_vector(vector)[source]

Get a deterministic unit vector perpendicular to vector.

Crossing vector with the Cartesian axis it is least aligned with can never be degenerate: the smallest component of a vector of length L is at most L / sqrt(3), so the cross product has a length of at least L * sqrt(2/3). Picking the axis by magnitude rather than arbitrarily keeps the result reproducible for a given input.

Parameters:

vector (list) – The vector to find a perpendicular of. Need not be normalized.

Raises:

  • VectorsError – If vector is not a finite, non-zero vector of length three.

  • ZeroDivisionError – If vector is non-zero but its squared length underflows to zero, which happens below a magnitude of about 1e-162.

Returns: list

A unit vector perpendicular to vector.

arc.species.vectors.get_vector(pivot, anchor, xyz)[source]

Get a vector between two atoms in the molecule (pointing from pivot to anchor).

Parameters:

  • pivot (int) – The 0-index of the pivotal atom around which groups are to be translated.

  • anchor (int) – The 0-index of an additional atom in the molecule.

  • xyz (dict) – The 3D coordinates of the molecule with the same atom order as in mol.

Returns: list

A vector pointing from the pivotal atom towards the anchor atom.

arc.species.vectors.get_vector_length(v)[source]

Get the length of an ND vector

Parameters:

v (list) – The vector.

Returns: float

The vector’s length.

arc.species.vectors.rotate_vector(point_a, point_b, normal, theta)[source]

Rotate a vector in 3D space around a given axis by a certain angle.

Inspired by https://stackoverflow.com/questions/6802577/rotation-of-3d-vector

Parameters:

  • point_a (list) – The 3D coordinates of the starting point (point A) of the vector to be rotated.

  • point_b (list) – The 3D coordinates of the ending point (point B) of the vector to be rotated.

  • normal (list) – The axis to be rotated around.

  • theta (float) – The degree in radians by which to rotate.

Returns: list

The rotated vector (the new coordinates for point B).

arc.species.vectors.set_vector_length(vector, length)[source]

Set the length of a 3D vector.

Parameters:

  • vector (list) – The vector to process.

  • length (float) – The desired length to set.

Returns: list

A vector with the desired length.

arc.species.vectors.unit_vector(vector)[source]

Calculate a unit vector in the same direction as the input vector.

Parameters:

vector (list) – The input vector.

Returns: list

The unit vector.