Simulation Time
This page provides more context about managing simulation time in GridLAB-D™.
The Clock Object
The clock object is used to indicate the start and stop time of a simulation, as well as provide time zone information. The clock controls the following features of the internal GridLAB-D™ clock:
- The timezone global variable defines the time zone used for schedules, reading, and writing. If the TZ environment variable is not set, the time zone should be the first feature specified because it is needed to read the starttime and stoptime.
- The starttime global variable determines the time at which the simulation begins. Before the first iteration begins, the clock will be set to
starttime. The default starttime is2000-01-01 00:00:00 UTC. If the time zone is not set (e.g., using the TZ environment variable), the command line or model parser may be unable to interpret the timestamp, and an error may occur. - The stoptime global variable determines the time at which the simulation ends. By default
stoptimeis set to one year afterstarttime. If the start time includes a time zone specification, then the time zone must be specified.
The clock object is organized as follows:
clock {
timezone tzspec;
starttime 'YYYY-MM-DD hh:mm:ss ZZZ';
stoptime 'YYYY-MM-DD hh:mm:ss ZZZ';
}
Using Date and Time
The time zone used by the clock object must be known before any timestamps can be interpreted. The time zone rules are used to determine the offset from UTC for all time calculations, as well as determine daylight or summer time shifts.
If the time zone is not set, the system will assume all timestamps are in local time. Time zones are specified using the POSIX time zone standard.
The time zone can be set as follows:
clock {
timezone PST8PDT;
starttime '2000-01-01 00:00:00 PST';
stoptime '2001-01-01 00:00:00 PST';
}
As mentioned previously, date and time specifications in GridLAB-D™ are usually specified using the ISO format, which is YYYY-MM-DD HH:MM:SS ZZZ. You can change the format of date/time values using the dateformat global variable. The supported formats include the following:
- ISO: The date/time format is
yyyy-mm-dd HH:MM:SS ZZZ. - US: The date/time format is
mm-dd-yyyy HH:MM:SS ZZZ. - EURO: The date/time format is
dd-mm-yyyy HH:MM:SS ZZZ.
In the absence of specific time zone information, GridLAB-D™ uses the UTC as the default time zone. Time zones are specified in the "tzinfo.txt" file that is installed with GridLAB-D™ under the share folder. The following time zones are currently supported for the United States:
UTC0 ; Coordinated Universal Time ~ never uses DST
GMT0 ; Greenwich Mean Time, no DST
EST5 ; Eastern no DST
CST6 ; Central no DST
MST7 ; Mountain no DST
PST8 ; Pacific no DST
[1970] ; Rules as of 1967
GMT0GMT,M3.5.0/02:00,M10.5.0/2:00 ; GMT, DST last Sun/Mar to last Sun/Oct
EST+5EDT,M4.5.0/02:00,M10.5.0/02:00 ; Eastern, DST last Sun/Apr to last Sun/Oct
CST+6CDT,M4.5.0/02:00,M10.5.0/02:00 ; Central, DST last Sun/Apr to last Sun/Oct
MST+7MDT,M4.5.0/02:00,M10.5.0/02:00 ; Mountain, DST last Sun/Apr to last Sun/Oct
PST+8PDT,M4.5.0/02:00,M10.5.0/02:00 ; Pacific, DST last Sun/Apr to last Sun/Oct
[1986] ; Rules as of 1986
EST+5EDT,M4.1.0/02:00,M10.5.0/02:00 ; Eastern, DST first Sun/Apr to last Sun/Oct
CST+6CDT,M4.1.0/02:00,M10.5.0/02:00 ; Central, DST first Sun/Apr to last Sun/Oct
MST+7MDT,M4.1.0/02:00,M10.5.0/02:00 ; Mountain, DST first Sun/Apr to last Sun/Oct
PST+8PDT,M4.1.0/02:00,M10.5.0/02:00 ; Pacific, DST first Sun/Apr to last Sun/Oct
[2007] ; Rules as of 2007
EST+5EDT,M3.2.0/02:00,M11.1.0/02:00 ; Eastern, DST second Sun/Mar to first Sun/Nov
CST+6CDT,M3.2.0/02:00,M11.1.0/02:00 ; Central, DST second Sun/Mar to first Sun/Nov
MST+7MDT,M3.2.0/02:00,M11.1.0/02:00 ; Mountain, DST second Sun/Mar to first Sun/Nov
PST+8PDT,M3.2.0/02:00,M11.1.0/02:00 ; Pacific, DST second Sun/Mar to first Sun/Nov
Since GridLAB-D™ can run historical simulations, the time zone rules may change from year to year. You may note in the "tzinfo.txt" snippbit above, there are different sections used to specify the year in which the time zone specification goes into effect.
GridLAB-D™ does not use the operating system's time zone specifications by default for several reasons:
- Some operating systems don’t recognize time zones that are historical but no longer used.
- The simulation often needs to run the simulation in a different time zone than that used by the host computer.
- The ability to use alternate time zone rules is essential to understand the energy use implication of altering the time zone rules, something which policymakers have an interest in and sometimes ask.
In GridLAB-D™, time zones follow the Posix TZ standard. Each time zone is described with a string using the form:
STZ[hh[:mm][DTZ][,M#[#].#.#/hh:mm,M#[#].#.#/hh:mm]]
where STZ is the 3-digit standard time zone specification and DTZ is the 3-digit daylight time zone specification, hh:mm describes the offset from GMT with negative for east and positive for west, the first M-spec describes the month, week and weekday on which daylight savings starts, and the second describes when it ends.
If we look at the example below,
// Examples:1b.glm
clock {
starttime '2000-01-01 00:00:00 UTC';
stoptime '2001-01-01 00:00:00 UTC';
}
module residential;
module tape;
object house {
object recorder {
property air_temperature;
file temperature.csv;
};
}
you can see the simulation clock advance by looking at the model's output from the recorder:
2000-01-01 00:00:00 UTC,+69
2000-01-01 01:00:00 UTC,+69.9947
2000-01-01 02:00:00 UTC,+70.6269
2000-01-01 03:00:00 UTC,+71.1764
2000-01-01 04:00:00 UTC,+71.6754
2000-01-01 05:00:00 UTC,+72.1189
2000-01-01 06:00:00 UTC,+72.5266
2000-01-01 07:00:00 UTC,+72.927
...
The Environment Variable - TZ
The time zone can also be set using the environmental variable TZ, if it isn't already set in the GLM file. As an example, the user may set the time zone as TZ=PST8PDT, which represents Pacific Time with the Daylight Savings Time option added. Remember that if the time zone is not set by either the clock object or the TZ environment variable, GridLAB-D™ may be unable to interpret timestamps and fatal errors may occur.
On Windows:
C:\> set TZ=PST8PDT
On Linux/Unix:
host% export TZ=PST8PDT
Locale Names
You may also use locale names instead of the time zone codes. Locale names are listed in the tzinfo file and take the form
Country/Region/City
For example, instead of coding
timezone PST+8PDT;
you can code
timezone US/CA/Los Angeles;
For a listing of country and region codes, see ISO Std 3166-2.
Time zones and daylight-savings/summer time rules can be found at www.worldtimezone.com.
Caveat
-
Most Asia and Africa time zones are not yet implemented in the "tzinfo.txt".
-
It is not clear whether 1/2 and 1/4 hours offset time zones always work properly.
-
Many of the historical rules for summer time around the world are not supported. In some cases the current summer time rules may be inappropriately applied to past years.
Disabling and Enabling Objects
It is possible to have an object activate at a pre-determined date and time, and have that object be deactivated at some time later. Each object has a pair of built-in properties called in and out that determine when the object enters service and when it goes out of service.
In the following example, we modify "house1.glm" to illustrate how the in and out properties function.
// Examples:1d.glm
clock {
timezone EST+5EDT;
starttime '2000-01-01 00:00:00';
stoptime '2001-01-01 00:00:00';
}
module residential;
module tape;
object house {
object recorder {
property air_temperature;
file temperature.csv;
in '2000-04-01 00:00:00';
out '2000-04-02 00:00:00';
};
}
Running "house1.glm" gives the following result:
2000-04-01 00:00:00 EST,+76.0806
2000-04-01 00:05:02 EST,+73.9952
2000-04-01 01:00:00 EST,+75.6225
...
2000-04-01 22:00:00 EST,+75.5875
2000-04-01 23:00:00 EST,+75.8156
2000-04-02 00:00:00 EST,+75.9208
You can see from the recorder's output that although the simulation started on January 1, 2000 at midnight, the data was only collected starting April 1, 2000 as specified by the in property of the recorder. You'll also notice the recorder stopped collecting data after midnight of April 2, 2000 as specified by the out property of the recorder.
Time Management
The previous sections provided an overview of how GridLAB-D™ simulates time and how to interact with time as a user. The operational details of GridLAB-D™ time management, however, deserve specific consideration. Namely, the global simulation clock of GridLAB-D™ may advance in either fixed or variable timesteps. This behavior depends on whether a simulation is executed in quasi-static or transient mode, described below.
Quasi-Static Mode | Default
Quasi-static mode simulations advance the the clock in variable timesteps. Specifically, GridLAB-D™ simulations are event-driven in this mode; each timestep depends on the pending state changes of the model’s objects, until no object reports a need for a future state change. Objects may schedule requests for future state changes at a granularity of one second. This mode offers computational efficiency and facilitates simulations with long time horizons.
An important function of event-driven simulations is that they enable quasi-static time-series simulations of the electric grid. Most tools that support such simulations execute them in fixed timesteps, and a GridLAB-D™ user may wish to replicate this behavior. In order to achieve that, a user may add a recorder scheduled to record at fixed time intervals, as well as adjust the minimum global timestep to match the recorder’s interval. In this way, the user can extract measurements at fixed timesteps from GridLAB-D™ simulations performed in quasi-static mode.
Quasi-static mode is also the default simulation mode of GridLAB-D™; every GridLAB-D™ simulation is event-driven until a switch to transient mode is executed. Such a switch can be triggered either directly by the user or indirectly depending on simulation conditions. The currently implemented GridLAB-D™ objects that can directly trigger a switch to transient mode are player, and eventgen. Moreover, transient mode is also supported by sync_check, inverter, inverter_dyn, motor, node, and evcharger_det. These devices can potentially trigger a switch to transient mode depending on the simulation conditions; for example, a drop in voltage can cause under-voltage load shedding, and the motor object will respond to such an event by entering transient mode to accurately simulate its dynamic behavior.
Discrete Time
TODO - Examples - Check that this Discrete Time example satisfies the needs of a Quasi-static mode example
GridLAB-D™ is a discrete time simulator, meaning it does not simulate a continuous flow of time as you might see in something like a SPICE circuit simulator or Simulink model. These simulators are not necessarily continuous, but the time steps used by the simulator are small enough and regularly spaced so as to closely and reasonably approximate continuous time. GridLAB-D™ makes no such effort and operates in a fundamentally different way.
GridLAB-D™ simulates time in discrete blocks that can vary in size; that is, the step size of the simulation is constant. The GridLAB-D™ core jumps from one discrete time to the next, asking all objects in the model (".glm") to update themselves based on how much time has elapsed since the last update. The algorithms and equations for each class define how objects of that class evolve over time. Using these relationships, all of the objects can determine their new state at this new point in time.
Many of the objects in a model interact with each other, with some outputs serving as other objects’ inputs. To handle this interdependency, the GridLAB-D™ core may re-iterate over a time step, asking all the models to re-update themselves using any new changes to their inputs to recalculate their state. This process may repeat many times until all of the objects have reached a new steady-state.
As a last step in the update process, all of the objects register with GridLAB-D™ the next time they need to be updated. Since by this point all the objects have reached a steady-state, most of them will indicate that they never need to be updated. Unless there is some external inciting event, their state will not change. There are only a few special objects that end up driving the simulation forward by requiring they be updated at particular times.
As an example, open up discrete_time_demo.glm. This is such a small model that we'll reproduce it here in its entirety.
module tape;
module residential;
module powerflow;
module climate;
clock {
timezone PST+8PDT;
starttime '2001-07-01 00:00:00';
stoptime '2001-07-08 00:00:00';
}
object climate {
tmyfile ""../../Shared Model Files/WA-Spokane-24157.tmy2"";
}
object triplex_meter {
phases AS;
nominal_voltage 120;
object house {
system_mode OFF;
auxiliary_strategy DEADBAND;
auxiliary_system_type ELECTRIC;
heating_system_type HEAT_PUMP;
cooling_system_type ELECTRIC;
air_temperature 70.0;
mass_temperature 70.0;
heating_setpoint 65;
cooling_setpoint 75;
number_of_stories 1;
window_wall_ratio 0.07;
heating_COP 1.00;
object recorder {
property air_temperature;
file "discrete_time_demo.csv";
interval 3600;
};
};
}
Looking at the clock object, you can see that this model will run from July 1st, 2001 to July 8th, 2001 and will use the weather from Spokane, WA. You can also see that a house is included in the model with a number of specific parameters defined.
Also attached to the house a recorder object. Recorders are not only one of the primary means of collecting data from a simulation, they are one of those special objects that regularly tell the GridLAB-D™ core when it next needs to be updated. One of the parameters of the recorder is its interval which is the number of seconds between data collection times. The recorder interval is set to 3600 seconds, indicating it will log a value once an hour. Running this simulation with the profiler turned on, via
gridlabd discrete_time_demo.glm --profile
prints the following to console:
Core profiler results
======================
Total objects 4 objects
Parallelism 1 thread
Total time 1.0 seconds
Core time 0.9 seconds (86.1%)
Compiler 0.5 seconds (47.8%)
Instances 0.0 seconds (0.0%)
Random variables 0.0 seconds (0.0%)
Schedules 0.0 seconds (0.1%)
Loadshapes 0.0 seconds (0.0%)
Enduses 0.0 seconds (0.0%)
Transforms 0.0 seconds (0.0%)
Model time 0.1 seconds/thread (13.9%)
Simulation time 7 days
Simulation speed 672 object.hours/second
Passes completed 552 passes
Time steps completed 552 timesteps
Convergence efficiency 1.00 passes/timestep
Read lock contention 0.0%
Write lock contention 0.0%
Average timestep 1096 seconds/timestep
Simulation rate 604800 x realtime
Model profiler results
======================
Class Time (s) Time (%) msec/obj
---------------- -------- -------- --------
climate 0.128 92.1% 128.0
house 0.005 3.6% 5.0
recorder 0.003 2.2% 3.0
triplex_meter 0.003 2.2% 3.0
================ ======== ======== ========
Total 0.139 100.0% 34.8
Note that your specific values will likely be different depending on the computer used for running these simulation. For our purposes, note the total simulation time in the lower table.
Now if you go back to the model file, change the interval to 6 and re-run the simulation:
Core profiler results
======================
Total objects 4 objects
Parallelism 1 thread
Total time 4.0 seconds
Core time 2.2 seconds (55.8%)
Compiler 0.5 seconds (12.2%)
Instances 0.0 seconds (0.0%)
Random variables 0.0 seconds (0.0%)
Schedules 0.0 seconds (0.0%)
Loadshapes 0.0 seconds (0.0%)
Enduses 0.0 seconds (0.3%)
Transforms 0.0 seconds (0.5%)
Model time 1.8 seconds/thread (44.2%)
Simulation time 7 days
Simulation speed 168 object.hours/second
Passes completed 101355 passes
Time steps completed 101355 timesteps
Convergence efficiency 1.00 passes/timestep
Read lock contention 0.0%
Write lock contention 0.0%
Average timestep 6 seconds/timestep
Simulation rate 151200 x realtime
Model profiler results
======================
Class Time (s) Time (%) msec/obj
---------------- -------- -------- --------
house 0.586 33.1% 586.0
triplex_meter 0.542 30.6% 542.0
recorder 0.325 18.4% 325.0
climate 0.317 17.9% 317.0
================ ======== ======== ========
Total 1.770 100.0% 442.5
You'll note the difference in total simulation time; it should be significant. By asking the recorder to collect data every 6 seconds instead of every 3600 seconds, we have forced GridLAB-D™ to update every object much more often, which requires significantly more calculation.
Comparing the entries in the lower table individually, you can see that when we updated every 3600 seconds, the vast majority of the simulation time was spent in the climate class, updating the weather being experienced by the house. When we move the time step down to 6 seconds, now the calculations of the house are largest, followed closely by the power flow of the meter attached to the house.
This example should make it clear that when we change the interval on the recorder, we are not simply changing which results are written out to a file, as if the results were calculated at a very fine time step and sampled as needed by the recorder. By changing the interval on the recorder, we are changing how often the simulation stops to recalculate the state of the system. For many simulations, the effective timestep of the simulation ends up being defined by the recorder, due to its special status in driving the simulation forward.
Transient Mode
GridLAB-D™ monitors when one or more objects may request to enter transient mode, as well as their preferred timestep, to decide when to transition from quasi-static to transient operations. Unlike timesteps in quasi-static mode, transient mode timesteps can be shorter than one second. When a transition to transient mode is triggered, all objects that support it switch to using the minimum requested timestep. State-dependent objects that do not support transient mode, such as water heaters or capacitors, do not update their state when in transient mode, but otherwise participate in the transient simulation using their pre-existing quasi-static mode values. Moreover, scheduled events are ignored during transient mode.
Transient mode is terminated and quasi-static operation is resumed when all objects report convergence to steady-state conditions. GridLAB-D™ users cannot directly cause a switch out of transient mode by using any special objects (unlike the case of switching into transient mode by using a player, for example); this change happens automatically. It is important to note that state-dependent models that lack support for transient mode do not update their state during transient simulations. Their state is only updated when they return to quasi-static mode. Using transient mode for extended periods of time may affect simulation results.