How to use EnergyPlus API in Building Energy Modeling
EnergyPlus is a widely used building energy simulation software that can model the thermal, lighting, and ventilation performance of buildings. However, using EnergyPlus can be challenging for some users, especially those who are not familiar with its input and output formats, or who want to customize or extend its capabilities. That is why EnergyPlus API was developed: to provide a flexible and user-friendly interface for interacting with EnergyPlus.
EnergyPlus API is a software library that allows users to access and manipulate EnergyPlus data and functions through various programming languages, such as Python, C++, or Java. With EnergyPlus API, users can create, modify, and run EnergyPlus models, as well as analyze and visualize the simulation results, without having to deal with the low-level details of EnergyPlus input and output files. EnergyPlus API also enables users to integrate EnergyPlus with other tools and platforms, such as optimization algorithms, machine learning frameworks, or web applications.
The main objective of this article is to show how to use EnergyPlus API and what features it offers. We will demonstrate how to install and configure EnergyPlus API, how to create and run a simple EnergyPlus model using Python, how to access and modify the model parameters and variables, how to perform sensitivity analysis and optimization using EnergyPlus API, and how to use some of the advanced features of EnergyPlus API, such as co-simulation, functional mock-up interface (FMI), and external interface (EI). By the end of this article, you should have a good understanding of how to use EnergyPlus API for your own building energy simulation projects.
Setting up EnergyPlus API
Before using EnergyPlus API, you need to make sure that you have the following requirements:
-A compatible version of EnergyPlus installed on your system. You can download the latest version of EnergyPlus from https://energyplus.net/downloads. EnergyPlus API supports EnergyPlus versions 9.5 and above.
-A programming language that can interface with EnergyPlus API. Currently, EnergyPlus API supports C++, Python, Java, and C#. You can use any of these languages to create and run EnergyPlus models using EnergyPlus API. You also need to install the corresponding compiler or interpreter for your chosen language.
-A development environment that can work with EnergyPlus API. You can use any integrated development environment (IDE) or text editor that supports your chosen language, such as Visual Studio, Eclipse, PyCharm, or VS Code. You also need to configure the IDE or editor to link with the EnergyPlus API library and include the necessary header files.
The steps for setting up EnergyPlus API vary depending on the language and platform you are using. Here are some examples of how to install and configure EnergyPlus API for different languages:
-For C++, you need to download the EnergyPlus API library file (libenergyplusapi.so or libenergyplusapi.dll) and the header file (energyplus.hh) from https://github.com/NREL/EnergyPlus/releases/tag/v9.5.0-API. You also need to download the EnergyPlus data dictionary file (Energy+.idd) from https://github.com/NREL/EnergyPlus/blob/v9.5.0/idd/Energy+.idd. You need to place these files in a folder that is accessible by your compiler and linker, such as the same folder as your source code or a system library folder. You also need to add the folder path to the compiler and linker options, such as -I and -L for GCC or /I and /LIBPATH for MSVC. You can then include the header file in your source code using #include “energyplus.hh” and link with the library file using -lenergyplusapi for GCC or energyplusapi.lib for MSVC.
-For Python, you need to install the energyplus package using pip or conda. You can do this by running pip install energyplus or conda install -c conda-forge energyplus in your terminal or command prompt. This will install the energyplus module and its dependencies, such as numpy and pandas, on your system. You also need to download the EnergyPlus data dictionary file (Energy+.idd) from https://github.com/NREL/EnergyPlus/blob/v9.5.0/idd/Energy+.idd and place it in a folder that is accessible by your Python interpreter, such as the same folder as your script or a system library folder. You can then import the energyplus module in your script using import energyplus.
-For Java, you need to download the EnergyPlus API jar file (energyplus-api-9.5.0.jar) and the JNI library file (libenergyplusapijni.so or libenergyplusapijni.dll) from https://github.com/NREL/EnergyPlus/releases/tag/v9.5.0-API. You also need to download the EnergyPlus data dictionary file (Energy+.idd) from https://github.com/NREL/EnergyPlus/blob/v9.5.0/idd/Energy+.idd. You need to place these files in a folder that is accessible by your Java compiler and runtime, such as the same folder as your source code or a system library folder. You also need to add the folder path to the classpath and library path options, such as -cp and -Djava.library.path for javac and java commands. You can then import the energyplus package in your source code using import energyplus.*;
-For C#, you need to download the EnergyPlus API dll file (EnergyPlusAPI.dll) and the wrapper dll file (EnergyPlusWrapper.dll) from https://github.com/NREL/EnergyPlus/releases/tag/v9.5.0-API. You also need to download the EnergyPlus data dictionary file (Energy+.idd) from https://github.com/NREL/EnergyPlus/blob/v9.5.0/idd/Energy+.idd. You need to place these files in a folder that is accessible by your C# compiler and runtime, such as the same folder as your source code or a system library folder. You also need to add a reference to the dll files in your project settings or using the /r option for csc command. You can then import the EnergyPlus namespace in your source code using using EnergyPlus;
By using EnergyPlus API, you can enjoy several benefits, such as:
-Performance: EnergyPlus API allows you to run EnergyPlus simulations faster and more efficiently than using the command line or the graphical user interface (GUI). EnergyPlus API also supports parallel and distributed simulations, which can further improve the performance and scalability of your simulations.
-Flexibility: EnergyPlus API gives you more control and flexibility over your EnergyPlus models and simulations. You can create, modify, and run EnergyPlus models programmatically, without having to deal with the input and output files. You can also access and manipulate the model parameters and variables, such as schedules, weather data, outputs, and internal variables, using EnergyPlus API functions. You can also use EnergyPlus API to perform various tasks, such as sensitivity analysis, optimization, calibration, validation, or uncertainty quantification, using your own algorithms or libraries.
-Interoperability: EnergyPlus API enables you to integrate EnergyPlus with other tools and platforms, such as optimization algorithms, machine learning frameworks, or web applications. You can use EnergyPlus API to communicate and exchange data with other software components, such as co-simulators, functional mock-up units (FMUs), or external interfaces (EIs). You can also use EnergyPlus API to create your own custom applications or interfaces for EnergyPlus, such as graphical user interfaces (GUIs), dashboards, or web services.
Writing EnergyPlus API programs
EnergyPlus API programs are programs that use the EnergyPlus API library to create and run EnergyPlus models and simulations. The structure and syntax of EnergyPlus API programs depend on the programming language you are using, but they generally follow these steps:
-Import the EnergyPlus API library or module in your source code.
-Create an EnergyPlus API object that represents an instance of EnergyPlus.
-Set the simulation parameters, such as the weather file, the output variables, and the simulation options, using the EnergyPlus API object methods.
-Create an EnergyPlus model using the EnergyPlus API object methods. You can either load an existing EnergyPlus input file (IDF) or create a new model from scratch using the EnergyPlus data dictionary (IDD).
-Run the simulation using the EnergyPlus API object methods. You can either run the simulation synchronously or asynchronously, depending on your needs.
-Retrieve and analyze the simulation results using the EnergyPlus API object methods. You can access the output variables, the error messages, and the internal variables of EnergyPlus.
-Close the EnergyPlus API object and release the resources.
Here are some examples of how to write EnergyPlus API programs for different purposes and scenarios:
-To run a simple simulation of a pre-defined model and print the output variables to a CSV file, you can use this Python code:
-To create a new model from scratch and run an optimization algorithm to find the optimal insulation thickness for a wall, you can use this C++ code:
Running EnergyPlus API simulations
After creating an EnergyPlus API object and setting up the model and the simulation parameters, you can run the simulation using the EnergyPlus API methods. The process and options for running EnergyPlus API simulations depend on the programming language you are using, but they generally follow these steps:
-Call the run or run_async method of the EnergyPlus API object to start the simulation. The run method runs the simulation synchronously, which means that it blocks the execution of your program until the simulation is finished. The run_async method runs the simulation asynchronously, which means that it returns immediately and allows your program to continue while the simulation is running in the background. You can use the run_async method if you want to run multiple simulations in parallel or if you want to perform other tasks while the simulation is running.
-If you use the run_async method, you can check the status and progress of the simulation using the is_running and get_progress methods of the EnergyPlus API object. The is_running method returns a boolean value indicating whether the simulation is still running or not. The get_progress method returns a float value between 0 and 1 indicating the percentage of completion of the simulation.
-When the simulation is finished, you can retrieve and analyze the results and outputs using the EnergyPlus API methods. You can access the output variables, the error messages, and the internal variables of EnergyPlus using the get_output_variables, get_error_messages, and get_internal_variable methods of the EnergyPlus API object. You can also access the output files, such as the eplusout.eso, eplusout.err, eplusout.mtr, and eplusout.sql files, using the get_output_file_path method of the EnergyPlus API object. You can also access the log messages of EnergyPlus using the get_log_messages method of the EnergyPlus API object.
Here are some examples of how to run EnergyPlus API simulations with different settings and parameters:
-To run a simple synchronous simulation and print the output variables to a CSV file, you can use this Python code:
-To run an asynchronous simulation and monitor its progress, you can use this C++ code:
-To run a simulation with custom callbacks and plugins, you can use this Java code:
Conclusion
In this article, we have shown how to use EnergyPlus API and what features it offers. We have demonstrated how to set up EnergyPlus API for different programming languages, how to write EnergyPlus API programs for different purposes and scenarios, and how to run EnergyPlus API simulations with different settings and parameters. We have also highlighted the results and outputs of EnergyPlus API simulations, such as variables, files, and logs, and how to access and manipulate them using EnergyPlus API methods.
Using EnergyPlus API has several advantages, such as:
-Performance: EnergyPlus API allows you to run EnergyPlus simulations faster and more efficiently than using the command line or the graphical user interface (GUI). EnergyPlus API also supports parallel and distributed simulations, which can further improve the performance and scalability of your simulations.
-Flexibility: EnergyPlus API gives you more control and flexibility over your EnergyPlus models and simulations. You can create, modify, and run EnergyPlus models programmatically, without having to deal with the input and output files. You can also access and manipulate the model parameters and variables, such as schedules, weather data, outputs, and internal variables, using EnergyPlus API functions. You can also use EnergyPlus API to perform various tasks, such as sensitivity analysis, optimization, calibration, validation, or uncertainty quantification, using your own algorithms or libraries.
-Interoperability: EnergyPlus API enables you to integrate EnergyPlus with other tools and platforms, such as optimization algorithms, machine learning frameworks, or web applications. You can use EnergyPlus API to communicate and exchange data with other software components, such as co-simulators, functional mock-up units (FMUs), or external interfaces (EIs). You can also use EnergyPlus API to create your own custom applications or interfaces for EnergyPlus, such as graphical user interfaces (GUIs), dashboards, or web services.
However, using EnergyPlus API also has some limitations, such as:
-Compatibility: EnergyPlus API only supports EnergyPlus versions 9.5 and above. If you want to use older versions of EnergyPlus, you need to use the command line or the GUI instead of the API.
-Documentation: EnergyPlus API is still under development and its documentation is not very comprehensive or up-to-date. You may need to refer to the source code or the examples to understand how to use some of the features or functions of the API.
-Debugging: EnergyPlus API does not provide a built-in debugger or a graphical interface for debugging your models or simulations. You may need to use external tools or libraries to debug your code or to trace the errors or warnings reported by EnergyPlus.
Here are some recommendations and tips for using EnergyPlus API effectively and efficiently:
-Use the appropriate programming language for your needs. Each programming language has its own strengths and weaknesses in terms of performance, readability, usability, and compatibility. Choose the language that suits your preferences and requirements best.
-Use the asynchronous mode for running multiple or long simulations. The asynchronous mode allows you to run simulations in parallel or in the background without blocking your program execution. This can save you time and resources when running multiple or long simulations.
-Use the callbacks and plugins for customizing your simulations. The callbacks and plugins allow you to interact with EnergyPlus during the simulation process and to access or modify its internal functionality and data. This can give you more flexibility and control over your simulations.
-Use the output files and logs for analyzing your results. The output files and logs contain valuable information about your simulation results, such as output variables, error messages, internal variables, log messages, etc. You can use them to analyze your results or to troubleshoot your problems.
We hope that this article has helped you learn how to use EnergyPlus API and what features it offers. We encourage you to try it out for yourself and explore its possibilities. Happy simulating!😊
If you are interested in building energy modeling and want to learn more about how to use EnergyPlus API and other tools, you can visit our website. We offer a variety of services and solutions for building energy modeling, such as training, support, development, or integration. We can help you create, run, and analyze your models and simulations, as well as optimize your design and performance. Whether you are a beginner or an expert, we can provide you with the best service and guidance for your needs. Contact us today and let us know how we can help you.
