[WIP] XAS detection modes as base classes

[mretegan]

This PR introduces distinct base classes for XAS detection modes and updates the NXxas application definition to utilize them via a choice element as suggested here: nexusformat#1352 (comment)

[mretegan]

XAS Measurement Mode - Definition Analysis

This document analyzes the trade-offs between different approaches for defining XAS measurement modes in NeXus.

The Challenge

We need to define approximately 15 different XAS measurement modes (Transmission, TFY, PFY, HERFD, GIXRF, EELS, etc.). The goal is to balance:

1. Validation Stringency: Ensuring files contain the correct metadata (e.g., HERFD must have an analyzer crystal).
2. Maintenance Overhead: Avoiding an explosion of tiny, nearly identical definition files.
3. Semantic Clarity: Making it obvious to users and tools what a specific mode implies.

---

Approaches Analyzed

Approach 1: Single Monolithic Base Class (NXxas_mode)

Create one single NXxas_mode.nxdl.xml with a mode enumeration field.

• Pros:
  • Simplicity: Only one file to maintain.
  • Compact Application Definition: NXxas_new is clean (<group type="NXxas_mode">).
• Cons:
  • Loose Validation: The schema becomes a "bag of optional fields." It cannot enforce that "IF mode=HERFD THEN analyzer is required."
  • Ambiguity: A file could technically claim mode="transmission" but contain emission_lines, which is nonsensical but valid syntax.

Approach 2: Grouped by Physics (Selected Approach)

Group modes that share fundamental detection physics or geometry into a moderate number of base classes.

• NXtransmission: Distinct physics (photon-in, photon-out, I/I0).

• NXxray_fluorescence: Covers all secondary X-ray emission modes (TFY, PFY, HERFD, GIXRF, etc.).

• NXelectron_yield: Covers electron emission (TEY, PEY).

• NXxray_scattering: Covers scattering (XRS, DAFS).

• Pros:

  • Balanced Granularity: Reduces file count from ~15 to 7.
  • Logical Grouping: Related techniques live together.

• Cons:

  • Partial Validation Looseness: Like Approach 1, NXxray_fluorescence relies on application-level validation to ensure HERFD has an analyzer, rather than schema-level validation.

Approach 3: Granular Base Classes (One File Per Mode)

Create a separate base class for every distinct mode (e.g., NXtfy.nxdl.xml, NXherfd.nxdl.xml, NXgixrf.nxdl.xml).

• Pros:
  • Strict Validation: The XML schema strictly enforces requirements. NXherfd requires an analyzer group; NXtfy does not allow it.
  • Explicit Semantics: Identifying a group type (type="NXherfd") immediately tells a tool exactly what data to expect.
• Cons:
  • File Explosion: Requires managing 15+ separate files, many of which differ by only one optional field or just a docstring.
  • High Maintenance: Changing a common field (e.g., energy) requires updating 15 files.

---

[mretegan]

I keep going back and forth between these three options.

The last approach is the best one in terms of validation at a cost of having ~15 new base classes, which might be a bit too much considering the existing NeXus classes. If this could, however, be reused for other techniques, then it might make sense.

Grouping modes avoid part of the issue, but aside from the fact that now some validation will need to be done at the application, the groups are at least partially arbitrary. Another person will come up with a different way to do it.

The first approach delegates all validation at the application level. FAIRmat seems to use a simple string to indicate the type of experiment:
https://fairmat-nfdi.github.io/nexus_definitions/classes/applications/NXxps.html
https://fairmat-nfdi.github.io/nexus_definitions/classes/applications/NXoptical_spectroscopy.html

Even though this PR goes towards approach 2 or 3, I am more favorable to using 1.

[maurov]

@mretegan thanks for proposing this. Personally, I suggest going for the Approach 3. Having ~15 new classes in NeXus is not a huge addition. The proposed "modes" correspond to specific experimental techniques used every day at synchrotron radiation beamlines and on laboratory sources. Each mode has its own scope in terms of instrumentation and data analysis practices. It is worth to have a dedicated NeXus class for it. It will make life easier for everybody, because we can clearly state what is mandatory or recommended.

@newville what do you think?