Custom Types

Timing Types

The Timing-related custom types are used to describe how the Simulation will compute its start and end times based on the time at which the program was launched.

Definitions

1. Base time: The time at which the Simulation was launched with the fields finer than the field set to be kept by the Clear subsection set to their minimum value (typically 0).
2. Start time: The time at which the Simulation will be started. This is computed by applying the Round and Offset fields to the base time (in that order)
3. End time: The time at which the Simulation will be stopped. This is computed by adding the Duration to the start time.

Inheritance

In order to simplify the process of recording timing information, all of the Timing types have a tree-based inheritance structure that allows the values of almost every field to be implicitly defined.

The root of the inheritance hierarchy is the global subsection of the timing section in the configuration file. Every other subsection of the timing section automatically fills in undefined fields with their values in global. Additionally, every Timing-related custom type has an inherit field which can be set to true, which tells the Simulation to treat that field as if it were not defined. This is primarily for use in the lower-level custom types (Clear, Duration, Offset, Round), which, because they can, depending on their type, have very different fields, cannot inherit their values directly.

Common Properties

1. The disabled type is a mode shared by all of the timing-related custom types. This mode is essentially a passthrough, and is only used when the field is not defined in global and the Module-specific subsection.
2. The type field is used to set the subtype of the timing-related custom type. The different subtypes can have different fields and processing methods, although the majority of the timing-related custom types only have one subtype.
3. Every timing-related custom type (except for Timing) has an implicit list type. This allows for any field within Timing to be declared as a list of fields of that type.
4. For values that refer to a particular Calendar field, valid values are:
   milliseconds, seconds, minutes, hours, days, months, years

• These are listed in decreasing fineness order.
• Fields that store these values will be listed as having the type, calendar-field.
• Although days, hours, minutes, and seconds are supported by all of the default Modules and Custom Types, years, months, and milliseconds are not necessarily supported and may cause unexpected behavior.

5. Undeclared fields are interpreted to mean that the timing-field that they affect will remain unchanged.

• To inherit the value from the parent, declare the field as having the value "inherit".

6. The enabled field will only disable a component if its value is set to false.

• This is to allow for more detailed to be placed within that field.

Timing

This is the collection type for the Timing-related custom types.

Fields

• clear: Determines the finest time field to keep in the base time. (default: disabled; type: Clear, List<Clear>; version: 4.0.0)
• duration: Determines the time range that the Simulation will cover. (default: disabled; type: Duration, List<Duration>; version: 4.0.0)
• offset: Determines how far from the rounded time the Simulation's start time should be offset. (default: disabled; type: Offset, List<Offset>; version: 4.0.0)
• round: Determines how the Simulation's base time will be rounded after Clear has been applied. (default: disabled; type: Round, List<Round>; version: 4.0.0)

Clear

These are used as a convenience method to quickly round time fields finer than the given field to zero prior to the base value being stored. This is useful primarily for simplifying timestamps and other preparatory processes.

Implementations

Standard

This implements simple round-to-zero logic. All Calendar values finer than the one given in the keep field are set to their minimum logical value according to the Calendar implementation.

Fields

• keep: Determines the finest time field to not round to its minimum value. (required; type: calendar-field; version: 4.0.0)
  • The minimum value is typically 0.

Duration

These are similar to Offset, except that they are used to specify for how long the Simulation is to be run.

Implementations

The default implementation is standard.

Standard

This implements simple wrapped addition logic. All values are integers; however, they do not need to fit within the Calendar's ranges for them (hours = 32 and days = 1, hours = 8 are equivalent).

Fields

• years: The number of years for which the Simulation is to be run. (default: 0; type: Integer; version: 4.0.0)
• months: The number of months for which the Simulation is to be run. (default: 0; type: Integer; version: 4.0.0)
• days: The number of days for which the Simulation is to be run. (default: 0; type: Integer; version: 4.0.0)
• hours: The number of hours for which the Simulation is to be run. (default: 0; type: Integer; version: 4.0.0)
• minutes: The number of minutes for which the Simulation is to be run. (default: 0; type: Integer; version: 4.0.0)
• seconds: The number of seconds for which the Simulation is to be run. (default: 0; type: Integer; version: 4.0.0)
• milliseconds: The number of milliseconds for which the Simulation is to be run. (default: 0; type: Integer; version: 4.0.0)

