This chapter guides you through the first steps of using GAMS MIRO and shows you how to deploy your own GAMS models. You will learn how 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.

Setup

GAMS MIRO is not included in the GAMS distribution and must be installed separately. You can download MIRO here.

• GAMS
• GAMSPy

After that you should make sure that GAMS and MIRO know about each other. If you work with GAMS Studio, then go to File → Settings → Remote and check whether the MIRO installation location is correct, e.g.:

On the MIRO side, open MIRO and go to Preferences → Paths. Ensure that the location of the correct GAMS version is specified, e.g.:

After that you should make sure that GAMSPy and MIRO know about each other. In case you installed MIRO in one of the standard locations on Windows or macOS you can omit this step. GAMSPy will automatically detect it. In case you are using Linux or installed MIRO in a custom location, the best way to let the GAMSPy CLI know about MIRO is to set the MIRO_PATH environment variable to the path of your MIRO executable (e.g. C:\Program Files\GAMS MIRO\GAMS MIRO.exe on Windows, /Applications/GAMS MIRO.app on macOS or ~/GAMS-MIRO-2.9.0.AppImage on Linux). Alternatively, you can specify the path to the executable file each time you call the GAMSPy CLI using the --path argument.

On the MIRO side, open MIRO and go to Preferences → Paths. Ensure that the location of the correct Python version (the one on which you have installed GAMSPy) is specified, e.g.:

Demo Applications

• GAMS
• GAMSPy

To get a feeling for the use of GAMS MIRO, we recommend to have a look at the demo applications first which you can download here. To use the demo applications, unzip the archive and put the extracted folder miro_lib into the user model library directory. Via GAMS Studio you can find this location by clicking on File → Settings → Misc. → user model library:

Next, if you are using GAMS Studio, go to GAMS → Model Library Explorer (shortcut F6) and click on the new entry GAMS MIRO model collection. There you will find the ready-to-use demo applications:

If you are using the command line, you can use the following command to access the applications: gamslib -lib /location/to/the/miro_lib/mirolib.glb <modelname>, e.g:

> gamslib -lib /location/to/the/miro_lib/mirolib.glb sudoku

To get a feeling for the use of GAMS MIRO, we recommend to have a look at the demo applications first which you can download here. To use the demo applications, simply unzip the archive. You will find the demo applications in a directory miro_lib_gampsy from where you can directly run the apps.

Start GAMS MIRO

Let's take the famous trnsport example from George Dantzig to guide us through this documentation: We own a bunch of factories and wish to find a least cost shipping schedule that meets the demand at markets we are shipping to. Furthermore, the capacity constraints of our factories must not be violated.

• GAMS
• GAMSPy

In order to launch the MIRO app for this model from within GAMS Studio, we open the model from the GAMS MIRO model collection and choose Run Base Mode from the MIRO menu.

Note:

If you start MIRO via GAMS Studio, note the group in which your model is located in the project explorer. In a group there is always a main file. 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 on the file in the project explorer → set as main file:

In order to launch the MIRO app for this model via the GAMSPy CLI, we simply navigate to the transport directory within the miro_lib_gampsy directory and execute the following command:

> gamspy run miro --mode="base" --model transport.py [--path <path_to_your_MIRO_installation>]

where <path_to_your_MIRO_installation> is the path to your MIRO executable file (e.g. C:\Program Files\GAMS MIRO\GAMS MIRO.exe on Windows, /Applications/GAMS MIRO.app on macOS or ~/GAMS-MIRO-2.9.0.AppImage on Linux). You can omit --path in case MIRO is installed in one of the standard locations on Windows or macOS.

Note that you can also set the MIRO installation path as an environment variable: MIRO_PATH, so that you do not have to enter it every time you use the GAMSPy CLI.

Skip model execution:

GAMS Studio/The GAMSPy CLI allow you to "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.

• GAMS
• GAMSPy

But: This option should be used with caution!
If the model execution is skipped, the GAMS/MIRO data contract is not created or renewed. 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) via the command line instead of skipping the model execution completely. This will only compile 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 input data and no output data.

