ESP-r: A dynamic building performance simulation program. 1. ACKNOWLEDGMENTS ESP-r is developed by an international consortium as listed at www.esru.strath.ac.uk/Downloads/ESP-r/Contributors/list.html. System development and application is supported by a community mailing list. To subscribe, please follow the instructions at www.esru.strath.ac.uk/Programs/user_club.htm. 2. LICENSE ESP-r is free software made available in the hope that it will be useful but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. It can be redistributed under the terms of the GNU General Public License as published by the Free Software Foundation (version 2 or later) and available as part of the ESP-r distribution. 3. OBTAINING ESP-r. The system source files and, separately, a pre-compiled installation (for Ubuntu 18.04 LTS) are available as downloads from the applications page at www.esru.strath.ac.uk/research/energysystemsresearchunit/applications/esp-r. Prior to an installation from source code, you should ensure that a writable directory /opt/esp-r exists (possibly by creating a link named /opt/esp-r pointing to a directory esp-r elsewhere that you own. 4. SYSTEM REQUIREMENTS ESP-r has been successfully installed on Linux, Cygwin, MSYS2 and MAC OS X systems using different compiler and graphics library combinations. The native (and preferred) environment is Linux. Instructions for configuring Ubuntu 18.04 LTS for ESP-r are available at the above download page. 5. OPTIONAL FEATURES By default, the ESP-r simulation engine (bps) creates a binary results database that is post-processed using a separate tool (res). Bps can optionally export results in XML and CSV formats provided that the GNU libxml2 library is available. If the GNU libxslt library is also available, bps can be configured to translate XML results to a user-specified ASCII format. 6. INSTALLATION Installation of ESP-r from source code is managed by an 'Install' script, which is located in the top level directory of the source download. A distribution can be installed into any user-writable directory as defined above. Thereafter, follow the instructions in the 'Readme' file. The Install script will guide you through the installation and can be controlled via command line arguments. For more information run: $ sudo ./Install --help A complete installation based on the embedded defaults will result from: $ sudo ./Install while the following command will change the default installation directory and compiler family: $ sudo ./Install -d <installation path> --gcc4 ESP-r is able to work cooperatively with third party support tools, most notably gtool for 3D geometry definition and Radiance for lighting simulation. A list of support tools and their location for download is provided at the end of an installation. 7. RELEASE TESTING A release includes scripts that when run quantify the difference in in predictions with any prior release. Please consult the file 'tester_example_use.txt' in folder 'tester/scripts' for further information. 8. POST INSTALLATION CONFIGURATION On most Linux and Cygwin systems, the only post-installation configuration is to update the PATH environment variable to include the location of the installed ESP-r binaries. Run ESP-r by issuing the command 'ESP-r' in a terminal window. 9. DOCUMENTATION Publications describing the theory and operation of ESP-r are available on the publications page at the above Web site, while other resources (such as coding standards and learning materials) are available from the downloads page. 10. VALIDATION ESP-r has participated in a large number of validation projects and includes the ability (activated via the 'self check' option in the Project Manager) to automatically perform analytic and ASHRAE 140 BESTEST tests. 11. QUALITY ASSURANCE AND RELEASE TESTING Development of ESP-r continues, and its predictions are subject to change as new features are added and existing facilities improved. To guarantee the reliability of ESP-r results, a quality assurance procedure is performed prior to each release. 12. SUPPORT The quickest route to a remedy for an ESP-r installation or application problem is to ask for help on the ESP-r mailing list as described above. 13. MODIFYING THE SOURCE CODE Under the terms of the GPL lcence you are free to modify the source code in any way you require for your own use. Should you wish to make the modified version available to a third party, you must pass the changes to the central repository. To help with the quality assurance of updates, please register your intention to change the source with the ESP-r archivist, who will work with you to prevent problems arising from simultaneous code changes.