Use POST /job
with multi-part form data to upload model files and set up a new simulation in one transaction.
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.
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.
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 ) |
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 |
model
and the cases
fields to include the root folder as well. See the examples below.
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
.
An HTTP 401 - Unauthorized response will be received
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
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()