Skip to content
Draft
Changes from 1 commit
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
88a3e0f
Update documentation for the relationship between CIF grammar and the…
janbridley Dec 8, 2025
39a9396
Fix string format
janbridley Dec 8, 2025
e283d39
Unix-style wildcards doc
janbridley Dec 8, 2025
aaf5ad5
Remove exclamation points
janbridley Dec 8, 2025
c498b9d
Clean up development guide
janbridley Dec 8, 2025
6db5a2a
Swap to RST link style for doc comment
janbridley Dec 8, 2025
f77c6f8
Update type hints
janbridley Dec 8, 2025
5e82c5c
Add type hints where they cannot be inferred
janbridley Dec 8, 2025
4d0ba4d
Standardize error handling for gemmi tests
janbridley Dec 8, 2025
d032730
Clean up unused TODOs
janbridley Dec 8, 2025
ea0e515
One straggler TODO
janbridley Dec 8, 2025
92ef1f3
Note TODO
janbridley Dec 8, 2025
3550eae
Swap note -> attention admonition
janbridley Dec 8, 2025
8b0e7ff
Swap to caution
janbridley Dec 8, 2025
81ef61a
One more caution
janbridley Dec 8, 2025
f9522b7
Add GSD requirement for testing
janbridley Dec 8, 2025
c66d871
Fix typos
janbridley Dec 8, 2025
2fef24d
Add HOOMD-Blue example and examples toc section
janbridley Dec 8, 2025
e083212
Add LAMMPS example
janbridley Dec 8, 2025
fe34e8d
Fix LAMMPS example
janbridley Dec 8, 2025
13b2823
Remove unused line
janbridley Dec 8, 2025
9398394
Add noisy data and fix headers
janbridley Dec 8, 2025
6357459
Final title
janbridley Dec 8, 2025
a8d80f4
Doctest LAMMPS output
janbridley Dec 8, 2025
239dc7e
Add example on numerical precision
janbridley Dec 9, 2025
81b0771
Update requirements file for py3.14
janbridley Dec 9, 2025
6ec6f29
Update changelog.rst
janbridley Dec 9, 2025
1b5be04
Fix label in CHANGELOG
janbridley Dec 9, 2025
ab33ab2
Pre-compile patterns for unit cell evaluation
janbridley Dec 10, 2025
4129943
Add example for setting Wyckoff sites
janbridley Dec 10, 2025
fbf40fb
Fix doctest-requires
janbridley Dec 10, 2025
21a5c3f
Add warning for setting structure
janbridley Dec 10, 2025
2287526
Fix type annotation
janbridley Dec 10, 2025
a624d3a
Include only necessary data
janbridley Dec 10, 2025
d3c189c
Merge branch 'doc/grammar' into feat/set_basis
janbridley Dec 10, 2025
84c08e3
sphinx-inline-tabs
janbridley Dec 12, 2025
6ca3a23
Description of Wyckoff postions
janbridley Dec 12, 2025
02c7740
Move up table and fix formatting
janbridley Dec 12, 2025
0860b82
Merge branch 'main' into feat/set_basis
janbridley Dec 12, 2025
ff427e7
Restore heading
janbridley Dec 12, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Move up table and fix formatting
  • Loading branch information
janbridley committed Dec 12, 2025
commit 02c774096c89fecb69fba9025703d80e3b79120b
299 changes: 170 additions & 129 deletions doc/source/example_new_structures.rst
Original file line number Diff line number Diff line change
Expand Up @@ -45,14 +45,150 @@ Formatted more nicely, we see the following:
- 0.20224
- 0.45224