Advanced: Start MIRO using the command line

In case you want to launch MIRO from the command line, the data contract between GAMS and MIRO must be created first (<modelname>_io.json). This happens when the model is called in GAMS with the option IDCGenerateJSON=path/to/conf_<modelname>/<modelname>_io.json.

For the transport model this would result in the following call:

> gams transport.gms IDCGenerateJSON=conf_transport/transport_io.json

While GAMS Studio automatically creates the required folder conf_modelname when launching MIRO, this does not happen when GAMS is called from the command line, so you have to create it manually. Once the model has been run with IDCGenerateJSON, the file conf_<modelname>/<modelname>_io.json should have been created.
Note: Whenever changes are made to the model that are relevant for MIRO (i.e. symbols tagged with $onExternalInput / $offExternalInput or $onExternalOutput / $offExternalOutput have been changed), the data contract must be updated!

Tip:

When launching MIRO via GAMS Studio, you will find a scenario named default in the database after the startup. When starting MIRO via the command line you can create this default scenario with the GAMS option IDCGenerateGDX=data_<modelname>/default.gdx.

Before you can start MIRO, a few environment variables need to be set. On Windows the default installation location is C:\Program Files\GAMS MIRO\GAMS MIRO.exe or C:\Users\<user>\AppData\Local\Programs\GAMS MIRO\GAMS MIRO.exe depending on whether MIRO was installed for all users or not.

• Windows
• macOS
• Linux

> set MIRO_DEV_MODE=true
> set MIRO_MODEL_PATH=C:\Users\<user>\Documents\GAMSStudio\workspace\transport.gms
> set MIRO_MODE=base
> "C:\Program Files\GAMS MIRO\GAMS MIRO.exe"

> export MIRO_DEV_MODE=true
> export MIRO_MODEL_PATH="/Users/<user>/Documents/model/transport/transport.gms"
> export MIRO_MODE=base
> "/Applications/GAMS MIRO.app/Contents/MacOS/GAMS MIRO"

> export MIRO_DEV_MODE=true
> export MIRO_MODEL_PATH=/home/<user>/model/transport/transport.gms
> export MIRO_MODE=base
> /GAMS-MIRO-1.0.AppImage

Note:

By default MIRO uses the GAMS version, which is in the PATH of your operating system. By setting another environment variable GAMS_SYS_DIR, you can tell MIRO where to look for GAMS instead. Note that at least GAMS version 30.2 is required to use MIRO.

> gamspy run miro --mode="base" --model <path_to_your_model> --skip-execution [--path <path_to_your_MIRO_installation>]

But: This option should be used with caution!
If the model execution is skipped, the GAMS/MIRO data contract is not created or renewed. This means that changes made in the model are not communicated to MIRO.

Structure of GAMS MIRO

Below you see the input mask as it appears after the launch.

The screen is essentially divided into two parts:

Navigation bar:

On the left side you can find the navigation bar. Here you can switch between different views:

1. Input:
   Visualization & configuration of input data for the next GAMS run.
2. Output:
   Visualization of output data.
3. GAMS interaction:
   While solving a model with GAMS this section shows the current status of your run as well as the log and listing (lst) files (listing file is not displayed when using GAMSPy). You can add a custom log here too.
4. Load scenarios:
   "Slice & dice" the database to fetch those scenarios you are interested in.
5. Compare scenarios:
   Module for the comparison of results / scenarios in a split view mode or two different multi-scenario comparison modes.

In addition, the buttons for loading input data and for starting a GAMS run are located here:

1. Load data:
   Load input data for a model run. This can be a local file or existing data from the database.
2. Solve model:
   Solve the GAMS model with the current set of input data. This will run your GAMS model and collect the results when it finished executing.

Main window:

The main window always displays the content of the section selected by the user in the navigation bar. Here, for example, data is visualized, scenarios are compared and analyses are carried out. In the screenshot above you can also see a README section that is displayed to the user.

Besides navigation bar and main window, some functions are accessible in the header bar:

• Scenario:
  Scenario management - load, save, edit, delete and export scenario data.
