How to Step Through a Simulation

Note: All examples in this guide will be shown using the python package alfalfa-client, please see "How to Install Alfalfa Client" for more details on using this package.

Start Simulation

Once a model has been fully preprossesed and a run created as described in "How to Preprocess and Upload a Model", the simulation can be started.

Several parameters are required in order to start a simulation. This includes:

• Start time
• End time
• Timescale
• External clock

Please see "Simulation Clock Advancement Modes" for more information on these parameters. These parameters can be defined as shown below:

start_dt = datetime.datetime(2021, 7, 1, 12, 2, 0)
end_dt = datetime.datetime(2021, 7, 3, 0, 0, 0)

params = {
    "external_clock": True,
    "start_datetime": start_dt,
    "end_datetime": end_dt
    }

Once these parameters have been defined, a simulation can be started.

ac.start(site_id, params)

Read and Write Inputs and Outputs

Once a simulation has been started, the status should switch to "running" and all simulation inputs and outputs will be accessible.

Simulation inputs can be accessed as follows:

inputs = get_inputs(site_id)

This will return a list with the names of all writeable input points. Any of these input points cna be written to at any point in a simulation with the following function:

ac.set_inputs(_site_id, inputs)

Defining the inputs will required assigning values to each input name. An example of this is shown below:

inputs = {'point_name': value}

Similarly, all output points (or points with readable values) can be returned as follows:

outputs = get_outputs(site_id) 

This will return all readable points as well as their values at the previous simulation time step.

Advance Simulation

If external clock is selected, then model can be advanced one time step by calling the API:

ac.advance(site_id)

This will advance the model one time step. The current simulation time can be read at any point in the simulation with the following function:

ac.get_sim_time(site_id)

When a simulation is complete, it can be stopped with the following function:

ac.stop(site_id)

Once a simulation is stopped, the status should switch to "complete", and any simulation results can be accessed. Once a simulation is stopped, a new simulation run can be created for that model upload.