The key notes are the symmetry multiplicity (8 for Mn1 and 12 for Mn2), which indicates
how many atomic positions arise from each Wyckoff site, and the Wyckoff label. While
this tutorial will not delve too deeply into crystallography, it is sufficient to note
that this label provides a mapping to the International Tables for each space group.
For β-Manganese, we will use this mapping to identify one coordinate equation that
describes each site. For Mn1, this yields ``[x, x, x]`` and for Mn2, we select
``[1 / 8, y, y + 1 / 4]`` to match the CIF data from above.
First, we note the symmetry multiplicity (8 for :math:`Mn_1` and 12 for
:math:`Mn_2`), which indicates how many atomic positions arise from each Wyckoff
site, and the Wyckoff label. Second, we can identify that each Wyckoff position is
labeled by a letter that differentiates it from other sites. While this tutorial will
not delve too deeply into crystallography, it is sufficient to note that this Wyckoff
letter provides a mapping to the `International Tables`_ for each space group. For
β-Manganese, we will use this mapping to identify one coordinate equation that describes
each site. The correct table for β-Mn is included in the tabs below, with the coordinate
equations that match the CIF data (:math:`(x, x, x)` and :math:`(1/8, y, y + 1/4)`)
highlighted in bold on their corresponding tabs.

.. _`International Tables`: https://web.archive.org/web/20170430110556/http://www.cryst.ehu.es/cgi-bin/cryst/programs/nph-wp-list?gnum=213

.. tab:: 4a

.. list-table::
:widths: 30 70
:header-rows: 0

* - **Multiplicity**
- 4
* - **Site Symmetry**
- ``.32``
* - **Coordinates**
- .. list-table::
:header-rows: 0
:widths: 50 50

* - :math:`(3/8, 3/8, 3/8)`
- :math:`(1/8, 5/8, 7/8)`
* - :math:`(5/8, 7/8, 1/8)`
- :math:`(7/8, 1/8, 5/8)`

.. tab:: 4b

.. list-table::
:widths: 30 70
:header-rows: 0

* - **Multiplicity**
- 4
* - **Site Symmetry**
- ``.32``
* - **Coordinates**
- .. list-table::
:header-rows: 0
:widths: 50 50

* - :math:`(7/8, 7/8, 7/8)`
- :math:`(5/8, 1/8, 3/8)`
* - :math:`(1/8, 3/8, 5/8)`
- :math:`(3/8, 5/8, 1/8)`

.. tab:: 8c

.. list-table::
:widths: 30 70
:header-rows: 0

* - **Multiplicity**
- 8
* - **Site Symmetry**
- ``.3.``
* - **Coordinates**
- .. list-table::
:header-rows: 0
:widths: 50 50

* - :math:`\mathbf{(x, x, x)}`
- :math:`(-x+1/2, -x, x+1/2)`
* - :math:`(-x, x+1/2, -x+1/2)`
- :math:`(x+1/2, -x+1/2, -x)`
* - :math:`(x+3/4, x+1/4, -x+1/4)`
- :math:`(-x+3/4, -x+3/4, -x+3/4)`
* - :math:`(x+1/4, -x+1/4, x+3/4)`
- :math:`(-x+1/4, x+3/4, x+1/4)`

.. tab:: 12d

.. list-table::
:widths: 30 70
:header-rows: 0

* - **Multiplicity**
- 12
* - **Site Symmetry**
- ``..2``
* - **Coordinates**
- .. list-table::
:header-rows: 0
:widths: 50 50

* - :math:`\mathbf{(1/8, y, y+1/4)}`
- :math:`(3/8, -y, y+3/4)`
* - :math:`(7/8, y+1/2, -y+1/4)`
- :math:`(5/8, -y+1/2, -y+3/4)`
* - :math:`(y+1/4, 1/8, y)`
- :math:`(y+3/4, 3/8, -y)`
* - :math:`(-y+1/4, 7/8, y+1/2)`
- :math:`(-y+3/4, 5/8, -y+1/2)`
* - :math:`(y, y+1/4, 1/8)`
- :math:`(-y, y+3/4, 3/8)`
* - :math:`(y+1/2, -y+1/4, 7/8)`
- :math:`(-y+1/2, -y+3/4, 5/8)`

.. tab:: 24e

.. list-table::
:widths: 30 70
:header-rows: 0

* - **Multiplicity**
- 24
* - **Site Symmetry**
- ``1``
* - **Coordinates**
- .. list-table::
:header-rows: 0
:widths: 50 50

