Modelkit/Params Framework

Modelkit (formerly called Params) is a free and open-source, cross-platform framework for parametric modeling (Ellis 2015). Modelkit integrates two powerful concepts: templates and scripting. Templates are an old method for combining static content with dynamic inputs. Scripting is a relatively new method for automating the process of modeling.

We developed Modelkit to automate the generation and management of EnergyPlus models but it’s generic enough to be used with any simulation engine that accepts text-based input files.

By integrating templates and scripting, Modelkit makes it possible to create a highly-efficient and flexible workflow for generating building energy models for parametric analysis.

Features

When used with EnergyPlus, the Modelkit framework includes the following major features:

Access to all of the capabilities and power of EnergyPlus
Works directly with IDF objects; no special API to learn
Nearly unlimited flexibility for configuring templates
Comprehensive library of EnergyPlus templates
“Baked-in” energy-efficiency measures
Easy-to-learn syntax accessible to non-programmers
Full-featured, modern scripting language via Ruby
Optimized for version control and collaboration
Direct replacement for EPMacro and DOE-2 macros.

Applications

Modelkit is suited for a number of building energy modeling applications:

Comparison of baseline versus proposed models
Comparison of multiple model cases
Parametric sweeps of inputs
Swapping out entire HVAC systems
Prototype model analysis and research
Market sector analysis of multiple building types and climates.

Modelkit has been used with the following simulation engines and tools:

EnergyPlus
CBECC-Com
California Simulation Engine (CSE)
CBECC-Res.

Documentation

Currently, our best documentation is a video recording of a webinar demo/tutorial from November 2018. The different topics discussed with their timestamp in the video are:

Presentation slides explaining Modelkit’s scripting and template framework (0:30)
Demonstration covering the net zero templates included in the Modelkit Catalyst installation that are applied across projects (17:55)
Demonstration covering the project-specific templates provided in the ‘simple-project’ example folder included in the Modelkit Catalyst installation (21:25)
Demonstration covering the Modelkit batch scripts that compose and run EnergyPlus files (31:25)
Demonstration covering the Modelkit Excel tool that enables parametric analysis in a spreadsheet (43:20)

You can also check out a series of short tutorial videos on YouTube.

Background

We began developing Modelkit in 2010 as an in-house software tool to automate a parametric analysis for the US Army Corps of Engineers (USACE). The project (Liesen et al. 2012) required us to generate and run EnergyPlus models for two building types across 15 climate zones and 14 energy-efficiency measures. By 2011, USACE drafted us into a multi-year project to help them develop a web-based computational platform called Net Zero Planner (NZP) (Case et al. 2014)–now rebranded as System Master Planning Tool (SMPL). Created as a decision-making aid for Army planners and energy managers, the SMPL/NZP platform provides a web-based graphical interface that allows users to model energy, water, and waste scenarios for hundreds of buildings at Army bases and installations.

Today we continue to work with USACE to develop and maintain Modelkit as one component of the overall SMPL/NZP technology stack. Modelkit accepts an XML input file specifying prototype model type, weather file, and a set of high-level parameter values. It automatically generates an EnergyPlus model from the parameter values and then runs the simulation with the weather file. When complete, it post-processes the energy results into an XML output file that can be parsed by the SMPL/NZP platform where the data are aggregated across the installation. The framework also uses an XML definition file that configures parameter inputs–according to climate zone–for energy code standards, predefined energy-efficiency measures, and predefined packages of measures.

Parametric Modeling Framework

Parametric analysis is an essential technique for building energy modeling. Almost every modeling project comes down to varying input parameters and studying the differences in results. Even the comparison of a baseline model to a proposed model is about changing multiple parameters to evaluate the effect.

The Modelkit framework is composed of a parametric templating system and a comprehensive library of EnergyPlus templates. The templates are plain-text files that consist of standard EnergyPlus input file (IDF) syntax “marked up” or parameterized with dynamic content in the Ruby scripting language. Because the templates are mostly made up of IDF objects, the templates can be readily modified and extended by modelers and other non-programmers.

Ruby is a full-featured, modern programming language that allows nearly unlimited flexibility for configuring and connecting templates. Yet it has a simple, easy-to-learn syntax that makes everyday template tasks as straightforward as programming an Excel spreadsheet macro. Templates can be parameterized with any number of inputs.

Modelkit offers several advantages compared to other parametric tools that are currently available. Modelkit does not require a knowledge of an extensive API or object-oriented programming structures. Modelkit only requires a basic understanding of programming concepts such as math operations, if-then logic, and looping with arrays. Modelkit is also more capable than other tools because it provides full access to all of the features and power of EnergyPlus. Perhaps the greatest strength of Modelkit is that it makes it easy to swap out entire HVAC systems parametrically in a model.

Template Library

The Modelkit framework includes a template library that we have developed for EnergyPlus. The library includes ready-to-use templates for space loads, zone HVAC equipment, central HVAC systems, and more. They include parameters for many common energy-efficiency measures “baked in” to the templates. They are designed to be modular and completely reusable from project to project. The template library has been developed and refined by Big Ladder and our clients over numerous modeling projects. The templates encapsulate a significant body of knowledge with respect to modeling best practices in EnergyPlus.

NOTE: Modelkit templates are distinct from the HVACTemplate input objects that are available in EnergyPlus. The rules that generate the HVACTemplate output are hard coded and compiled into an executable program. The actual source for HVACTemplate objects cannot be viewed or changed by the user. Modelkit, on the other hand, is based on true text-based templates that can be viewed and modified by the user.

