Getting Started with Model Measures Part 1: Creating Inputs and Outputs

This tutorial will lead you through the process of creating a measure which creates an output that reads the electricity consumption of the heating coils in the model as well as an input which reports its value.

1. Set up

If you are going to be testing your measure locally it is recommended that you follow the Alfalfa ruby gem installation instructions.

For the purpose of this tutorial a model folder has been prepared, available for download here. Download the zip file and move it to a folder to work on. You should see within the measures folder two folders, for this tutorial we will be working within the example_model_measure folder.

2. Adding Measure to the OSW

In the top level of the point_demo folder open the workflow.osw file. This file is what Alfalfa reads from when setting up a site. A measure, even if included in the uploaded folder, will not be run unless it is included within the steps list below.

Take the step below and copy it into your workflow.osw

  "steps" : [
    {
      "measure_dir_name" : "example_model_measure",
      "name" : "Example Model Measure",
      "description" : "An Example Measure to act as a starting point for a tutorial",
      "modeler_description" : "An Example Measure to act as a starting point for a tutorial"
    }
  ]

3. Adding an Output

Open the measure.rb file from within the example_model_measure folder and scroll down to the run(...) method declaration.

The following code within the run(...) method will create an output for each CoilHeatingDXSingleSpeed in the model which reports the electrical consumption

# Get a list of all of the heating coils in the model of type CoilHeatingDXSingleSpeed
heating_coils = model.getCoilHeatingDXSingleSpeeds

# Iterate through each heating coil in the list
heating_coils.each do |heating_coil|
  # Get the name of the component, which is needed to refer to it
  name = heating_coil.name.get

  # Create an output variable which is connected to the 'Heating Coil Electricity Rate' of the heating coil
  heating_electricity = create_output_variable(name, 'Heating Coil Electricity Rate')

  # Set the name that will be displayed in Alfalfa to '<coil_name> Heating Electricity'
  heating_electricity.display_name = "#{name} Heating Electricity"

  # Tell Alfalfa that you would like to the output variable to be exposed. Without this line the output will not show up
  register_output(heating_electricity)
end

4. Confirming that Points are Being Generated

In order to test that a measure is working properly without uploading to Alfalfa you can run your model as follows. For more information about running locally see this guide.

It is recommended to run with the -m flag to only run the measures.

openstudio --gem_path <path_to_gems> run -m

If this runs correctly you should find a example_model_measure_report_outputs.json file within the reports folder in the run folder. In this file you should see several entries which look something like the example below.

{
    "1671ea0d-b4e1-40ee-b4d1-32ca0cd0376c": {
        "id": "1671ea0d-b4e1-40ee-b4d1-32ca0cd0376c",
        "component": "Perimeter_ZN_4 ZN HP Htg Coil 20 Clg kBtu/hr 8.0HSPF",
        "variable": "Heating Coil Electricity Rate",
        "display_name": "Perimeter_ZN_4 ZN HP Htg Coil 20 Clg kBtu/hr 8.0HSPF Heating Electricity"
    },
    "fbf3038d-c910-4fe1-85c6-4bdcad7e85d0": {
        "id": "fbf3038d-c910-4fe1-85c6-4bdcad7e85d0",
        "component": "Core_ZN ZN HP Htg Coil 21 Clg kBtu/hr 8.0HSPF",
        "variable": "Heating Coil Electricity Rate",
        "display_name": "Core_ZN ZN HP Htg Coil 21 Clg kBtu/hr 8.0HSPF Heating Electricity"
    },
    "3db26d78-e025-4b5a-a08b-6c6459e905e4": {
        "id": "3db26d78-e025-4b5a-a08b-6c6459e905e4",
        "component": "Perimeter_ZN_2 ZN HP Htg Coil 17 Clg kBtu/hr 8.0HSPF",
        "variable": "Heating Coil Electricity Rate",
        "display_name": "Perimeter_ZN_2 ZN HP Htg Coil 17 Clg kBtu/hr 8.0HSPF Heating Electricity"
    },
    "f7c22958-0835-4ccf-af70-90face15edee": {
        "id": "f7c22958-0835-4ccf-af70-90face15edee",
        "component": "Perimeter_ZN_3 ZN HP Htg Coil 20 Clg kBtu/hr 8.0HSPF",
        "variable": "Heating Coil Electricity Rate",
        "display_name": "Perimeter_ZN_3 ZN HP Htg Coil 20 Clg kBtu/hr 8.0HSPF Heating Electricity"
    },
    "ff30c6ea-3204-466d-b654-0d181e432f97": {
        "id": "ff30c6ea-3204-466d-b654-0d181e432f97",
        "component": "Perimeter_ZN_1 ZN HP Htg Coil 23 Clg kBtu/hr 8.0HSPF",
        "variable": "Heating Coil Electricity Rate",
        "display_name": "Perimeter_ZN_1 ZN HP Htg Coil 23 Clg kBtu/hr 8.0HSPF Heating Electricity"
    }
}

If you do not see the file check that the run completed successfully. If the file exists but there are no entries check that you have registered all of your outputs.

5. Adding an Input

The code below is added to generate an Input which can be used to control other parts of the model.

# Create an string for the name of the input variable.
# create_ems_str takes any string and makes it a valid string that can be used in energyplus
input_variable_ems_name = create_ems_str('Example Variable')

# Create an external interface variable which is used as an input
input_variable = create_external_variable(input_variable_ems_name)

# Set the display name to 'Example Variable' this is how we'll find it in the site
input_variable.display_name = 'Example Variable'

# Tell Alfalfa that we want this variable to be exposed
register_input(input_variable)

At this point you can repeat step 4. and look at the example_model_measure_report_inputs.json file to confirm that the input is properly generated. At this point you can write to this point in Alfalfa but you can't read the value of it out of the model. The next step will walk through the process of adding an echo to an input so its value can be interrogated.

6. Adding an Echo to an Input

The below code shows how to add an echo to the point we created in step 5. so that we can get the value out of the site.

# Create an output which listens to the value of the input variable
output_variable = create_ems_output_variable(input_variable_ems_name)

# Set the output as the echo of the input.
input_variable.echo = output_variable

# Register the output with Alfalfa
register_output(output_variable)

At this point you should be able to run the model, write to the Example Variable input and see the value reflected in the Example Variable output.