9. Parameterisation and constraints¶
9.1. From tree to vector¶
The pydantic model tree compiles to an ordered table of parameters with
stable dot-separated paths (phases.0.cell.a, instrument.profile.w) and
an affine constraint block
Source: rietx.params.vector
with sparse \(C\) rebuilt at every stage boundary and constant during a least-squares run, so a constant matmul stays exact under the autodiff backends. Cell ties (\(b \leftarrow a\), fixed angles) are the identity-row special case, and Wyckoff site constraints supply general rows. Three kinds of entry are structurally locked and can never be freed by a glob: the first emission line’s weight (degenerate with the phase scales), symmetry-fixed cell angles, and fully fixed special positions.
The cell ties follow the space-group setting rather than the crystal system. Three settings disagree with the system alone, and in each the number of free cell parameters is the same either way. The count is right while the subspace is wrong, so the test is which angle is held and which length follows which:
a monoclinic symbol may be unique-axis \(a\), \(b\) or \(c\), and the one angle its symmetry leaves free is \(\alpha\), \(\beta\) or \(\gamma\) respectively;
an R lattice on rhombohedral axes needs \(a = b = c\) with \(\alpha = \beta = \gamma\) free, in place of the hexagonal-axes \(b \leftarrow a\) with \(c\) free and all three angles fixed. The file decides which description arrives:
read_small_structureresolves a bareR -3 cover a rhombohedral cell to the:Rsetting;the
:1/:2extensions are origin choices and leave the metric untouched.
A symmetry-fixed angle is checked against the value its symmetry demands, and the cell is refused if it disagrees by more than 0.001°. The angle is held at its stored value, so an orthorhombic symbol over a cell carrying \(\beta = 93.2°\) would otherwise compute every \(d\)-spacing from that angle in silence.
Source: rietx.crystallography.symmetry.cell_constraints
Strictly positive quantities (widths, scales) refine through the softplus transform,
Source: rietx.params.transforms
smooth, monotonic and \(p > 0\) for all finite \(u\), so the optimiser works in an unconstrained variable instead of pressing a hard zero bound. Bounded quantities use a logit.
9.2. Site-symmetry degrees of freedom¶
Coordinates and anisotropic ADPs refine as site-symmetry DOFs. The constraint bases are derived from the space-group operators by exact rational linear algebra, with no floating-point tolerance and no per-site lookup table. (Wyckoff naming is a separate job, delegated to spglib [Togo et al., 2024].)
A displacement δ of a site fixed by operations \(\{(R, \mathbf{t})\}\) must satisfy \(R\,\delta = \delta\), so the coordinate basis spans
Source: rietx.crystallography.wyckoff.coordinate_basis
([Hahn, 2002] sect. 8.3.2). The \(U^{ij}\) tensor transforms as \(U \to R\,U R^\top\) under a rotation acting on fractional coordinates, so the allowed ADP pattern spans the invariant subspace of that action on symmetric 3×3 matrices [Peterse and Palm, 1966] (cross-checked against the cctbx tables [Grosse-Kunstleve and Adams, 2002]):
Source: rietx.crystallography.wyckoff.adp_basis
Both bases come back as smallest-integer row vectors in a deterministic RREF-derived form. An \(x,x,z\) site gives \([[1,1,0],[0,0,1]]\), and a hexagonal three-fold site gives \(U_{11} = U_{22} = 2U_{12}\) as \([2,2,0,1,0,0]\). Coordinate DOFs are affine ties through (9.1). ADP DOFs are absolute (\(U = \sum_k \theta_k B_k\)), which enforces the site symmetry exactly, and a tensor outside the allowed subspace raises rather than being symmetrised. The same construction one rank up yields the Stephens \(S_{HKL}\) bases of Microstructure.
The stabiliser also fixes how many atoms the site puts in the cell. The site multiplicity is the orbit length, and by orbit-stabiliser it is
Source: rietx.crystallography.symmetry.site_orbit
so \(m\) always divides the group order [Hahn, 2002], and the orbit is generated one image per left coset of \(G_{\mathbf{x}}\). Counting distinct images by pairwise comparison instead gives the same answer wherever the comparison is exact, and no answer at all where it is inexact: proximity within a tolerance is not transitive, so the partition follows the order the operators arrive in and its size need not divide \(|G|\). A coordinate within the tolerance of a special position is therefore projected onto it before the images are generated, by the Reynolds average over \(G_{\mathbf{x}}\), which moves the coordinate only along the directions (9.3) forbids. Multiplicities feed \(ZMV\) and hence every quantitative phase fraction of Estimation, and none of that reaches \(R_{wp}\).
9.3. Magnetic moment constraints¶
A site’s ordered magnetic moment is symmetry-constrained the way a coordinate is, by the operators that fix the site. Two things differ. A moment is an axial vector rather than a polar one, and a magnetic operation carries a time-reversal sign \(\varepsilon = \pm 1\) that an ordinary space-group operation does not. An operation \((R, \mathbf{t}, \varepsilon)\) acts on a moment as
Source: rietx.crystallography.magnetic.operators.MagneticOperator.moment_matrix
with \(R\) untransposed [Halpern and Johnson, 1939] and \(\varepsilon\) the magnetic group’s own sign [Perez-Mato et al., 2015]. The reciprocal-space \(R^\top\) convention this manual uses elsewhere for an hkl does not apply to a real-space axial vector. The allowed-moment subspace for a site’s stabiliser is then \(\bigcap \ker(\varepsilon\det(R)R - I)\), the same construction as (9.3) with this action in place of \(R\).
Moment components are stored on the crystal axes, in a right-handed basis of unit vectors parallel to the cell edges rather than the edges themselves. Outside a cubic cell the magnitude is therefore something other than \(\sqrt{\sum_i m_i^2}\):
Source: rietx.crystallography.magnetic.operators.moment_magnitude
with \(G\) the unit-vector metric, ones on the diagonal and the cell’s cosines
off it. A hexagonal \((1, 1, 0)\) moment therefore has magnitude 1 \(\mu_B\), and
not \(\sqrt{2}\). A moment in this crystal-axis form also converts to the
orthonormal Cartesian frame rietx.crystallography.adp.cartesian_basis already
builds for the ADP tensor of (9.4). Normalise each direct-lattice basis
vector to unit length before applying it:
Source: rietx.crystallography.magnetic.operators.moment_to_cartesian
the same Cholesky-derived Cartesian frame the ADP construction uses. The
crystal-axis and fractional components differ by \(D = \mathrm{diag}(a, b, c)\),
so on crystal-axis components an operation acts by \(D R D^{-1}\), which is \(R\)
itself exactly when every pair of axes \(R\) mixes has equal lengths: a 4-fold’s
\(a\) and \(b\), a hexagonal 3-fold’s \(a\) and \(b\). Every tabulated setting meets
that, so the constraint algebra never has to see a cell. A sheared cell of the
same lattice does not: MnF₂’s group restated in \((a, b, a+c)\) has a 4-fold
that mixes \(a+c\) with \(a\), whose lengths no cell of that setting can make
equal. A magnetic group carries no cell, so in such a setting its crystal-axis
moment methods refuse by name rather than answer with \(R\)
(MagneticGroup.axis_mixing names the operation).
9.4. Moment degrees of freedom¶
A magnetic moment takes the same construction one tensor rank down, and then departs from it in the one way that matters. The allowed subspace at a site is the simultaneous fixed points of the axial action over the site’s magnetic stabiliser: the rotation untransposed, times its determinant, times the operation’s time-reversal sign:
Source: rietx.crystallography.magnetic.operators
The same exact rational nullspace as (9.3) and (9.4), and the same deterministic smallest-integer basis. The transposed set is a group too, so a wrong action leaves the dimension of this subspace unchanged in every crystal system; the only test that can fail is whether a known moment lies in the derived span. Measured over all 1651 magnetic space groups against a grid of sites, \(R\) and \(R^{\mathsf T}\) give different spans for 543 (group, site) pairs and every one of them is trigonal or hexagonal, so a test set built from rutile, perovskite and spinel proves nothing here.
Where the moment departs from the ADP is the parameterisation. A powder average determines \(|m|\) and, for a uniaxial structure, the angle to the unique axis, and nothing else [Shirane, 1959]. Those undeterminable directions have to be columns of the least-squares problem for the package’s flat-direction rule to name them, and neither the components nor their coefficients on (9.9) is one: a rotation of the moment is a combination of all of them, so every coefficient would come back unmeasured and the magnitude, which the data does determine, would come back with no esd. So the DOFs are a modulus and angles inside the allowed subspace,
Source: rietx.crystallography.magnetic.moments
with \(\{\mathbf{e}_k\}\) a Gram-Schmidt frame of (9.9) in the magCIF unit-vector metric \(G\) (ones on the diagonal, cosines of the cell angles off it). That metric is what makes \(\mu\) equal \(|m|\) as the CIF defines it: on hexagonal axes the moment \((1, 1, 0)\) is \(1\ \mu_B\), not \(\sqrt 2\). One dimension gives \((\mu)\) with \(\mu\) signed, two give \((\mu, \phi)\) and three \((\mu, \theta, \phi)\); the frame is frozen per stage from the declared cell, like every other discrete object here.
Nothing bounds these DOFs while a stage solves, so a fit can end at \(\phi + 2\pi k\), at \((-\mu, \phi + \pi)\) or at \((\mu, -\theta, \phi + \pi)\), which are all the same moment. Every commit therefore moves a block into one chart: \(\mu \ge 0\) for two or three DOFs, \(\theta \in [0, \pi]\) and \(\phi \in (-\pi, \pi]\), the chart the stage’s seed is already in. Each move is an identity on the moment and negates whole columns at most, so it changes no esd, and the solver’s correlations are re-signed with it. An entry a tie reads or the caller holds is left where it is. The chart still has a cut at \(\phi = \pm\pi\), so the series fences compare an angle across patterns modulo a turn.
9.5. Soft restraints¶
A bond-length, angle or value restraint contributes one row to the residual of (1.5) [Waser, 1963; Watkin, 1994]:
Source: rietx.model.restraints.restraint_residual
appended after the data rows, so restraints land in the covariance \(J^\top J\) and are excluded from \(R_{wp}\), Durbin-Watson and the Bérar-Lelann inflation. A soft observation carries weight in the solution and none in the agreement statistics. The geometry is nonlinear in θ, where the background-penalty and Pawley rows are linear, because a bond length \(d = \sqrt{\Delta x^\top G\, \Delta x}\) depends on coordinates and cell. The rows and their Jacobian are therefore recomputed per θ. The neighbour atom is taken at a symmetry image \(R\mathbf{x} + \mathbf{t} + \mathbf{n}\) with \((R, \mathbf{t}, \mathbf{n})\) frozen per stage, the exact analogue of the frozen reflection list, so positions move smoothly inside a stage while the discrete image choice stays fixed.
9.6. Weighting the restraints¶
A stage scales every restraint at once. The minimised quantity is then eq (7) of the IUCr guidelines [McCusker et al., 1999],
Source: rietx.model.forward.CompiledModel.restraint_residual
with \(S_y\) the data rows of (8.1) and \(S_G\) the restraint rows of (9.11) squared. The guidelines set \(c_w\) high while the structural model is incomplete or approximate, and reduce it as the model improves. That makes it a property of the stage rather than of the restraint. It is frozen onto the compiled model at stage compile, so a schedule changes it between stages and never inside one.
Two seams decide where the scalar may act. \(\sqrt{c_w}\) multiplies the assembled rows, so every backend sees it through one row builder. It never reaches the compiled restraints or their partials, whose second consumer computes the derived-quantity esds of (8.6) at \(\sigma = w = 1\); a scale leaking that far would multiply every reported bond esd by \(\sqrt{c_w}\). And \(c_w = 0\) silences the rows without deleting them, so the row count the agreement statistics exclude cannot move part-way through a plan.