Add support for active alarm windows in MPAS timekeeping

[amstokely]

This PR introduces user-defined active windows for recurring alarms in the MPAS timekeeping module. Previously, alarms could only be defined with an anchor time and a recurrence interval. Once the anchor was reached, the alarm would ring repeatedly until the end of the clock. There was no way to restrict alarms to a bounded time range.

Previous behavior

Alarms were defined only by anchor time and interval:

A ---------------- B ---------------------- E
^                 ^                        ^
Clock start    Alarm anchor              Clock stop

Once the anchor was reached, alarms rang every interval until the clock ended. There was no mechanism to disable alarms outside of a chosen window.

New behavior

With this PR, all alarms now have an active window. If the user does not explicitly provide a start or stop time, the window defaults to the clock start and stop times, so existing behavior is preserved. This allows the same logic to be applied consistently to both alarms with user-defined windows and alarms without them.

Timeline with user-defined window:

A                B          C            D                E
|----------------|----------|------------|----------------|
^                ^          ^            ^                ^
Clock start   Alarm anchor  Window     Window stop     Clock stop
                           start

Alarms do not ring before the window opens, ring normally inside it at the specified interval, and stop ringing after the window closes, even if the clock continues. Resets and direction changes interact correctly with these boundaries.

Internal structure

Several internal helpers were added to make the logic clearer and easier to maintain:

• mpas_is_alarm_active checks whether the current clock time is inside an alarm’s active window.
• mpas_prev_ring_in_window verifies whether the alarm’s previous ring time occurred strictly inside the window, using open-interval semantics (start, stop).
• mpas_time_in_interval performs the low-level interval membership check, supporting both closed [start, end] and open (start, end) intervals.

These helpers are not tested directly; instead, their correctness is validated indirectly through behavioral tests of alarms. This ensures that the implementation can be refactored without breaking tests, as long as the observable alarm behavior remains consistent.

Tests

A new test fixture (alarm_fixture_t) and suite (test_window_alarm) validate alarm behavior across 17 scenarios. These cover cases before and after the anchor, ringing at the window boundaries, ringing inside the window, leaving the window, delayed anchor times, resets, and clock direction changes.

mpas_reset_clock_alarm is invoked in several cases to confirm that the previous ring time is updated correctly. It is called at both window boundaries and inside the active window to exercise different internal bound checks that could fail in one case but not the other.

The tests focus strictly on behavior: they verify only whether alarms ring when expected, not how that behavior is implemented. This design allows the internal code to evolve without destabilizing the suite. At the same time, the tests serve as executable documentation of the alarm ringing contract, which was previously implicit. They will make future development in MPAS timekeeping more efficient, reliable, and safe.

[jim-p-w]

What is the use case?
Why would the window_stop time be before the clock_stop time? If the anchor occurs after the window_stop time the alarm will be missed.
Why would the window_start time be later than the clock_start time?

[mgduda]

What is the use case? Why would the window_stop time be before the clock_stop time? If the anchor occurs after the window_stop time the alarm will be missed. Why would the window_start time be later than the clock_start time?

@jim-p-w The original motivation for enabling alarms to ring only within a specified window was to allow us to create output streams that are written only during part of a model simulation (i.e., within a window of time). The output times for a stream are controlled by alarms, and so starting with a change to the fundamental alarm functionality made sense. Generally when running MPAS, the starting and stopping times for the simulation clock -- within which alarms are instantiated -- are the starting and stopping times for the simulation.

[amstokely]

What is the use case? Why would the window_stop time be before the clock_stop time? If the anchor occurs after the window_stop time the alarm will be missed. Why would the window_start time be later than the clock_start time?

@jim-p-w Here’s a snippet from a streams.atmosphere file that demonstrates how this feature is used:

<immutable_stream name="da_state"
                  type="output"
                  precision="single"
                  clobber_mode="truncate"
                  filename_template="mpasout.$Y-$M-$D_$h.$m.$s.nc"
                  packages="jedi_da"
                  io_type="pnetcdf,cdf5"
                  output_interval="0:40:00"
                  stop_time="0_03:20:00"/>

<stream name="da_state_low_freq"
        type="output"
        precision="single"
        clobber_mode="truncate"
        filename_template="mpasout_low_freq.$Y-$M-$D_$h.$m.$s.nc"
        packages="jedi_da"
        io_type="pnetcdf,cdf5"
        output_interval="1:00:00"
        start_time="0_04:20:00">
    <stream name="da_state"/>
</stream>

In this example, the da_state stream has an activeStartTime equal to the clock’s start time and an activeEndTime 3 hours and 20 minutes later, which is earlier than the clock’s end time. The da_state_low_freq stream begins 4 hours and 20 minutes after the start of the calculation and remains active until the clock’s end time.

The da_state stream writes output more frequently than da_state_low_freq. Although they are defined as separate streams, they write the same data and differ only in stream_name, filename_template, active window, and output frequency. This setup is useful in MPAS-JEDI, where users may want to vary the output frequency of the da_state stream during different phases of a model run.

[jim-p-w]

What is the use case? Why would the window_stop time be before the clock_stop time? If the anchor occurs after the window_stop time the alarm will be missed. Why would the window_start time be later than the clock_start time?

In this example, the da_state stream has an activeStartTime equal to the clock’s start time and an activeEndTime 3 hours and 20 minutes later, which is earlier than the clock’s end time. The da_state_low_freq stream begins 4 hours and 20 minutes after the start of the calculation and remains active until the clock’s end time.

The da_state stream writes output more frequently than da_state_low_freq. Although they are defined as separate streams, they write the same data and differ only in stream_name, filename_template, active window, and output frequency. This setup is useful in MPAS-JEDI, where users may want to vary the output frequency of the da_state stream during different phases of a model run.

So start_time in the yaml is actually activeStartTime and stop_time is actually activeStopTime?

And what is the anchor time?

[amstokely]

What is the use case? Why would the window_stop time be before the clock_stop time? If the anchor occurs after the window_stop time the alarm will be missed. Why would the window_start time be later than the clock_start time?

In this example, the da_state stream has an activeStartTime equal to the clock’s start time and an activeEndTime 3 hours and 20 minutes later, which is earlier than the clock’s end time. The da_state_low_freq stream begins 4 hours and 20 minutes after the start of the calculation and remains active until the clock’s end time.
The da_state stream writes output more frequently than da_state_low_freq. Although they are defined as separate streams, they write the same data and differ only in stream_name, filename_template, active window, and output frequency. This setup is useful in MPAS-JEDI, where users may want to vary the output frequency of the da_state stream during different phases of a model run.

So start_time in the yaml is actually activeStartTime and stop_time is actually activeStopTime?

And what is the anchor time?

@jim-p-w The anchor time is an internally defined variable that serves as the reference point for the alarm’s time field. You’re also correct about the start_time and stop_time attributes. I find those names concise and intuitive for users. Internally, though, I avoided them in the timekeeping APIs because it’s clearer to think of an alarm as entering or exiting an active window rather than starting or stopping. The active window terminology makes this distinction explicit, since the start and stop values define when an alarm is active rather than when it begins or ends execution.

[mgduda]

Since existing code compares the value of ierr returned by this subroutine with 0 to determine success, I'd suggest we set ierr to 0 rather than to ESMF_SUCCESS.

[mgduda]

Let's use just one space between intent(out), and optional.

[mgduda]

Does the alarm argument need to be a pointer here?

[mgduda]

Does alarm need to be a pointer?

[mgduda]

Let's leave this blank line in place.

[mgduda]

Here (and maybe elsewhere), can you check that we're using an ASCII single-quote rather than some other Unicode character?