Vecctor Support

Vecctor Support#

NumPy-based 3D vector mathematics for molecular analysis.

This module provides efficient vector operations for high-performance molecular geometry calculations, supporting both single vectors and batch operations on multiple vectors simultaneously.

class hbat.core.np_vector.NPVec3D(coords: float | ndarray | List[float] | Tuple[float, float, float] = 0.0, y: float | None = None, z: float | None = None)[source]#

Bases: object

NumPy-based 3D vector class for molecular calculations.

This class provides comprehensive 3D vector operations using NumPy, enabling efficient batch processing of multiple vectors simultaneously.

Parameters:

  • coords (Union[float, np.ndarray]) – Either x,y,z coordinates or numpy array of shape (3,) or (N,3)

  • y (Optional[float]) – Y coordinate (only if coords is a float)

  • z (Optional[float]) – Z coordinate (only if coords is a float)

__init__(coords: float | ndarray | List[float] | Tuple[float, float, float] = 0.0, y: float | None = None, z: float | None = None)[source]#

Initialize a 3D vector or batch of vectors.

property x: float | ndarray#

X coordinate(s).

property y: float | ndarray#

Y coordinate(s).

property z: float | ndarray#

Z coordinate(s).

property shape: Tuple[int, ...]#

Shape of the underlying array.

property is_batch: bool#

Whether this represents multiple vectors.

__add__(other: NPVec3D | ndarray) → NPVec3D[source]#

Vector addition.

__sub__(other: NPVec3D | ndarray) → NPVec3D[source]#

Vector subtraction.

__mul__(scalar: float | ndarray) → NPVec3D[source]#

Scalar multiplication.

__rmul__(scalar: float | ndarray) → NPVec3D[source]#

Reverse scalar multiplication.

__truediv__(scalar: float | ndarray) → NPVec3D[source]#

Scalar division.

__eq__(other: object) → bool[source]#

Vector equality comparison.

__getitem__(index: int | slice | ndarray) → float | NPVec3D[source]#

Get component or subset.

dot(other: NPVec3D) → float | ndarray[source]#

Dot product with another vector.

Parameters:

other (NPVec3D) – The other vector(s)

Returns:

Dot product result(s)

Return type:

Union[float, np.ndarray]

cross(other: NPVec3D) → NPVec3D[source]#

Cross product with another vector.

Parameters:

other (NPVec3D) – The other vector(s)

Returns:

Cross product vector(s)

Return type:

NPVec3D

length() → float | ndarray[source]#

Calculate vector length/magnitude.

Returns:

Euclidean length of the vector(s)

Return type:

Union[float, np.ndarray]

magnitude() → float | ndarray[source]#

Alias for length().

normalize() → NPVec3D[source]#

Return normalized unit vector(s).

Returns:

Unit vector(s) in the same direction

Return type:

NPVec3D

unit_vector() → NPVec3D[source]#

Alias for normalize().

distance_to(other: NPVec3D) → float | ndarray[source]#

Calculate distance to another vector.

Parameters:

other (NPVec3D) – The target vector(s)

Returns:

Euclidean distance(s) between vectors

Return type:

Union[float, np.ndarray]

angle_to(other: NPVec3D) → float | ndarray[source]#

Calculate angle to another vector in radians.

Parameters:

other (NPVec3D) – The target vector(s)

Returns:

Angle(s) between vectors in radians

Return type:

Union[float, np.ndarray]

to_array() → ndarray[source]#

Convert to numpy array.

Returns:

Numpy array of coordinates

Return type:

np.ndarray

to_list() → List[float][source]#

Convert to list [x, y, z] (single vector only).

Returns:

Vector components as a list

Return type:

List[float]

to_tuple() → Tuple[float, float, float][source]#

Convert to tuple (x, y, z) (single vector only).

Returns:

Vector components as a tuple

Return type:

Tuple[float, float, float]

classmethod from_list(coords: List[float]) → NPVec3D[source]#

Create vector from list [x, y, z].

Parameters:

coords (List[float]) – List of coordinates

Returns:

New NPVec3D instance

Return type:

NPVec3D

classmethod from_tuple(coords: Tuple[float, ...]) → NPVec3D[source]#

Create vector from tuple (x, y, z).

Parameters:

coords (Tuple[float, ...]) – Tuple of coordinates

Returns:

New NPVec3D instance

Return type:

NPVec3D

classmethod from_atoms(atoms: List) → NPVec3D[source]#

Create batch vector from list of atoms.

Parameters:

atoms (List) – List of atoms with x, y, z attributes

Returns:

Batch NPVec3D instance

Return type:

NPVec3D

hbat.core.np_vector.compute_distance_matrix(coords1: ndarray, coords2: ndarray | None = None) → ndarray[source]#

Compute pairwise distance matrix between two sets of coordinates.

Parameters:

  • coords1 (np.ndarray) – First set of coordinates, shape (N, 3)

  • coords2 (Optional[np.ndarray]) – Second set of coordinates, shape (M, 3). If None, computes self-distances

Returns:

Distance matrix of shape (N, M) or (N, N)

Return type:

np.ndarray

hbat.core.np_vector.batch_angle_between(a: NPVec3D, b: NPVec3D, c: NPVec3D | None = None) → float | ndarray[source]#

Calculate angles between vectors (optimized for batches).

If c is provided: Calculate angle ABC where B is the vertex. If c is None: Calculate angle between vectors a and b.

Parameters:

  • a (NPVec3D) – First vector(s) or point(s) A

  • b (NPVec3D) – Second vector(s) or vertex point(s) B

  • c (Optional[NPVec3D]) – Optional third point(s) C for angle ABC

Returns:

Angle(s) in radians

Return type:

Union[float, np.ndarray]

hbat.core.np_vector.batch_dihedral_angle(a: NPVec3D, b: NPVec3D, c: NPVec3D, d: NPVec3D) → float | ndarray[source]#

Calculate dihedral angles between planes ABC and BCD (optimized for batches).

Parameters:

  • a (NPVec3D) – First point(s) defining plane ABC

  • b (NPVec3D) – Second point(s) defining both planes

  • c (NPVec3D) – Third point(s) defining both planes

  • d (NPVec3D) – Fourth point(s) defining plane BCD

Returns:

Dihedral angle(s) in radians

Return type:

Union[float, np.ndarray]

Contents