Prototype Models

Through our ongoing work with the US Army Corps of Engineers, we have developed 34 prototype building models in Modelkit format for the SMPL/NZP project (Case et al. 2014). The prototype models include 14 Army building types, 16 commercial building types, and 4 residential building types. The commercial models are derived from the Commercial Reference Buildings developed by NREL and PNNL.

All of our prototype models are fully parameterized for common modeling inputs. Available parameters include:

Wall details (assembly type, cavity and continuous insulation R-values)
Roof details (assembly type, cavity and continuous insulation R-values)
Slab/basement details (horizontal/vertical insulation widths/depths and R-values)
Window details (U-value, SHGC)
Infiltration (air leakage rate, air leakage schedule, use of vestibules)
Occupancy (people densities and schedules by space type)
Lighting (lighting power densities and schedules by space type)
Equipment (equipment power densities and schedules by space type)
Domestic hot water (flow rates, temperatures, schedules)
Zone HVAC (unit type - ATU, FCU, PTAC, PTHP, Win AC, WSHP, VRF, UH, radiant)
Zone HVAC operation (thermostat setpoints, setback/setup schedule, outdoor air)
Zone HVAC performance (fan/heat/cool efficiencies)
Central HVAC (system type - VAV, CAV, DOAS, HW, CHW, VRF, dual duct)
Central HVAC operation (schedule, outdoor air, supply setpoints, controls)
Central HVAC performance (fan/pump efficiencies, heating/cooling COPs)
And more…

The models also include “baked-in” energy-efficiency measures. In addition to the efficiency measures that can be applied by changing a single parameter (e.g., lighting power density, fan efficiency, or chiller COP), there are parameters that act as “switches” to make larger changes to the model in order to simulate measures such as fan/pump type (constant vs. variable speed), boiler type (non-condensing vs. condensing), condenser type (air-cooled vs. water-cooled), daylighting controls, and even different HVAC system types.

Noteworthy Projects

We have successfully used the Modelkit framework on a number of noteworthy projects to perform parametric analyses across multiple building types and climate zones.

US Army Corps of Engineers, 2010. We performed a parametric analysis to assess the Army’s strategies for meeting the stringent requirements of the Energy Independence and Security Act of 2007. We modeled two building types (barracks and brigade headquarters) across 15 ASHRAE climate zones. For each building type and location we simulated 15-17 energy-efficiency measures including Passive House super insulation, dedicated outdoor air systems, and radiant heating and cooling. The barracks study was published by ASHRAE (Liesen et al. 2012).
National Renewable Energy Laboratory, 2011. We performed the energy modeling analysis for the K-12 school and grocery store editions of NREL’s Advanced Energy Retrofit Guide series (NREL 2012; 2013). We used the secondary school and supermarket models from the Commercial Reference Buildings models as the starting point for our Modelkit models. We simulated 24-27 energy-efficiency measures for the two building types across five climate zones.
US-based, independent, nonprofit electricity research entity, 2015. We performed a small parametric study to analyze the energy performance of VRF systems versus a baseline system across four building types (small office, medium office, primary school, and small hotel) and two building vintages (new and post-1980) in Kansas. We used our Modelkit versions of the Commercial Reference Building models.
US-based, independent, nonprofit electricity research entity, 2015. We performed a parametric study to analyze the energy performance of heat pump chiller systems versus a baseline system across five building types (hospital, large hotel, large office, secondary school, and dormitory) and two climate zones. We used our Modelkit versions of the Commercial Reference Building models.
US-based, electric utility organization, 2015. We worked as a subcontractor on a team to help perform a large-scale parametric analysis to develop interaction factors between lighting and HVAC for the Pacific Northwest region. We modeled 15 building types (14 from the Commercial Reference Building models plus a new one) across 9 climates and 2 building vintages (old and new) with several lighting options. We used our Modelkit versions of the Commercial Reference Building models with building stock and operation inputs drawn from NEAA data. We also developed a new prototype model for residential care facilities for the elderly.

References

Case, M.; Liesen, R.; Zhivov, A.; Swanson, M.; Stinson, J. 2014. “A Computational Framework for Low Energy Community Analysis and Optimization”, NY-14-011, ASHRAE Transactions, Volume 120, Part 1. Atlanta, GA: ASHRAE.

Ellis, P. 2015. “Parametric Modeling with Templates and Scripting”, Presentation at 2015 ASHRAE Energy Modeling Conference, Sep. 30 - Oct. 2, 2015, Atlanta, GA.

Ellis, P. 2016. “A Parametric Tool for Community-Scale Modeling”, Proceedings of SimBuild 2016, ASHRAE and IBPSA-USA National Conference, Salt Lake City, UT, August 8-12, 2016.

Liesen, R.; Ellis, P.; Zhivov, A.; Herron, D. 2012. “Extremely Low Energy Design for Army Buildings: Barracks”, CH-12-008, ASHRAE Transactions, Volume 118, Part 1. Atlanta, GA: ASHRAE.

NREL. 2012. Advanced Energy Retrofit Guide: Practical Ways to Improve Energy Performance, Grocery Stores. Building Technologies Program (BTP). 212 pp.; NREL Report No. BK-5500-54243; DOE/GO-102012-3655.

NREL. 2013. Advanced Energy Retrofit Guide: Practical Ways to Improve Energy Performance, K-12 Schools. Energy Efficiency & Renewable Energy (EERE). 214 pp.; NREL Report No. BK-5500-60913; DOE/GO-102013-4333.