Welcome to the GAMS MIRO Quick Start Guide. This guide is designed to provide a fast, reliable onboarding path to help you transform your existing GAMS or GAMSPy optimization models into fully functional, interactive web applications.

In the following sections, we will walk you through the essential stages of building your first MIRO app. You will learn how to establish a data contract to seamlessly link your model's inputs and outputs to the MIRO interface, launch your application to immediately interact with your data, and customize the user experience using widgets and charts. Finally, we will cover how to package and deploy your application so it can be easily shared with end users.

This quick start guide covers the most important aspects of MIRO application development. The individual aspects are explained in more detail in corresponding linked chapters.

GAMS MIRO consists of several components that work together to turn GAMS and GAMSPy models into interactive applications. Understanding these components helps clarify how models, user interfaces, and deployment workflows interact during development and operation.

In the simplest setup, all MIRO components run locally on the same machine as GAMS or GAMSPy. This setup is referred to as GAMS MIRO Desktop.

MIRO User Interface

The most visible component is the MIRO user interface (MIRO UI). It provides the interactive application shown in the browser, where users can:

• Modify model input data
• Run optimization jobs
• Analyze model results
• Create and compare scenarios

GAMS/MIRO Connector

The GAMS/MIRO connector is responsible for the communication between the optimization model and the MIRO interface. It manages the MIRO data contract and transfers model input and output data between GAMS or GAMSPy and the MIRO application.

MIRO Desktop Library

Locally deployed MIRO applications are managed through the MIRO Desktop Library. It acts as a central launcher for installed applications and also provides access to global settings such as language preferences, paths, and browser configuration.

Cloud and Enterprise Setups

Besides local desktop usage, MIRO applications can also be deployed in centralized cloud and enterprise environments using GAMS MIRO Server. In this setup, applications are hosted on a server and accessed directly through the browser, eliminating the need for local deployment on end-user machines. Optimization jobs are executed by GAMS Engine, which acts as the scalable backend infrastructure for MIRO Server and provides enterprise-grade job scheduling, execution, and user management capabilities.

• GAMS or GAMSPy: A working installation of the GAMS system (including GAMS Studio) or a Python environment with GAMSPy installed.
• File Encoding: Ensure your model files are encoded in UTF-8. Other encodings are not supported and will cause errors. In GAMS Studio you can change the encoding of your file via Edit → Encoding → convert to ... → UTF-8.

Download and Path Configuration

Download and install GAMS MIRO Desktop. After installation, make sure that MIRO and your modeling environment know about each other.

• GAMS
• GAMSPy

If you work with GAMS Studio, go to File → Settings → Remote and check whether the MIRO installation location is correct.

On the MIRO side, open MIRO Desktop and go to Preferences → Paths. Ensure that the location of the correct GAMS version is specified. Restart MIRO if you change the path.

If MIRO is installed in one of the standard locations on Windows or macOS, GAMSPy usually detects it automatically. On Linux or when using a custom installation location, set the MIRO_PATH environment variable to the path of your MIRO executable. Alternatively, pass the path each time you call the GAMSPy CLI using the --path argument.

Typical executable paths are C:\Program Files\GAMS MIRO\GAMS MIRO.exe on Windows, /Applications/GAMS MIRO.app on macOS, /usr/bin/com.gams.miro on Debian/Ubuntu if installed via a .deb file, or an AppImage path such as ~/GAMS-MIRO-2.9.0.AppImage on other Linux distributions.

On the MIRO side, open MIRO Desktop and go to Preferences → Paths. Ensure that the location of the correct Python version, i.e. the environment in which GAMSPy is installed, is specified.

Licensing Setup

For GAMS-based MIRO applications, ensure that your license includes the GAMS MIRO connector. You can check this using the Licensing dialog in GAMS Studio.

To install a GAMS license, use one of the following methods:

• Using GAMS Studio (network connection required).
• Offline or behind an HTTP Proxy: If your machine is not connected to the internet or an HTTP proxy is blocking the connection to the GAMS license server, you need to activate the license on a different machine. You can find all necessary steps here.

Choose How to Get Started with MIRO

Once your environment is set up, there are several ways to start working with GAMS MIRO:

