This is the help file for Hit2Gap model calibration environment. Calibration requests may be made by providing details of the model. The contents list displays the various tasks that may be performed using this API.

Contents:

1. Introduction
2. Get authentication code
3. Get models list
4. Edit model name
5. Add model
6. Run calibration
7. Calibro ESP-r coupling

Introduction

A number of PHP scripts are available in the RESTful folder of the source distribution. Each of these scripts is standalone and performs one task as listed in the contents list. The PHP scripts may be invoked by editing the URL of this page and replacing manual.html by each of the PHP scripts listed below. Python scripts have been generated by ESRU and are available here.
Users may either use the PHP or the Python scripts but should be aware they are called in different ways. The Python scripts have the same names but different extensions as the PHP scripts (and are simple wrappers around the PHP scripts). Arguments such as model names, path and file names and authentication codes need to be provided to the scripts for them to work. For the PHP scripts arguments are provided within the url as explained in the sections below. For the Python scripts a file called variables.py holds all the arguments. It is expected that the user will edit this file to add their own arguments.
The PHP scripts are run from a browser i.e. the url is copied into a browser. Python scripts may be called from stdin which could be a DOS or UNIX shell. The format of these calls is "py script_name.py" for DOS and "python3 script_name.py" for bash. Arguments for the Python scripts are taken from variables.py.

Get authentication code

Before doing anything else you need to have a user account and authentication code. Authentication code for each user may be obtained/edited in the edit user section of the interface.

Get models list

Once authentication code is known a complete list of all the models that you own or have been shared with you should be downloaded. You will need the model id from this list (to be used in the remainder of the scripts). Form of the url is:

    GetID.php?auth=auth_code

Where

    auth_code

should be replaced by the actual authentication code

Edit model name

Editing a model name requires both the new name and id of the model. Form of the url is:

    EditModelName.php?auth=auth_code&pid=pid&mname=mname

Where:

    auth_code

should be replaced by the actual authentication code

    pid

(2nd occurrence) should be replaced by the model id for that model found in models list

    mname

(2nd occurrence) should be replaced by the new model name (spaces are allowed)

Add model

A model may be added by providing its name and compressed model file (see calibration documentation for how to create this). The location of the file could be a url (e.g. those available from Strathcloud or third party cloud sites like Dropbox or Googledrive etc.). Form of the url is:

    AddModel.php?auth=auth_code&mname=mname&FNP=tarball

Where:

    auth_code

should be replaced by the actual authentication code

    mname

(2nd occurrence) should be replaced by the new model name (spaces are allowed)

    tarball

should be replaced by the url of the compressed model file

Run calibration

Calibration may be run by providing the id for the model. The script will send the job to be run and will wait for however long it takes the assessment to be made. Terminating the script will not cause the job to be terminated but will render it inaccessible. The resulting json (or pdf) report will be provided when the script returns. Form of the url is:

    Run.php?auth=auth_code&pid=pid&mode=mode

Where:

    auth_code

should be replaced by the actual authentication code

    pid

(2nd occurrence) should be replaced by any model id

    mode

(2nd occurrence) should be replaced by either pdf or json

Calibro ESP-r coupling

Calibro can be coupled with ESP-r to provide automatic simulation calibration facility. Before running ESP-r Calibro calibrations the environment needs to be set up after which calibrations may be run. Environment setup

1. Install ESP-r Linux version
2. Install curl, python3 and jq
3. Create a complete ESP-r model (i.e. one that can be simulated successfully) or copy one from its exemplar library
4. Unzip Calibro RESTful API to cfg folder of the ESP-r model (or any other location)
5. Unzip ESP-r Calibro API to same location as RESTful API

Running calibrations

1. ESP-r should automatically zip files required for running Calibro. This zipped file must be a tar.gz file and must be present in the cfg folder. To run automatic calibration use the command

       ./calibrateme.bash tarballname.tar.gz

   It is possible to run the calibration script from any location on a tarball at any location as long as their absolute paths are specified. The resulting calibration file will always be written in the folder the command was issued from.