Skip to content

Coordinate Class

Overview

The Coordinate class represents a 3D coordinate with support for periodic boundary conditions. It provides efficient vector operations and is the fundamental building block for all spatial calculations in SMolSAT.

Class Definition

class Coordinate:
    """3D coordinate with periodic boundary condition support."""

Constructor

Coordinate(x=0.0, y=0.0, z=0.0)

Creates a new coordinate.

Parameters: - x (float): X coordinate (default: 0.0) - y (float): Y coordinate (default: 0.0)
- z (float): Z coordinate (default: 0.0)

Example: 

import smolsat

# Create coordinates
origin = smolsat.Coordinate()  # (0, 0, 0)
point = smolsat.Coordinate(1.0, 2.0, 3.0)

Properties

x() → float

Returns the X coordinate.

y() → float

Returns the Y coordinate.

z() → float

Returns the Z coordinate.

magnitude() → float

Returns the magnitude (length) of the coordinate vector.

Example: 

coord = smolsat.Coordinate(3.0, 4.0, 0.0)
print(f"Magnitude: {coord.magnitude()}")  # 5.0

Indexing

coord[index] → float

Access coordinates by index (0=x, 1=y, 2=z).

Parameters: - index (int): Index (0, 1, or 2)

Example: 

coord = smolsat.Coordinate(1.0, 2.0, 3.0)
print(coord[0])  # 1.0 (x)
print(coord[1])  # 2.0 (y)
print(coord[2])  # 3.0 (z)

Vector Operations

dot(other) → float

Calculates dot product with another coordinate.

Parameters: - other (Coordinate): Another coordinate

Returns: Dot product value

Example: 

coord1 = smolsat.Coordinate(1.0, 2.0, 3.0)
coord2 = smolsat.Coordinate(4.0, 5.0, 6.0)
dot_product = coord1.dot(coord2)  # 32.0

cross(other) → Coordinate

Calculates cross product with another coordinate.

Parameters: - other (Coordinate): Another coordinate

Returns: New coordinate representing the cross product

Example: 

coord1 = smolsat.Coordinate(1.0, 0.0, 0.0)
coord2 = smolsat.Coordinate(0.0, 1.0, 0.0)
cross_product = coord1.cross(coord2)  # (0, 0, 1)

distance_to(other) → float

Calculates Euclidean distance to another coordinate.

Parameters: - other (Coordinate): Target coordinate

Returns: Distance value

Example: 

coord1 = smolsat.Coordinate(0.0, 0.0, 0.0)
coord2 = smolsat.Coordinate(3.0, 4.0, 0.0)
distance = coord1.distance_to(coord2)  # 5.0

Periodic Boundary Conditions

distance_to_pbc(other, box_size) → float

Calculates minimum distance considering periodic boundary conditions.

Parameters: - other (Coordinate): Target coordinate - box_size (Coordinate): Box dimensions

Returns: Minimum distance with PBC

Example: 

coord1 = smolsat.Coordinate(0.5, 0.5, 0.5)
coord2 = smolsat.Coordinate(9.5, 9.5, 9.5)
box = smolsat.Coordinate(10.0, 10.0, 10.0)
distance_pbc = coord1.distance_to_pbc(coord2, box)  # ~1.73 (not 16.6)

wrap_pbc(box_size) → Coordinate

Wraps coordinate into the primary periodic cell.

Parameters: - box_size (Coordinate): Box dimensions

Returns: New coordinate wrapped into [0, box_size)

Example: 

coord = smolsat.Coordinate(12.3, -2.1, 5.0)
box = smolsat.Coordinate(10.0, 10.0, 10.0)
wrapped = coord.wrap_pbc(box)  # (2.3, 7.9, 5.0)

Arithmetic Operations

Addition: coord1 + coord2

Element-wise addition.

Subtraction: coord1 - coord2

Element-wise subtraction.

Multiplication: coord * scalar

Scalar multiplication.

Division: coord / scalar

Scalar division.

Example: 

coord1 = smolsat.Coordinate(2.0, 4.0, 6.0)
coord2 = smolsat.Coordinate(1.0, 2.0, 3.0)

sum_coord = coord1 + coord2      # (3.0, 6.0, 9.0)
diff_coord = coord1 - coord2     # (1.0, 2.0, 3.0)
scaled_coord = coord1 * 2.0      # (4.0, 8.0, 12.0)
divided_coord = coord1 / 2.0     # (1.0, 2.0, 3.0)

Eigen Integration

eigen() → numpy.ndarray

Returns the underlying Eigen::Vector3d as a NumPy array.

Returns: 3-element NumPy array

Example: 

import numpy as np
coord = smolsat.Coordinate(1.0, 2.0, 3.0)
array = coord.eigen()
print(type(array))  # <class 'numpy.ndarray'>
print(array)        # [1. 2. 3.]

String Representation

str(coord)

Returns formatted string representation.

Example: 

coord = smolsat.Coordinate(1.5, 2.5, 3.5)
print(coord)  # (1.500000, 2.500000, 3.500000)

Usage Examples

Basic Vector Calculations

import smolsat
import numpy as np

# Create vectors
a = smolsat.Coordinate(1.0, 2.0, 3.0)
b = smolsat.Coordinate(4.0, 5.0, 6.0)

# Vector operations
dot = a.dot(b)                    # 32.0
cross = a.cross(b)                # (-3, 6, -3)
magnitude_a = a.magnitude()       # 3.742
distance = a.distance_to(b)       # 5.196

Periodic Boundary Conditions

# Setup periodic system
box_size = smolsat.Coordinate(10.0, 10.0, 10.0)

# Particles near box boundaries
particle1 = smolsat.Coordinate(0.1, 5.0, 5.0)
particle2 = smolsat.Coordinate(9.9, 5.0, 5.0)

# Compare regular vs PBC distance
regular_dist = particle1.distance_to(particle2)      # 9.8
pbc_dist = particle1.distance_to_pbc(particle2, box_size)  # 0.2

# Wrap coordinates
unwrapped = smolsat.Coordinate(12.3, -1.5, 5.0)
wrapped = unwrapped.wrap_pbc(box_size)  # (2.3, 8.5, 5.0)

Integration with NumPy

import numpy as np

# Convert to NumPy for advanced operations
coord = smolsat.Coordinate(1.0, 2.0, 3.0)
array = coord.eigen()

# NumPy operations
normalized = array / np.linalg.norm(array)
rotated = np.dot(rotation_matrix, array)

# Create coordinate from NumPy array
new_coord = smolsat.Coordinate(rotated[0], rotated[1], rotated[2])

See Also

  • Particle - Uses coordinates for position data
  • System - Handles periodic boundary conditions
  • Trajectory - Manages coordinate time series