User Tools

Action disabled: source

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)
weather text Weather file name (optional)
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.

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()


Site Tools