torchref.base.coordinates package
Coordinate transformation functions for crystallography.
This submodule provides functions for transforming between different coordinate systems used in crystallography: - Cartesian <-> fractional coordinate conversions - Periodic boundary condition handling - Transformation matrix computations
Both PyTorch (GPU-accelerated) and NumPy (CPU) implementations are provided.
- torchref.base.coordinates.cartesian_to_fractional_torch(xyz, cell, B_inv=None)[source]
Convert Cartesian coordinates to fractional coordinates.
- Parameters:
xyz (torch.Tensor) – Cartesian coordinates of shape (N, 3).
cell (array-like) – Unit cell parameters [a, b, c, alpha, beta, gamma].
B_inv (torch.Tensor, optional) – Inverse fractionalization matrix. If None, it will be calculated from cell.
- Returns:
Fractional coordinates of shape (N, 3).
- Return type:
- torchref.base.coordinates.fractional_to_cartesian_torch(xyz_fractional, cell, B=None)[source]
Convert fractional coordinates to Cartesian coordinates.
- Parameters:
xyz_fractional (torch.Tensor) – Fractional coordinates of shape (N, 3).
cell (array-like) – Unit cell parameters [a, b, c, alpha, beta, gamma].
B (torch.Tensor, optional) – Fractionalization matrix. If None, it will be calculated from cell.
- Returns:
Cartesian coordinates of shape (N, 3).
- Return type:
- torchref.base.coordinates.get_fractional_matrix(cell)[source]
Calculate the fractional-to-Cartesian transformation matrix.
Constructs the matrix B that transforms fractional coordinates to Cartesian coordinates based on the unit cell parameters.
- Parameters:
cell (torch.Tensor) – Unit cell parameters [a, b, c, alpha, beta, gamma] where lengths are in Angstroms and angles are in degrees.
- Returns:
3x3 transformation matrix B such that cart = frac @ B.T.
- Return type:
- torchref.base.coordinates.get_inv_fractional_matrix_torch(cell)[source]
Calculate the Cartesian-to-fractional transformation matrix (PyTorch version).
Computes the inverse of the fractional matrix for converting Cartesian coordinates to fractional coordinates.
- Parameters:
cell (torch.Tensor) – Unit cell parameters [a, b, c, alpha, beta, gamma] where lengths are in Angstroms and angles are in degrees.
- Returns:
3x3 inverse transformation matrix B_inv such that frac = cart @ B_inv.T.
- Return type:
- torchref.base.coordinates.cartesian_to_fractional(xyz, cell)[source]
Convert Cartesian coordinates to fractional coordinates.
- Parameters:
xyz (numpy.ndarray) – Cartesian coordinates with shape (N, 3).
cell (numpy.ndarray or list) – Unit cell parameters [a, b, c, alpha, beta, gamma] where lengths are in Angstroms and angles are in degrees.
- Returns:
Fractional coordinates with shape (N, 3).
- Return type:
- torchref.base.coordinates.fractional_to_cartesian(xyz_fractional, cell)[source]
Convert fractional coordinates to Cartesian coordinates.
- Parameters:
xyz_fractional (numpy.ndarray) – Fractional coordinates with shape (N, 3).
cell (numpy.ndarray or list) – Unit cell parameters [a, b, c, alpha, beta, gamma] where lengths are in Angstroms and angles are in degrees.
- Returns:
Cartesian coordinates with shape (N, 3).
- Return type:
- torchref.base.coordinates.get_fractional_matrix_numpy(cell)
Calculate the fractional-to-Cartesian transformation matrix.
Constructs the matrix B that transforms fractional coordinates to Cartesian coordinates based on the unit cell parameters.
- Parameters:
cell (numpy.ndarray or list) – Unit cell parameters [a, b, c, alpha, beta, gamma] where lengths are in Angstroms and angles are in degrees.
- Returns:
3x3 transformation matrix B such that cart = frac @ B.T.
- Return type:
- torchref.base.coordinates.get_inv_fractional_matrix(cell)[source]
Calculate the Cartesian-to-fractional transformation matrix.
Computes the inverse of the fractional matrix for converting Cartesian coordinates to fractional coordinates.
- Parameters:
cell (numpy.ndarray or list) – Unit cell parameters [a, b, c, alpha, beta, gamma] where lengths are in Angstroms and angles are in degrees.
- Returns:
3x3 inverse transformation matrix B_inv such that frac = cart @ B_inv.T.
- Return type:
- torchref.base.coordinates.convert_coords_to_fractional(df, cell)[source]
Convert coordinates from a DataFrame to fractional coordinates.
Extracts x, y, z columns from a DataFrame and converts them from Cartesian to fractional coordinates.
- Parameters:
df (pandas.DataFrame) – DataFrame containing ‘x’, ‘y’, ‘z’ columns with Cartesian coordinates.
cell (numpy.ndarray or list) – Unit cell parameters [a, b, c, alpha, beta, gamma] where lengths are in Angstroms and angles are in degrees.
- Returns:
Fractional coordinates with shape (N, 3).
- Return type:
- torchref.base.coordinates.smallest_diff(diff, inv_frac_matrix, frac_matrix)[source]
Compute minimum image squared distances with periodic boundary conditions.
- Parameters:
diff (torch.Tensor) – Difference vectors of shape (…, 3).
inv_frac_matrix (torch.Tensor) – Inverse fractionalization matrix of shape (3, 3).
frac_matrix (torch.Tensor) – Fractionalization matrix of shape (3, 3).
- Returns:
Squared distances with shape (…).
- Return type:
- torchref.base.coordinates.smallest_diff_aniso(diff, inv_frac_matrix, frac_matrix)[source]
Compute minimum image difference vectors for anisotropic calculations.
- Parameters:
diff (torch.Tensor) – Difference vectors of shape (…, 3).
inv_frac_matrix (torch.Tensor) – Inverse fractionalization matrix of shape (3, 3).
frac_matrix (torch.Tensor) – Fractionalization matrix of shape (3, 3).
- Returns:
Signed difference vectors with shape (…, 3). Note: For anisotropic calculations, the signed vectors are needed to correctly compute the quadratic form r^T × B^(-1) × r with off-diagonal U tensor terms.
- Return type: