Fairmat 2024: additions and clarifications in NXbeam

[lukaspie]

With this PR, the idea is:

• to clarify how the incident_energy field in NXbeam is to be used. Specfically, for polychromatic beams, a single field incident_energy is not sufficient, but rather one needs information about the incident_energy_spread. In addition, for a polychromatic beam, it is useful to incidate the incident_energy_weights, i.e., how much each each of energies contributes to the overall intensity.
• add some fields about pulsed beams and allow for descriptions of FROG (frequency-resolved optical gating) setups.
• add a field previous_device to indicate that this beam originate from a given beam device. This can be useful to describe the chain of devices and beams in the description of the beam paths (e.g., in an optical spectroscopy experiment).

[prjemian]

RST wraps computer code with double backticks:

* correct: ``energy``
* incorrect: `energy`

This is one of the most common typos in the documentation.

[lukaspie]

RST wraps computer code with double backticks:

* correct: ``energy``
* incorrect: `energy`

This is one of the most common typos in the documentation.

You are right, I changed it here for our new contribution where we make use of backticks.

[RubelMozumder]

I just randomly went through the file to be knowledged of the NAIC decision. I found some typos of bouble back tick while mentioning some fields.

[lukaspie]

@phyy-nx I added a bit of description to this PR as well. As far as I can remember, there was a bit of discussion on this PR in the NIAC meeting, but no formal decision was taken. This PR is ready in so far as further discussion (and subsequent decision) by NIAC can be initiated.

Note that when going through this PR again, I figured it could also be useful to extract the characteristics of a pulsed beam (which make up most of the changes in this PR) to its own sub-class. We would be open to doing so if that is what NIAC wants.

[phyy-nx]

Comments from Telco:

• Instead of duplicating documentation from incident_wavelength in incident_energy, supply a reference instead and note the same conventions. The same for incident_energy_weights and incident_energy_spread.
• Change units back to NX_ANY for incident_polarization and final_polarization. Rationale: neutrons are specified as a percentage of spin states, so we can't constrain it here.

Once done, based on Telco conversation, we can put this up for an online vote

[phyy-nx]

Hi all, as discussed in the Telco, now that the above points have been addressed (thanks @lukaspie), we can now move this PR to an online vote.  NIAC committee members please vote on this PR using emojis. 👍 for yes, 👎 for no, anything else (for example 👀) to abstain.  We need 14 votes to hit quorum so please review and vote!

As you review, please make a special note of the proposal to add these fields:

    <field name="previous_device">
        <doc>
             Indicates the beam device from which this beam originates.
             This defines, whether the beam in an "input" or "output" beam.
        </doc>
    </field>
    <field name="next_device">
        <doc>
             Gives the beam device which this beam will interact with next.
        </doc>
    </field>

As discussed on the call, these two fields allow connecting devices together. A figure was shown demonstrating the usage. We decided that the depends_on convention used for NXtransformations wasn't applicable here, due to the possibility of a set of branched connections.

Any questions we can answer here. Otherwise, cast a vote! Thanks!

[lukaspie]

As a follow up to the discussion in the Telco, here is the image that I was showing on how we are envisioning connecting devices and instances of NXbeam together.

[PeterC-DLS]

Can the previous/next thing be an NXsample? Maybe a better name is required than device

[phyy-nx]

Can the previous/next thing be an NXsample? Maybe a better name is required than device

My thought was that this is for components hooked together. The only usage of NXbeam at present is in NXmx and it is a member of an NXinstrument group. The implication is that beam hits the sample. Indeed, NXmx used to have the NXbeam group in the NXsample group, but we moved it to the NXinstrument group instead.

@sanbrock @mkuehbach @lukaspie is connecting a beam to a sample directly a use case you are interested in?

[phyy-nx]

Proposal from Telco:

• Remove previous/next device from this PR
• Remove NXbeam_element from this PR
• Add inputs and outputs to NXcomponent: lists of other components (NX_CHAR, rank of 0 or 1 (single or multiple), but it's optional)

Implies that NXcomponent would include anything that can affect the beam

A charge to the committee: go review and comment on #1525!! (consider implications of #1507)

Would want a flow/class diagram showing this inheritance. Also, don't want to lose the cool figure above of the multiple beam paths!

[lukaspie]

Proposal from Telco:

• Remove previous/next device from this PR
• Remove NXbeam_element from this PR

Done here, should be ready for trying another vote.

• Add inputs and outputs to NXcomponent: lists of other components (NX_CHAR, rank of 0 or 1 (single or multiple), but it's optional)

Implies that NXcomponent would include anything that can affect the beam

Implemented like this in #1525

A charge to the committee: go review and comment on #1525!! (consider implications of #1507)

Would want a flow/class diagram showing this inheritance. Also, don't want to lose the cool figure above of the multiple beam paths!

What's missing here is where to put this figure. Should the beam still have next/previous element? Or is this chaining just through the components?

[phyy-nx]

Hi all, as discussed in the Telco, we can now move this PR to an online vote. NIAC committee members please vote on this PR using emojis on this comment. 👍 for yes, 👎 for no, anything else (for example 👀) to abstain. We need 14 votes to hit quorum so please review and vote!

[paulmillar]

First, the definition seems to restrict the location to a "diagnostic point". What is a diagnostic point? NXbeam description doesn't mention "diagnostic point".

Second, the description suggests that this field is only available for diagnostic points; it is not available for the other uses of NXbeam. Is this the intention?

These two comments also apply to average_power, fluence and pulse_duration.

[lukaspie]

The docs of NXbeam are talking about "properties of the beam at a given location", which to be is the same as the diagnostic point. What other use of NXbeam than "the characteristics of the beam at a certain point" do you imagine?

[paulmillar]

You say that "properties of the beam at a given location" is the same as the diagnostic point, but this definition isn't provided in the proposed changes. The term "diagnostic point" is just used.

Also, I'm also not sure your statement is true. The definition of NXBeam also lists NXsample as a place where NXbeam is used and I don't think a sample is a diagnostic point.

The existing fields seem to use "this component". As a suggestion, would the following work?

Energy of a single pulse at this component.

[lukaspie]

I agree with you here, but this is not covered by the vote. We could just add it after the vote (since it only changes the docstring) or make a separate PR for this.

[paulmillar]

The value is NX_CHAR, but perhaps the semantics of the value could be better described.

Is the value some facility-local specification, some internal reference to a description elsewhere within the NeXus file, ...?

[lukaspie]

The idea here is to use it like the @depends_on field in NXtransformations (see also discussion about NXcomponent), i.e., an internal reference to a description elsewhere within the NeXus file.

We could make this clearer, but not sure if that is covered by the ongoing vote.