3. Installation and Configuration

This chapter describes how to install, configure and uninstall EnergyPlusToFMU.

3.1. Software requirements

To export an EnergyPlus simulation as an FMU, EnergyPlusToFMU needs:

1. Python 2.6, 2.7, or 3.x
2. A C compiler and linker.
3. A C++ compiler and linker.

EnergyPlusToFMU has been tested on:

• Linux Ubuntu 18.04.
• Windows 10.
• Mac OS X 10.15.

with Python 2.7, 3.7 and 3.8

Note

FMI for Co-Simulation version 2.0 is not supported on Linux 32 bit.

3.2. Installation

To install EnergyPlusToFMU, proceed as follows:

1. Download the installation file from the Download page.
2. Unzip the installation file into any subdirectory (hereafter referred to as the “installation directory”).

The installation directory should contain the following main subdirectories:

-bin/

(Script for running the unit tests)

-Documentation/

(Documentation files )

-Examples/

(Example files for testing)

• Scripts/ (Python scripts that create an FMU from an IDF file)

  • win/ (batch files for Windows)
  • linux/ (shell scripts for Linux)
  • darwin/ (shell scripts for Mac OS X)

• SourceCode/

  (C and C++ source code for creating an EnergyPlus FMU)

  • fmu-export-prep-shared/
  • read-ep-file/
  • socket/
  • utility/
  • v10/EnergyPlus/
  • v20/EnergyPlus/

3.3. Configuration

EnergyPlusToFMU comes pre-configured to handle the most common system configurations. Usually, you can simply create an FMU, as described in Creating an FMU, and everything will work.

The remainder of this section provides tips for configuring EnergyPlusToFMU to match your particular system and needs. This may be needed in case problems arise. In addition, you may wish to reconfigure EnergyPlusToFMU, for example to optimize the FMU code, or to change the memory model under which it runs.

3.4. Batch files

EnergyPlusToFMU requires a C compiler and linker (in order to build the FMU), and a C++ compiler and linker (in order to build supporting tools). Configuring EnergyPlusToFMU mainly consists of:

• Choosing a different compiler or linker than the default.
• Passing the compiler or linker different options than the default.

EnergyPlusToFMU controls both aspects of the configuration using batch files on Windows, and shell scripts on Linux and Macintosh. Batch files have the extension .bat, while shell scripts have the .sh extension. For convenience, this guide refers to all such files as batch files.

EnergyPlusToFMU includes the following batch files:

Batch (shell) file	Purpose
compile-c.bat	Compiles a C source code file into an object file.
link-c-exe.bat	Links object files, generated by the C compiler, into an executable (i.e., a stand-alone application).
link-c-lib.bat	Links object files, generated by the C compiler, into a shared or dynamic link library.
compile-cpp.bat	Compiles a C++ source code file into an object file.
link-cpp-exe.bat	Links object files, generated by the C++ compiler, into an executable (i.e. a stand-alone application).
test-c-exe.bat	Automates a test of batch files compile-c.bat and link-c-exe.bat.

The EnergyPlusToFMU installation includes default versions of these batch files. However, the contents of these batch files depends on:

1. The operating system.
2. The compiler/linker environment (e.g., gcc or Microsoft Visual Studio).
3. The options desired (e.g., a 32-bit or 64-bit FMU).

As shown above, the installation directory contains a batch subdirectory for each of the supported platforms. Therefore to configure your system, you should first identify the appropriate subdirectory.

Note that Python detects your platform when it runs. Therefore if you are using an emulator or virtual machine (for example, Cygwin under Windows, or a Windows virtual machine on a Mac), you should look in the subdirectory corresponding to the emulated operating system.

Each system-specific batch subdirectory includes sample batch files. In addition to the default versions, some alternate versions also may be present. The alternate versions can be identified in two ways:

1. The file extension is “.txt”, rather than “.bat” (or “.sh”).
2. The file name indicates the associated options. For example, a file compile-c-gcc-32bit.txt is one possible version of compile-c.sh. It is specific to the gcc compiler/linker environment, and it generates 32-bit object files, even on a 64-bit operating system.

Note that the default batch file is an exact copy of one of the supplied alternate versions. For example, in the win subdirectory, the default batch file compile-c.bat is the same as compile-c-mvs10.txt (the version for Microsoft Visual Studio 10).