• Help:
  Link to this documentation, the GAMS Forum, the command palette with access to all keyboard shortcuts and license information.

There are several ways to use GAMS MIRO. However, a typical workflow could look like this:

1. Import input data
2. Modify the data
3. Solve GAMS model
4. Inspect the results (in the form of tables and/or charts)
5. Save the scenario data or discard the results

• In addition, already saved results can be re-imported and compared at any time.

Import data

A GAMS MIRO app is quite useful if there is data to be visualized, e.g. in the form of tables, diagrams or other charts. This applies to output data as well as input data. Data that is to be visualized in MIRO can be imported either from existing scenarios in the database or via a local file (currently, this can be a MIROSCEN file, a GDX container, an Excel spreadsheet, or CSV files). A MIROSCEN file is a special file format used by MIRO to export and import a complete MIRO scenario. In contrast to other supported file formats like GDX, Excel or CSV, a MIROSCEN file includes metadata such as tags, views, attachments etc.

To import such data, click on the Load data button in the navigation bar. The following dialog pops up:

Local Files

To import a file from your local machine, either in the form of a MIROSCEN file, a GDX container, an Excel spreadsheet or a CSV file, select the menu item Local and click on browse. Navigate to the directory where your file resides and select it. Confirm the data import with a click on import. If you started with an empty sheet, a new, unnamed scenario is now shown in the interface. To save it, click on Save as and give it a name.

Note:

When importing CSV data, delimiters other than the comma are also supported. The currently supported delimiters are: , tab ; | :.

Excel spreadsheet - import rules

If you want to import data from a spreadsheet, it must either contain an index sheet describing the layout of your data, or it must meet certain criteria regarding the format in which the data is provided.

Workbook without index sheet

If you do not want to create an index sheet, your Excel file must meet strict requirements:

• Only one GAMS symbol per worksheet
• The name of a sheet must be identical to the symbol name
• The first line must contain the column headers. The names of the column headers are ignored.
• All symbols must be in list view (no columns may be pivoted). The only exceptions to this rule are tables, where the last column must be pivoted.

The image below shows a valid spreadsheet for the transport model:


For scalars there are 2 possibilities:

• Either all scalar values are combined in one tab named _scalars or _scalars_out (separate sheets for input and output scalars). These tables must have 3 columns: scalar, description and value.

• Alternatively, each scalar value is stored in a separate sheet as with other symbols (tab name = symbol name). The "table" then consists only of the scalar value in cell A1. There is therefore no header.

• If you want to import command line parameters/GAMS options, the symbol name must be preceded by _gmspar_ or _gmsopt_ (see screenshot above).
• To import scalar output variables and/or equations, the sheet name must be _scalarsve_out. The table has to have 7 columns: scalar, description, level, marginal, lower, upper, scale.

Workbook with index sheet

If you want more flexibility, you must create an index sheet that describes your layout. If you are already familiar with GDXXRW, this will already be familiar to you. You can skip most of this chapter, but be aware of the differences between GDXXRW and MIRO that we list below. We encourage everyone to read the documentation of GDXXRW, especially the chapter about the index option, as it covers the topic in much greater detail than we will do here.

When the layout of your data differs from the default layout described above, you need to tell MIRO where to find what. This can be achieved by a so-called index. Here you list all the GAMS symbols that are included in your workbook as well as the layout they are in.

Note:

Unlike GDXXRW, MIRO already knows a lot about your data from the GAMS/MIRO data contract. This means that information such as the dimensions of your symbols is known to MIRO and does not need to be specified again.

The first three columns of the index range have a fixed interpretation: dataType, symbol identifier and dataRange. Even though MIRO does not need and ignores the dataType information (except dSet, see info box below), it is a good practice to specify it because it allows your worksheet to be read by both MIRO and GDXXRW.

The fourth and subsequent columns can be used for additional options. The column heading indicates the option name and the cell contents indicate the option value. Note that although GDXXRW allows options also in a comma-separated option=value format, MIRO does not support this.

Domain Sets (dSet):

