output at flexible time levels by guoqing-noaa · Pull Request #217 · ufs-community/MPAS-Model

guoqing-noaa · 2026-02-24T06:06:12Z

Introduce a new output_timelevels attribute for MPAS streams that enables variable output intervals.

With this capability, we may outoput every 15 minutes in the first hour, every hour in the first 3 days, every 3 hours for the next 4 days, and every 6 hours in the last 3 days.

We can also use this to only write out forecast files during a given period, such as: output_timelevels="6-12h"

Check the PR description below for details on how to specify the time levles.
Here is a quick example: output_timelevels="0-3-15m 4-72 75-168-3 174-240-6"

FYI, with this PR, we may write out mpasout files at "0 1 2 3 6 9 12", while history files at "4 5 7 8 11 13-99999" to avoid duplicate output of both mpasout and history files at the same time levels, which are almost the same.

This PR solves issue #214

Priority Reviewers

…ttribute Introduce a new `output_timelevels` attribute for MPAS streams that enables variable output intervals. With this capability, we may outoput every 15 minutes in the first hour, every hour in the first 3 days, every 3 hours for the next 4 days, and every 6 hours in the last 3 days. We can also use this to only write out forecast files during a given period, such as: output_timelevels="6-12h" Check the PR description for details on how to specify the time levles. Here is a quick example: output_timelevels="0-3-15m 4-72 75-168-3 174-240-6"

guoqing-noaa · 2026-02-24T06:09:02Z

`output_timelevels` Specification

The forecast output times are defined by a space-separated list of sections:

<section> [section] [section] ...

Each section expands into one or more forecast times.
The final output is the union of all expanded times.
Users need to make sure the times are in a ascending order.

1. Time String Format

A time_string represents a forecast time (offset from the initialization time).
It may be written in one of the following forms:

1.1 Integer Forms (Hours)

An integer with no suffix represents hours:

6     → 6 hours
12    → 12 hours
0     → 0 hours

1.2. Integer With Unit Descriptors

A duration may be written using unit suffixes:

h  → hours
m  → minutes
s  → seconds
D  → days

Examples:

1h30m   → 1 hour 30 minutes
45m     → 45 minutes
90s     → 90 seconds
6h15m   → 6 hours 15 minutes

2. Sequence Expansion (Range Expression)

A section may define a regularly spaced sequence using:
start-stop-step
This generates values beginning at start, incremented by step, and ending at stop (inclusive if exactly reached).
Examples:

0-1h-15m

expands to:

0 15m 30m 45m 1h

If -step is omitted, a default step of 1 hour is used:
7-12 means 7-12-1 and expands to 7 8 9 10 11 12

Note: Integer and unit-based forms may be freely mixed

3. The EBNF (Extended Backus-Naur Form) style grammar:

specification   = section , { SP , section } ;

section         = range
                | time_string ;

range           = time_string , "-" , time_string , [ "-" , time_string ] ;
                  (* start-stop[-step] *)

time_string     = integer
                | duration ;

duration        = duration_part , { duration_part } ;

duration_part   = integer , unit ;

unit            = "h" | "m" | "s" | "D" ;

integer         = digit , { digit } ;

digit           = "0" | "1" | "2" | "3" | "4"
                | "5" | "6" | "7" | "8" | "9" ;

SP              = " " , { " " } ;

guoqing-noaa · 2026-02-24T06:10:09Z

The following situations have been tested:
Note: extra spaces were intentionally added to test whether this PR can handle them corrently.

output_timelevels="0  1     "
output_timelevels="0h  1h   "

output_timelevels="0-1-15m 2-6-2"
output_timelevels="2-6-2"
output_timelevels="2-6-2   8-999"
output_timelevels="2-6h-2   8-999h"

output_timelevels="0m 15m  1h    1h3m"
output_timelevels="0s 30s 15m  1h    1h3m"
output_timelevels="0m 30s 15m  1h    1h3m"

guoqing-noaa · 2026-02-24T07:11:46Z

For a conus12km 12 hours forecasts, I tried different settings for the da_state stream (no changes on the history and diag outputs)

the output_interval="1:00:00" run took 606s
the output_timelevels="0-999" run took 609s
This 3s cost saves more time due to the skipping of mpasout output at hours 4-12:
the output_timelevels="0-3" run took 549s

SamuelTrahanNOAA

These code changes are overcomplicated and will be difficult to extend or maintain. Any significant changes to the functionality will require a complicated rewrite.

More specific overview comments:

Most of the parser code is a reimplementation of the Fortran standard split function. It would be better to call split.
Much of the time-related code reimplements the MPAS and ESMF alarm functionality. It would be better to extend the alarm functionality.
Parser errors aren't reported. If you type something wrong, you don't know what it was.
There are out-of-bounds array reads due to off-by-one errors.
The new syntax deviates from the MPAS days_HH:MM:SS time specification.
Unlike the rest of the MPAS I/O interface, this uses a cryptic string instead of XML tags. If you used XML tags, the parser code wouldn't be necessary at all.

SamuelTrahanNOAA · 2026-02-24T18:05:07Z