INSTRUCTIONS FOR SETTING UP APASS SIMULATION SERVICE

1. File structure

To "install" the service, unpack the source code archive.
You should see a directory structure as follows:

[APASS 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
      [PAM scripts, utilities and resources]
      [symlinks to PAM scripts:]
      ISO7730_thermal_comfort
      CIBSE_thermal_comfort
      visual_comfort
      indoor_air_quality
      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 be installed:
    sys
    os
    subprocess
    time
    multiprocessing
    re
    datetime
    shutil
    glob
    signal
    ctypes
  Packages that you will probably need to install:
    mysql (mysql-connector-python is the correct pip package name)
    setproctitle 
  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
  All of these should be standard with the TeX Live distribution.
ESP-r v13.3.7
Radiance v5.2
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 ([APASS back end service root]/jobs/job_X).
The job will be killed at the next dispatch, and the job directory erased.

5. Notes

In this version of the service, automatic calibration using data from BEMserver is disabled.
This functionality is currently not generalised.






    