Just like GDXXRW, MIRO supports reading a set as domain set by specifying it as type dSet. This option is supported only for one-dimensional sets. Duplicates and set text are ignored. The dSetText option is also supported by MIRO.

Note that in most cases, it is preferred to use the Implicit Set Definition feature of GAMS! This avoids domain violations caused by having to maintain two tables in MIRO.

Let's look at an example:

The first thing you may notice is the name of the index sheet: _index. Although the index could be on any sheet and in any range, MIRO can automatically recognize it if the sheet is named _index and the index table starts in the upper left corner: A1. The most important information MIRO requires is the symbol name, range (columns B and C) and one of rDim (row dimension) or cDim (column dimension). If neither rDim nor cDim is supplied, MIRO will assume a default of 1 for cDim. This means that the last column is pivoted as is the case for the parameter d:

You can see that the last column (index j) is pivoted. Also note that we can ignore rows and columns via the ignoreRows and ignoreColumns options. In this example, we want to ignore the row 16 because it does not belong to the data for d, but for the set j, which is also read from the same range (sheet1!L15:N16). This brings us to the next option: values. Each tuple in a set can have associated text. To read a set from a spreadsheet, the values option is used to indicate whether there is data, and if so, whether the data should be interpreted as associated text or as an indicator of whether or not the tuple should be included in the set. In our example here, we use the YN option, which specifies that only tuples that have a data cell that is not empty and does not contain 0, N, or No will be included. This means that in our example j only the tuple New-York is read. MIRO supports all options GDXXRW supports: auto, noData, YN, sparse and dense. See the related section of the GDXXRW documentation for more information on the other options. Below you find a list of all options supported by MIRO.

Supported options

Option	Description	Allowed values
range	Excel range: Open and closed ranges are supported. It must be of the form SheetName!TopLeft:BottomRight. If the sheet name is omitted, the first sheet in the workbook is used by default. If the BottomRight corner is omitted, the data is read until skipEmpty+1 empty rows/columns are found. If range is omitted, an open range with left upper corner A1 is assumed.
rDim	Row dimension: the number of columns in the data range that will be used to define the labels for the rows. The first rDim columns of the data range will be used for the labels.	0..dim
cDim	Column dimension: the number of rows in the data range that will be used to define the labels for the columns. The first cDim rows of the data range will be used for labels.	0..dim
values	How set data is handled. See the related section of the GDXXRW documentation for more details.	auto, noData, YN, sparse, dense
ignoreRows	Rows to ignore	comma-separated list of positive integers
ignoreColumns	Columns to ignore	comma-separated list of positive integers or column letters
skipEmpty	When reading an open range, controls how many empty rows or columns will be ignored before the next empty row or column indicates the end of the block	0, 1
squeeze	Controls whether zeros are squeezed out/removed	y, 1, n, 0
dSetText	This controls the reading of explanatory text for set elements of domain sets. By default, no text is read for domain sets. If this option is activated this is changed. If an element appears more than once, the first one defines the explanatory text read.	y, 1, n, 0

Reading scalars

In addition to reading each scalar individually as supported by GDXXRW, MIRO also supports reading in table form. To read an entire table of scalars, you must do so using the special _scalars/_scalars_out symbols for input and output scalars, respectively. In this way MIRO reads scalars grouped in a table with 3 columns: Scalar, Description, Value. The Description column can also be omitted. Let's look at our example again:

If we look at the corresponding index sheet again, we see that both the output scalar total_cost and the input scalar table _scalars are defined on this sheet. In this example, the table is pivoted (scalar names in the columns) and the Description column has been omitted.

Note that you can mix the declaration of table and individual scalars. Scalars that are missing from the table are appended if they are individually declared. If a scalar is found both in one of the special tables and individually declared, the scalar in the table takes precedence and the individually declared scalar is ignored.

Note:

Command line parameters/GAMS options are treated like normal input scalars with the special prefixes _gmspar_ and _gmsopt_.

Differences between GDXXRW and MIRO

Below we list the important differences you need to be aware of when migrating from GDXXRW to MIRO or vice versa.

