3 Requirements

3.1 Date calculations

• Support Gregorian and ``no-leap'' calendars. A ``no-leap'' calendar is the same as a Gregorian calendar with no leap years.

• Represent dates and times to a precision of 1 second.

• Date and time representations must have a range of at least 200,000 years.

3.2 Simulation control

• The time manager will be initialized by specifying the calendar type, timestep size, start date and stop date. The user may optionally specify the reference date. By default the reference date equals the start date.

• The timestep size must be chosen so that there are an integral number of steps in a day.

• The stop date may optionally be specified by any of the following:
  • a number of timesteps from the start date;
  • a number of days from the start date;
  • a number of timesteps from the restart date;
  • a number of days from the restart date;

• The current date may be changed at any point during a simulation.

• Provide methods to query timestep size, start date, stop date, and reference date.

• Provide methods to query the following:
  • the start date, stop date, and reference date;
  • current timestep number and size;
  • current date, time, and calendar day;
  • previous date, i.e., date at the beginning of the current timestep;
  • perpetual date,
  • if the current timestep is the final one of the day or month;
  • if the current timestep is the first one of an initial or restart run;
  • if the current timestep is the last one of the run;

• The methods that return the current date and calendar day should provide for an optional offset to be specified. This provides easy access to the calendar calculations required to find date or calendar day values that are offset from the end-point of the current timestep.

• Provide an option to allow running the simulation in a ``perpetual calendar'' mode. Under this option the time and dates are always available both as the usual simulation time and date, and as a perpetual time and date. The simulation time and date are written to the output history files and log files to track the simulation progress with a monotonic time progression. The perpetual time and date are used to determine the sun position and interpolate boundary datasets. The perpetual day (i.e., the year, month, and day of month part of the date) may either be read from the initial file or may be set to user specified values. When running in aqua-planet mode the perpetual day is set to March 21 of year 0. The perpetual date and calendar day include a diurnal cycle.
  • A query method will be provided to determine if the time manager is using the perpetual calendar mode.
  • A query method will be provided that returns the current perpetual date which is the perpetual year, month, and day of month, plus the time of day component from the simulation's current date. This forces the time of day written to the history files to be consistent with the phase of the diurnal cycle that is used in the solar calculations.
  • The method that returns the current calendar day will return the calendar day corresponding to the current perpetual date when running in perpetual mode.

• The time manager must be able to "restart", i.e., it must be able to write its state to a binary restart file, and reset its state after reading the restart file. The only attribute of the time manager state that may be changed when initializing a restart run is the stop date.

3.3 Alarms

An alarm is used to signal that some event should take place during the current timestep. Alarms are initialized by specifying a set of times when they should be turned on. The time manager will turn an alarm on during the first timestep whose late end-point (i.e., the current time) equals or exceeds the current alarm time. When an alarm is turned on the alarm time is updated. Some specific requirements for alarm functionality are:

• Provide alarms that are turned on periodically and can be specified by a period and an offset.

• Provide alarms that are turned on when year and month boundaries are crossed.

• Provide method to query whether an alarm is on or off.

• Provide methods to query the current alarm time and date. The current alarm time is the time that the alarm is set to be turned on. If the alarm in currently on, then the current alarm time is the next time that the alarm will be turned on since the time manager updates the alarm time when it turns an alarm on.