Once you have identified the appropriate batch file subdirectory, you can either:

• Test the existing batch files to determine whether a 32-bit or 64-bit FMU will be created. See Running a basic test.
• Modify the existing files, according to your particular needs. See Modifying the batch files.

3.5. Running a basic test

In addition to the batch files that run the compiler and linker, EnergyPlusToFMU includes a batch file that tests some of the existing batch files. In particular, batch file test-c-exe.bat tests the compiler and linker batch files which build an executable from C source code. Once these batch files work, it should not be difficult to make the other compiler and linker batch files work.

The batch file test-c-exe.bat runs the appropriate compiler and linker batch files, and tests the resulting executable. It reports its progress, and so should give information as to where problems occur, if any.

To run the basic test, open a command-line window (see Notation). Next, change to the appropriate batch file directory, and run the test batch file.

A sample session at the Windows DOS prompt:

# Change to the batch file directory.
> cd  epfmu_install_dir\Scripts\win

# Run the batch file.
> test-c-exe.bat
===== Checking for required files =====
===== Removing old output files =====
===== Running compiler =====
get-address-size.c
===== Running linker =====
===== Running output executable =====
== The address size, e.g., 32 or 64, should appear below ==
32
== The address size should appear above ==
===== Cleaning up =====

A sample session in a Linux command shell:

# Change to the batch file directory.
> cd  epfmu_install_dir/Scripts/linux

# Run the batch file.
# Note the "./" before the batch file name.
> ./test-c-exe.sh
===== Checking for required files =====
===== Removing old output files =====
===== Running compiler =====
===== Running linker =====
===== Running output executable =====
== The address size, e.g., 32 or 64, should appear below ==
32
== The address size should appear above ==
===== Cleaning up =====

A sample session in a MacOS Terminal window:

# Change to the batch file directory.
> cd  epfmu_install_dir/Scripts/darwin

# Run the batch file.
# Note the "./" before the batch file name.
> ./test-c-exe.sh
===== Checking for required files =====
===== Removing old output files =====
===== Running compiler =====
===== Running linker =====
===== Running output executable =====
== The address size, e.g., 32 or 64, should appear below ==
64
== The address size should appear above ==
===== Cleaning up =====

In the sessions shown above, the test batch file successfully ran to completion. If the test batch file fails at some point, then you will have to modify either the compiler or linker batch file, or possibly both. See Modifying the batch files.

The test batch file automates the individual steps described in Checking compile-c.bat and Checking link-c-exe.bat below. Therefore as you fine-tune your configuration, you may want to look to those sections for help.

3.6. Checking compile-c.bat

This section describes how to check the current version of batch file compile-c.bat. A later section describes checking link-c-exe.bat. Once these batch files work, it should not be difficult to make the other compiler and linker batch files work.

The check is to build and then run one of the EnergyPlusToFMU supporting applications. If the application builds and runs correctly, it reports whether your compiler generates 32-bit or 64-bit executables.

To check the compiler batch file, open a command-line window (see Notation). Next, change to the appropriate batch file directory, and run the compiler batch file. The compiler should produce an object file in the same directory.

A sample session at the Windows DOS prompt:

# Change to the batch file directory.
> cd  epfmu_install_dir\Scripts\win

# Run the batch file.
> compile-c.bat  ..\..\SourceCode\utility\get-address-size.c

# Check the object file.
> dir  *.obj
get-address-size.obj

A sample session in a Linux command shell:

# Change to the batch file directory.
> cd  epfmu_install_dir/Scripts/linux

# Run the batch file.
# Note the "./" before the batch file name.
> ./compile-c.sh  ../../SourceCode/utility/get-address-size.c

# Check the object file.
> ls  *.o
get-address-size.o

A sample session in MacOS Terminal:

# Change to the batch file directory.
> cd  epfmu_install_dir/Scripts/darwin

# Run the batch file.
# Note the "./" before the batch file name.
> ./compile-c.sh  ../../SourceCode/utility/get-address-size.c

# Check the object file.
> ls  *.o
get-address-size.o

In the sessions shown above, the compiler batch file successfully built the object file. Unfortunately, this is not always the case. Reasons for failure fall into a few broad categories:

• The commands in the batch file are wrong for your system. This is the most likely cause of failure. The subsections below give hints on providing an appropriate compile-c.bat batch file.
• You do not have permission to run the batch file. When you run the batch file, watch for output like “Permission denied” from the operating system. See Troubleshooting permissions below.
• The source code file is not on the specified path. When you run the batch file, watch for output like “No such file or directory”, along with the name of the source code file. Check the installation directory structure, as specified above.
• The compiler did not accept some statement in source code file get-address-size.c. In this case, please contact the EnergyPlusToFMU team to report the problem.

Successfully compiling get-address-size.c does not completely test the compiler batch files. In particular:

• The batch file compile-c.bat must specify whether or not your compiler/linker environment provides a function called memmove. The simple application being tested here does not use memmove, so this aspect of the compiler batch file is not checked. See Troubleshooting the memmove function below.
• The batch file compile-cpp.bat must be configured for the C++ language, rather than the C language. Often no particular changes are required compared to compile-c.bat See the sample batch files in the standard distribution.

3.7. Checking link-c-exe.bat

Once you have successfully compiled the source code file get-address-size.c into an object file, the next step is to link the object file into an executable.

Working in the same subdirectory where you built the object file, run the linker batch file. In response, the linker should produce an executable, called test.exe, which you should be able to run.

A sample session at the Windows DOS prompt:

# Run the batch file.
> link-c-exe.bat  test.exe  get-address-size.obj

# Check the executable.
> dir  *.exe
test.exe

# Run the executable (32-bit system).
> test.exe
32

A sample session for both a Linux command shell and MacOS Terminal:

# Run the batch file.
# Note the "./" before the batch file name.
> ./link-c-exe.sh  test.exe  get-address-size.o

# Check the executable.
> ls  *.exe
test.exe

# Run the executable (32-bit system).
> ./test.exe
32

Again, the batch file may not work, for a few reasons:

• The commands in the batch file are wrong for your system. The subsections below give hints on providing an appropriate link-c-exe.bat batch file. In particular, if the linker complains of not being able to find the standard library function printf, see Troubleshooting missing libraries below.
• You do not have permission to run the batch file. When you run the batch file, watch for output like “Permission denied” from the operating system. See Troubleshooting permissions below.

Successfully building test.exe does not completely test the linker batch files. In particular:

• The batch file link-c-lib.bat has an additional complication. This batch file must link objects into a shared library. Creating a shared library generally requires passing a special switch or flag to the linker, such as -shared, -dynamiclib, or /LD. See the documentation for your development environment.
• The batch file link-cpp-exe.bat must link objects generated by the C++ compiler. This may require changing the linker switches or flags used in link-c-exe.bat.
• Building test.exe uses a single object file. The linker batch file must be able to handle a list of object files. The provided batch files all do this correctly. Since proper behavior depends on the operating system, rather than on the linker, no problems should arise here.

In all cases, comparing the batch files provided by the EnergyPlusToFMU installation may help solve some of these problems.

3.8. Modifying the batch files

This section gives general advice for editing your batch files, in case the default versions do not work on your system, or in case you want to modify or replace the default versions (for example, to change the optimization level, or to use a different compiler/linker).

Unfortunately, it is beyond the scope of this document to give full instructions on installing and using developer tools such as compilers and linkers.

The EnergyPlusToFMU tools only use the batch files named in the table shown in subsection Batch files. Thus, editing compile-c-gcc.txt will have no effect on how the FMU gets created. Only compile-c.bat affects how EnergyPlusToFMU compiles C source code files.

If a batch file does not work, it may simply be a matter of changing the directory path hard-coded in the batch file. For example, the batch files for Microsoft Visual Studio list several known locations for finding the Visual Studio program files. If your machine has Visual Studio installed in some other location (say, on the “D:\” drive rather than on “C:\”), then editing the batch file to point to the correct path may be all that is needed.

On most systems, the compiler also can act as the linker (or call the linker, filling in appropriate options). Therefore once you have your system’s compiler working, try listing the same tool in the linker batch files.