• Global options are not supported by MIRO: all options are symbol-specific and must be part of the symbol declaration row
• The only special values supported by MIRO are: +Inf and -Inf. Eps, YES, NO, NA, Undef, etc. are not properly recognized when used in MIRO
• Acronyms are not supported
• The only options supported by MIRO are: rDim, cDim, dim, values, ignoreRows, ignoreColumns, skipEmpty, squeeze
• Option=value columns are not supported and will be skipped. Please specify the option names as column headers and the values as cell contents.
• skipEmpty must be specified for each symbol individually. The state of this option is not transferred to the next symbols as with GDXXRW.
• Named ranges are not supported.
• Ranges with .. instead of : as separator between TopLeft and BottomRight corner are not supported.
• skipEmpty > 1 is not supported i.e. only values 0 and 1 can be used
• It is possible to read variables/equations with MIRO. They are treated like normal parameters, with an additional dimension that must contain at least one of the following elements: level, marginal, upper, lower and scale. These do not all have to be assigned, i.e. you can skip some.
• When reading scalars, you can either declare them individually as in GDXXRW, or you can use the special symbol names _scalars/_scalars_out to read input/output scalars grouped in a table with 3 columns: Scalar, Description, Value. The Description column can be omitted. You can also mix declaration of individual scalars and scalar tables. Scalars that are missing in the scalar table are appended if they are declared individually. If an individually declared scalar is also in a scalar table, the individually declared scalar is ignored.
• In tables/variables/equations, if squeeze=1, empty cells and NA are indistinguishable
• Output scalar variables and equations must be in a single table named _scalarsve_out with dimensions: scalar, description, type, where type must not contain any elements other than: level, marginal, upper, lower, scale. Please note that the Description dimension must be present (unlike the _scalars/_scalars_out tables), but is ignored when MIRO imports it.

Instead of importing all the datasets for your model, you can also select the symbols to import manually. To do so, click on Manually choose datasets and choose those symbols to be imported from the uploaded spreadsheet. This will cause MIRO to ignore other datasets.

Data manipulation

The tables that were empty before are now populated. In the upper part of the main window, you can navigate between different tabs to switch through the different GAMS symbols that you have specified in your model.
We can now change the input data. You may want to edit individual cells, sort by a different column or add/remove entire records (rows in the table). In our transport demo you have the option to edit the capacities, the demand, the distance matrix and several scalar values:

Data cleaning

Your input data must not contain duplicate records. MIRO can help you automatically find and remove duplicate records in your input data sets using the Scenario → Remove duplicates menu in the header. MIRO first checks if any of your input records contain duplicate records, and gives you the option to keep only the first or only the last occurrence of the duplicate.

Solve the model

A click on the Solve model button starts the model run. In the background GAMS is called and the model transport.gms is started. The values set by us in MIRO now serve as input data for the model.
During the calculations, MIRO automatically switches to the section GAMS interaction. There you can see the current GAMS log and lst files. If you specified a custom log this is also shown here.

Note: Since the models of the demo applications are solved very quickly, this step is sometimes hardly visible. The menu entry GAMS interaction can also be viewed at any time after a model run.

As long as the calculations are running in GAMS, the Stop button on the left can be clicked. A first click on this button sends an interrupt request to the running job in order to perform a graceful stop and collect an incumbent result back from the execution if the solver supports this feature. A second click sends a request to stop the running job immediately.
After the run, the view changes again to the Output section.

Inspect results

In the Output section the results are visualized. As with the input data, a distinction is made between GAMS parameters and scalar values. The GAMS parameters are each visualized in a separate tab and the scalars are summarized in a table.
If you have configured a graphical representation of your data, you can also see it here. In the model Transport a plot for the transport schedule is configured in the form of a map, see figure below.

With a click on the button in the upper right corner you can switch between a plot and the tabular representation of the data.

The Costs tab shows the objective function value of the model calculation in a tile. Like before, you can switch between graphical and tabular representation with a click on the button.

Download temporary files:

If this option is enabled, all temporarily created files of the model run (like solution reports or the lst and log files) can be downloaded either separately or as a ZIP archive with a click on the button.

Save / export / delete a scenario

