# pbc_distance_calculator
This Python package computes pairwise distances in a simulation box accounting for [periodic boundary conditions](https://en.wikipedia.org/wiki/Periodic_boundary_conditions).
The only inputs are the positions of each particle and the simulation supercell matrix.
To install:
```bash
pip install pbc_distance_calculator
```
Example usage:
```python
from numpy.typing import NDArray
from pbc_distance_calculator import get_pairwise_distances
# array of shape (N, 3) where N is the number of particles
positions: NDArray = ...
# array of shape (3, 3)
cell_matrix: NDArray = ...
# array of shape (N, N)
# element (i, j) is minimum image distance between i and j
pairwise_distances: NDArray = get_pairwise_distances(positions, cell_matrix)
```
The above script performs the calculation in a vectorized form, computing every pairwise distance at once. To do it serially instead:
```python
from numpy.typing import NDArray
from pbc_distance_calculator import get_pairwise_distance
# arrays of shape (1, 3) or (3, 1)
first_position: NDArray = ...
second_position: NDArray = ...
# array of shape (3, 3)
cell_matrix: NDArray = ...
# minimum image distance
pairwise_distance: float = get_pairwise_distance(
first_position - second_position,
cell_matrix
)
```
In both functions, you can also specify different engines to compute the distances. This is especially advantageous for large systems, where you can specify ``jax.numpy`` or ``torch`` as an engine. For example:
```python
import torch
from pbc_distance_calculator import get_pairwise_distances
...
torch.set_default_device("cuda")
pairwise_distances = get_pairwise_distances(
positions,
cell_matrix,
engine=torch
)
```
which will calculate the pairwise distances using the CUDA-backend of PyTorch. Note that the only engine installed by default is ``numpy``, so make sure to separately install ``jax`` or ``torch`` if you want to use these modules.
Note that the cell matrix, is, in general:
$$
\begin{pmatrix} \mathbf{a} & \mathbf{b} & \mathbf{c} \end{pmatrix}
$$
where $\mathbf{a}$, $\mathbf{b}$, and $\mathbf{c}$ are the lattice vectors of the supercell. Note that this definition works for any set of lattice parameters! So, no matter how weird your crystal, this package should work. If there are any problems, feel free to [open an issue](https://github.com/MUEXLY/pbc_distance_calculator/issues) 🙂.
Raw data
{
"_id": null,
"home_page": "https://github.com/muexly/pbc_distance_calculator",
"name": "pbc-distance-calculator",
"maintainer": null,
"docs_url": null,
"requires_python": "<=3.12,>=3.8",
"maintainer_email": null,
"keywords": "periodic-boundary-conditions, distance-computation, simulation, molecular-dynamics, lattice-systems, neighbor-lists, periodic-images",
"author": "Jacob Jeffries",
"author_email": "jwjeffr@clemson.edu",
"download_url": "https://files.pythonhosted.org/packages/c5/16/45575fbf83b3d43305d86038324b5cac7f28a46e915d0c5e82bb7aefafc7/pbc_distance_calculator-1.3.1.tar.gz",
"platform": null,
"description": "# pbc_distance_calculator\n\n\n\nThis Python package computes pairwise distances in a simulation box accounting for [periodic boundary conditions](https://en.wikipedia.org/wiki/Periodic_boundary_conditions).\n\nThe only inputs are the positions of each particle and the simulation supercell matrix.\n\nTo install:\n\n```bash\npip install pbc_distance_calculator\n```\n\nExample usage:\n\n```python\nfrom numpy.typing import NDArray\nfrom pbc_distance_calculator import get_pairwise_distances\n\n# array of shape (N, 3) where N is the number of particles\npositions: NDArray = ...\n\n# array of shape (3, 3)\ncell_matrix: NDArray = ...\n\n# array of shape (N, N)\n# element (i, j) is minimum image distance between i and j\npairwise_distances: NDArray = get_pairwise_distances(positions, cell_matrix)\n```\n\nThe above script performs the calculation in a vectorized form, computing every pairwise distance at once. To do it serially instead:\n\n```python\nfrom numpy.typing import NDArray\nfrom pbc_distance_calculator import get_pairwise_distance\n\n# arrays of shape (1, 3) or (3, 1)\nfirst_position: NDArray = ...\nsecond_position: NDArray = ...\n\n# array of shape (3, 3)\ncell_matrix: NDArray = ...\n\n# minimum image distance\npairwise_distance: float = get_pairwise_distance(\n first_position - second_position,\n cell_matrix\n)\n```\n\nIn both functions, you can also specify different engines to compute the distances. This is especially advantageous for large systems, where you can specify ``jax.numpy`` or ``torch`` as an engine. For example:\n\n```python\nimport torch\nfrom pbc_distance_calculator import get_pairwise_distances\n\n...\n\ntorch.set_default_device(\"cuda\")\npairwise_distances = get_pairwise_distances(\n positions,\n cell_matrix,\n engine=torch\n)\n```\n\nwhich will calculate the pairwise distances using the CUDA-backend of PyTorch. Note that the only engine installed by default is ``numpy``, so make sure to separately install ``jax`` or ``torch`` if you want to use these modules.\n\nNote that the cell matrix, is, in general:\n\n$$\n\\begin{pmatrix} \\mathbf{a} & \\mathbf{b} & \\mathbf{c} \\end{pmatrix}\n$$\n\nwhere $\\mathbf{a}$, $\\mathbf{b}$, and $\\mathbf{c}$ are the lattice vectors of the supercell. Note that this definition works for any set of lattice parameters! So, no matter how weird your crystal, this package should work. If there are any problems, feel free to [open an issue](https://github.com/MUEXLY/pbc_distance_calculator/issues) \ud83d\ude42.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A package for computing distances accounting for periodic boundary conditions",
"version": "1.3.1",
"project_urls": {
"Homepage": "https://github.com/muexly/pbc_distance_calculator"
},
"split_keywords": [
"periodic-boundary-conditions",
" distance-computation",
" simulation",
" molecular-dynamics",
" lattice-systems",
" neighbor-lists",
" periodic-images"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b03192de9ddb8ed4701115bd08aead33d0dc53e5ad87fbed662d67844d0e4d9f",
"md5": "cec41a4eac8d4509bbc813215fc59b4a",
"sha256": "94ae663d41c5c9e73dbb650ca68ef3d1b7d36d51425629300b37d7e2e6cf9fb5"
},
"downloads": -1,
"filename": "pbc_distance_calculator-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cec41a4eac8d4509bbc813215fc59b4a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<=3.12,>=3.8",
"size": 5710,
"upload_time": "2024-05-09T20:15:41",
"upload_time_iso_8601": "2024-05-09T20:15:41.586332Z",
"url": "https://files.pythonhosted.org/packages/b0/31/92de9ddb8ed4701115bd08aead33d0dc53e5ad87fbed662d67844d0e4d9f/pbc_distance_calculator-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c51645575fbf83b3d43305d86038324b5cac7f28a46e915d0c5e82bb7aefafc7",
"md5": "133ea06bd35c0ed15eee519cffe4a154",
"sha256": "2209d4ef868092e55f9bcde5a3618d26b6b37d144a042ea99dc79a6322e7c21d"
},
"downloads": -1,
"filename": "pbc_distance_calculator-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "133ea06bd35c0ed15eee519cffe4a154",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<=3.12,>=3.8",
"size": 4791,
"upload_time": "2024-05-09T20:15:42",
"upload_time_iso_8601": "2024-05-09T20:15:42.813663Z",
"url": "https://files.pythonhosted.org/packages/c5/16/45575fbf83b3d43305d86038324b5cac7f28a46e915d0c5e82bb7aefafc7/pbc_distance_calculator-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-09 20:15:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "muexly",
"github_project": "pbc_distance_calculator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "setuptools",
"specs": []
}
],
"lcname": "pbc-distance-calculator"
}
JSON