If your compiler/linker environment comes with an integrated development environment (IDE), you often can use the IDE to determine appropriate flags for controlling the compiler and linker. For example, Microsoft Visual Studio is the standard IDE for Microsoft’s C/C++ compilers, and the configuration panels in Visual Studio show the flags corresponding to each option. Therefore if you are having problems compiling a source code file with a provided batch file, try using the IDE to compile that source code file, and check what options the IDE uses.

3.9. Finding a compiler/linker (Unix)

The following tips for finding the compiler/linker apply to Unix-like environments, including Linux and MacOS.

Unix-like environments often define cc as a link to the standard C compiler, and c++ as a link to the standard C++ compiler.

If you have a standard compiler on your search path, the which command will locate it. For example, entering the command:

> which gcc

will return the path to the gcc compiler, provided your system has it, and provided it is on the search path. Otherwise, which gcc will return nothing.

If you believe you have a certain compiler, but cannot find it on your search path, try the find command. For example, to locate the icc compiler, try:

> find /usr -name icc
> find /bin -name icc
> find /opt -name icc
> find / -name icc

The first three commands search specific directories that commonly contain developer tools (your system may not have all of these directories). The last command searches the entire directory tree (and may take quite a while).

The find command accepts wildcards. Put them in quote marks, in order to prevent the shell from operating on the wildcard. For example:

> find /usr -name "*icc*"

searches the /usr directory for any file whose name contains the string icc.

Finally, the apropos command may help:

> apropos compiler

will search your help files for information pertaining to compilers. Unfortunately, it may return many entries unrelated to compiling C and C++ source code.

3.10. Troubleshooting permissions (Unix)

Permissions problems arise on Unix-like systems. The batch files must have “execute” permission, meaning you are allowed to run the file as a set of commands. To check the permissions:

# Linux, MacOS:
> ls -lt  *.sh
-rwxr--r--  ...  link-c-lib.sh
-rwxr--r--  ...  link-cpp-lib.sh
-rwxr--r--  ...  link-c-exe.sh
-rwxr--r--  ...  compile-c.sh
-rwxr--r--  ...  link-cpp-exe.sh
-rwxr--r--  ...  compile-cpp.sh

All five of the default batch files should have “-rwx” at the beginning of the permissions block (indicating you are allowed to read, write, and execute the file). If not, then set the permissions:

# Linux, MacOS:
> chmod  u=rwx,g=r,o=r  *.sh

and try running the compiler batch file again.

3.11. Troubleshooting the memmove function

The batch file that runs the C compiler, compile-c.bat, needs to indicate whether or not your C compiler/linker environment provides a non-standard function called memmove. While memmove is non-standard in C, it is standard for C++. Therefore many C environments provide it as well.

If your C compiler/linker environment does provide memmove, then the batch file should pass the macro definition HAVE_MEMMOVE to the compiler. The included batch files show how to define a macro for various compilers.

If, on the other hand, your C compiler/linker environment does not provide memmove, then do not define the macro in the compiler batch file.

If you are not sure whether or not your system provides the function, simply watch for any errors while building your first FMU. If you fail to define HAVE_MEMMOVE when your system has it, the linker will complain about duplicate definitions of memmove. Conversely, if you define HAVE_MEMMOVE when your system does not have it, the linker will complain about not being able to find memmove.

3.12. Troubleshooting missing libraries

Some linkers need explicit instructions to link to library code. Libraries are needed to provide standard functions, such as printf, that are called by the EnergyPlusToFMU source code. If the linker emits an error message indicating it cannot find a particular function, then consult your development environment’s documentation to determine which libraries it may need.

Note that specifying libraries is often somewhat arcane. For example, on Unix-like systems, to link a library libm.a typically requires the linker flag -lm. Furthermore, the order in which libraries are linked can matter, and you may need to add another flag to indicate the path(s) where the linker should search for libraries.

3.13. UnitTests

The unittests use PyFMI to run the FMUs generated by the EneryPlusToFMU. To run the unittests, install PyFMI and the EnergyPlus version which will be used to export and run the unittests.

You can start the unittests from the installation bin folder with

> python runUnitTest.py

If EnergyPlus can’t be found on your system, the script will prompt you to provide the full path to the EnergyPlus installation directory (e.g. D:EnergyPlusV9-0-1)

3.14. Uninstallation

To uninstall EnergyPlusToFMU, delete the installation directory.