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.
When used with EnergyPlus, the Modelkit framework includes the following major features:
Modelkit is suited for a number of building energy modeling applications:
Modelkit has been used with the following simulation engines and tools:
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:
You can also check out a series of short tutorial videos on YouTube.
Parametric Modeling Framework
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 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.
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.
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:
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.
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.
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.