Add option to evaluate unit cells symbolically (#45)

<!-- Provide a general summary of your changes in the Title above -->

## Description
Unit cells can now be build symbolically, using `sympy`'s Rational
numbers to determine the correct atomic coordinates. This reduces
rounding errors for large and complicated unit cells and allows for more
accurate deduplication of atoms.

## Motivation and Context

As in #42 and #44, floating point errors can accumulate to result in
imperfect deduplication of atoms for complex structures. The new
implementation has a few changes:

- Fractional coordinates are rounded before PBC wrapping, reducing the
number of duplicate points near the edges of a cell
- Symmetry operation expressions can be evaluated symbolically by
setting the `parse_mode` flag of `build_unit_cell` to `sympy`. The
previous implementation is accessible by setting that value to
`python_float`
- New `sympy` evaluation mode is enabled by default only if sympy is
installed on the system.

### Notes on the method

Symbolically evaluating every site is slow relative to the performance
of the pure python implementation - however, the total runtime per
crystal is on the order of tens of milliseconds and should be fast
enough for most users.

Symbolic evaluation of sites is NOT guaranteed to accurately reconstruct
every crystal! While `parsnip` works for 1102/1103 of the files in my
test suite, some tuning of `n_decimal_places` may be required. For
really degenerate systems (orthorhombic, monoclinic, or triclinic
crystals with >100 atoms and sites represented with 3 or fewer decimal
places), even symbolic evaluation may not be able to properly
deduplicate a crystal.

## Types of Changes
<!-- Please select all items that apply, either now or after creating
the pull request: -->
- [ ] Documentation update
- [x] Bug fix
- [x] New feature
- [ ] Breaking change<sup>1</sup>

<sup>1</sup>The change breaks (or has the potential to break) existing
functionality and should be merged into the `breaking` branch

## Checklist:
<!-- Please select all items that apply either now or after creating the
pull request. -->
- [x] I am familiar with the [Development
Guidelines](https://github.com/glotzerlab/parsnip/blob/main/doc/source/development.rst)
- [x] The changes introduced by this pull request are covered by
existing or newly introduced tests.
- [ ] I have updated the
[changelog](https://github.com/glotzerlab/parsnip/blob/main/ChangeLog.rst)
and added my name to the
[credits](https://github.com/glotzerlab/parsnip/blob/main/doc/source/credits.rst).

Author: janbridley

.github/requirements-3.10.txt

@@ -1,5 +1,5 @@
 # This file was autogenerated by uv via the following command:
-#    uv pip compile --python-version=3.10 pyproject.toml tests/requirements.in
+#    uv --allow-python-downloads pip compile --python-version=3.10 pyproject.toml requirements-sympy.txt tests/requirements.in
 ase==3.24.0
     # via -r tests/requirements.in
 contourpy==1.3.1
@@ -8,19 +8,21 @@ cycler==0.12.1
     # via matplotlib
 exceptiongroup==1.2.2
     # via pytest
-fonttools==4.56.0
+fonttools==4.57.0
     # via matplotlib
-gemmi==0.7.0
+gemmi==0.7.1
     # via -r tests/requirements.in
-iniconfig==2.0.0
+iniconfig==2.1.0
     # via pytest
 kiwisolver==1.4.8
     # via matplotlib
 matplotlib==3.10.1
     # via ase
 more-itertools==10.6.0
     # via parsnip-cif (pyproject.toml)
-numpy==2.2.3
+mpmath==1.3.0
+    # via sympy
+numpy==2.2.4
     # via
     #   parsnip-cif (pyproject.toml)
     #   ase
@@ -39,9 +41,11 @@ pluggy==1.5.0
     # via pytest
 ply==3.11
     # via pycifrw
-pycifrw==4.4.6
+prettytable==3.16.0
+    # via pycifrw
+pycifrw==5.0.1
     # via -r tests/requirements.in
-pyparsing==3.2.1
+pyparsing==3.2.3
     # via matplotlib
 pytest==8.3.5
     # via
@@ -55,5 +59,11 @@ scipy==1.15.2
     # via ase
 six==1.17.0
     # via python-dateutil
+sympy==1.13.3
+    # via
+    #   -r requirements-sympy.txt
+    #   -r tests/requirements.in
 tomli==2.2.1
     # via pytest
+wcwidth==0.2.13
+    # via prettytable

.github/requirements-3.11.txt

@@ -1,24 +1,26 @@
 # This file was autogenerated by uv via the following command:
-#    uv pip compile --python-version=3.11 pyproject.toml tests/requirements.in
+#    uv --allow-python-downloads pip compile --python-version=3.11 pyproject.toml requirements-sympy.txt tests/requirements.in
 ase==3.24.0
     # via -r tests/requirements.in
 contourpy==1.3.1
     # via matplotlib
 cycler==0.12.1
     # via matplotlib
-fonttools==4.56.0
+fonttools==4.57.0
     # via matplotlib
-gemmi==0.7.0
+gemmi==0.7.1
     # via -r tests/requirements.in
-iniconfig==2.0.0
+iniconfig==2.1.0
     # via pytest
 kiwisolver==1.4.8
     # via matplotlib
 matplotlib==3.10.1
     # via ase
 more-itertools==10.6.0
     # via parsnip-cif (pyproject.toml)
-numpy==2.2.3
+mpmath==1.3.0
+    # via sympy
+numpy==2.2.4
     # via
     #   parsnip-cif (pyproject.toml)
     #   ase
@@ -37,9 +39,11 @@ pluggy==1.5.0
     # via pytest
 ply==3.11
     # via pycifrw
-pycifrw==4.4.6
+prettytable==3.16.0
+    # via pycifrw
+pycifrw==5.0.1
     # via -r tests/requirements.in
-pyparsing==3.2.1
+pyparsing==3.2.3
     # via matplotlib
 pytest==8.3.5
     # via
@@ -53,3 +57,9 @@ scipy==1.15.2
     # via ase
 six==1.17.0
     # via python-dateutil
+sympy==1.13.3
+    # via
+    #   -r requirements-sympy.txt
+    #   -r tests/requirements.in
+wcwidth==0.2.13
+    # via prettytable

.github/requirements-3.12.txt

@@ -1,24 +1,26 @@
 # This file was autogenerated by uv via the following command:
-#    uv pip compile --python-version=3.12 pyproject.toml tests/requirements.in
+#    uv --allow-python-downloads pip compile --python-version=3.12 pyproject.toml requirements-sympy.txt tests/requirements.in
 ase==3.24.0
     # via -r tests/requirements.in
 contourpy==1.3.1
     # via matplotlib
 cycler==0.12.1
     # via matplotlib
-fonttools==4.56.0
+fonttools==4.57.0
     # via matplotlib
-gemmi==0.7.0
+gemmi==0.7.1
     # via -r tests/requirements.in
-iniconfig==2.0.0
+iniconfig==2.1.0
     # via pytest
 kiwisolver==1.4.8
     # via matplotlib
 matplotlib==3.10.1
     # via ase
 more-itertools==10.6.0
     # via parsnip-cif (pyproject.toml)
-numpy==2.2.3
+mpmath==1.3.0
+    # via sympy
+numpy==2.2.4
     # via
     #   parsnip-cif (pyproject.toml)
     #   ase
@@ -37,9 +39,11 @@ pluggy==1.5.0
     # via pytest
 ply==3.11
     # via pycifrw
-pycifrw==4.4.6
+prettytable==3.16.0
+    # via pycifrw
+pycifrw==5.0.1
     # via -r tests/requirements.in
-pyparsing==3.2.1
+pyparsing==3.2.3
     # via matplotlib
 pytest==8.3.5
     # via
@@ -53,3 +57,9 @@ scipy==1.15.2
     # via ase
 six==1.17.0
     # via python-dateutil
+sympy==1.13.3
+    # via
+    #   -r requirements-sympy.txt
+    #   -r tests/requirements.in
+wcwidth==0.2.13
+    # via prettytable

.github/requirements-3.13.txt

@@ -1,24 +1,26 @@
 # This file was autogenerated by uv via the following command:
-#    uv pip compile --python-version=3.13 pyproject.toml tests/requirements.in
+#    uv --allow-python-downloads pip compile --python-version=3.13 pyproject.toml requirements-sympy.txt tests/requirements.in
 ase==3.24.0
     # via -r tests/requirements.in
 contourpy==1.3.1
     # via matplotlib
 cycler==0.12.1
     # via matplotlib
-fonttools==4.56.0
+fonttools==4.57.0
     # via matplotlib
-gemmi==0.7.0
+gemmi==0.7.1
     # via -r tests/requirements.in
-iniconfig==2.0.0
+iniconfig==2.1.0
     # via pytest
 kiwisolver==1.4.8
     # via matplotlib
 matplotlib==3.10.1
     # via ase
 more-itertools==10.6.0
     # via parsnip-cif (pyproject.toml)
-numpy==2.2.3
+mpmath==1.3.0
+    # via sympy
+numpy==2.2.4
     # via
     #   parsnip-cif (pyproject.toml)
     #   ase
@@ -37,9 +39,11 @@ pluggy==1.5.0
     # via pytest
 ply==3.11
     # via pycifrw
-pycifrw==4.4.6
+prettytable==3.16.0
+    # via pycifrw
+pycifrw==5.0.1
     # via -r tests/requirements.in
-pyparsing==3.2.1
+pyparsing==3.2.3
     # via matplotlib
 pytest==8.3.5
     # via
@@ -53,3 +57,9 @@ scipy==1.15.2
     # via ase
 six==1.17.0
     # via python-dateutil
+sympy==1.13.3
+    # via
+    #   -r requirements-sympy.txt
+    #   -r tests/requirements.in
+wcwidth==0.2.13
+    # via prettytable

.github/requirements-3.8.txt

@@ -1,5 +1,5 @@
 # This file was autogenerated by uv via the following command:
-#    uv pip compile --python-version=3.8 pyproject.toml tests/requirements.in
+#    uv --allow-python-downloads pip compile --python-version=3.8 pyproject.toml requirements-sympy.txt tests/requirements.in
 ase==3.23.0
     # via -r tests/requirements.in
 contourpy==1.1.1
@@ -8,23 +8,25 @@ cycler==0.12.1
     # via matplotlib
 exceptiongroup==1.2.2
     # via pytest
-fonttools==4.55.3
+fonttools==4.57.0
     # via matplotlib
-gemmi==0.7.0
+gemmi==0.7.1
     # via -r tests/requirements.in
 importlib-resources==6.4.5
     # via matplotlib
-iniconfig==2.0.0
+iniconfig==2.1.0
     # via pytest
 kiwisolver==1.4.7
     # via matplotlib
 matplotlib==3.7.5
     # via ase
 more-itertools==10.5.0
-    # via parsnip (pyproject.toml)
+    # via parsnip-cif (pyproject.toml)
+mpmath==1.3.0
+    # via sympy
 numpy==1.24.4
     # via
-    #   parsnip (pyproject.toml)
+    #   parsnip-cif (pyproject.toml)
     #   ase
     #   contourpy
     #   matplotlib
@@ -41,11 +43,13 @@ pluggy==1.5.0
     # via pytest
 ply==3.11
     # via pycifrw
-pycifrw==4.4.6
+prettytable==3.11.0
+    # via pycifrw
+pycifrw==5.0.1
     # via -r tests/requirements.in
 pyparsing==3.1.4
     # via matplotlib
-pytest==8.3.4
+pytest==8.3.5
     # via
     #   -r tests/requirements.in
     #   pytest-doctestplus
@@ -57,7 +61,13 @@ scipy==1.10.1
     # via ase
 six==1.17.0
     # via python-dateutil
+sympy==1.13.3
+    # via
+    #   -r requirements-sympy.txt
+    #   -r tests/requirements.in
 tomli==2.2.1
     # via pytest
+wcwidth==0.2.13
+    # via prettytable
 zipp==3.20.2
     # via importlib-resources

.github/requirements-3.9.txt

@@ -1,5 +1,5 @@
 # This file was autogenerated by uv via the following command:
-#    uv pip compile --python-version=3.9 pyproject.toml tests/requirements.in
+#    uv --allow-python-downloads pip compile --python-version=3.9 pyproject.toml requirements-sympy.txt tests/requirements.in
 ase==3.24.0
     # via -r tests/requirements.in
 contourpy==1.3.0
@@ -8,20 +8,22 @@ cycler==0.12.1
     # via matplotlib
 exceptiongroup==1.2.2
     # via pytest
-fonttools==4.56.0
+fonttools==4.57.0
     # via matplotlib
-gemmi==0.7.0
+gemmi==0.7.1
     # via -r tests/requirements.in
 importlib-resources==6.5.2
     # via matplotlib
-iniconfig==2.0.0
+iniconfig==2.1.0
     # via pytest
 kiwisolver==1.4.7
     # via matplotlib
 matplotlib==3.9.4
     # via ase
 more-itertools==10.6.0
     # via parsnip-cif (pyproject.toml)
+mpmath==1.3.0
+    # via sympy
 numpy==2.0.2
     # via
     #   parsnip-cif (pyproject.toml)
@@ -41,9 +43,11 @@ pluggy==1.5.0
     # via pytest
 ply==3.11
     # via pycifrw
-pycifrw==4.4.6
+prettytable==3.16.0
+    # via pycifrw
+pycifrw==5.0.1
     # via -r tests/requirements.in
-pyparsing==3.2.1
+pyparsing==3.2.3
     # via matplotlib
 pytest==8.3.5
     # via
@@ -57,7 +61,13 @@ scipy==1.13.1
     # via ase
 six==1.17.0
     # via python-dateutil
+sympy==1.13.3
+    # via
+    #   -r requirements-sympy.txt
+    #   -r tests/requirements.in
 tomli==2.2.1
     # via pytest
+wcwidth==0.2.13
+    # via prettytable
 zipp==3.21.0
     # via importlib-resources

.github/workflows/update-uv-lockfiles.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-for version in 3.{9..13}; do
-    uv pip compile --python-version="$version" pyproject.toml tests/requirements.in > ".github/requirements-$version.txt"
+for version in 3.{8..13}; do
+    uv pip compile --python-version="$version" pyproject.toml requirements-sympy.txt tests/requirements.in > ".github/requirements-$version.txt"
 done

README.rst

@@ -75,7 +75,8 @@ additional dependencies are required to run the tests and build the docs.
 .. code:: bash
 
     pip install .            # Install with no additional dependencies
-    pip install .[tests]     # Install with dependencies required to run tests
+    pip install .[sympy]     # Install with sympy for symbolic unit cell math
+    pip install .[tests]     # Install with dependencies required to run tests (including sympy)
     pip install .[tests,doc] # Install with dependencies required to run tests and make docs
 
 Dependencies

changelog.rst

@@ -10,11 +10,19 @@ v0.X.X - 20XX-XX-XX
 Added
 ~~~~~
 - Additional testpath flag to conftest
+- Symbolic parsing mode for ``build_unit_cell``
+
+Changed
+~~~~~~~
+- ``build_unit_cell`` now uses sympy by default if it is intalled - otherwise, it falls
+  back to the previous variant
 
 Fixed
 ~~~~~
 - Accessing data pairs with ``get_from_pairs`` or ``__getitem__`` now allows for case-insensitive searches
 - Quote-delimited strings containing the delimiting character are now parsed properly
+- ``build_unit_cell`` now rounds coordinates before wrapping into the box, fixing edge cases
+  where boundary atoms were not properly deduplicated
 
 v0.2.1 - 2025-03-12
 -------------------