INSTRUCTIONS FOR SETTING UP MARATHON RESILIENCE ASSESSMENT SIMULATION SERVICE

1. File structure

To "install" the service, simply unpack the source code .tar.gz archive.
You should find the following file structure:

[Marathon back end service root]
  jobs
    [each simulation job is run here in a directory called "job_XXX" where X is the job ID number]
  scripts
    assessments
      [RA scripts, utilities and resources]
      [symlinks to RA scripts:]
      Domestic_(free_running)
      Domestic_(mechanically_cooled)
      Office
      District_heating
      wireframe
    common
      [various utility scripts]
    main.py
    .SQL.txt

2. Prerequisites

Operating system:

The program is designed to run on a Linux OS.
It been successfully implemented on: 
  Ubuntu 16.04 LTS
  Ubuntu 18:04 LTS

Dependencies:

Python v3.5.2
  Packages that are probably already installed:
    sys
    os
    subprocess
    time
    multiprocessing
    re
    datetime
    shutil
    glob
    signal
    ctypes
	argparse
	copy
	itertools
	csv
  Packages that you will probably need to install:
    mysql (mysql-connector-python is the correct pip package name)
    setproctitle
	pandas
	numpy
	tqdm
	scipy
	sklearn
	statsmodels
  You may need to install pip first with "sudo apt install python3-pip".
  You can install packages with "pip3 install -u [package name]"
TeX Live 2018 (v3.14159265)
  Packages:
    geometry
    times
    underscore
    multirow
    scrextend
    lscape
    longtable
    booktabs
    pgfplots
    siunitx
	fontspec
  All of these should be standard with the TeX Live distribution.
  Marathon uses the luatex interpreter.
  You will also need the TeX Gyre Termes font, which you should be able to install with the command:
    tlmgr install tex-gyre
ESP-r v13.3.7
Gawk v4.1.3

The versions given above are a known working configuration. Other versions may or may not work.
It is recommended to install the most recent versions of all of the above, and then downgrade if problems are encountered.

3. Data exchange with the user interface:

Information exchange with the BPA user interface is accomplished through an SQL database. The current default is for a remote connection to this database. 
See documentation for the BPA front end for instructions on setting up the SQL database.
The file ".SQL.txt" (see section 1) contains information used by the back end to log in to this database.
File format is:

[IP address]
[user name]
[password]
[database]
[error log file name]

File exchange with the BPA user interface can be accomplished using any file sharing service (e.g. Dropbox, shared folder mounting, etc.).
The simulation service interacts with files on the local system at a location specified on the command line (see section 4).
This local file structure should be synced with the same file structure on the machine hosting the front end service.
The sharing file structure is:

[file exchange root]
  Models
    [model files uploaded via the user interface]
  Results
    [job results directories named "X" where X is the job ID number]

The simulation service creates a results directory for each job it runs, and copies job outputs to this directory.

4. Running the service

To run the service, invoke the script "main.py".
This has two command line options, and two command line arguments:

Command line options:
  -h - display help text and exit
  -d - debug mode; print output to the terminal and write a log file for each job

Command line arguments:
  1. file exchange root directory
  2. interval between dispatch in seconds (optional; default 15)

The service runs in an infinite loop, unless an error or user intervention causes it to halt.
At intervals specified by a command line argument, a dispatch is initiated.
A dispatch consists of:

1. Connecting to the SQL database and retrieving a list of active jobs.
2. Initiating any new jobs and checking the status of any currently running jobs.
3. Updating the SQL database with the status of all active jobs.

Individual jobs can be killed by the service administrator without halting the service.
To do this, create a file named "kill.it" in a job directory ([Marathon back end service root]/jobs/job_X).
The job will be killed at the next dispatch, and the job directory erased.

5. Notes

This version of the service, while basically functional, is a work in progress.
Firstly, some assessment metrics are not active and the fields in the UI are placeholders; the assessments will not evaluate these metrics.
These are:
  Domesitc assessments:
    Lighting energy use
	Equipment energy use
	DHW energy use
	Emissions
  Office assessments:
    Lighting energy use
	Equipment energy use
	DHW energy use
	Emissions
Secondly, some aspects of the RAs have not been widely tested with a diverse range of ESP-r models.
In particular, you may experience problems with models with complex zone controls in the case of Domestic and Office assessments, and models with complex plant networks and/or coupled building and plant domains in the case of District Heating assessments.
Future updates will address these aspects of functionality.
  
Full documentation of the methodology, conventions and model prerequisites is also a work in progress.
In future, this information will be available through the "futher information" link in the front-end UI.

Finally, it must be noted that the resilience assessments have not at this stage been quality assured to an extent that the results may be used in practice.
We take no responsiblity for any mishap or loss that may result from doing so.






    
