The table below gives an overview of the widgets and their different appearance in the base and the Hypercube mode.

The transformation of input widgets has the following implication for the submission of Hypercube jobs: Unless explicitly specified in the MIRO configuration of the model, each scalar is expanded and the cartesian product over all scalars defines a Hypercube job. In other words: All combinations are generated from the configuration selected by the user and each of those combinations is the basis of what we call a scenario in the base mode.

In the example, the slider for freight in dollars per case per thousand miles was set by us to a range from 75 to 150 with a step size of 5. The slider configured in this way leads to 16 different variants.

• Variant 1: freight = 75
• Variant 2: freight = 80
• Variant 3: freight = 85
[...]
• Variant 16: freight = 150

For the scalar minimum shipment the slider was set to a range between 20 and 200 with a step size of 20. The resulting variants would therefore be:

• Variant 1: number of days for training = 20
• Variant 2: number of days for training = 40
• Variant 3: number of days for training = 60
[...]
• Variant 10: number of days for training = 200

The third slider for the scalar parameter beta is not set to a range but to a single value. Due to the non-existent variation of the scalar, only one variant results from it. The same is true for the last widget, a multi dropdown menu where we specify to only consider the MIP version of our model.

The cartesian product that results from the combination of all variations is now calculated: It is created from the different variants of the symbols freight in dollars per case per thousand miles (16), minimum shipment (10), beta (1) and Select model type (1) resulting in 16 x 10 x 1 x 1 = 160 individual scenarios.

It becomes clear that the number of scenarios resulting from a particular Hypercube job configuration can increase rapidly with the number of scalar that are expanded. Depending on how computationally intensive the underlying GAMS model is, the scenarios should be carefully configured.
You may want to restrict certain input widgets to be transformed: This can be done in the MIRO Configuration mode by unchecking the widget-specific option Should element be expanded automatically in Hypercube mode?.

When activated, this configuration has the consequence that the scalar can still be selected in the scenario generation but with a regular slider instead of a slider range.

When we decided which of the scenarios to submit, we have two options of HOW to submit the job:

1. Automated job submission
2. Manual job submission

General

All scenarios of the Hypercube job are calculated automatically on the machine running MIRO.

Job tags: When submitting a Hypercube job automatically, we can optionally specify job tags. Job tags are an identifier attached to all scenarios of a Hypercube job. They can help you identify scenarios of a certain job or a group of jobs with similar attributes. This means that you can use those tags as part of your database queries in order to easily find certain scenarios that you are interested in. Additionally, job tags can also be used to compare different groups of scenarios that you are interested in via PAVER.

Import results

When we submit the Hypercube job automatically, it will be executed in the background. Without going into too much detail, what happens here is simple:
First, a Hypercube file which contains all scenario configurations is created by MIRO. This file gets converted into executable GAMS calls, which are then processed. The script which is responsible for this conversion is located in the /resources folder of the MIRO installation directory and can be customized as needed. More about these steps in the section on manual execution of a Hypercube job.

Once a Hypercube job has been submitted, it is shown in the Import results section which can be accessed via the sidebar menu. There, all jobs are listed that are still running or whose results have not yet been imported.

The overview shows for each submitted job the owner, the submission date and the (optional) specified job tag(s). In addition, the current status (scheduled, running or completed) is visible. The progress of a run can be displayed by clicking on the corresponding show progress button and results that have not yet been loaded into the database or are still pending can be discarded. As soon as a job has finished, the results can be loaded into the database with a click on Import.

If you want to see jobs that you previously imported or discarded, you can do so by clicking on Show history:

Once a job has been imported, the results are stored in the database.

Download zip archive

If we want to execute a Hypercube job manually, we can download a ZIP archive with all needed data by clicking on Submit job → Process job manually.

The archive has the following contents:

• transport.gms
  model file
• static folder
  This folder contains all non-scalar (thus multidimensional) input data in form of a GDX file. As explained here, this data remains the same for all scenarios of a Hypercube job.
• hcube.json
  Hypercube file. Contains all variable information on the scenarios to be calculated (scenario ID, command line arguments).
• transport.pf
  This parameter file contains options which must be set in order to solve the scenarios of a hypercube job. You should not touch this file.
• hcube_submission.gms
  File used in automated job submission to generate a script based on the contents of the hypercube file and all static data, which then can be executed in GAMS.
