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]

The np_vector module provides NumPy-optimized 3D vector mathematics for high-performance molecular analysis.

Key Features#

  • Vectorized Operations: All operations support batch processing of multiple vectors simultaneously

  • NumPy Integration: Leverages NumPy’s optimized C implementations for fast computation

  • Compatibility: Maintains API compatibility with the original Vec3D class for easy migration

  • Performance: 10-100x faster for operations on large sets of coordinates

Classes#

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]#

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

Functions#

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]

Usage Examples#

Single Vector Operations:

from hbat.core.np_vector import NPVec3D

# Create vectors
v1 = NPVec3D(1.0, 2.0, 3.0)
v2 = NPVec3D(4.0, 5.0, 6.0)

# Vector operations
v3 = v1 + v2
distance = v1.distance_to(v2)
angle = v1.angle_to(v2)
dot_product = v1.dot(v2)

Batch Operations:

import numpy as np
from hbat.core.np_vector import NPVec3D, compute_distance_matrix

# Create batch of vectors
coords = np.array([[1.0, 2.0, 3.0],
                   [4.0, 5.0, 6.0],
                   [7.0, 8.0, 9.0]])
vectors = NPVec3D(coords)

# Compute all pairwise distances
distances = compute_distance_matrix(coords)

# Batch angle calculations
angles = vectors[0].angle_to(vectors[1:])

Performance Comparison#

The NumPy implementation provides significant performance improvements:

  • Distance matrix computation: ~50-100x faster for 1000+ atoms

  • Batch angle calculations: ~20-50x faster

  • Vector normalization: ~30x faster for batch operations

Migration Guide#

To migrate from Vec3D to NPVec3D:

  1. Replace imports:

    # Old
from hbat.core.vector import Vec3D

# New
from hbat.core.np_vector import NPVec3D

  2. The API is mostly compatible, but NPVec3D supports batch operations:

    # Single vector (works the same)
v = NPVec3D(x, y, z)

# Batch operations (new capability)
coords = np.array([[x1, y1, z1], [x2, y2, z2], ...])
batch = NPVec3D(coords)
Contents