The set of all the input and output data is what we call a scenario. Data that is currently loaded in the MIRO interface (in memory) is what we call a sandbox scenario (more on this here). A sandbox scenario can be saved at any point. The menu where you can interact with your currently active scenario can be found in header bar of your MIRO app:

• Edit metadata
  Allows you to edit scenario metadata, i.e. the scenario name and/or the tags assigned as well as file attachments and scenario access permissions. Read more about scenario metadata here.
• Save
  Saves the currently active sandbox scenario under an already specified name. Data of the initially loaded scenario is overwritten.
  
  
  Tip:

  Unless otherwise configured, the log and lst file of the GAMS run will also be saved and can be accessed when re-loading the corresponding scenario.

• Save As
  Saves the currently active sandbox scenario under an new name. If the sandbox scenario has no name yet, only this option is available for saving.
  
  Optionally, you can add tags to the scenario. Tags are stored together with the scenario data. If you want to find a scenario later on, you can search for a given tag. This may help you to better find a certain scenario or a set of scenarios that share certain attributes. Also, if your sandbox scenario contains attachments or you have defined user access permissions, you can adopt these settings for the scenario to be saved.
• Export
  Download of the scenario data in the form of a MIROSCEN file, a GDX container, as an Excel spreadsheet or as CSV files.
• Delete
  Delete the scenario from the database.

Finding and loading scenarios

To help you find and load exactly the scenarios you are interested in, MIRO has a powerful Batch Load module that graphically assists you create and execute complex database queries.

Filters can be applied to scenario metadata such as the creation time, scenario name, or optional tags you have assigned to a scenario. You can also filter by any input and output scalars defined in your model as well as any Double-dash parameters and GAMS options. You can combine any of these filters with the logical operators AND and OR:

You can execute your query by clicking on the Fetch results button. After the results have been retrieved, the page will be updated and you will see a table with the scenarios that correspond to your query.

Once you have found the scenarios you were looking for, you can do one of the following:

• Delete scenarios:
  Remove the selected scenarios.
• Download data:
  Download scenario data for external analysis. Here you can find an example of such an external analysis. The data of selected scenarios were analyzed using R in combination with Jupyter Notebook.
• Analyze:
  Run one of your customized batch analysis scripts (only visible if you have custom analysis scripts set up).
• Load into sandbox:
  Load the selected scenario into the sandbox (only visible if you have selected exactly one scenario).
• Compare:
  Interactive scenario comparison: Compare different scenarios directly in split, tab or pivot view. Best suited for a small number of scenarios to be compared (maximum allowed number of scenarios: 10).

Scenario comparison

The scenario comparison mode is useful if you want to compare the input and/or output data of different model runs. Scenarios from the database as well as the currently loaded sandbox scenario can be used for comparison. There are three different types of comparison available, split view, tab view and pivot view mode.

Pivot view

Unlike the split view and tab view, which take your chart configuration into account, here all records are displayed as pivot tables. Also note that the pivot view comparison mode always compares the sandbox scenario with other scenarios. The sandbox scenario is therefore also called base scenario in this context.

The data of the sandbox scenario and all selected scenarios are merged into a single table with an additional domain: Scenario. You can add/remove scenarios at any time by clicking the button in the upper left corner. To close the scenarios currently loaded in the pivot mode, click the button in the upper right corner. If you have made changes to your sandbox scenario and want to update the data in the pivot view, click the button.

Views can also be used in pivot view mode. They are attached to the sandbox/base scenario. Thus, the scenario you currently have in your sandbox determines what views will be available to you in the pivot view scenario comparison. To save a new view, you only need to save your sandbox scenario once the new view has been added.

Views from the pivot view comparison mode can be managed (imported/exported/deleted) just like normal views via the Views dialog in the Scenario → Edit Metadata menu. You can learn more about views here.

Tip:

If you have opened scenarios in the split or tab view mode and switch to the pivot view, the scenarios from these modes are pre-selected in the load dialog so that you can easily continue using them.

Split view

If two scenarios are to be compared, the split-screen view is particularly suitable. Here the data of two scenarios can be compared side by side.