Offset

These are similar to Duration, except that they are used to specify how far the actual start time of the Simulation should be offset from the rounded base time.

Implementations

Standard

This implements simple addition logic. All values are integers; however, they do not need to fit within the Calendar's ranges for them (hours = 32 and days = 1, hours = 8 are equivalent).

Fields

• years: The number of years for which the Simulation is to be run. (default: 0; type: Integer; version: 7.1.0)
• months: The number of months for which the Simulation is to be run. (default: 0; type: Integer; version: 7.1.0)
• days: The number of days for which the Simulation is to be run. (default: 0; type: Integer; version: 4.0.0)
• hours: The number of hours for which the Simulation is to be run. (default: 0; type: Integer; version: 4.0.0)
• minutes: The number of minutes for which the Simulation is to be run. (default: 0; type: Integer; version: 4.0.0)
• seconds: The number of seconds for which the Simulation is to be run. (default: 0; type: Integer; version: 4.0.0)
• milliseconds: The number of milliseconds for which the Simulation is to be run. (default: 0; type: Integer; version: 7.1.0)

Round

This is the key timing-related custom type for allowing flexibility in how the start and end times of the Simulations are computed. Every sub-type has a different set of fields, and some are incredibly flexible. This means that relying on implicit inheritance is possible, it is not recommended in any situation other than a complete overwrite.

Common Properties

1. Fields are grouped by the timing-field that they modify.
2. Field groups are processed independently. Thus, there are no requirements that involve multiple field groups.
3. Because each timing-field has the same possible field combinations, instead of providing a fields list, the possible field combinations will be listed rather than the exact supported fields.
4. Within a field group's description, the word "group" in a field name should be replaced with the appropriate timing-field for the group.

• i.e. "group-rounding-mode" for the "minutes" group would be "minutes-rounding-mode"

Implementations

Bucket

This is the default implementation. There are four valid field combinations for each group; however, they all define the parameters for the same basic operation.

Each timing-field is rounded by defining buckets into which each field value is placed. The fields are then rounded to the value at the start or end of the bucket as appropriate. The way that the rounding is performed is defined by Java's RoundingMode.

Implementation Notes

1. Fields that define RoundingModes are listed as having the type, rounding-mode. They are case-insensitive Strings and can have one of eight values:
   ceiling, down, floor, half_down, half_even, half_up, unnecessary, or up.

• Although unnecessary is a valid value, it will almost certainly cause runtime issues.

2. Negative timing-field values are not supported at this time - although they are not explicitly rejected, undefined behavior should be expected.

Fields

• rounding-mode: The default RoundingMode for all field groups. (default: FLOOR; type: rounding-mode; version: 4.0.0)
  • This field is not associated with an field group - it defines the default rounding mode to be used for all groups.
  • Its value is referred to as global-rounding-mode within field groups.

Field Groups

Default Step-Offset

This group type generates a series of buckets that have a constant width and are optionally offset from 0 by an integer offset value.

• group-step: The width of each bucket (the name is derived from the shape that these functions make on a graph). (required; type: Integer; version: 4.0.0)
  • The "-step" suffix is optional.
• group-offset: How far from 0 the start of the buckets is offset. (default: 0; type: Integer; version: 4.0.0)
  • Because buckets extend in both directions, the actual offset amount is effectively "group-offset % group-step".
• group-rounding-mode: The RoundingMode to be used for the group's timing-field. (default: global-rounding-mode; type: rounding-mode; version: 4.0.0)

Object Step-Offset

This is a variation of the Default Step-Offset field group - it performs the same functions; however, it's values are defined within a JSON Object. The JSON Object's valid fields are:

• step: The width of each bucket (the name is derived from the shape that these functions make on a graph). (required; type: Integer; version: 4.0.0)
• offset: How far from 0 the start of the buckets is offset. (default: 0; type: Integer; version: 4.0.0)
  • Because buckets extend in both directions, the actual offset amount is effectively "offset % step".
