Skip to content

UB_matrix: import a UB matrix and inject it into a crystal component - #2896

Draft
willend wants to merge 20 commits into
mccode-dev:mainfrom
willend:ub-matrix-injector
Draft

willend wants to merge 20 commits into
mccode-dev:mainfrom
willend:ub-matrix-injector

Conversation

@willend

@willend willend commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Adds a UB_matrix component (McStas and McXtrace) that reads a UB matrix, writes the crystal orientation into a named crystal component before that component initialises, and exports the UB. Design and convention survey: https://claude.ai/artifact/LpProu685t4A7DiB5jxU5s (v2 tab).

Code generator (cogen.c.in, mccode-r.h.in)

COMP_GETPAR3(type, "name", par) can write another instance's SETTING parameters, but needs the target type at compile time and offers no run-time check. The generator now also emits:

  • #define MCCODE_COMP_TYPE_<type> per component type present, to guard COMP_GETPAR3 on that type;
  • char* _getcomp_type(char* name) and int _getcomp_rotation(char* name, Rotation r);
  • #define MCCODE_HAS_GETCOMP_TYPE, so components can detect the feature.

No change to generated simulation behaviour.

UB_matrix.comp

  • Input, exactly one of: a file (format="mccode", or "isaw" for Mantid SaveIsawUB .mat), 9 numbers (UBin), or lattice_a..lattice_cc with two reflections hkl1/dir1, hkl2/dir2.
  • Injection by target type: Single_crystal, Single_crystal_process, Single_magnetic_crystal, Single_crystal_inelastic, FluoCrystal, Dispersion_relation (contrib) get ax..cz; NCrystal_sample, NCrystal_process, Union_NCrystal_material get dir1/dir2 appended to cfg.
  • Output: UB.txt (cell, U, B, UB, R, R·UB), and the UB vector parameter's NeXus runtime_value.
  • Convention: Q = 2π R UB (h,k,l) in the target frame (z along beam, y up), no 2π in UB, B in the Busing–Levy frame, Q = kf − ki.
  • Fails loudly if: the target is placed before UB_matrix, already has an orientation, or is unknown/unsupported; det(UB) < 0 (likely opposite Q sign convention); the cell disagrees with given lattice parameters; reflection angles disagree beyond tol.

Tests

Test_UB_matrix in both flavours' examples/Tests_samples compares each input route against a directly oriented reference (1e6 rays, seed 1234, macOS arm64, Apple clang):

Flavour Target Input Laue intensity
McStas Al Single_crystal reference ax..cz 1.27054e-09 ± 2.27e-11
McStas Al Single_crystal UBin / ISAW file / cell + reflections 1.27052e-09 / 1.27052e-09 / 1.27077e-09
McStas Al NCrystal_sample reference dir1/dir2 / UBin 5.69706e-09 / 5.69706e-09
McStas Dispersion_relation (4×5×6 Å) reference ax..cz / UBin 2.26331e-08 / 2.26331e-08
McXtrace Si Single_crystal reference / UBin / cell + reflections 3.55771e-12 / 3.55801e-12 / 3.55557e-12
McXtrace Si FluoCrystal reference / UBin 8.85222e-11 / 8.84381e-11
McStas La2CuO4 Single_magnetic_crystal (Test_UB_matrix_magnetic) reference / UBin 1.93992e-08 / 1.93992e-08
McStas Single_crystal_inelastic, example.sqw4 cell (Test_UB_matrix_inelastic) reference / UBin 3.86375e-08 / 3.86375e-08
McStas Al Single_crystal_process (Test_UB_matrix_Union) reference / UBin 1.02670e-09 / 1.02705e-09
McStas Al NCrystal_process (Test_UB_matrix_Union) reference / UBin 5.74784e-09 / 5.74784e-09
McStas Al Union_NCrystal_material (Test_UB_matrix_Union) reference / UBin 5.70065e-09 / 5.70065e-09

Single_magnetic_crystal and Single_crystal_inelastic share struct and function names with Single_crystal, so they can not be in one instrument and have their own tests. In Test_UB_matrix_Union the processes are placed AT (0,0,0) ABSOLUTE and goniometer is the Union volume.

2D Laue patterns correlate at 0.999997 with the reference; a 17° rotation drops it to 0.0007. UB.txt reads back with format="mccode". All eight error paths were triggered and stop with their message. The Dispersion_relation cases need python on PATH for the SHELL step that writes their dispersion file, as Test_Dispersion_relation_TAS does.

Not tested / open

  • Linux, Windows/MSVC, MPI, OpenACC/GPU (CI classic legs green on the first push)
  • NeXus output (the runtime_value capture, see comment)
  • Union targets, Single_magnetic_crystal, Single_crystal_inelastic, FluoCrystal (tests above)
  • A real Mantid-written .mat file (SetUB + SaveIsawUB, see comment)
  • mccode-antlr lacks the three generator additions; UB_matrix stops there with an #error, so the UB_matrix tests will fail in the mccode-antlr CI legs until it is updated

