===========================================================

                         ESP-r

   A multi-domain building performance simulation program

Contents
--------

   1. Acknowledgments
   2. License
   3. Obtaining ESP-r
   4. System requirements
   5. Optional features
   6. Installation
   7. Post-installation configuration
   8. Documentation
   9. Validation
  10. Release testing 
  11. Support

===========================================================
1. ACKNOWLEDGMENTS

ESP-r is developed and distributed by the Energy Systems Research Unit
(ESRU) of the University of Strathclyde and Natural Resources Canada
(NRCan), in collaboration with researchers and practitioners around
the world.


Send inquiries to:

   Energy Systems Research Unit (ESRU)
   University of Strathclyde,
   James Weir Building
   75 Montrose Street
   Glasgow UK
   G1 1XJ

   http://www.esru.strath.ac.uk/
   [email protected]

ESP-r is also supported through a community mailing list.  To subscribe
to the list, visit:


   http://lists.strath.ac.uk/mailman/listinfo/esp-r

===========================================================
2. LICENSE

ESP-r is free software.  You can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, either version two of the License, or (at your
option) any later version.

ESP-r is distributed 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. See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License along
with ESP-r. If not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA 02111-1307 USA.


===========================================================
3. OBTAINING ESP-r.

ESP-r is distributed via version-controlled source code. The
GPL license encourages you to contribute any changes you made
back into the community.


Version-controlled source code
------------------------------
The ESP-r source code is stored on a publicly-accessible repository
at <https://github.com/ESP-rCommunity. To checkout the full repository
issue the following command:

git clone --recurse-submodules https://github.com/ESP-rCommunity/ESP-rSource.git ESP-rCentral

The download zip button may not include all of the documentation and
example models.

You can learn more about accessing the ESP-r repository here:

   http://www.esru.strath.ac.uk/Programs/ESP-r_central.htm

Assuming you have a folder structure in the form 
of /home/fred/Src/simulation  unzip the downloaded file 
within Src/simulation folder. You will also need a folder
for the compiled ESP-r. Lets assume this is /opt/esru
(create it if it does not exist). 

In the top folder is an Install script. For Linux, OSX and
Cywin and/or MSYS a typical set of commands to build ESP-r
is:
 ./Install -d /opt/esru --gcc4 --debug
 
Answer yes to installing the databases and example models.
more information about setting up computers and development
tool chains are found in the doc/manual/OS folders.


===========================================================
4. SYSTEM REQUIREMENTS

ESP-r has been installed Linux, Cygwin, MinGW and MAC
OS X systems, using a variety of compiler and graphics library
combinations.

While ESP-r has been built on all of the supported platforms and
configurations, it is most routinely used on Linux.  Installation on
common Linux distributions (including Ubuntu, Redhat/Fedora and
Gentoo) using the gcc 4 (gcc g++ gfortran) series of compiler 
suites has proven robust, and you can use it with confidence on 
these systems.  OSX is similar to Linux in the build process (see
the notes in the doc/manual/OS/Apple folder). ESP-r can also be 
build on Windows via Cygwin or MSYS2 (see the doc/manual/OS/Cygwin
or doc/manual/OS/Native_windows).

Some facilities of ESP-r use the Radiance lighting simulation
suite to carry out tasks. Radiance can be downloaded from
<radsite.lbl.gov/radiance/>. The release of July 2014 4.2
as rad4R2all.tar.gz works with ESP-r.


Architectures
-------------
ESP-r is presently supported on 32 and 64 bit systems.

 -----------------------------------------------------------
                      Linux   Cygwin  MSYS2    OS X
 ...........................................................
 32-bit                  S       S       S       S
 64-bit                  S       S       S       S
 -----------------------------------------------------------
 S = Stable
 B = Beta testing
 X = Not supported
 - = Not applicable

Compilers
---------
Compilation of ESP-r is presently supported with
the following compiler sets:
  - GCC 4.4 - 4.9 (gcc, g++ and gfortran)

Graphics libraries
------------------
Traditionally, ESP-r incorporated an X11-based graphical interface and
could also be built as a text-only shell application. Work is presently
underway to modernize the ESP-r interface using the GTK interface,
and GTK versions of ESP-r can be installed on all platforms provided
the GTK libraries are available.

 -----------------------------------------------------------
                      Linux   Cygwin  MinGW    OS X
 ...........................................................
 X11                    S       S      -       S
 GTK                    S       S      S       S
 no graphics            S       S      S       S
 -----------------------------------------------------------
 S = Stable
 B = Beta testing
 X = Not supported
 - = Not applicable

===========================================================
5. OPTIONAL FEATURES

XML & CSV output
----------------
By default, the ESP-r simulation engine (bps) writes out binary results
libraries that must be post-processed using a separate tool (res). bps
can also optionally export the results directly into ASCII XML and
comma-separated-value formats, provided the GNU libxml2 library is
available on the system.

If the GNU libxslt library is also available, bps can be configured to
translate the XML result file into any user- specified ASCII format.


===========================================================
6. INSTALLATION

