Adding Points with OpenStudio Measures - NatLabRockies/alfalfa GitHub Wiki

As of Alfalfa 1.0 and OpenStudio 3.9.0 the tools to expose model inputs and outputs have been added to OpenStudio. This document outlines the basic api structure and provides specific examples of common use-cases.

Accessing the OpenStudio Alfalfa JSON API

The OpenStudio runner object, which is passed to all measures when the run method is called, has access to the API via runner.alfalfa. This API provides the functions to expose constants, actuators, meters, output variables, and global variables as Alfafa Points. Class reference can be found here.

This API is accessible from from both model and EnergyPlus measures in Python and Ruby.

Exposing points with the Alfalfa JSON API

There are several ways to expose points via the Alfalfa JSON API.

Exposing from IdfObject or ModelObject

Calling alfalfa.exposeFromObject and passing in the object that represents the point you want to expose creates an AlfalfaPoint object and adds it to the JSON. Documentation of which object types are accepted can be found here.

Example

meter_object = # get meter object from OpenStudio
alfalfa_point = runner.alfalfa.exposeFromObject(meter_object, "Whole Building Electricity")

Exposing from Object Information

If you know an object exists in the model and you don't want to fetch it from OpenStudio you can directly expose a point from the Alfalfa JSON API by supplying the relevant information. This can be done for constants, actuators, meters, output variables and global variables. Documentation for each function can be found in the class reference.

Example

alfalfa_point = runner.alfalfa.exposeMeter("Electricity:Building")

Exposing from Alfalfa Components

Alfalfa Components allow fine grained control of how points behave. Each object type has a respective component type, see object list. Once a component is initialized it can be turned into a point by passing it into the exposeFromComponent function.

Example

meter_component = AlfalfaMeter("Electricity:Building")
alfalfa_point = runner.alfalfa.exposeFromComponent(meter_component)

Constants

Constant points are a special case. They are read only and have the value given to them by the Alfalfa JSON API. They can be used in cases where you may have additional information you want to be available through the Alfalfa API but doesn't fit into an existing OpenStudio object type. These can be used in any of the ways listed above.

Customizing AlfalfaPoints

Every expose function (with the exception of exposePoint) return an optional<AlflafaPoint> object. This will only be empty if they were improperly called. These objects have several properties to help control how they are presented in the Alfalfa API. Documentation can be found in the class reference.

Display Name

This property sets the human readable name that can be seen on the Alfalfa webpage and in the Alfalfa API.

Units

This property sets the units presented on the Alfalfa webpage and in the Alfalfa API.

Optional

A point can be set as optional if the underlying object may not exist in the model the point is being added to. If the object does not exist and the point is not set as optional it will cause the model to exit and throw an error. If it is set as optional Alfalfa will skip that point.

Input and Output

The input and output of an Alfalfa Point can be set independently to achieve desired behavior. For example, a point to control a zone setpoint can be setup such that the input controls an actuator and the output comes from the output variable reporting the zone's setpoint.