How to use Python EMS in Building Energy Modeling

Introduction

EnergyPlus is a whole building energy simulation program that models heating, cooling, lighting, ventilation, and other energy flows in buildings. It is widely used by researchers, engineers, architects, and policymakers to design and evaluate energy-efficient buildings and technologies. EnergyPlus is an open-source software that can be customized and extended by users to suit their specific needs.

EnergyPlus has a feature called Energy Management System (EMS) that allows users to write custom control logic and override certain aspects of the simulation. EMS uses a scripting language called Erl that is embedded in the EnergyPlus input file. Users can use EMS to implement complex or dynamic control strategies, such as demand response, predictive control, or adaptive comfort. However, Erl has some limitations, such as limited data structures, no external libraries, and no debugging tools.

Python EMS is a new feature that allows users to write EMS programs in Python instead of Erl. Python EMS uses an external Python interpreter to execute the EMS scripts, which are stored in separate files. Python EMS communicates with EnergyPlus via a socket connection, exchanging data and commands at each simulation timestep. Users can use Python EMS to access and modify the simulation variables, such as zone temperatures, setpoints, schedules, or outputs.

Python EMS opens up new possibilities for EnergyPlus simulations, as it allows them to interact with other simultaneously running models, weather forecasts, physical building equipment, and control hardware. Python EMS also enables users to leverage the Python ecosystem and its rich set of libraries and frameworks for various tasks and applications.

In this article, we will show you how to use Python EMS and what features it offers. We will explain how to set up Python EMS, how to write Python EMS scripts, how to run Python EMS simulations, and what results and outputs you can expect. We will also provide some examples and use cases to illustrate the potential and limitations of Python EMS.

 

Setting up Python EMS

To use Python EMS, you need to have the following requirements:

• A compatible version of EnergyPlus. Python EMS is available in EnergyPlus version 9.6 and later. You can download EnergyPlus from the official website or install it using a package manager, such as Conda or Homebrew.
• A compatible version of Python. Python EMS supports Python version 3.6 and later. You can download Python from the official website or install it using a package manager, such as Conda or Homebrew.
• A compatible version of PyEMS. PyEMS is a Python package that provides the interface between EnergyPlus and Python EMS. You can install PyEMS using pip, the Python package manager, by running the command pip install pyems in your terminal.

To set up Python EMS, you need to do the following steps:

• Create an EnergyPlus input file (.idf) that defines your building model and simulation settings. You can use any text editor or graphical user interface (GUI) tool to create and edit your input file. You can also use existing input files from the EnergyPlus example files or other sources.
• Add an ExternalInterface:FunctionalMockupUnitImport:To:Schedule object to your input file. This object tells EnergyPlus to use an external interface to update a schedule variable at each simulation timestep. You need to specify the name of the schedule variable, the initial value, the unit type, and the file name of the external interface. For example, you can add the following object to your input file:

• Create a Python EMS script (.py) that contains your custom control logic and overrides. You can use any text editor or IDE tool to create and edit your script file. You can also use existing script files from the PyEMS examples or other sources.
• Add an ExternalInterface:Python object to your script file. This object tells PyEMS to connect to EnergyPlus via a socket connection and exchange data and commands at each simulation timestep. You need to specify the host name, the port number, and the name of the schedule variable that you defined in your input file. For example, you can add the following object to your script file:

• Write your custom control logic and overrides in your script file using the PyEMS API functions and methods. You can use PyEMS API to get or set simulation variables, such as zone temperatures, setpoints, schedules, or outputs. You can also use PyEMS API to import and use other Python libraries and frameworks, such as NumPy, SciPy, or TensorFlow. For example, you can write the following code in your script file to implement a simple thermostat control logic:

• Save your input file and script file in the same folder.
• Run EnergyPlus with your input file and weather file as arguments. For example, you can run the following command in your terminal:

• Wait for EnergyPlus and Python EMS to finish their simulations and check their results and outputs.

Using Python EMS has several benefits for EnergyPlus users and developers. Python EMS offers more flexibility and customization than Erl, as it supports more data types, structures, and operations. Python EMS also enables users to leverage the Python ecosystem and its rich set of libraries and frameworks for various tasks and applications. Moreover, Python EMS facilitates the integration of EnergyPlus with other models, data sources, and hardware components, creating new opportunities for building energy simulation and analysis.

 

Writing Python EMS scripts

Python EMS scripts are Python files (.py) that contain the custom control logic and overrides for EnergyPlus simulations. Python EMS scripts use the PyEMS API functions and methods to communicate and interact with EnergyPlus via a socket connection. Python EMS scripts are executed by an external Python interpreter at each simulation timestep.

The structure and syntax of Python EMS scripts are similar to regular Python scripts, with some differences and conventions. A typical Python EMS script has the following structure:

• Import statements: These statements import the PyEMS package and other Python libraries or modules that are needed for the script. For example:

• Custom control logic and overrides: These are the statements that implement the custom control logic and overrides for EnergyPlus simulations. They use the PyEMS API functions and methods to access and manipulate the simulation variables, as well as other Python libraries or frameworks for various tasks and applications. For example:

The syntax of Python EMS scripts follows the standard Python syntax rules, with some exceptions and limitations. For example:

• The indentation of Python EMS scripts must be consistent and use four spaces per level.
• The comments of Python EMS scripts must start with a hash sign (#) and end with a newline character (\n).
• The names of simulation variables must match exactly with the names in EnergyPlus, including case sensitivity and spaces.
• The values of simulation variables must be compatible with their data types and units in EnergyPlus, such as real numbers, integers, or strings.
• The PyEMS API functions and methods must be called with the correct arguments and in the correct order, as specified in the PyEMS documentation.

Python EMS scripts can be written for different purposes and scenarios, depending on the user’s needs and preferences. For example, Python EMS scripts can be used to:

• Implement complex or dynamic control strategies, such as demand response, predictive control, or adaptive comfort.
• Co-simulate EnergyPlus with other simulation tools, such as Modelica, MATLAB, or Simulink.
• Use real-time or forecasted weather data from web services or sensors.
• Connect EnergyPlus to building automation systems or smart devices.
• Implement advanced control algorithms using Python libraries, such as NumPy, SciPy, or TensorFlow.

Python EMS scripts have several features that make them powerful and versatile for EnergyPlus simulations. Python EMS scripts can use:

• Data types: Python supports various data types, such as numbers, strings, lists, tuples, dictionaries, sets, and more. These data types can store different kinds of information and perform different kinds of operations on them.
• Structures: Python supports various structures, such as loops, conditional statements, functions, classes

 

Running Python EMS simulations

To run Python EMS simulations, you need to have the following files in the same folder:

• An EnergyPlus input file (.idf) that defines your building model and simulation settings, and includes an ExternalInterface:FunctionalMockupUnitImport:To:Schedule object.
• A Python EMS script file (.py) that contains your custom control logic and overrides, and includes an ExternalInterface:Python object.
• A weather file (.epw) that provides the weather data for your simulation location and period.
• A PyEMS FMU file (PyEMS.fmu) that provides the external interface between EnergyPlus and Python EMS. This file is automatically generated by PyEMS when you install it using pip.

To run Python EMS simulations, you need to do the following steps:

• Open a terminal window and navigate to the folder where your files are located.
• Run EnergyPlus with your input file and weather file as arguments. For example, you can run the following command in your terminal:

Ready to leverage the power of Python EMS for your building energy simulations? Connect with us to explore our specialized services today

• Building Energy Modeling
• energy simulation
• EnergyPlus
• Python

Share post: