Controlling Simulation Time

Example file: docs/examples/api/example_sim_stepping.py](../../../../examples/api/example_sim_stepping.py)

Managing simulation time is one of the fundamental tasks in running a time-series simulation; this example walks through how to advance simulation time through GridLAB-D™'s provided step_to() and step() methods.

Using step() and step_to()

As shown in the previous example, it is possible to programmatically set the start and stop time of a simulation prior to actually simulating the model. In many cases, this may be all you need to do, such as when wanting to, say, evaluate solar production for each month of the year independently by running models in parallel (see discussion in our section on this). It is common, though, to need to interact with the model while running (e.g. data collection or controller implementation) and to do that, you need to control the simulation time such that its advancement pauses at the times of our choosing so that we can interact with the model as we need. To facilitate this, there are two methods available: step_to() and step().

step_to() provides the ability to advance simulation time to a time specified a timestamp string. step() allows the user to advance through simulation time at regular step sizes (specifed by GridLAB-D™ or by the user with set_time_step()). Because of how GridLAB-D™ simulates objects internally, there may be internal time steps that it takes but GridLAB-D™ will not pause the simulation at these times. As far as you, the programmer, are concerned, you are asking to step to a specific time or take a time step of a specific size and GridLAB-D™ will do what it takes to properly advance simulation time to that point and then pause, returning control back to the script that called that API. This distinction is important if you're doing data collection using recorders and have the interval set to -1 which collects data at every time step. When using step_to() in these cases, you'll get data written to these output files at these intermediate time.

This example shows the use of both API calls. The first call is to step_to() specifying a time 20 minutes after the "starttime" of the model. After reaching this point, the simulation is advanced a few time steps with the step() API. Lastly, the script demonstrates the fatal error that is generated when trying to step beyond the end of the specified "stoptime" in the simulation.

Using step() Withoutset_time_step()`

Not shown in this example is the use of step() without first using set_time_step(). When using the API in this way, the user leaves it up to GridLAB-D™ to define the step size. This will produce the same sequence of steps as if the you had called run() instead of step() but after each advancement of simulation time, GridLAB-D™ returns control to the calling script. These pauses allow you to do any data collection and/or modify the model prior to taking the next simulation step.

TODO - API docs - partially held up by Github issue #1699