Skip to content

BUG: getFZQuat returns one FZ quaternion for every equivalent orientation - #64

Closed
imikejackson wants to merge 3 commits into
BlueQuartzSoftware:developfrom
imikejackson:topic/fz_boundary_unique
Closed

imikejackson wants to merge 3 commits into
BlueQuartzSoftware:developfrom
imikejackson:topic/fz_boundary_unique

Conversation

@imikejackson

@imikejackson imikejackson commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

getFZQuat (through LaueOps::ConvertToFZ) now returns the same fundamental-zone (FZ) quaternion for every symmetry-equivalent orientation, including orientations on the FZ boundary.

Fixes #63. Originally reported as BlueQuartzSoftware/DREAM3D#458.

Problem

ConvertToFZ returned the input unchanged if it was inside the FZ. Otherwise it returned the first symmetry image inside the FZ. On the FZ boundary, two equivalent orientations are both inside, so they gave different results. Example for cubic m-3m: the +45° and -45° rotations about [001] are equivalent, but their FZ quaternions were 0.765 apart.

Changes

LaueOps::ConvertToFZ

  • Fast path: if the input is still inside the FZ after its Rodrigues length is scaled by 1 + 1e-6, it is strictly inside and is returned unchanged. This is the same result as before for interior points.
  • Boundary points: check every symmetry image that is inside the FZ. Pick the one with the largest (w, x, y, z), compared in that order with a 1e-10 tolerance. The result does not depend on which equivalent orientation was the input.
  • 180° rotations: q and -q are the same rotation when w is 0. The sign is fixed (first non-zero of x, y, z is positive) before the comparison.
  • Removed the normalizedQuat.w() < 1.0E5 check. It was always true.

FZ checks that rejected every symmetry image (second commit)

An independent check against MTEX (below) found inputs in the 2/m, 4/m, -3, 6/m and 4/mmm Laue classes where no symmetry image passed the FZ check, so getFZQuat returned the all-infinity quaternion. develop fails on the same inputs. The checks come from EMsoftOO, which has the same defect.

  • InsideCyclicFZ: uses the quaternion form of the slab test, |n| sin(θ/2) <= tan(π/2n) cos(θ/2) + eps. The Rodrigues form multiplied a roundoff axis component (about 3e-17) by a length of about 1e16 for near-180° rotations. For infinite lengths it required the axis component to be exactly 0.0.
  • IsInsideFZ(QuatD): builds the cyclic test directly from the quaternion, because toRodrigues sets the length to infinity for w < 1e-8.
  • InsideDihedralFZ: the FourFold (422) comparisons and the sqrt(3) early-out get the same + eps as the other orders.
  • ConvertToFZ: skips the interior fast path for cyclic FZs. The cyclic FZ is an unbounded slab, so near-180° images about different basal axes are all inside it with radial margin, and the margin test cannot detect the tie. Cyclic groups have at most 6 operators.
  • EMsoftOO's tol = 1.0D+5 clamp, of which the removed w() < 1.0E5 check was a mistranslation, is not ported. It turns valid near-180° representatives into infinite ones and rejects them.

Tests

  • ConvertToFundamentalZoneTest::CubicBoundaryUnique: the ±45° about [001] case. It fails on develop (distance 0.7653668647) and passes with this change.
  • ConvertToFundamentalZoneTest::SymmetryOrbitUnique: for every Laue class, every symmetry operator s, and both q and -q, checks that getFZQuat(s * q) is finite, equals getFZQuat(q) up to sign, and is inside the FZ. The inputs are boundary orientations (45°, 60°, 90°, 120° and 180° about [001], [100], [110], [101] and [111], each also offset by ±1e-12, ±1e-9 and ±1e-6 rad), roundoff-bearing 180° rotations, symmetry images from other Laue classes, and 128 random orientations with a fixed seed.
  • The existing ConvertToFundamentalZoneTest data comparison is unchanged and passes.
  • Full suite on macOS arm64 (ci-macos-arm64 preset, HDF5 on, run serially): 430/430 passed.

Independent check against MTEX 6.1.0

