Table of Contents

Back to JESS API

Upload and Run a Simulation Job Directly


Use POST /job with multi-part form data to upload model files and set up a new simulation in one transaction.

Synopsis

Submission Form

The direct submit and run transaction can be used to run both EnergyPlus simulations and jEPlus projects. The form's data fields vary for different jobs to run. Files can be uploaded directly, or in a pre-packed zip archive.

Uploading Options

You can upload both files are they are, using multiple file fields, or packed the files in a zip archive first, and then upload the zip file. The latter is particularly useful for a jEPlus project where more than a handful of files are involved. JESS will unpack the zip archive once it is received.

Run E+ Simulation

To create an EnergyPlus simulation job, at least one IDF and one EPW files need to be uploaded.

The relevant fields include:

Field Value Description
file file one or more files, all with the same field name file
type EP EP for EnergyPlus models (optional)
title text Caption of the job (optional)
desc text Description of the job (optional)
model text IDF model file name (optional; if omitted, make sure there is only one .idf or .imf file in the package)
weather text Weather file name (optional; if omitted, make sure there is only one .epw file in the package)
split boolean Run simulation using the run period-split method or not (default FALSE)

Run jEPlus Project

To create a jEPlus job, all files that the jEPlus project contains must be uploaded, hence it is easier to pack them in a zip archive rather than using multiple file fields.

Field Value Description
file file zip archive containing all the project files
type JEP JEP for jEPlus projects (if omitted, JESS will assume the project based on the presence of a .json or a .jep file)
title text Caption of the job (optional)
desc text Description of the job (optional)
model text jEPlus project file name (optional. If omitted, make sure that there is only one .json or .jep file in the folder)
subset DEFAULT default: Run the project as defined in the project file
ALL Override the run option in the project and run all the jobs instead
LHS Override the run option in the project and run a random sample using LHS method. Sample size specified in the cases field
LIST_FILE Override the run option in the project and run the cases defined in the case list file (specified in the cases field)
cases text Sample size (with the LHS option above) or the jobs list file name to use with the LIST_FILE option of the subset field
When packing the project files into a zip archive, you should not include the root folder of the files. The screenshots below show the difference. If you do, you need then adjust the model and the cases fields to include the root folder as well. See the examples below.

Run Radiance Simulation

JESS supports Radiance Rtrace and Rpict jobs. To create a Radiance job, all files that the simulation job depends on must be uploaded. They can be uploaded using multiple file fields or as a packed zip archive.

Field Value Description
file file repeatable for multiple files, or a zip archive containing all files
type RAD RAD for Radiance simulations
title text Caption of the job (optional)
desc text Description of the job (optional)
model text The octree (.oct) file
program rtrace Run Rtrace, requires sensors grid as input
rpict Run Rpict, requires view definitions as input
args text Radiance program arguments
input text Input stream file name. For Rtrace, these are sensor definitions; for Rpict, these are view defs. Wildcard char * is supported to specify multiple input files, e.g. *.inp
output text Output file(s) extension, e.g. ill for Rtrace or hdr for Rpict

Run DaySim Simulation

JESS supports DaySim jobs. To create a DaySim job, all files that the simulation job depends on must be uploaded. These typically include various Radiance model files (.rad), a weather file, sensors grid, and occupancy schedule etc. It would be easier to upload a zip archive rather than using multiple file fields.

Field Value Description
file file repeatable for multiple files, or a zip archive containing all files
type DS DS for DaySim simulations
title text Caption of the job (optional)
desc text Description of the job (optional)
model text The DaySim header file
input text Input stream file name for the sensors grid. Wildcard char * is supported to specify multiple input files, e.g. *.inp

Return Object

A successful return object contains the status flag, a message, and a data field containing the ID of the newly created job, as shown in the example below. 

{
    "ok": true,
    "status": "Job 12248 is created",
    "data": 12248
}

The returned object does not show whether or not the job will simulate successfully. To get the information on the job's status, use GET /job/status.