• In addition, all directories and files that have been assigned to the model by the user (see model assembly file) are also included.

Let's have a brief look at the hcube.json file which originates from the already shown configuration above:

{
    "jobs":[ {
        "id": "e505eb77f2fed92ecb6c7609a6873974ea87d69b620a7ca9aa8d6a1a62e7159b", 
        "arguments": [
            "--HCUBE_SCALARV_mins=20", 
            "--HCUBE_SCALARV_beta=0.97", 
            "--HCUBE_SCALARV_f=75", 
            "--type=\"mip\""
        ]
    },
    {
        "id": "834cc2ff77d5cddc70f6462263a500ab43d22f084a0d98ff1fd8cfc354c8e6ec", 
        "arguments": [
            "--HCUBE_SCALARV_mins=40", 
            "--HCUBE_SCALARV_beta=0.97", 
            "--HCUBE_SCALARV_f=75", 
            "--type=\"mip\""
        ]
    },
    {
        "id": "867432ac65a22a251ee6fca0ce5eb7ba45195538e389406abe7593f21b8255c4", 
        "arguments": [
            "--HCUBE_SCALARV_mins=60", 
            "--HCUBE_SCALARV_beta=0.97", 
            "--HCUBE_SCALARV_f=75", 
            "--type=\"mip\""]
    },
    
    [...]
    
    ]
}
                                            

Each object contains the information needed for exactly one scenario, i.e. each variable scenario configuration is stored in a separate JSON object:

• ID:
  Each job has an individual ID in form of a hash value which used to (almost) uniquely identify a scenario. To learn more about how this hash is generated, read more on how MIRO indentifies Hypercube jobs here.
• Arguments:
  The arguments contain information on all scalar values, i.e. GAMS Scalars, scalar Sets, double-dash parameters and GAMS Options. This is where the individual scenarios differ.

Run the Hypercube job

To be able to calculate all configured scenarios in GAMS, we need to convert the scenario-specific information provided in the file hcube.json together with the static data into an executable GAMS script. Additionally, the results need to be saved in such a way that MIRO can validate and import them. The file hcube_submission.gms is a simple script which is used in the automated job submission for this purpose and which can also be used here.

By running the hcube_submission.gms we can generate a script based on the contents of the hcube.json file and all static data, which then can be executed in GAMS. This is how the resulting file jobsubmission.gms looks like.

$if dexist 4upload $call rm -r 4upload
$call mkdir 4upload
$call cd 4upload && mkdir tmp0
$if errorlevel 1 $abort problems mkdir tmp0
$call cd 4upload/tmp0 && gams "C:\Users\Robin\Documents\.miro\hcube_jobs\transport\1\transport.gms" --HCUBE_SCALARV_mins=20 --HCUBE_SCALARV_beta=0.97 --HCUBE_SCALARV_f=75 --type="mip" pf="C:\Users\Robin\Documents\.miro\hcube_jobs\transport\1\transport.pf"
$if dexist e505eb77f2fed92ecb6c7609a6873974ea87d69b620a7ca9aa8d6a1a62e7159b $call rm -r e505eb77f2fed92ecb6c7609a6873974ea87d69b620a7ca9aa8d6a1a62e7159b
$call cd 4upload && mv tmp0 e505eb77f2fed92ecb6c7609a6873974ea87d69b620a7ca9aa8d6a1a62e7159b

$onecho > "%jobID%.log"
1/160
$offecho
$call cd 4upload && mkdir tmp1
$if errorlevel 1 $abort problems mkdir tmp1
$call cd 4upload/tmp1 && gams "C:\Users\Robin\Documents\.miro\hcube_jobs\transport\1\transport.gms" --HCUBE_SCALARV_mins=40 --HCUBE_SCALARV_beta=0.97 --HCUBE_SCALARV_f=75 --type="mip" pf="C:\Users\Robin\Documents\.miro\hcube_jobs\transport\1\transport.pf"
$if dexist 834cc2ff77d5cddc70f6462263a500ab43d22f084a0d98ff1fd8cfc354c8e6ec $call rm -r 834cc2ff77d5cddc70f6462263a500ab43d22f084a0d98ff1fd8cfc354c8e6ec
$call cd 4upload && mv tmp1 834cc2ff77d5cddc70f6462263a500ab43d22f084a0d98ff1fd8cfc354c8e6ec

