Skip to content
Eric Bonnema edited this page Sep 15, 2023 · 15 revisions

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 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:

  1. Provide an industry-standard API for co-simulation through which an OpenStudio/EnergyPlus, Spawn, or Modelica model can be interacted with.
  2. Support large-scale parallel building simulation using commodity cloud computing resources such as AWS.
  3. 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 an access to an Alfalfa instance, you are ready to upload a model to an Alfalfa server and interactively run simulations. Refer to Getting Started with Uploading and Running a Model Using the UI for a an overview of uploading and running model with the UI and refer to Getting Started with Uploading and Running a Model Using 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.

Openstudio

Tutorials: Getting Started with Model Measures Part 1: Creating Inputs and Outputs | Getting Started with Model Measures Part 2: Creating Actuators | Getting Started with EnergyPlus Measures Part 1: Creating Inputs and Outputs | Getting Started with EnergyPlus Measures Part 2: Creating Actuators

Guides: How to Configure an OpenStudio Model | How to Configure Measures for Use with Alfalfa Ruby Gem | How to Create Inputs and Outputs With Measures | How to Run URBANopt Models in Alfalfa | How to Migrate EnergyPlus Python Plugins | How to Integrate Python based Electric Vehicle Models with OpenStudio Workflows | How to Locally Test OpenStudio Models

Reference: Required Structure of OpenStudio Workflow | List of Automatically Generated Energyplus Points | Alfalfa EnergyPlus Mixin Methods

Modelica

Guides: How to Configure a Modelica Model

Alfalfa Interaction Documentation

These documents guide a user through the process of uploading a model to an Alfalfa instance and interactively running simulations with these models.

Tutorials: Getting Started with Uploading and Running a Model Using Python | Getting Started with Uploading and Running a Model Using the UI

Guides: How to Install Alfalfa Client | How to Preprocess and Upload a Model | How to Step Through a Simulation | How to View Historical Data in Grafana | How to Configure an Alias | How to Troubleshoot Models

Reference: Run and Job Statuses | Simulation Clock Advancement Modes | Alfalfa Client Code Documentation

Explanation: Lifecycle of a Site

Alfalfa Development Documentation

These documents guide a user through the process of contributing to Alfalfa.

Guides: How to Set Up a Development Environment | How to Deploy Alfalfa for Development | How to Run Local Tests | Release Instructions

General Documentation

Reference: Alfalfa Dependency Version Matrix | Projects Which Have Used Alfalfa | Glossary | Related Repos

Explanation: Choosing a Simulation Engine


Model Configuration

Openstudio

Tutorials

Guides

Reference

Modelica

Guides

Alfalfa Interaction

Tutorials

Guides

Reference

Explanation

Alfalfa Development

Guides

General

Reference

Explanation

Clone this wiki locally