Getting Started with Uploading and Running a Model Using Python

This tutorial shows you how to interact with the Alfalfa API using Python and the alfalfa-client Python package. You will learn to:

1. Upload models to a running Alfalfa deployment, and
2. Step through simulations, change input values, and view simulation outputs

Note: this tutorial assumes that you have already set up a python environment with python version 3.8 or higher. A repository containing jupyter notebooks containing the code in this tutorial, example models, and more detailed instructions to set up a python environment can be found at alfalfa-notebooks.

Setup

Before attempting this tutorial, you should either have the Alfalfa stack deployed locally or have the url for the remote Alfalfa deployment that you are using.

Install and import packages

alfalfa-client is available on PyPI and may be installed with pip as follows:

pip install alfalfa-client

Once relevant packages are installed to your python environment, we can import them as:

import datetime
from alfalfa_client.alfalfa_client import AlfalfaClient
from pprint import pprint

Create new Alfalfa Client object

First, we will initialize an Alfalfa Client object as follows:

ac = AlfalfaClient(host='http://localhost')

If you are running Alfalfa locally no changes in the above code are required. If not, change the the url in the second cell ('http://localhost' by default) to the url of your Alfalfa deployment. Note:Trailing slashes in the URL can lead to errors. This is a known issue that will be fixed in the future.

Define path to model

If you do not already have a model configured for use with Alfalfa, a directory containing the model and all necessary components can be found here. The model path can be a directory (for OSWs) or a file (.zip for OSWs or .fmu).

Assuming you have saved this directory in your project folder, the path may be defined as:

model_path = './twobldgs'

Upload models to Alfalfa

The ac.submit function returns the site_id which is used to interact with that specific site over the API.

site_id = ac.submit(model_path)
print(site_id)

Once you have uploaded your model to Alfalfa, sites can be viewed in the GUI at http://localhost/sites.

Define Parameters to run the simulations

First, we will define variables for our simulation start and end time using datetime objects:

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

Then, we will define all required parameters for simulation in a dictionary:

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

For external_clock == true, API calls are used to advance the model. If external_clock == false, Alfalfa will handle advancing the model according to a specified timescale. See "Stepping Through Simulations" for more information on these options,

In this tutorial, we will step through with the external clock.

Run Simulations

The ac.start function will start a simulation given a site ID and the parameters we have previously defined.

print(f"Starting site: {site_id}")
ac.start(site_id, **params)

However, since we are using an external clock, the simulation will stay at t=0 until we tell it otherwise.

Get the model's input points

In order to display the available input points for your model, we will use the ac.get_inputs function as follows:

print(f"{site_id} inputs:")
pprint(ac.get_inputs(site_id))

This will return a list of available input points.

Set model input point

We can set input values at any point in the simulation for any of the points returned by ac.get_inputs. To set an input value we can use the ac.set_inputs(site_id, inputs) function as follows:

input_dict = {'Core_ZN_ZN_PSZ_AC_1_Outside_Air_Damper_CMD': 0.7}
ac.set_inputs(site_id, input_dict)

Where the input parameters are as follows:

• site_id - the id of the site returned by the ac.submit function
• inputs - a dictionary of input names and the desired values The ac.set_inputs will change the input for the following timestep in the simulation, and it can be called at any point as you are stepping through a simulation.

Advance the model

We will use ac.advance to step through the model as follows:

timesteps = 5
for _ in range(timesteps):
    ac.advance(site_id)
    print(f"Model advanced to time: {ac.get_sim_time(site_id)}")

Each time the ac.advance function is called, the simulation will advance 1 timestep. Currently in Alfalfa, each timestep is hardcoded to 1 minute.

Get model's outputs

For each timestep of the simulation, we can get outputs for all available output variables with the ac.get_outputs function as follows:

print(f"{site_id} outputs:")
pprint(ac.get_outputs(site_id))

This will return a dictionary with each output name as the key, and sensor readings as values for the current timestep of the simulation.

Stop Simulation

Finally, we can stop the simulation with the ac.stop function:

ac.stop(site_id)