* - :math:`(x, y, z)`
- :math:`(-x+1/2, -y, z+1/2)`
* - :math:`(-x, y+1/2, -z+1/2)`
- :math:`(x+1/2, -y+1/2, -z)`
* - :math:`(z, x, y)`
- :math:`(z+1/2, -x+1/2, -y)`
* - :math:`(-z+1/2, -x, y+1/2)`
- :math:`(-z, x+1/2, -y+1/2)`
* - :math:`(y, z, x)`
- :math:`(-y, z+1/2, -x+1/2)`
* - :math:`(y+1/2, -z+1/2, -x)`
- :math:`(-y+1/2, -z, x+1/2)`
* - :math:`(y+3/4, x+1/4, -z+1/4)`
- :math:`(-y+3/4, -x+3/4, -z+3/4)`
* - :math:`(y+1/4, -x+1/4, z+3/4)`
- :math:`(-y+1/4, x+3/4, z+1/4)`
* - :math:`(x+3/4, z+1/4, -y+1/4)`
- :math:`(-x+1/4, z+3/4, y+1/4)`
* - :math:`(-x+3/4, -z+3/4, -y+3/4)`
- :math:`(x+1/4, -z+1/4, y+3/4)`
* - :math:`(z+3/4, y+1/4, -x+1/4)`
- :math:`(z+1/4, -y+1/4, x+3/4)`
* - :math:`(-z+1/4, y+3/4, x+1/4)`
- :math:`(-z+3/4, -y+3/4, -x+3/4)`

.. testsetup::

Expand Down Expand Up @@ -83,8 +219,8 @@ And of course, the Wyckoff position data reflects the data tabulated above:
>>> np.testing.assert_allclose(mn2[2], y + 1 / 4)
>>> np.testing.assert_allclose(mn2[0], 1 / 8)

Introducing β-Manganese
^^^^^^^^^^^^^^^^^^^^^^^
Exploring β-Manganese
^^^^^^^^^^^^^^^^^^^^^

β-Manganese is a `tetrahedrally close-packed`_ (TCP) structure, a class of complex
phases whose geometry minimizes the distance between atoms in a manner that prevents the
Expand Down Expand Up @@ -200,127 +336,10 @@ the same in the atomic and ideal crystals:


A more general choice of the basis will often result in different point symmetry.
Referring to the `symmetry tables`_ for space group 213 shows the ``a`` and ``b``
Referring to the `International Tables`_ for space group 213 shows the ``a`` and ``b``
Wyckoff positions, which have higher symmetry and a lower multiplicity. Selecting any
value from the "coordinates" table for the 4a position yields the expected 4-particle
unit cell with a site symmetry of ``'.32'``. For convenience, we include the table for
space group #213 here. Each tab is titled by its multiplicity and Wyckoff letter, with
the coordinate used in these examples highlighted in bold.

.. tab:: 4a

.. list-table::
:widths: 30 70
:header-rows: 0

* - **Multiplicity**
- 4
* - **Site Symmetry**
- ``.32``
* - **Coordinates**
- | **(3/8, 3/8, 3/8)**
| (1/8, 5/8, 7/8)
| (5/8, 7/8, 1/8)
| (7/8, 1/8, 5/8)

.. tab:: 4b

.. list-table::
:widths: 30 70
:header-rows: 0

* - **Multiplicity**
- 4
* - **Site Symmetry**
- ``.32``
* - **Coordinates**
- | **(7/8, 7/8, 7/8)**
| (5/8, 1/8, 3/8)
| (1/8, 3/8, 5/8)
| (3/8, 5/8, 1/8)

.. tab:: 8c

.. list-table::
:widths: 30 70
:header-rows: 0

* - **Multiplicity**
- 8
* - **Site Symmetry**
- ``.3.``
* - **Coordinates**
- | **(x, x, x)**
| (-x+1/2, -x, x+1/2)
| (-x, x+1/2, -x+1/2)
| (x+1/2, -x+1/2, -x)
| (x+3/4, x+1/4, -x+1/4)
| (-x+3/4, -x+3/4, -x+3/4)
| (x+1/4, -x+1/4, x+3/4)
| (-x+1/4, x+3/4, x+1/4)

