arc.species.vectors

A module for manipulating vectors

arc.species.vectors.calculate_angle(coords: list | tuple | dict, atoms: list, index: int = 0, units: str = 'degs') → float[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: list | tuple | dict, torsion: list, index: int = 0, units: str = 'degs') → float[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: list | tuple | dict, atoms: list, index: int = 0) → float[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: list | tuple | dict, atoms: list, index: int = 0) → float[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: List[float], v2: List[float], units: str = 'rads') → float[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: float, a2: float) → float[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: List[float], v2: List[float], v3: List[float], units: str = 'degs', tol: float = 1e-08) → float[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: str, mol: Molecule, xyz: dict, pivot: int) → list[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: List[float], v2: List[float]) → List[float][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_vector(pivot: int, anchor: int, xyz: dict) → list[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: List[float]) → float[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: List[float], point_b: List[float], normal: List[float], theta: float) → List[float][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: List[float], length: float) → List[float][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: List[float]) → List[float][source]

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

Parameters:

vector (list) – The input vector.

Returns: list

The unit vector.