Getting Started

Screenshot 2023-06-27 at 10 42 02 AM

Alfalfa Overview

What is Alfalfa?

Alfalfa is an open source web application forged in the melting pot of Building Energy Modeling (BEM), Building Controls, and Software Engineering domain expertise. Alfalfa transforms a Building Energy Models (BEMs) into virtual buildings by providing industry standard building control interfaces for interacting with models as they run. From a software engineering perspective, Alfalfa leverages widely adopted open source products and is architected according to best practices for a robust, modular, and scalable architecture.

The main goals of Alfalfa include the following:

Provide an industry-standard API for co-simulation through which an OpenStudio/EnergyPlus, Spawn, or Modelica model can be interacted with.
Support large-scale parallel building simulation using commodity cloud computing resources such as AWS.
Provide a RESTful interface for uploading, starting, and stopping simulation(s), as well as a simple user interface for these tasks.

Why use Alfalfa?

Consolidation

Alfalfa handles all the details for running energy models with a variety of engines, including IO to the running model. These implementation details are obscure, time consuming, and error prone when tackled on a project-by-project basis. Similarly, Alfalfa handles the details of implementing industry standard control interfaces. The modular architecture allows you to pick and choose the right engine and interface for your application.

Need something new? Consider contributing to the project instead of re-inventing to stand something up end-to-end for your application.

Abstraction

For project workflows that leverage Alfalfa, the entire model, including modeling engine, can be swapped out without affecting other components in the workflow. Replacing an OpenStudio model with a Modelica-generated FMU is as simple as uploading a different file.

Getting Started

Getting an Alfalfa Instance

Alfalfa is a web service that must be deployed onto a server before models can be uploaded and interacted with.

Internal NREL Users

There are existing Alfalfa instances available to you if this supports your use case. Please refer to the CBRI user guide or contact Anya Petersen([email protected]) or Tobias Shapinsky([email protected]) for access instructions.

External Users

If you do not have access to an existing Alfalfa instance, or require a standalone deployment for your use case, refer to the deployment guide for instructions to deploy via docker-compose, Docker Swarm, or Kubernetes.

Running your first model

Once you have a properly configured simulation model, you are ready to upload this model to an alfalfa server and interactively run simulations. Refer to 'Getting Started with Uploading and Running a Model in UI' for a an overview of uploading and running model with the UI and refer to 'Getting Started with Uploading and Running a Model in Python' for an overview of interacting with models with alfalfa-client.

Documentation Overview

This documentation is organized according to the Diataxis Framework, which is separated into Tutorials, How-to Guides, Reference Articles, and Topic articles. These documents have goals as described below:

Tutorials: Concretely guide a user to a meaningful and attainable outcome, follow a workflow from start to finish and assume no background knowledge
How-to guides: Step by step and instructions to accomplish a particular task, may start in middle of process and assume background knowledge
Explanation: Provide a higher level perspective to a topic to encourage understandin
Reference: Provide technical information on a specific topic or part of software, may link to how-to guides, explanation, and tutorials as necessary

Further, documents across these types are split into categories which generally follow the workflow one will follow when setting up a new project, including:

Alfalfa Deployment
Model Configuration
Alfalfa Interaction
Development

These categories and the documents within will be outlined in the following sections.

Alfalfa Deployment Documentation

These documents walk a user through the necessary steps to deploying an instance of Alfalfa through various methods if an existing deployment is not available.

Guides: How to Deploy with docker-compose | How to Deploy with Docker Swarm | How to Deploy Historian

Explanation: General Deployment Considerations

Model Configuration Documentation

These documents walk a user through the process of configuring a simulation model so that it is ready for upload to Alfalfa, including information on exposing points to be interacted with in Alfalfa. Please see Choosing a Simulation Engine for more information on which simulation engine will be suitable for your use case.