Primitive cells

primitive_cell constructs a reproducible primitive cell from the IT standard-setting conventional cell. It uses the fixed centring-dependent transformation convention adopted by spglib, so the result is tied to the standardized crystallographic basis rather than to a cell-shape reduction algorithm.

The transformation convention

With lattice vectors represented as columns, spglib defines

\[ B_p = B_s P_c, \]

where \(B_s\) is the standard-setting conventional basis and \(B_p\) is the primitive basis. The column-vector matrices are

\[\begin{split} P_A =\begin{pmatrix} 1&0&0\\ 0&\frac12&-\frac12\\ 0&\frac12&\frac12 \end{pmatrix},\quad P_C =\begin{pmatrix} \frac12&\frac12&0\\ -\frac12&\frac12&0\\ 0&0&1 \end{pmatrix}, \end{split}\]
\[\begin{split} P_R =\begin{pmatrix} \frac23&-\frac13&-\frac13\\ \frac13&\frac13&-\frac23\\ \frac13&\frac13&\frac13 \end{pmatrix},\quad P_I =\begin{pmatrix} -\frac12&\frac12&\frac12\\ \frac12&-\frac12&\frac12\\ \frac12&\frac12&-\frac12 \end{pmatrix}, \end{split}\]
\[\begin{split} P_F =\begin{pmatrix} 0&\frac12&\frac12\\ \frac12&0&\frac12\\ \frac12&\frac12&0 \end{pmatrix},\qquad P_P=I_3. \end{split}\]

httk stores cell vectors as rows. It therefore applies the row-form matrix \(T_c=P_c^T\):

\[ \mathop{\rm basis}_{\rm prim}=T_c\mathop{\rm basis}_{\rm conv},\qquad f_p=f_sT_c^{-1}, \]

with fractional coordinates normalized into \([0,1)\). The matrix has determinant \(1/n\), where \(n\) is the number of centring translations: 1 for P, 2 for A, C, and I, 3 for R, and 4 for F.

Relation to conventional_cell

The operation first calls conventional_cell(), including its optional recognition step. primitive_cell then applies the fixed table above to that exact conventional result. It does not reduce the primitive basis by Niggli or any other cell-shape algorithm. A primitive cell is consequently reproducible from the standard setting, while a Niggli cell is a separate canonical lattice reduction.

All matrix and coordinate arithmetic remains exact after recognition: rational fractional coordinates stay rational, and Cartesian basis operations retain httk’s exact surd arithmetic. Cell and coordinate precision metadata is widened by the corresponding exact matrix norms.

Site moments carry through as per-site data. The centring collapse maps several conventional sites onto one primitive site, so those translation images must agree: a ferromagnetic supercell folds down with its moments intact, but any collapse of sites with disagreeing moments needs the larger cell and raises ValueError. Cartesian and collinear moments pass through the basis recombination unchanged; CrystalAxisSiteMoments are refused because they are stated against the old lattice frame — see Site moments.

Example

>>> from httk.atomistic import ASUStructure, WyckoffSite, primitive_cell
>>> from httk.core import FracVector
>>> carbon = [{"name": "C", "chemical_symbols": ["C"], "concentration": [1.0]}]
>>> asu = ASUStructure(
...     [[5, 0, 0], [0, 5, 0], [0, 0, 5]], 229,
...     [WyckoffSite("a", FracVector(()), "C")], carbon,
... )
>>> result = primitive_cell(asu)
>>> result.multiplier
Fraction(1, 2)
>>> len(result.structure.sites)
1

To obtain a Niggli-reduced cell after this operation, use niggli_reduced() as a separate step; see Lattice reduction (Niggli).