In addition to a normal GAMS job, GAMS Engine also supports so-called Hypercube jobs.
These are essentially a collection of normal jobs with varying command line arguments. Why is this
useful? Imagine a GAMS model that runs through a number of different scenarios. The model is always
initialized by the same large GDX file, but behaves differently depending on double dash parameter --scenId. In this situation you want to avoid
uploading the same large GDX file for each scenario. Instead, you want to upload it once and create
a number of jobs with different command line arguments: a Hypercube job.
To spawn a new Hypercube job, you need to use the POST /hypercube/ endpoint. The only
difference to posting a normal job is a so-called Hypercube description file. This is a JSON
file that describes your Hypercube job. This Hypercube description file has the following
schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"pattern": "^[0-9a-zA-Z_\-. ]+$"
},
"arguments": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
}
},
"required": [
"id",
"arguments"
]
},
"required": [
"items"
],
"minItems": 1
}
},
"required": [
"jobs"
]
}
With this in mind, our example described above could result in the following Hypercube
description file:
{
"jobs": [
{
"id": "first scenario",
"arguments": ["--scenId=1"]
},
{
"id": "second scenario",
"arguments": ["--scenId=2"]
},
{
"id": "third scenario",
"arguments": ["--scenId=3"]
}
]
}
This would result in the creation of three GAMS jobs with different values for --scenId.
The id of a job can be any string. However, it must be unique among the different jobs of a
Hypercube job and is used as the directory name where the results are stored. The content of
the result archive of the Hypercube job described above would look like this (results are
filtered via INEX file):
.
├── first\ scenario
│ └── results.gdx
├── second\ scenario
│ └── results.gdx
└── third\ scenario
└── results.gdx
3 directories, 3 files