Getting started

Introduction

This chapter shows the first steps of how to use GAMS MIRO and how to deploy your own GAMS models. For using this application a few components have to be installed first, see section Installation.

In this as well as the subsequent sections we will mainly deal with the GAMS 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. The Hypercube mode will be the subject of an extra section, see here.

Start GAMS MIRO

Demo Applications

To get a feeling for the use of GAMS MIRO, it is recommended to have a look at the demo applications first. They can be found in the GAMS data utilities library. You can get them e.g. in GAMS Studio via GAMS -> Model Library Explorer or via the shortcut F6. You can also find those demo applications here.

GAMS MIRO beta:

In order to use the GAMS MIRO BETA version, a special installation is necessary. Until an official release of GAMS MIRO, the demo models will only be available via this special version in the data utilities library.

The following demos are available:

  • transport
    This problem looks for a least cost shipping schedule that meets requirements at markets and supplies at factories. More about this transportation problem, see here.
    Note:

    The well-known model from the GAMS model library is called trnsport. To avoid two models of the same name, the GAMS MIRO Demo model is called transport.

  • transport_live
    A "live" version of the transport model. Extends transport in the sense that locations of suppliers and markets can be adjusted right from within MIRO. Geographical information about the cities you entered is automatically fetched and the distance matrix calculated via embedded Python code.
    This model needs an internet connection.
  • pickstock
    Optimization model to find a small subset of stocks of the Dow Jones index together with some weights, such that this portfolio has a similar behavior to the overall index.
  • kport
    This problem computes minimal cost solutions satisfying the demand of certain product portfolios. More about this optimization Problem, see here.
To launch one of the demo applications from within GAMS Studio, simply click the Launch MIRO button or press F11.
Launch MIRO button
In order to launch MIRO from the old GAMS IDE or via the command line, the GAMS option statement miro=launch has to be added to the command line (e.g. cd path/to/model && gams transport.gms miro=launch).

Note: To run GAMS MIRO from the command prompt, it has to be either added to the PATH environment variable of your operating system or called with an absolute path!

Structure of GAMS MIRO

Let's take the famous trnsport example from George Dantzig to guide us throgh 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. In order to launch the MIRO app for this model, we open the transport.gms file in GAMS Studio and run it with the GAMS command line parameter miro=launch.

Once all the packages have been loaded, the MIRO app will start. Below you see the input mask as it appears after the launch.

initial GAMS MIRO screen

The screen is essentially divided into two parts:

Navigation bar:


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

  1. Input:
    Visualization & configuration of input data for the next calculations.
  2. Output:
    Visualization of calculated 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 Lst files.
  4. Compare scenarios:
    Module for the comparison of results / scenarios in a split screen mode or a multi-scenario comparison mode (also referred to as tab view).

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, existing data from the database or scenarios coming from the Hypercube mode.
  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.

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

  • Scenario:
    Scenario management - load, save, edit, delete and export scenario data.
  • Help:
    Link to this documentation and license information.

How to work with GAMS MIRO

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

  1. Import input data
  2. Modify the data if desired
  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. Input data that is to be visualized in MIRO can be (re-)imported either from existing scenarios in the database or via a local file (currently, this can be either a gdx container or an Excel spreadsheet). To import such data, click on the Load data button in the navigation bar. The following window pops up:

Database import
Local Import


You can decide whether you want to import an existing scenario from the database or load a spreadsheet from your local computer. When you start a GAMS MIRO app for a specific GAMS model for the first time, GAMS automatically extracts the data from your model and loads this data into the MIRO database. This happens every time you rebuild your MIRO app i.e. every time you launch it from GAMS Studio or via the GAMS option miro=launch. A special scenario with the name default is created for this purpose and overridden every time you rebuild your app!

Note:

Every time you start a MIRO app in development mode (via GAMS Studio or the GAMS option miro=launch), the data relevant to MIRO is extracted from your model and stored in the MIRO database as a special scenario named default.

To import a file from your local machine, either in the form of a gdx container or as an Excel spreadsheet, select the menu item Local and click on browse. Navigate to the directory where your file resides and select it. Now assign a name for the new scenario and confirm the data import with a click on import. A new (currently still unsaved) scenario is now created under the name specified.

Tip:

Instead of importing all the datasets for your model, you can also load individual symbols of your input data. For this click on Manually choose datasets and select the desired symbols to be imported from the selected spreadsheet. The other data remain unchanged.

Besides the local and the database import there is the third option: "Hypercube". This tab allows you to import scenarios that have been generated and saved in the Hypercube mode. Since Hypercube scenarios are identified by their hash value (read more about this here) and not by a user-defined name like in base mode, you need to import them differently.