Installation of ESP-r is managed through the 'Install'
script, which is located in the top level directory. ESP-r
can be installed into any user-writable directory.

The Install script provides interactive prompts to guide
you through the ESP-r installation, and also understands
a number of command line arguments. For more information,
run:

  $ ./Install --help


Local installations
-------------------

  1. Run the command:

          $ ./Install -d <path/to/esp-r> --gcc4

     Where <path/to/esp-r> describes the desired
     installation directory. For instance,
     './Install -d ~/my_esp-r' will install ESP-r
     in a directory called my_esp-r, in the user's
     home folder.

After installing ESP-r, be sure to update your PATH
environment variable as described below.

===========================================================
7. POST INSTALLATION CONFIGURATION

On most Linux and Cygwin systems, the only post-installation
configuration required is updating the path environment
variable to include the location of ESP-r binaries. 


Updating your PATH
------------------
You'll need to update your PATH environment variable to
include the location of your ESP-r binaries. The steps
required to configure your path depend on the shell in
use on your system. Enter the command:

  $ echo $SHELL

Configuration of the PATH environment variable using the
bash and csh shells are described below. Information on
setting environment variables for other shell types (e.g.,
sh, zsh, ksh) is available on the Internet.

  BASH:

      Append the following line to your .bashrc file in
      your home directory (or in the system's .bashrc file)

      export PATH="<path/to/esp-r>/esp-r/bin/:$PATH"

      (Where <path/to/esp-r> describes the location
      in which you installed ESP-r)

  CSH:

      Append the following line to your .cshrc file in
      your home directory (or in the system's .cshrc file):

      set path = ( <path/to/esp-r>/esp-r/bin/ $path )

      (Where <path/to/esp-r> describes the location
      in which you installed ESP-r)


Setting EFONTS environment variable
-----------------------------------
On most Linux and Cygwin systems, acceptable fonts are
located automatically at runtime. However, if you find
ESP-r crashes after invocation, you may need to set the
EFONTS environment variable. Include the following lines
in your .bashrc /.cshrc file

   setenv EFONT_0 6x12
   setenv EFONT_1 6x13
   setenv EFONT_2 8x13
   setenv EFONT_3 9x15

Default settings
----------------
The file <path/to/esp-r>/esp-r/default defines the default
settings for example problems, climate, control, etc. These
can be changed if the default settings offered in the
standard distribution are not appropriate for your site.


===========================================================
8. DOCUMENTATION

An extensive collection of books, academic theses,
peer-reviewed papers, reports and manuals describing the
theoretical basis and application of ESP-r are available.
A complete list of ESP-r documentation can be found on the
ESRU website:

   http://www.esru.strath.ac.uk/publications.htm

Theoretical basis
-----------------
  
  - "Energy Simulation in Building Design" by Joe Clark
    (Butterworth Heinemann 2001) provides a broad
    description of ESP-r methodologies.

Application of ESP-r
--------------------

  - "The ESP-r Cookbook"  describes the application of
    ESP-r in building simulation:
       
       ftp://ftp.strath.ac.uk/Esru_public/documents/esp-r_cookbook.pdf

  - "Data model summary ESP-r Version 9 Series" describes
    the  format of ESP-r's input files:

       ftp://ftp.strath.ac.uk/Esru_public/documents/ESP-r_data_doc.pdf

Developing with ESP-r
---------------------

  - "Structure of the ESP-r Source Code Archive"
    outlines the branch structure in use on ESP-r
    central, and procedures for merging code:

       ftp://ftp.strath.ac.uk/Esru_public/documents/repository.pdf

  - "An overview of Subversion for ESP-r Central
    Users" summarizes the use of subversion to
    access and maintain branches on ESP-r Central:
       
       ftp://ftp.strath.ac.uk/Esru_public/documents/subversion.pdf

  - "ESP-r Coding Guide" provides guidelines for
    modifying ESP-r source code:

       ftp://ftp.strath.ac.uk/Esru_public/documents/coding_guide.pdf

  - "ESP-r Developers' Quality Assurance Checklist"
    prescribes testing procedures for contributers:

       ftp://ftp.strath.ac.uk/Esru_public/documents/QA_checklist.pdf

===========================================================
9. VALIDATION

ESP-r has been extensively validated both through comparison
to other simulation programs, and comparison to experimental
data. An overview of ESP-r validation studies is available
at the following URL:

    http://www.esru.strath.ac.uk/Documents/validation.pdf

In addition, ESP-r includes an option to automatically
perform the IEA BESTEST/ASHRAE 140 and CEN validation tests,
and report these results. You can exercise these tests
by clicking on the 'validation' option in prj.

===========================================================
10. 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. 

http://espr.trac.cvsdude.com/esp-r/wiki/PreReleaseTesting11.11

===========================================================
11. SUPPORT

The quickest route to a remedy for an ESP-r installation or
modelling problem is to ask for help on the ESP-r mailing
list. To subscribe to the list, visit:

  http://lists.strath.ac.uk/mailman/listinfo/esp-r

Good Luck!