How to Configure Measures for Use with Alfalfa Ruby Gem

Alfalfa measures are OpenStudio measures (Model or EnergyPlus measures are supported) with extended features used to create Alfalfa points. This guide will go over how to create a measure and test it locally.

Installing the Alfalfa Ruby Gem

...

Configuring an OpenStudio Measure

For information about creating a measure see here.

1. Import Alfalfa

At the top of your measure.rb file add the line require 'alfalfa'. This imports the Alfalfa Gem for use in your measure.

require 'alfalfa' # add this line

class ExampleMeasure < OpenStudio::Measure::EnergyPlusMeasure

2. Include Alfalfa Mixin

Inside your class block add the following line depending on which measure type you are creating.

Model Measure: include OpenStudio::Alfalfa::OpenStudioMixin

EnergyPlus Measure: include OpenStudio::Alfalfa::EnergyPlusMixin

This adds relevant boilerplate to your measure to make it work well with Alfalfa.

class ExampleMeasure < OpenStudio::Measure::EnergyPlusMeasure

  include OpenStudio::Alfalfa::EnergyPlusMixin # add this line. If the class is ModelMeasure refer to the information above.

3. Report Inputs and Outputs

At the end of the def run(..) block before the return true add the line report_inputs_outputs.

This function actually writes the report files that Alfalfa needs in order to expose the correct points.

# define what happens when the measure is run
def run(workspace, runner, user_arguments)
  ...
  report_inputs_outputs # add this line

  runner.registerFinalCondition("Done")

  return true
end

Configuring and Running an OpenStudio Workflow

Comprehensive documentation for OpenStudio Workflow files can be found in the schema files and OpenStudio CLI guide. If you need help with the basic structure you can checkout the Alfalfa documentation on the topic here.

1. Adding your measure to a Workflow .osw File

A .osw file includes a section, steps, which lists all of the measures to run in the workflow. Below is an example of what that section might look like.

  "measure_paths": [
    "./measures/"
  ],
  "steps" : [
    {
      "measure_dir_name": "example_measure",
      "name": "Example Measure",
      "description": "Example Measure for Alfalfa",
      "modeler_description": "Example Measure for Alfalfa"
    }
  ]

Running your workflow locally

To run your workflow locally you can use the OpenStudio CLI.

You need to add a --gem-path argument to point to where the Alfalfa gem is installed on your machine.

openstudio --gem_path <path_to_gems> run ...