Import scenario via hash value

Please refer to the chapter about Hypercube scenario import if you do not know how to get the hash value of a Hypercube scenario.

Data manipulation

The tables that were empty before are now filled with some data. 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. More about the tabular and graphical representation of input data in MIRO is explained here.
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:

Input data screen
With the help of sliders and a dropdown menu we can now adjust the freight costs and the model type to be used. If we are satisfied with the settings we can start the GAMS run.

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 the previous section 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.

GAMS interaction screen

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. This immediately stops the running GAMS process and thus the model calculations.
After the run, the view of MIRO changes to the Output view.

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. GAMS parameters are each visualized in a separate tab and scalars are combined in one table.
If you configured a graphical representation of your data, it can also be seen here. In the transport model a plot is configured for the only present output parameter in the form of a map, see image below.

Output data screen

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

All scalar results are summarized in Output Scalars. The default visualization selected here are tiles. Like before, you can switch between graphical and tabular representation with a click on the Switch to tabular view button button.

Output data screen - scalars

Tip:

All temporarily created files of the model run (like solution reports or the lst and log files) can be downloaded separately or as a ZIP archive with a click on the Download temporary files button.

Output data screen - scalars

Save / delete results

The set of all the input and output sheets that are visible in MIRO for a particular model run is what we call a scenario. A scenario can be saved at any point. The menu where you can interact with your currently acitve scenario can be found in header bar of your MIRO app:

Scenario data - database interaction

Here, we can choose from the following options:

  • Save
    Saves the currently active scenario.
  • Save As
    Saves the currently active scenario under another name.
    Save scenario in database
    Optionally, you can add tags to the scenario. Tags can help you better find a certain scenario or a set of scenarios that share certain attributes.

    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.

  • Edit metadata
    Allows you to edit scenario metadata, i.e. the scenario name and/or the tags assigned.
    Edit scenario metadata
    You can also attach files to a scenario here, see the section below.
  • Export
    Download of the scenario data in the form of a gdx container or as an Excel spreadsheet. The spreadsheet contains all datasets of the currently active scenario.
  • Delete
    Delete a scenario from the database.
File attachments

With the attachments option, you can attach files to the scenario you currently have open. These can be files of any format. MIRO distinguishes between two types of attachments: 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.

Scenario comparison

The scenario comparison mode is useful if you want to compare the input and/or output data of different model runs.
If two scenarios are to be compared, the split-screen view is particularly suitable. Here the data of two scenarios can be compared directly next to each other.

Integrated scenario comparison - split screen

If you are in the split screen view, you can load scenarios you want to compare. You can choose between:

  • Load scenario:
    Load saved scenario data.
  • Load active:
    Load the scenario which is opened in the Input / Output section. If you select this option, the last saved state of this scenario will be loaded.

By the way: Via the download spreadsheet button in the upper right corner you can access the input and output data which have been communicated with the GAMS model.

In addition to the split screen mode, more than two scenarios can also be compared lying side by side in individual tabs (like tabs in a browser). You can use the button in the navigation bar to switch between the splitscreen view and the display of scenarios in tab pages.

compare scenarios tab wise
Tip:

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

The comparison mode makes comparing scenarios more convenient. As soon as this option is activated via the Comparison mode button in the navigation bar, the switch to another data set of a scenario is also performed for all other open scenarios. This means that if you change the symbol to be displayed in a scenario (e.g. switch from 'Price' to 'absolute error' in the image above), the view also changes accordingly for the other currently open scenario(s).

Tip:

For many operations in MIRO there are shortcuts. Especially when comparing scenarios it can be helpful to switch through the different tabs with shortcuts. To learn more about shortcuts, check out our cheat sheets!

Additional Features

Manage multiple scenarios

The mode of GAMS MIRO that you learned about in this chapter is designed to configure and solve one scenario at a time. But what if we want to solve a multitude of such scenarios with different parameterizations one after the other? To avoid having to configure and solve each scenario individually, there is another mode built into MIRO that we call the Hypercube mode. In this mode, you can automatically solve scenarios with several different parameterizations.

We developed this mode to efficiently generate, store and analyze a multitude of scenarios. Look at the chapter about the Hypercube mode to learn more.

Run GAMS MIRO on a server

You can also run GAMS MIRO on a server. This adds multi-user and multi-application support as well as many enterprise features such as authorization via LDAP, load balancing, rolling updates and much more. If you are interested in this version, please contact us!

GAMS MIRO on a server with multi-user and multi-application support