Root Api Documentation

class api.EnergyPlusAPI(running_as_python_plugin: bool = False)

Bases: object

This class exposes the EnergyPlus C Library API to Python. The API is split into three categories, and this class exposes each API category through member variables. If an instance of this class is created as api = EnergyPlusAPI(), then the following members are available:

• api.functional: The functional API provides access to static API calls, such as thermophysical property methods.

• api.runtime: The runtime API allows a user to provide Python functions as callbacks, which are then called from within EnergyPlus at specific points in the simulation.

• api.exchange The data_exchange API allows a user to exchange data (get sensor values, set actuator values) from within runtime callback methods, during a simulation. When this class is instantiated for Python Plugin use, this also exposes the plugin global data members to allow sharing data between plugins.

In a makefile-style build, the API library (dll) should be in Products; for example: /path_to_build/Products. For Visual Studio, the DLL is inside of a Debug or Release folder inside that Products directory. At build time, the cmake/PythonSetupAPIinBuild.cmake script is executed (the energyplusapi target depends on it). At build time, the Python API files are placed inside of the Products directory on Makefile builds, and copied into both the Release and Debug folders on Visual Studio builds. The API scripts are put into a pyenergyplus directory, so in all cases, the dynamic library will simply be in the current script’s parent directory. In an installation, the library will be in the installation root, and the Python API files will be in a pyenergyplus directory inside that install root as well, so the binary will again just be in this script’s parent directory.

For either case, utilizing the Python API wrappers is straightforward: if executing from directly from the build or install folder, scripts can be imported as from pyenergyplus.foo import bar. If executing from a totally separate directory, the build or install directory can be inserted into the beginning of sys.path so that the pyenergyplus directory can be found.

To reference this in an IDE to allow writing scripts using autocomplete, etc., most IDEs allow you to add third- party library directories. The directory to add would be the build or install folder, as appropriate, so that the from pyenergyplus import statements can find a pyenergyplus package inside that third-party directory.

static api_version() → str

Returns a string representation of the version of this API. The EnergyPlus API will evolve over time, but in most cases, it will be simply adding new functionality and methods, not breaking existing API calls. The fractional portion of the API will be incremented when new functionality is added, and the whole number portion will be incremented when an existing API is broken. :return:

api.api_path() → str

This function returns a string to the EnergyPlus dynamic library. The energyplusapi target in the build system depends on the Python API build script, so you shouldn’t be able to generate the EnergyPlus dynamic library without these scripts being successfully set up in the build tree by CMake.

Returns

A string absolute path to the EnergyPlus DLL.