You can choose between:

• Load scenario:
  Load saved scenario data from the database.
• Load sandbox:
  Load the sandbox scenario which is opened in the Input / Output section.

Tip:

If you have opened scenarios in the pivot or tab view mode and switch to the split view, the scenarios from these modes are shown in a "Local" tab.

Tab view

Scenarios can also be loaded into tabs (as you know it from e.g. your internet browser). This allows to compare more than two scenarios including their graphics.

Tip:

If you have opened scenarios in the split or pivot view mode and switch to the tab view, the scenarios from these modes are pre-selected in the load dialog so that you can easily continue using them.

To understand the concept of data exchange between the GAMS model and its MIRO application, let's start with the following illustration:

1. Data is loaded into the MIRO interface. These come either from the internal database, from external data sources such as Excel or GDX or are entered manually, but they do NOT come directly from the GAMS model.
2. When clicking on solve, the data visible in the MIRO input section is sent to the GAMS model. All data of affected symbols in the model will be overwritten. Symbols that are not visible in MIRO are not touched.
3. The model is now run with the updated data.
4. Afterwards the results are sent to MIRO and displayed in the output section. From there, data can be saved in the internal database and/or exported as a file.

A little more detail:

In addition to the data concept, MIRO's scenario concept also needs to be understood.

In addition to the classic data of a scenario, which is visualized in the form of tables, widgets and graphics and with which the user interacts primarily for and after a model run, a scenario also consists of metadata. Metadata can be edited under Scenario → Edit metadata. This includes the following:

Attachments

With the attachments option, you can attach files to the (sandbox) scenario you currently have open. These can be files of any format. MIRO distinguishes between attachments that can be seen and read by your GAMS model and files that can not be seen. For example, if you want to provide data to your model that doesn't need to be visible/modifiable in the UI (e.g. in the form of a GDX container or Excel files), attachments that your model can read are what you are looking for. In case you just want to add some report about a particular scenario, which is irrelevant for the GAMS model, you should not allow the model to read this file. Note that all files that you allow your model to read need to be first downloaded into the working directory before GAMS is executed. Thus, it is advisable to select only those files to be readable that are actually relevant for the optimization run.

Besides this type of attachments, there are also output attachments which allow you to automatically attach files after a GAMS run has been successfully completed. This lets you store additional results alongside the ones displayed in the UI. You can also use such an attachment for the next GAMS run with this scenario. Read more about output attachments here.

Note:

Attachments added to a sandbox scenario are not automatically saved! If you want to apply the changes to a database scenario, you have to save it.

Views

Views are a special type of attachments that store configurations of renderers. An example is the pivot table renderer. Here a view is a snapshot of the current configuration. Below you can see two pivot table views side by side.

Views can either be bound to a scenario like attachments or registered app-wide. From now on, scenario-specific views will be referred to as local views, while app-wide views will be referred to as global views. You can import and export view configurations in the form of JSON files. Each view has an id that has to be unique per GAMS symbol.

Tip:

Views can also be imported automatically when a MIRO application is started by placing the JSON file(s) in the folder data_<modelname>. Note that views are always tied to a scenario. If you want to store views for a scenario called "my-scenario", you would have a GDX file called my-scenario.gdx as well as a views file called my-scenario_views.json inside the data_<modelname> directory. So the file name of the views must start with the name of the scenario you want to attach them to and end with _views.json.

To get a more intuitive understanding of what a view is, the following videos give an example that leads through the most important aspects. With the pivot table renderer, we can filter and aggregate input and output data by dragging and dropping domains. The video below shows how a few actions draw a stacked bar chart of the shipment quantities between canning plants and markets. By clicking the Add View button we can attach a local view to the current scenario. This allows us to return to a configuration later in our analysis.

We can import, download, and remove local views by navigating to the Scenario → Edit metadata → Views dialog. By clicking the Export button, the selected views are saved in the Download folder as a JSON file, which we can use to share with others or to include as global views in the app.