• Explore Demo Applications: You can try out pre-deployed MIRO demo apps to instantly see the capabilities of the interface. To add these apps to your MIRO Library, open MIRO Desktop and click Edit → Add example apps. Launch any app by clicking on one of the app tiles. You can find an overview of how to work with a GAMS MIRO app here.
• Add an Existing MIRO App: If you already have a fully deployed MIRO application (a .miroapp file), you can add it directly to your MIRO Library. Simply double-click the .miroapp file or use Edit apps in MIRO Desktop to import it. See Installing and Running a developed MIRO App for details.
• Develop Your First App: If you want to turn your own GAMS or GAMSPy model into a MIRO application, continue with the development workflow starting at Step 1: Prepare Your Model Pre-configured demo applications are also available as reference implementations and starting points for your own projects. You can download them here.

Installing and Running a developed MIRO App

• Simply double-click on the <app_name>.miroapp file.

Alternatively:

• Open GAMS MIRO Desktop and click on Edit apps in the top right-hand corner.
• Click the plus () symbol in the box that appears.
• Browse for and select the <app_name>.miroapp file and click Add app.

• Click on the <app_name> tile in MIRO Desktop to start the interface.
• If no default scenario is loaded, click on Load data in the left hand menu panel and select one.
• Click on Solve model to generate results.

Using Demo Applications as Starting Points

Demo applications are a useful way to explore MIRO before building an app from scratch. They are also helpful reference projects because they show how the data contract, app configuration, and model execution fit together.

• GAMS
• GAMSPy

To work with the GAMS demo applications outside the MIRO Library, download the demo applications here, unzip the archive, and place the extracted miro_lib folder in your user model library directory. In GAMS Studio, you can find this directory under File → Settings → Misc. → user model library.

Then open GAMS → Model Library Explorer in GAMS Studio and select GAMS MIRO model collection. From the command line, you can access an app with:

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

To work with the GAMSPy demo applications, download the demo applications here and unzip the archive. The apps are located in the miro_lib_gamspy directory and can be launched directly with the GAMSPy CLI.

Before you can launch a model as a MIRO application, the model must define which symbols (sets, parameters, variables, or equations) should be available as inputs and outputs in the MIRO interface. This connection between the model and MIRO is called the "Data Contract". Symbols that are not part of the data contract are not shown in the app.

Set
   i 'canning plants' / seattle,  san-diego /
   j 'markets'        / new-york, chicago, topeka /
;

$onExternalInput
Parameter
   a(i) 'capacity of plant i in cases'
        / seattle    350
          san-diego  600 /
   b(j) 'demand at market j in cases'
        / new-york   325
          chicago    300
          topeka     275 /;
Table d(i,j) 'distance in thousands of miles'
              new-york  chicago  topeka
   seattle         2.5      1.7     1.8
   san-diego       2.5      1.8     1.4
;

Scalar f 'freight in dollars per case per thousand miles' / 90 /;
$offExternalInput

Parameter c(i,j) 'transport cost in thousands of dollars per case';
c(i,j) = f*d(i,j)/1000;

$onExternalOutput
Variable
   x(i,j) 'shipment quantities in cases'
   z      'total transportation costs in thousands of dollars'
;
$offExternalOutput

Positive Variable x;

Equation
   cost      'define objective function'
   supply(i) 'observe supply limit at plant i'
   demand(j) 'satisfy demand at market j';

cost..      z =e= sum((i,j), c(i,j)*x(i,j));
supply(i).. sum(j, x(i,j)) =l= a(i);
demand(j).. sum(i, x(i,j)) =g= b(j);

Model transport / all /;
solve transport using lp minimizing z;
display x.l, x.m;

...
...
data preparation
...
...

a = Parameter(m, name="a", domain=[i], records=capacities)
b = Parameter(m, name="b", domain=[j], records=demands)
d = Parameter(m, name="d", domain=[i, j], records=distances, is_miro_input=True)

x = Variable(m, name="x", domain=[i, j], type="Positive", is_miro_output=True)
...
...
model.solve()
    

Once your model is prepared for MIRO, continue with the next step and launch it in Base Mode to verify that the app starts correctly.

After launching MIRO for the first time, all selected symbols are automatically available in tabular form. Even without additional configuration, you can already:

• Load and modify input data
• Run or stop optimization jobs
• Inspect logs and generated files
• Analyze model results
• Store and compare scenarios

The complete workflow for preparing a model for MIRO, including detailed examples for GAMS and GAMSPy, is described here.

Run the model in MIRO Base Mode to verify that your data contract works and generates a default interface.

• GAMS
• GAMSPy

In GAMS Studio, open the model and choose Run Base Mode from the MIRO menu.

Note:

If you start MIRO via GAMS Studio, make sure that the model file you want to run is marked as the main file in the corresponding project group. If needed, right-click the file in the project explorer and select set as main file.

After you mark your miro symbols with is_miro_input and is_miro_output, you can run MIRO. Navigate to your model directory and launch MIRO from the command line:

