Time-of-flight: use epoch reference time and guess the PulseStrideOffset

[nvaytet]

In this PR, we use epoch to create a reference time for computing pulse_index.
The method is

# Define a common reference time using epoch as a base, but making sure that it
# is aligned with the pulse_period and the frame_period.
diff_to_epoch = (event_time_zero.min() - epoch) % pulse_period
# Here we offset the reference by half a pulse period to avoid errors from
# fluctuations in the event_time_zeros in the data. They are triggered by the
# neutron source, and may not always be exactly separated by the pulse period.
# While fluctuations will exist, they will be small, and offsetting the times
# by half a pulse period is a simple enough fix.
reference = epoch + diff_to_epoch - (pulse_period // 2)
# Use in-place operations to avoid large allocations
pulse_index = event_time_zero - reference
pulse_index %= frame_period
pulse_index //= pulse_period

We also add a simple method to guess the PulseStrideOffset parameter, as using a global reference time now means that the pulse_index will depend on when we began to record the data (at the start of a frame period, or half way through it).

We choose a few random events, compute the time-of-flight for every possible value
of pulse_stride_offset, and return the value that yields the least number of NaNs
in the computed time-of-flight.

We leave the option to specify the PulseStrideOffset as a parameter, and the guess is only performed if it is not provided.

This is a workaround for #184 . It should be easy enough to swap it out later for a solution that reads the chopper logs.

[jokasimr]

In this PR, we use epoch to create a reference time for computing pulse_index

This might be a silly question, but what is pulse_index and why do we need it?

Edit: aha got it, it's the index of the pulse in the pulse skipping frame

Isn't epoch just 0?

[nvaytet]

Isn't epoch just 0?

Are you asking why do I need to subtract epoch from the minimum event_time_zero?
I can't do da.bins.coords['event_time_zero'].min() % pulse_period because the operation isn't handled event if pulse_period is an integer.
Subtracting epoch converts the time stamp to a duration, to which I can then apply the modulo.

[jokasimr]

Would we get the same result by doing

pulse_index = event_time_zero - min_event_time_zero + pulse_period/2
pulse_index %= frame_period
pulse_index //= pulse_period

or am I missing something?

If possible I think it's simpler to not mix in the concept of an epoch.
This is more clearly saying: we assume min_event_time_zero coincides with the start of a pulse skipping frame.

[nvaytet]

We can't simply use the minimum time because of #180 (comment)

I added a comment to clarify this.

[jokasimr]

We can't simply use the minimum time because of #180 (comment)

That makes sense 👍

So essentially the solution is: Instead of assuming the minimum event time zero coincides with a pulse skipping frame start, we assume that the first pulse time after epoch coincides with a pulse skipping frame start?

[nvaytet]

Not really. It's more that we find a global reference time for everyone, which will give us consistent pulse index 0 or 1 depending on the pulse (even if there are skipped pulses with no data).

Whether or not it corresponds to the start of a frame or in the middle of a frame is resolved by the pulse_stride_offset guesswork.

[jokasimr]

Aha I see. Pulse index 0 doesn't necessarily meant it's the first pulse of a pulse skipping frame 👍

[jokasimr]

Looks good to me!