EnergyPlus How To

EnergyPlus supports interfacing with external software through its ExternalInterface module. It natively supports the Functional Mockup Interface for input and export, as well as the Building Controls Virtual Testbed. Our FNCS integration with EnergyPlus also takes advantage of the ExternalInterface module, so if you are familiar with using these products then the transition to FNCS will be smooth.

Getting the Code

We maintain a fork of EnergyPlus in our FNCS github project page. EnergyPlus releases are tagged, e.g., v8.3.3, v8.6.0. For many tagged releases, we add our FNCS patches via a new branch based on the released tags. For example, for tag v8.3.0, we add the branch fncs-v8.3.0. To see a list of the releases containing FNCS modifications, search the branches of our E+ fork using the "fncs" prefix. Once you have cloned our fork of E+, make sure you check out one of our modified release branches. For example:

git clone https://github.com/FNCS/EnergyPlus.git
cd EnergyPlus
git checkout fncs-v8.3.0

Known Versions

Version 8.3.0 is known to work. Version 8.3.1 is known to fail. For some reason it doesn't wait for the "Warming up" phase to complete before starting the co-simulation.

Building on Linux

The easiest way to build E+ on Linux is to make sure your PKG_CONFIG_PATH points to appropriate install location for FNCS and its dependencies. FNCS depends on ZeroMQ and CZMQ. See our other wiki page for instructions on building FNCS and its dependencies, though try to use the most up-to-date versions of each software package. For example, if you install all sofwtare to --prefix=$HOME/local_fncs, then set your PKG_CONFIG_PATH to $HOME/local_fncs/lib/pkgconfig.

You will use CMake to build and install E+. Start by creating a build directory, mkdir build, from within the E+ sources you cloned earlier. From within the build directory, run cmake ... Assuming your PKG_CONFIG_PATH points to where FNCS is installed, you should see output indicating the successful locating of FNCS and its dependencies. If you need to update any configuration values, we recommend using ccmake .. for the GUI (ncurses) version of CMake. Once configuration has succeeded, run make to begin the build. The make install target will copy the energyplus binary and some other files to your install location. We find that this often misses important files such as the Energy+.idd file and the various weather files, so you will likely find missing files within the build directory, e.g., EnergyPlus/build/Products/Energy+.idd, or within the source directory, e.g., EnergyPlus/weather, EnergyPlus/testfiles.

Running a Test

Let's walk through using the test file EnergyPlus/testfiles/_ExternalInterface-variable.idf. Copy this file to your current working directory for ease of use. You must edit only one line of the IDF file. It looks like:

  ExternalInterface,
    PtolemyServer;           !- Name of External Interface

Replace PtolemyServer with FNCS. You're done with this file and half way to running E+ with FNCS.

FNCS simulators require a configuration file. See this page for details. Due to the use of spaces in variable names, we recommend using the YAML format; otherwise you must replace any spaces with '+' because the original ZPL format does not support spaces.

Here is a sample, small config file to get you started. We named it fncs.yaml.

name: ep1
time_delta: 10m

Notice that our time delta is 10 minutes. That corresponds to the Timestep,6; line in the IDF file indicating 6 divisions of an hour (10 minutes) will be the time step used.

This IDF file requires a weather file and the Energy+.idd file. The weather file is EnergyPlus/weather/USA_IL_Chicago-OHare_TMY2.epw. We copied both files to the current directory to make launching a bit easier. Here is how we ran E+ with FNCS.

FNCS_CONFIG_FILE=fncs.yaml ./energyplus -w ./USA_IL_Chicago-OHare_TMY2.epw ./_ExternalInterface-variable.idf