> gamspy run miro --model <path_to_your_model> [--path <path_to_your_MIRO_installation>]

You can omit --path if MIRO is installed in one of the standard locations on Windows or macOS, or if you configured the MIRO_PATH environment variable.

Skip Model Execution

GAMS Studio and the GAMSPy CLI can start MIRO without executing the model first. This can be helpful for large models, but it should be used with caution: if model execution is skipped, the GAMS/MIRO data contract is not created or refreshed. Changes to MIRO input or output symbols are therefore not communicated to MIRO.

• GAMS
• GAMSPy

For long-running GAMS models, consider compiling the model instead of skipping execution completely. You can use the GAMS option a=c to update the data contract without solving the model. In this case, a new default scenario is created with input data only.

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.py> --skip-execution [--path <path_to_your_MIRO_installation>]

Use this option only if the current data contract is already up to date.

After launching an app, the MIRO interface is divided into a navigation bar and a main window. The navigation bar lets you switch between the main app views and trigger common actions such as loading data or solving the model.

Navigation Bar

The navigation bar provides access to the main views of a MIRO application:

1. Input:
   Visualization and configuration of input data for the next model run.
2. Output:
   Visualization of output data.
3. GAMS interaction:
   Status information, logs, and listing files while the model is being solved. Listing files are not displayed when using GAMSPy.
4. Load scenarios:
   Explore and manage scenarios stored in the MIRO database.
5. Compare scenarios:
   Compare results and scenarios in split-view or multi-scenario comparison modes.

The navigation bar also contains the main action buttons:

1. Load data:
   Load input data for a model run. This can be a local file or an existing scenario from the database.
2. Solve model:
   Solve the model with the current input data and collect the results after the run has finished.

Main Window and Header

The main window displays the content of the selected view. Depending on the app configuration, this can include input widgets, output charts, scenario comparisons, logs, or a README section shown to users.

Additional functions are available in the header bar:

• Scenario:
  Scenario management, including loading, saving, editing, deleting, and exporting scenario data.
• Help:
  Links to this documentation, the GAMS Forum, the command palette with keyboard shortcuts, and license information.

The default interface is fully functional, but you can enhance it by assigning widgets (sliders, drop-downs), defining charts, and setting global options. Read about the app configuration in detail here.

• In GAMS Studio: Launch the app using Configuration Mode instead of Base Mode.
• Using GAMSPy CLI: Run the following command:
> gamspy run miro --mode="config" --model <path_to_your_model.py>

You will enter a configuration screen. Any change you save (e.g., turning a scalar input into a slider, or configuring a default Pivot chart) is automatically written to a <modelname>.json file in your model's conf_<modelname> directory.

• General settings:
  Appearance and general behavior of the app.
• Symbols:
  Symbol naming, ordering, grouping, etc.
• Tables:
  Global table and individual output table settings.
• Input Widgets:
  Input widgets can be used to communicate input data with GAMS/GAMSPy. Examples of such widgets include: tables, sliders, dropdown menus, date selectors or checkboxes.
• Graphs:
  GAMS/GAMSPy symbols can be visualized as graphs. A lot of plotting types are available and only need to be configured, i.e. adapted to your model-specific data. To create graphics that are perfectly tailored to your data and not available in MIRO yet, you can also write your own custom renderer.
• Colors:
  Configure custom themes.
• Database management:
  Backup, restore or remove the database.

When the MIRO app is completely configured, i.e. all graphics have been created, options have been set and adjustments have been made, the app can be packaged into a .miroapp file so that it can be easily shared and used in the daily business of your end users. No further changes to the model or the configuration can be made once it is deployed.

• GAMS
• GAMSPy

The result is a single .miroapp file which can be sent to the end user(s) of the application.

This quick start guide covers the essential workflow for building and deploying a MIRO application. The following resources provide more detailed information about specific topics:

• Preparing Models for MIRO
  Learn how to define the MIRO data contract and prepare GAMS and GAMSPy models for MIRO.
• Working with GAMS MIRO
  Learn how to use MIRO applications, manage scenarios, compare results, and work with input and output data.
• Customizing MIRO Applications
  Configure widgets, charts, layouts, themes, custom renderers, and advanced app behavior.
• Deployment
  Learn how to package, distribute, and deploy MIRO applications locally or via MIRO Server.
• GAMS MIRO Cheat Sheets
  Quick references for the MIRO interface, configuration workflow, and common tasks.
• FAQs
  Frequently asked questions, troubleshooting tips, and solutions to common problems.