INSTRUCTIONS FOR SETTING UP CALIBRO SERVICE

1. File structure

[caliserv back end service root]
  jobs
    [each calibration job is run here in a directory called "job_XXX" where X is the job ID number]
  scripts
    calibrino
    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:

Calibro v2.2
  This can be obtained from https://www.strath.ac.uk/research/energysystemsresearchunit/applications/calibro/.
  You will need to copy the calibrino script that comes with calibro into the scripts directory (see section 1).

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 ([caliserv back end service root]/jobs/job_X).
The job will be killed at the next dispatch, and the job directory erased.






    