$onecho > "%jobID%.log"
2/160
$offecho
$call cd 4upload && mkdir tmp2
$if errorlevel 1 $abort problems mkdir tmp2
$call cd 4upload/tmp2 && gams "C:\Users\Robin\Documents\.miro\hcube_jobs\transport\1\transport.gms" --HCUBE_SCALARV_mins=60 --HCUBE_SCALARV_beta=0.97 --HCUBE_SCALARV_f=75 --type="mip" pf="C:\Users\Robin\Documents\.miro\hcube_jobs\transport\1\transport.pf"
$if dexist 867432ac65a22a251ee6fca0ce5eb7ba45195538e389406abe7593f21b8255c4 $call rm -r 867432ac65a22a251ee6fca0ce5eb7ba45195538e389406abe7593f21b8255c4
$call cd 4upload && mv tmp2 867432ac65a22a251ee6fca0ce5eb7ba45195538e389406abe7593f21b8255c4

[...]
                                            

We can see the commands for running through the first three scenarios of the hcube.json file. A separate (temporary) folder is created for each scenario to be calculated. In the main GAMS call all arguments contained in the hcube.json file which belong to the scenario are listed as command line parameters.

$call [...] gams "[...]\transport.gms" --HCUBE_SCALARV_mins=20 --HCUBE_SCALARV_beta=0.97 --HCUBE_SCALARV_f=75 --type="mip" [...]
                                            

GAMS Scalars can usually not be set via a GAMS call, but are defined in the model. In order to be able to set scalars via the command line, MIRO adds a special prefix: --HCUBE_SCALARV_<scalar-name>=<scalar-value>, e.g. --HCUBE_SCALARV_f=90 for scalar f and a value of 90. To continue this example, if a GAMS model is called with IDCGDXInput (which is done here using the pf file) and the compile-time variable --HCUBE_SCALARV_f=90, a scalar f is searched in the list of symbols declared in your GAMS model and, if declared, set to the value of the compile-time variable, i.e. 90. The set text of a singleton set is communicated via the prefix --HCUBE_SCALART_.

Besides this scenario-specific data, a GDX file containing all static data is included at the end of the $call as part of a pf file:

$call [...] pf="[...]\transport.pf"
                                            

execMode=0
IDCGDXOutput="_miro_gdxout_.gdx"
IDCGenerateGDXInput="_miro_gdxin_.gdx"
IDCGDXInput="..\..\static\_miro_gdxin_.gdx"
trace="_sys_trace_transport.trc"
traceopt=3

                                            

The pf file also contains the command to create a trace file. In case you are interested in doing performance analysis using PAVER, you need to make sure to generate trace files for your scenarios.

After the calculations, the results of a scenario (input and output data) are stored in a folder named by its ID.

Import rules

At the end of the calculations, the results should be available in the form of a ZIP archive. For MIRO to accept the archive as a valid set of scenarios, the input and output data records for a certain scenario must be available as GDX files. These must be located in a folder named after the hash value of the scenario and located in the root directory of the zip file.

There are some files that must exist in order for MIRO to accept a particular scenario. Other datasets are optional and don't have to be included in the zip archive. The mandatory files are:

• _miro_gdxin_.gdx
  Scenario input data (GDX file)
• _sys_trace_<modelname>.trc
  Trace file of the scenario run. This file contains numerous run statistics which are used for the the integrated performance analysis tool PAVER. The Hypercube job file already contains the GAMS options for generating the trace file automatically. In case you specified (in your MIRO app configuration) that you are not interested in trace information (option saveTraceFile set to false), mustn't be included in your scenario data. You can find more information about the trace file here.

These files are generated automatically when you use the hcube_submission.gms file. If scenario data does not contain all mandatory files, this scenario will be ignored and thus not be stored in the database. If results are available, beside the GDX with input data also one with output data is created, namely the GDX _miro_gdxout_.gdx. This file contains all output parameters declared in the GAMS model between the $onExternalOutput / $offExternalOutput tags. If a model calculation is aborted, this GDX is not generated automatically.

The following figure summarizes the steps required to move from the downloaded archive created by MIRO to a ZIP archive that you can import back into MIRO:

Import results

Upload Zip file with results:

A dialog pops up that lets you choose the zip archive with the Hypercube job results. Note that you probably want to assign job tags here as well.

With a click on upload the archive is evaluated and stored in the MIRO database if the contained data is valid.