Global views are bundled with a MIRO app and are scenario-independent. A local view can shadow a global view if it has the same name as the global view. This means that when you apply this view, the configuration of the local view is applied. When the local view is removed, the global view is applied again.

Global views can be bundled with an application by placing a JSON file with the filename views.json in the conf_<modelname> directory. This file can also be created automatically by configuring the views via the Configuration Mode.

Access permissions / Scenario sharing

If multiple users have access to the same MIRO app, they can share scenarios. Shared scenarios can be loaded from the database into the sandbox in the same way as your own scenarios.

Since scenario sharing is much more powerful using MIRO Server, you can find more information about this in the MIRO Server section.

Scenario sharing using MIRO Desktop:
Scenarios can also be shared in MIRO Desktop. However, unlike MIRO Server, MIRO Desktop does not offer sophisticated user management including user groups. Users of a local MIRO Desktop application are automatically assigned to the only group available, 'users'. As a consequence, scenarios can be shared either with all users ('users' group) or with no users.

Note:

In contrast to the database used by GAMS MIRO Server, the database for MIRO Desktop is not designed for concurrent use. We therefore recommend to use one database per user for MIRO Desktop applications.

The size and/or complexity of a GAMS model does not affect the performance of a MIRO application. As the data concept shows, only data declared as external input and output (data contract) is communicated between the model and the application. The amount of data to be exchanged as well as the complexity of its visualization influence the performance of your application. Important factors are:

• Number of symbols that are communicated with MIRO
  The more symbols you want to display in MIRO, the more tables and charts need to be set up. MIRO renders most of them lazily, that is, only when the user actually activates a particular tab. However, each of the symbols has a slight overhead and you should ask yourself whether displaying all of them is really necessary. For example, it is usually not a good idea to declare each domain set separately as external input. Instead, use the Implicit Set Definition feature of GAMS! This not only saves rendering time in MIRO, but is often better for the user experience as it simplifies data entry. As a rule of thumb, try to limit the number of symbols in your data contract to 50.
• Amount of data that is communicated with MIRO
  Each dataset is displayed in MIRO in the form of a table and a graph. The larger the amount of data, the more computationally intensive this process becomes. In addition, the rendering of graphics can vary in complexity. While a simple pie chart is usually rendered fairly quickly, graphs that contain animations can take significantly more time. In the case of very large amounts of data that are only displayed in MIRO for visualization purposes, it may make sense from a performance point of view to communicate only parts of the data with MIRO or to visualize only sections of it, e.g. by aggregating data.
• Table tool to use
  MIRO provides several table tools for input symbols, each of which has its advantages and disadvantages. The default input data tool provides a spreadsheet-like feel. However, all data is held in the user's browsers, which becomes problematic when dealing with large amounts of data. If you have larger data sets (>10,000 records and >10 columns), MIRO offers the Big Data Table as well as the MIRO Pivot Table. With these two table types, most of the data is kept on the server side and only fractions of the data are kept in the user's browser. This allows for much larger data sets (>3 million records).
• Attachments provide a convenient way to communicate large amounts of data from MIRO to the GAMS model without significantly impacting application performance. Since attachments are communicated as a file and therefore do not require data to be rendered, they require very few computational resources.

Manage multiple scenarios

In this chapter we learned how to configure and solve one scenario at a time. But what if we want to efficiently solve a large number of such scenarios with different parameterizations? To avoid having to configure and solve each scenario individually, there is an option to submit so-called Hypercube jobs. Hypercube jobs allow you to efficiently and automatically create, store and analyze a variety of scenarios. Learn more here.

GAMS MIRO Server

In the most basic setup - GAMS MIRO Desktop - both the MIRO application and GAMS are installed on the same computer and run exclusively on this machine. But MIRO is not limited to this setup: You may also trigger your GAMS jobs to be solved in the cloud. For you nothing changes, the interface remains the same. GAMS MIRO Server also allows you to run both the GAMS execution engine as well as GAMS MIRO in a highly scalable cloud environment. Your optimization applications can then be accessed from any modern web browser.

GAMS MIRO Server adds multi-user and authentication support as well as many enterprise features such as load balancing, rolling updates and much more.