.. tab:: 12d

.. list-table::
:widths: 30 70
:header-rows: 0

* - **Multiplicity**
- 12
* - **Site Symmetry**
- ``..2``
* - **Coordinates**
- | **(1/8, y, y+1/4)**
| (3/8, -y, y+3/4)
| (7/8, y+1/2, -y+1/4)
| (5/8, -y+1/2, -y+3/4)
| (y+1/4, 1/8, y)
| (y+3/4, 3/8, -y)
| (-y+1/4, 7/8, y+1/2)
| (-y+3/4, 5/8, -y+1/2)
| (y, y+1/4, 1/8)
| (-y, y+3/4, 3/8)
| (y+1/2, -y+1/4, 7/8)
| (-y+1/2, -y+3/4, 5/8)

.. tab:: 16e

.. list-table::
:widths: 30 70
:header-rows: 0

* - **Multiplicity**
- 24
* - **Site Symmetry**
- ``1``
* - **Coordinates**
- | (x, y, z)
| (-x+1/2, -y, z+1/2)
| (-x, y+1/2, -z+1/2)
| (x+1/2, -y+1/2, -z)
| (z, x, y)
| (z+1/2, -x+1/2, -y)
| (-z+1/2, -x, y+1/2)
| (-z, x+1/2, -y+1/2)
| (y, z, x)
| (-y, z+1/2, -x+1/2)
| (y+1/2, -z+1/2, -x)
| (-y+1/2, -z, x+1/2)
| (y+3/4, x+1/4, -z+1/4)
| (-y+3/4, -x+3/4, -z+3/4)
| (y+1/4, -x+1/4, z+3/4)
| (-y+1/4, x+3/4, z+1/4)
| (x+3/4, z+1/4, -y+1/4)
| (-x+1/4, z+3/4, y+1/4)
| (-x+3/4, -z+3/4, -y+3/4)
| (x+1/4, -z+1/4, y+3/4)
| (z+3/4, y+1/4, -x+1/4)
| (z+1/4, -y+1/4, x+3/4)
| (-z+1/4, y+3/4, x+1/4)
| (-z+3/4, -y+3/4, -x+3/4)


.. _`symmetry tables`: https://web.archive.org/web/20170430110556/http://www.cryst.ehu.es/cgi-bin/cryst/programs/nph-wp-list?gnum=213
unit cell with a site symmetry of ``'.32'``.


.. doctest-requires:: spglib
Expand Down Expand Up @@ -368,7 +387,7 @@ one or more degrees of freedom. In β-Manganese, the 8c and 12d Wyckoff sites ea
have one degree of freedom -- the ``x`` and ``y`` variables assigned above. If we set
these degrees of freedom such that Wyckoff positions are no longer independent, we also
alter the space group of the structure. In this case, we solve the system of equations
that arises from setting the coordinates ``[x, x, x] = [1 / 8, y, y + 1 / 4]`` and
that arises from setting the coordinates :math:`[x, x, x] = [1 / 8, y, y + 1 / 4]` and
assign that value to both ``x`` and ``y``. The resulting points end up reconstructing
the 16d Wyckoff position in the space group #227!

Expand All @@ -387,6 +406,28 @@ the 16d Wyckoff position in the space group #227!
>>> get_particle_point_groups(box, not_beta_mn_uc)
(['d'], ['.-3m'])

.. tab:: #227 16d

.. list-table::
:widths: 30 70
:header-rows: 0

* - **Space Group**
- #227
* - **Multiplicity**
- 16
* - **Site Symmetry**
- ``.-3m``
* - **Coordinates**
- .. list-table::
:header-rows: 0
:widths: 50 50

* - :math:`(5/8, 5/8, 5/8)`
- :math:`(3/8, 7/8, 1/8)`
* - :math:`(7/8, 1/8, 3/8)`
- :math:`(1/8, 3/8, 7/8)`

Takeaways
^^^^^^^^^

Expand Down
Loading