GAMS Studio integration#

Introduction#

In this section we show you how to use GAMS Studio for the development and deployment of your MIRO apps. GAMS Studio has built-in support for the most important interactions with MIRO. This section gives an overview; details are explained in the linked chapters.

Note:

GAMSPy users should use the GAMSPy CLI instead of GAMS Studio.

General#

MIRO installation location#

After installing GAMS MIRO, make sure that Studio and MIRO know about each other. In Studio go to File → Settings → Remote and check whether the MIRO installation location is correct:

MIRO installation location

Note:

There is a known issue in GAMS Studio when it comes to specifying the MIRO location on macOS. Make sure that the path does not stop at /Applications/GAMS MIRO.app, but points to the executable inside the app bundle: /Applications/GAMS MIRO.app/Contents/MacOS/GAMS MIRO. The /Contents/MacOS/GAMS MIRO part is always the same and needs to be appended to the path of the app bundle.

Main file in Studio#

GAMS Studio does not execute the file currently visible in the editor, but the file that is set as main file in the corresponding group in the project explorer. Make sure that the model you want to use for MIRO is marked as the main file. If this is not the case, you can change it by right-clicking the file in the project explorer → set as main file:

Set as main file in Studio

File encoding#

Your GAMS model files need to be encoded in UTF-8. In GAMS Studio this is the default file encoding from version 0.14.5 on. You can change the encoding of your file via Edit → Encoding → convert to ... → UTF-8. Other file encodings are not supported in GAMS MIRO!

File encoding in GAMS Studio

MIRO interaction#

All interaction between GAMS Studio and MIRO can be found in the MIRO menu:

MIRO menu in GAMS Studio

Run Base Mode#

Launch MIRO Base Mode

This option starts the MIRO Base Mode. In the Base Mode, you can supply your models with input data, generate, display and save the results of your optimization as well as compare different scenarios with each other, everything visually supported by various plotting tools.

MIRO Base Mode

Run Configuration Mode#

Launch MIRO Configuration Mode

This option starts the MIRO Configuration Mode. Here, you can create plots and widgets or change certain settings with a few mouse clicks, visually supported by a live preview.

MIRO Configuration Mode

Skip model execution#

In the MIRO menu of GAMS Studio there is the entry "Skip model execution". If this option is activated, the model is not executed before MIRO is started, but MIRO is called directly instead. This can be helpful if the model takes a long time to be solved.

Skip model execution

However, use this option with caution!

If the model execution is skipped, the GAMS/MIRO data contract is not created or refreshed. This means that changes made in the model are not communicated to MIRO. If you have a model that takes a long time to be solved and you don't want to run through it in order to launch MIRO, you can simply set the GAMS option a=c (action=compile) instead of the option "Skip model execution". This only compiles the model, which is sufficient to update the data contract. Note that in this case a new default scenario is created, but it contains only the data that is available after the compilation phase (most of the time only input data).

Create model assembly#

If you want to deploy a fully configured app, MIRO needs to know about the files that belong to your model. This is primarily the main model file, but also all files necessary to calculate all inputs and outputs, e.g. files that are included in the model. To tell MIRO about these files, go to Assembly and Deploy. In the Assembly File section select those folders and files which are needed. If you select a folder, all files in it will be included. If you want to use only single files of a folder, you have to expand the folder and select the corresponding file(s). When you are finished, click on create.

create model assembly file

Deploy#

When the MIRO app is completely configured it can be deployed, i.e. exported and installed so that it can be easily shared with end users. No further changes to the model or the configuration can be made once it is deployed.

Deploy MIRO model

In GAMS Studio, select Assembly and Deploy. In the Deploy Configuration section you need to decide how your model shall be executed (execution environment). There are three options:

  1. Multi-user: This option allows your app to be used by multiple users simultaneously. Your model files are extracted at a random location, which is different for each user, and your model is executed from there.

  2. Single-user: Your model is executed inside the model directory. No extraction of your model files is required, but this means that you can NOT have multiple users accessing your MIRO app at the same time.

  3. Local multi-user (uses idir): With this third option, your model is again executed from a random location, but this time no model data is extracted here. Instead, GAMS is executed with an input directory pointing to the path where your model files are located. Choose this option ONLY if you have many large files that belong to your model and extracting them would take a long time. Be aware that using idir might break your model! For example, if you use $call or the execution-time equivalent execute (or related functions), the relative paths used in these calls will no longer exist (since the curdir is now a random location). The solution is to prefix all these relative paths with %gams.idir1%. For example, in order to import an Excel file test.xlsx, GDXXRW needs to be called like this: $call gdxxrw i=%gams.idir1%test.xlsx. Alternatively, you can also use absolute paths (e.g. via $setNames "%gams.input%" fp fn fe, see here).

    Adjusting all affected paths is potentially a lot of work, so we strongly advise against using this option unless you know what you are doing!

Note:

With MIRO version 2.1, the Hypercube Mode was deprecated and no longer exists as a separate mode. You can now submit Hypercube jobs from the Base Mode if you are using GAMS MIRO with a GAMS Engine backend (GAMS MIRO Server or GAMS MIRO Desktop - boosted by GAMS Engine). You can find the most recent documentation here.

Advice

We advise you to test your MIRO app before distributing it. GAMS Studio offers an option test deployment. This simulates how your end users will experience the MIRO app (e.g. for the Base Mode MIRO is launched in the specified execution environment). In particular, you should check whether you forgot to include important files in the model assembly.