32,398 orientations were reduced in all 12 Laue classes by this branch, by the develop algorithm, and by MTEX project2FundamentalRegion. The inputs were 2,000 random orientations plus boundary orientations and their full symmetry orbits.

  • Symmetry tables: in every class, the MTEX symmetry operators are the same set as EbsdLib's. The matching conventions are hexagonal X‖a, 6/m and -3 X‖a*, -3m1, and monoclinic unique axis b.
  • Interior orientations: this branch, develop and MTEX agree to 6e-16 in every class.
  • Boundary orientations:
    • Every result from this branch is finite and inside the FZ.
    • Every result is symmetry-equivalent to MTEX's result (to 4e-16).
    • Each rotation angle matches MTEX's to within 5e-11 in |w|; the gap is the 1e-10 tie tolerance.
    • Every symmetry orbit gives exactly one result.
  • Not unique on the boundary: develop gives up to 6 different results per orbit, and MTEX gives up to 4. MTEX, like EMsoftOO, keeps the first symmetry image it finds on a tie.
  • No result: develop returned the all-infinity quaternion for 1,446 inputs, and this branch for none.

Notes for reviewers

  • Results change only for orientations on or within about 1e-6 (relative) of the FZ boundary. Downstream code that compares FZ quaternions with exemplar files (for example simplnx ComputeFZQuaternions) may see different values for boundary points after updating EbsdLib.
  • Boundary inputs now check all symmetry operators instead of stopping at the first match. Interior inputs take the fast path and cost one extra IsInsideFZ call.

Comment thread Source/EbsdLib/LaueOps/LaueOps.cpp Resolved
Comment thread Source/EbsdLib/LaueOps/LaueOps.cpp Resolved
Comment thread Source/EbsdLib/LaueOps/LaueOps.cpp Resolved
Comment thread Source/EbsdLib/LaueOps/LaueOps.cpp Resolved
Comment thread Source/EbsdLib/LaueOps/LaueOps.cpp Resolved
imikejackson and others added 3 commits November 11, 2026 18:22
…tion

ConvertToFZ returned the input unchanged as soon as it was inside the
fundamental zone, and otherwise the first symmetry image inside it. On the
FZ boundary two symmetry-equivalent orientations are both inside, so
equivalent inputs gave different FZ quaternions (for example the +/-45
degree rotations about [001] in cubic m-3m).

- Inputs strictly inside the FZ (still inside after the Rodrigues length is
  scaled by 1 + 1e-6) are returned unchanged, as before.
- Other inputs check every symmetry image inside the FZ and pick the
  largest (w, x, y, z) with a 1e-10 tolerance. The sign of 180 degree
  rotations is fixed so that q and -q give the same result.
- Remove the always-true w() < 1.0E5 check.
- InsideCyclicFZ accepts points within 1e-10 of the boundary, so roundoff
  no longer makes every image of a boundary point fail the check.
- Add CubicBoundaryUnique and an all-Laue-class SymmetryOrbitUnique test.

Fixes BlueQuartzSoftware#63
…ions

getFZQuat returned the all-infinity quaternion for some inputs in the
cyclic (2/m, 4/m, -3, 6/m) and 4/mmm Laue classes, because no symmetry
image passed the FZ check. The checks come from EMsoftOO and have the
same problem there.

- InsideCyclicFZ uses the quaternion form |n| sin(t/2) <= tan(pi/2n)
  cos(t/2) + eps of the slab test. The Rodrigues form multiplied a
  roundoff axis component (about 3e-17) by a length of about 1e16, and for
  infinite lengths required the axis component to be exactly 0.
- IsInsideFZ(QuatD) builds the cyclic test from the quaternion, because
  toRodrigues sets the length to infinity for w < 1e-8.
- InsideDihedralFZ adds eps to the FourFold comparisons and the sqrt(3)
  early-out, like the other orders.
- ConvertToFZ skips the interior fast path for cyclic FZs. The slab is
  unbounded, so near-180 degree images about different basal axes are all
  inside it with radial margin.
- Extend SymmetryOrbitUnique with near-180, 90 and 120 degree inputs and
  require a finite result.
- Keep w non-negative after the half-turn sign fix.
- Select the representative by the maximum of each component in turn
  (w, x, y, z) within tolerance, so the result does not depend on the
  order of the symmetry operators. Use a fixed stack buffer.
- Restore the interior fast path for cyclic Laue classes.
- Merge the identical doM branches in InsideCyclicFZ and name the
  interior margin.
- Test that results have w >= 0 and the largest |w| in the orbit, and
  add inputs near 1e-10 from tie points.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@imikejackson

Copy link
Copy Markdown
Collaborator Author

Closed in favor of #86, which merges this branch (with its history) together with the other open EbsdLib fixes for the next release, so simplnx can build against one EbsdLib branch. The branch is kept.

🤖 Generated with Claude Code

@imikejackson
imikejackson deleted the topic/fz_boundary_unique branch November 13, 2026 16:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

BUG: getFZQuat returns different FZ quaternions for equivalent orientations on the fundamental zone boundary

2 participants