Time-Varying CSV File Format

Many inputs to Cruncher use Time-Varying CSV files to describe values that change over time. This format provides a flexible and lightweight way to pass forecasts, weather data, or scheduled interface targets into Simulator. Each row in the file specifies a value for a particular object at a specific time.

Core Structure

Each file must include the following elements:

Object Header — Column name in the form <OBJECTTYPE> (e.g. <GEN>, <LOAD>, <AREA>, <ZONE>, <INTERFACE>, or <WEATHERSTATION>). Identifies the device or aggregate object. The cells below should contain either the Simulator ObjectID or a valid Label identifying objects of the given type.
DateTime column — Timestamp for the row. Required in each file. Alternatively, use of either DateTimeBegin or DateTimeEnd explicitly tells Cruncher if the timestamps given should be interpreted as Interval Beginning or Interval Ending. Time zone can be explicitly specified by attaching a zone tag in angle brackets to this header (e.g. DateTimeEnd<UTC>). Current values explicitly supported include UTC, US/Pacific, US/Mountain, US/Central, and US/Eastern. Other time zones may be supported depending on your system.
Value Fields — One or more fields appropriate to the object type (e.g. MW for generators and loads, GenMW/LoadMW for areas, TempC for weather stations).

Optional Columns

Disable — Marks a row to be ignored (YES disables; NO or blank keeps active).
Any Other Header — Any additional headers may be used for informational purposes; Cruncher will ignore them.

Interval Convention

Cruncher must know whether a timestamp represents the beginning or end of the interval:

Interval Beginning — Value applies at this time and forward.
Interval Ending — Value applies up to this time.

This can be defined in the Cruncher configuration, or specified by the column header (DateTimeBegin or DateTimeEnd).

Supported Fields

The following object types and fields are currently supported:

Forecast Phase
- GEN — MW
- LOAD — MW
- AREA — GenMW, LoadMW
- ZONE — GenMW, LoadMW
- INJECTIONGROUP — GenMW, LoadMW, MW
Weather Phase
- WEATHERSTATION — TempF, TempC, CloudCoverPerc, WindDirection, WindSpeedkmph, WindSpeedmph
OPF Phase
- INTERFACE — LimitUsed
- NOTE: any Interfaces with a LimitUsed value applied in a given Snapshot will also have its OPFEnforceEquality field set to YES

Precedence Rules

When multiple files are applied, Cruncher follows a consistent order:

Individual object data (e.g. <GEN>, <LOAD>) are processed first.
Aggregate object data (e.g. <AREA>, <ZONE>, <INJECTIONGROUP>) are processed after.
If multiple files provide values for the same object, the file with higher priority in the Study or Snapshot configuration overrides lower-priority files.

Example: Generator Forecast

			<GEN>,DateTime,MW
			GEN1,2025-09-09 06:00,150
			GEN1,2025-09-09 07:00,160
			GEN2,2025-09-09 06:00,200
			GEN2,2025-09-09 07:00,210

Example: Area Load/Gen

			<AREA>,DateTime,GenMW,LoadMW
			1,2025-09-09 06:00,500,450
			1,2025-09-09 07:00,520,470

Best Practices

Keep timestamp formatting consistent (ISO format %Y-%m-%d %H:%M is recommended).
If possible, use consistent time zones across all forecast files in a Study.
Group related files into directories for simpler configuration and re-use.