Authorization Failed

An HTTP 401 - Unauthorized response will be received

Example using curl://

Assuming the session token has been saved in the cookies file using the log on command, send the confirm command using curl on Linux as below: 

curl -b cookies -F 'file=@job_example/5ZoneAirCooled-v93.idf' -F 'file=@job_example/in.epw' -F 'title=Test job' -F 'desc=Test upload and run' -F 'model=5ZoneAirCooled-v93.idf' -F 'weather=in.epw' -F 'split=FALSE' https://api.ensims.com/jess_web/api/job

On Windows: 

curl -b cookies -F "file=@job_example/5ZoneAirCooled-v93.idf" -F "file=@job_example/in.epw" -F "title=Test job" -F "desc=Test upload and run" -F "model=5ZoneAirCooled-v93.idf" -F "weather=in.epw" -F "split=FALSE" https://api.ensims.com/jess_web/api/job

Or, to pack the input files in a zip archive and upload with one -F 'file=@…' on Linux: 

zip -j upload.zip job_example/*
curl -b cookies -F 'file=@upload.zip' -F 'title=Test job' -F 'desc=Test upload and run' -F 'model=5ZoneAirCooled-v93.idf' -F 'weather=in.epw' -F 'split=FALSE' https://api.ensims.com/jess_web/api/job

On Windows: 

zip -j upload.zip job_example/*
curl -b cookies -F "file=@upload.zip" -F "title=Test job" -F "desc=Test upload and run" -F "model=5ZoneAirCooled-v93.idf" -F "weather=in.epw" -F "split=FALSE" https://api.ensims.com/jess_web/api/job

If the submission is successful, a confirmation object will be returned with the new job ID. If the session token is invalid, an HTTP 401 code will be returned.

This example shows how to run a jEPlus project with a job-list file, on Linux: 

curl -b cookies -F 'file=@upload_jep.zip' -F 'title=Test jE+ job' -F 'desc=Test upload and run' -F 'model=project.json' -F 'subset=LIST_FILE' -F 'cases=jobs.txt' https://api.ensims.com/jess_web/api/job

On Windows: 

curl -b cookies -F "file=@upload_jep.zip" -F "title=Test jE+ job" -F "desc=Test upload and run" -F "model=project.json" -F "subset=LIST_FILE" -F "cases=jobs.txt" https://api.ensims.com/jess_web/api/job

Or, if the zip file contains the root folder, it should be run as this, on Linux: 

curl -b cookies -F 'file=@Shoebox_v8.9.zip' -F 'title=Test jE+ job' -F 'desc=Test upload and run' -F 'model=Shoebox_v8.9/project.json' -F 'subset=LIST_FILE' -F 'cases=Shoebox_v8.9/jobs.txt' https://api.ensims.com/jess_web/api/job

On Windows: 

curl -b cookies -F "file=@Shoebox_v8.9.zip" -F "title=Test jE+ job" -F "desc=Test upload and run" -F "model=Shoebox_v8.9/project.json" -F "subset=LIST_FILE" -F "cases=Shoebox_v8.9/jobs.txt" https://api.ensims.com/jess_web/api/job

Example using Python Requests

Make sure Requests is correctly installed in your Python environment, and run the following lines: 

import requests

files = [
    ('file', ('5ZoneAirCooled-v93.idf', open('job_example\\5ZoneAirCooled-v93.idf', 'rb'), 'text/plain')),
    ('file', ('in.epw', open('job_example\\in.epw', 'rb'), 'text/plain')),
    ('title', 'Test job'),
    ('desc', 'This is test submission made from python example'),
    ('model', '5ZoneAirCooled-v93.idf'),
    ('split', 'FALSE'),
    ('weather', 'in.epw')
]

# Make a post request. Session token must be available in the saved cookies during log-on
r = requests.post('https://api.ensims.com/jess_web/api/job', files=files, cookies=cookies)

# Show return info
r.json()