🤖 Generated with Claude Code

willend and others added 19 commits October 22, 2026 17:35
…TYPE_<type>

COMP_GETPAR3(type, "name", par) lets a component write another instance's
SETTING parameters, but needs the target's type at compile time and gives no
way to check it at run time. The code generator now emits:

- #define MCCODE_COMP_TYPE_<type> next to each component parameter typedef,
  so code can guard COMP_GETPAR3 on that type being present;
- char* _getcomp_type(char* name): the type of a named instance, or NULL;
- int _getcomp_rotation(char* name, Rotation r): its absolute rotation;
- #define MCCODE_HAS_GETCOMP_TYPE, so components can detect the feature.

No change to generated simulation behaviour. mccode-antlr needs the same
additions to support components that use them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New component for McStas and McXtrace. Placed before a crystal component, it
reads a UB matrix (a file in McCode or Mantid ISAW format, 9 numbers, or a
cell with two reflections), writes the orientation into the named target's
SETTING parameters before the target initialises, and exports the UB to a
text file and to NeXus as the run-time value of its 'UB' parameter.

Targets: Single_crystal, Single_crystal_process, Single_magnetic_crystal,
Single_crystal_inelastic, FluoCrystal (direct lattice vectors ax..cz), and
NCrystal_sample, NCrystal_process, Union_NCrystal_material (dir1/dir2
appended to cfg). The target type is looked up from the instance name.

Convention: Q = 2*pi*R*UB*(h,k,l) in the target frame (z along the beam,
y up), no 2*pi in UB, B in the Busing-Levy frame, R the goniometer rotation.

Test_UB_matrix (McStas: Al Single_crystal and NCrystal_sample; McXtrace:
Si Single_crystal) compares each input route with a directly oriented
reference; all reproduce the reference intensity and Laue pattern.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dispersion_relation takes direct real-space lattice vectors ax..cz in the
component frame, like Single_crystal but without recip_cell, so UB_matrix
injects them the same way.

Test_UB_matrix gains SAMPLE=6 (Dispersion_relation with ax..cz given) and
SAMPLE=7 (injected through UBin) for an orthorhombic 4x5x6 AA cell. The
anisotropic dispersion mode is written at compile time by
write_ub_dispersion.py (standard library only). Both give 2.26331e-08 at
1e6 rays; the 2D patterns agree to 1.5e-8 relative.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…al absorption fix

Main's mu/rho*density absorption (74cc36d) attenuates Si.lau more
strongly; CI on Linux/macOS/Windows gives 3.555-3.558e-12 for all three
samples, which still agree with each other.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- ub_inv: do not use I as an identifier (clashes with <complex.h>).
- Document vector lengths, the dir1/dir2 angle check and that the UB cell
  replaces the reflection-file cell.
- New tests: Test_UB_matrix_magnetic, Test_UB_matrix_inelastic,
  Test_UB_matrix_Union (McStas), FluoCrystal modes in McXtrace Test_UB_matrix.

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

willend commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

Checked the two open items (McStas, macOS arm64, mccode-dev env with this branch's mcstas code generator).

NeXus output. Test_UB_matrix with --format=NeXus, SAMPLE=2. Every UB_matrix instance writes its UB to /entry1/instrument/components/<NNNN_name>/parameters/UB @runtime_value with runtime_value_status = ok (@value keeps the zero default):

Instance UB runtime_value
UB_numbers, UB_file, UB_nc {-0.17459426696, 0.17459426696, 0, 0, 0, 0.246913580247, 0.17459426696, 0.17459426696, 0}
UB_cell same, within ~1e-17
UB_disp {-0.176776695296637, 0.14142135623731, 0, 0, 0, 0.166666666666667, 0.176776695296637, 0.14142135623731, 0}

Mantid-written ISAW file. MantidWorkbench Python:

ws = CreateSampleWorkspace()
SetUB(ws, a=4.05, b=4.05, c=4.05, alpha=90, beta=90, gamma=90, u=[1,1,0], v=[-1,1,0])
SaveIsawUB(ws, "UB_mantid.mat")
  • Mantid's UB equals the test's UBin; LoadIsawUB reads the file back unchanged.
  • The .mat file matches UB_Al.mat apart from precision (8 vs 12 digits).
  • With it in place of UB_Al.mat (1e6 rays, seed 1234): SAMPLE=3 gives Laue_I = 1.27052e-09 vs 1.27054e-09 for the SAMPLE=0 reference; 2D patterns correlate at 0.999997.

🤖 Generated with Claude Code

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.

1 participant