Lifecycle of a Site

This page walks through the stages involved in uploading and running a model. Note that many of these actions (e.g. preprocessing) are triggered automatically.

Model Upload

When a model is uploaded to Alfalfa it is assigned a unique identifier and saved to an S3 bucket. A database entry is also created which links together the id, bucket location, and original filename it had.

Creating a Run

In order to create a run from a model a CreateRun job must be generated. This is usually accomplished via the REST API. There are two different CreateRun jobs that exist and which one to call is dependent on whether the model is an OpenStudio workflow or a Modelica FMU. While these are two distinct jobs the tasks they take are similar.

Initialization

The first thing either job will do is download the model, unzip it if necessary, and create a new run database entry with information about which model it was seeded by, a unique identifier, the type of simulation, the run status, and a few other useful pieces of information. Until this point the run will not show up in the UI or the API.

Preprocessing

Once a CreateRun job has initialized it will start to preprocess the uploaded model. This includes confirming that the said model exists in the upload, and setting up the run directory so that everything needed to run the model is there. In the case of OpenStudio models this also includes executing all of the workflow measures, installing and linking python dependencies, and generating a point list. After this step is complete the directory is uploaded to an S3 bucket and the job is complete.

Starting a Run

Once a model has been preprocessed is can be run by invoking the StepRun job. This is usually accomplished via the REST API. Invoking this job requires the id of the run which completed the preprocessing as well as the time information for when to start the model and whether to advance it on an internal clock.

Started

After invoking the job it may take some time before it starts running. This is due to the time it take for the underlying simulation engine to get initialized, connected, and warmed up. Depending on the size of the model this can take several minutes.

Running

Once running the model can be interacted with by setting the points associated with the run. This is usually done via the REST API. At every timestep the job will pull the new values and, after executing a timestep, push updated output values. If the job is configured to use an internal clock the model will advance on its own in accordance to the set timescale. Otherwise a message must be sent to the job telling it to advance the model.

Completing and Cleanup

After a model either reaches a set end time or is terminated via a command it will reupload all of the files it generated to the S3 bucket and exit.

Errors

When an error is encountered it will immediately cause the job to exit what it is doing and record the error log in the database. The status of the run will change to reflect the fact that an error has occurred and its error log will be accessible via the REST API.