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.
This chapter guides you through the first steps of using GAMS MIRO and shows you how to deploy your own GAMS models.
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.
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:
The following demos are available:
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.
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.
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.
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 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.
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) instead of the option "Skip model execution". 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.
Below you see the input mask as it appears after the launch.
The screen is essentially divided into two parts:
On the left side you can find the navigation bar. Here you can switch between different views:
In addition, the buttons for loading input data and for starting a GAMS run are located here:
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 functions are accessible in the header bar:
Take a look at our cheat sheets to get to know the MIRO interface and its components better!
There are several ways to use GAMS MIRO. However, a typical workflow could look like this:
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 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 dialog pops up:
You can decide whether you want to import an existing scenario from the database or load a file from your local computer. Scenarios that you have previously named and saved in the MIRO database will be displayed in Database. When you start a GAMS MIRO app for the first time, GAMS automatically extracts the data from your model and loads this data into the database. This happens every time you rebuild your MIRO app i.e. every time you launch it in the development mode via GAMS Studio or the command line. A special scenario with the name default is created for this purpose and overridden every time you rebuild your app!
Every time you start a MIRO app in development mode (via GAMS Studio or the command line), 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, 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.
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.
Besides the local and the database import there is a third option: Hypercube. This tab allows you to import scenarios that have been generated and saved in the Hypercube mode. Such a scenario that is generated in Hypercube mode corresponds to a scenario from the base mode, except that the former additionally contains a trace file. Since those 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.
Please refer to the chapter about scenario selection in Hypercube mode to learn how to retrieve the hash value of a Hypercube scenario.
Import multiple scenarios on startup
In addition to the options mentioned above, which can be accessed directly from MIRO, (multiple) scenarios can also be imported automatically when starting an application. To do this, the scenarios to be imported (GDX or Ecxcel file) must be put in the folder data_<modelname> (located in the model directory). With the next start of MIRO, those scenarios are imported automatically.
All files in the data_<modelname> folder are deleted after they have been imported.
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:
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.
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.
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 button.
If this option is not disabled, 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.
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:
Here, we can choose between the following options:
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.
In the general options tab you can change the scenario name and add/edit scenario tags.
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 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.
Attachments added to a sanbox scenario are not automatically saved! If you want to apply the changes to a database scenario, you have click on save.
With access permissions you can determine who can access your scenario. You can differentiate between read permissions (users can load the scenario but are not authorized to edit or execute it), write permissions (users can edit the scenario), and execution permissions (users can solve the model with your scenario data).
If you edit metadata, the changes will initially only affect the loaded sandbox scenario. You have to save the scenario, so that the changes are stored in the database and are available at a later stage.
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 two different types of comparison available, split screen mode and tab view mode.
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.
If you are in the split screen view, you can load scenarios you want to compare.
You can choose between:
Via the 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, scenarios can be loaded into tabs (as you know it from e.g. your internet browser). This allows to compare more than two scenarios. You can use the button in the navigation bar to switch between the splitscreen view and the display of scenarios in tab pages.
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. It can be used in both the split screen and the tab view. 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 dataset to be displayed in one scenario (e.g. switch from 'Price' to 'absolute error' in the image above), the view also changes for all the other scenario(s) loaded in the comparison mode.
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!
To understand the concept of data exchange between the GAMS model and its MIRO application, let's start with the following illustration:
A little more detail:
In addition to the data concept, MIRO's scenario concept also needs to be understood.
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.
In the most basic setup - GAMS MIRO Desktop - both the MIRO application and GAMS itself 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. If you are interested in this version, please contact us!