Support integer time

[Sbozzolo]

Draft. This is in progress

Tasks

Preview Give feedback

1. Add ITime
2. Rename counter to something else
3. Support SSPKnoth in ClimaTimeSteppers
4. Constructor for ITime from Date/Period
5. Support running with floats only
6. Support more generic period types/calendars (besides Dates)
7. Modifications in ClimaDiagnostics
8. Support ARS in ClimaTimeSteppers
9. Update the TimeVaryingInputs
10. Unifty callback system across packages, ensure that they can leverage ITime
11. Verify support for Int32
12. Support ARS343 in ClimaTimeSteppers (for ClimaAtmos CI)
13. Support SSP333 in ClimaTimeSteppers (for ClimaAtmos CI)

[ph-kev]

Problem

Due to floating point errors, time can stop incrementing and can become wildly inaccurate
when attempting to complete a long run.

Background

For ClimaAtmos, the simulation can be set to run using single-precision or double-precision
floating point using the FLOAT_TYPE parameter in the simulation configuration. For
sufficiently large values for time, adding a small floating point number to a big floating
point number will not increment the big floating point number. Consider the expression
Float32(16777216) + Float32(1) == Float32(16777216) which evaluates to true rather than
false. In this example, the simulation would stop if dt is one second. Furthermore,
there are round-off errors that can accumulate when adding many small floating point
numbers. For example, when running the Agnesi linear hydrostatic mountain experiment
(uniform) configuration in ClimaAtmos, the resulting time is 3h 59 m 51.0s despite t_end
being set to 14400.0 seconds or four hours. Finally, due to the imprecision of time, this
also results in any functions that involve dates being wrong as dates are computed using a
start date and the current time of the simulation.

Requirements for solution

Any solution must support accurate tracking of time. Furthermore, if a different type or
struct is used to replace time, then it must also support conversion to float or date.
Conversion to float is necessary because quantities in ClimaAtmos (e.g. tendencies) are
computed using the value of time. Conversion to dates is necessary because some functions,
like diagnostics, use dates.

Proposed solution

A proposed solution is to use ITime which is defined as a struct with the fields counter,
period, and epoch. A counter is an integer (e.g. Int32 or Int64) or rational number
(e.g. Rational{Int32} or Rational{Int64}), a period is a Dates.FixedPeriod, and an
epoch is a DateTime. Keeping track of time is accurate, because integer addition and
subtraction are exact, except in the case of overflow or underflow. Furthermore, two methods
date and seconds are provided which can be used to convert to a date or seconds since
the epoch.

Affected packages

• ClimaUtilities: Support for ITime in TimeVaryingInputs.
• ClimaDiagnostics: Support for ITime in schedules and writing data (e.g. NetCDF writers).
• ClimaTimeSteppers: Support for ITime in TimeSteppers.
• ClimaAtmos: Replace time with ITime and apply float when necessary.

For ClimaTimeSteppers, adding support for ITime necessitates changing the tableaus so that
the values are Rational or Integer instead of Float. This also means that any
irrational values need to be approximated as a rational number.