• rounding-mode: The RoundingMode to be used for the group's timing-field. (default: global-rounding-mode; type: rounding-mode; version: 4.0.0)

To use this field group, the JSON Object is assigned to a field with the same name as the group. For the hours group with a step of 3, an offset of 1 and the global RoundingMode, this would look like:

"round" : {
  "hours" : {
    "step" : 3,
    "offset" : 1
  }
}

Default Explicit Buckets

This group type uses a series of explicitly defined buckets to round the timing-field's value. This field group should be used with caution because it is possible for certain values to be unroundable depending on the provided buckets and RoundingMode.

• group: The start values for each bucket. Buckets end at the next bucket's start value. (required; type: List<Integer>; version: 4.0.0)
  • Although timing-field values will only be rounded to values within the List, there are two implicitly created buckets.
    • The first starts at negative infinity and ends at the first value in the List.
    • The second starts at the last value in the List and ends at positive infinity.
• group-rounding-mode: The RoundingMode to be used for the group's timing-field. (default: global-rounding-mode; type: rounding-mode; version: 4.0.0)
  • In the following conditions, "the List" refers to the list of start values for each bucket.
  • The conditions under which a value cannot be rounded are as follows:
    • For ceiling:
      • The timing-field value is greater than the last value in the List
    • For down:
      • The timing-field value is negative and greater than the last value in the List
      • The timing-field value is positive and less than the first value in the List
    • For floor
      • The timing-field value is less than the first value in the List
    • For up
      • The timing-field value is negative and less than the first value in the List
      • The timing-field value is greater than the last value in the List

Object Explicit Buckets

This is a variation of the Default Explicit Buckets field group - it performs the same functions; however, it's values are defined within a JSON Object. The JSON Object's valid fields are:

• buckets: The start values for each bucket. Buckets end at the next bucket's start value. (required; type: List<Integer>; version: 4.0.0)
  • Although timing-field values will only be rounded to values within the List, there are two implicitly created buckets.
    • The first starts at negative infinity and ends at the first value in the List.
    • The second starts at the last value in the List and ends at positive infinity.
• rounding-mode: The RoundingMode to be used for the group's timing-field. (default: global-rounding-mode; type: rounding-mode; version: 4.0.0)
• In the following conditions, "the List" refers to the list of start values for each bucket.
• The conditions under which a value cannot be rounded are as follows:
  • For ceiling:
    • The timing-field value is greater than the last value in the List
  • For down:
    • The timing-field value is negative and greater than the last value in the List
    • The timing-field value is positive and less than the first value in the List
  • For floor
    • The timing-field value is less than the first value in the List
  • For up
    • The timing-field value is negative and less than the first value in the List
    • The timing-field value is greater than the last value in the List

To use this field group, the JSON Object is assigned to a field with the same name as the group. For the hours group with 8 buckets and a rounding mode of up, this would look like:

"round" : {
  "hours" : {
    "buckets" : [0, 3, 6, 9, 12, 15, 18, 21],
    "rounding-mode" : "up"
  }
}

Parallel

This type is used to define how the subprocess calls for each Module are generated.

Implementations

Standard

This implementation is designed to work with parallelization implemented via MPI (primarily MPICH2 implementation), which is the framework with which all of the WRF project's parallelization is implemented.

It uses the mpiexec command, which is the default name under which both the MPICH2 and OpenMPI implementations are installed.

• is-dmpar: Whether the Module's command should be run with mpiexec (this is required in order to use parallelization within WRF and WPS) - it is functionally equivalent to the enabled flag. (default: false; type: Boolean; version: 5.2.0)
• boot-lam: Whether the mpiexec call should include the boot flag. This should only be used on personal machines that will not have another MPI process running on them. (default: false; type: boolean; version: 5.2.0)
  • Note: MPICH2 appears to no longer use this flag. This option is now kept purely for backwards-compatibility.
• processors: The number of processors to allow the Module to use. If you intend to continue using the computer on which you are running the Simulation while the Simulation is in progress, leave your system at least 2 processors. (default: 2; type: Integer; version: 5.2.0)