GAMS MIRO Engine

Introduction

GAMS MIRO Engine is a REST API designed to run in cloud environments. You can connect to it either via GAMS MIRO Desktop, via the GAMS MIRO Engine UI or via any of the clients supported by OpenAPI (Python, Java, Javascript, C++, ...).

GAMS MIRO Engine automatically schedules your jobs and assigns them to an available GAMS worker to solve it. It comes with a powerful user management system that allows you to restrict the activities of your users according to your organizational hierarchy.

The (technical) API documentation can be found here.

Note:

GAMS MIRO Engine is currently in the closed BETA stage. Please send an e-mail to support@gams.com to request access.

Installation

The installation of GAMS MIRO Engine highly depends on your setup. When you purchase GAMS MIRO Engine, you will receive installation instructions tailored to your setup.

System overview

GAMS MIRO Engine is a highly distributed system to solve your GAMS models. The heart of this system is a REST API - also referred to as broker - where you can submit your GAMS jobs. The system will then queue your jobs and assign them to an available worker - a GAMS process that solves your model. In case all workers are busy solving other jobs, your job is pending in the queue until a free worker is available. You can limit the amount of CPU and RAM a worker may use and workers can even run on different machines.

Components of GAMS MIRO Engine

User management

GAMS MIRO Engine comes with a highly flexible user management system. After first installing the system, there is a single default user available with name: admin and password: admin.

Note:

We strongly recommend that you change the default password for the admin user immediately after installing the system to prevent unauthorized users from accessing your system!

In addition, there is a single namespace available with the name: global. Namespaces are similar to directories in the UNIX file system: you can specify which users have access to which namespaces. If you want to start a new GAMS job, it always runs within a namespace. Just like the UNIX file system, GAMS MIRO Engine has three types of permissions on namespaces:

  • Read Permission
    Users can download GAMS models registered in this namespace
  • Write Permission
    Users can register new models in this namespace
  • Execute Permission
    Users can execute models in this namespace
Warning:

In order to restrict a user from accessing your model files, you have to specify a proper INEX file in addition to revoking read permission from this user!

The table below show the mapping of these permissions to the permission codes used by GAMS MIRO Engine.

Permission Code Read Permission Write Permission Execute Permission
0 - - -
1 - -
2 - -
3 -
4 - -
5 -
6 -
7

GAMS MIRO Engine distinguishes two types of jobs:

  • Jobs with a registered model
    The GAMS model is registered inside the namespace and the user only provides the data to run the model with.
  • Jobs with an unregistered model
    The user provides both the model files as well as the data to run the model with.
To run the first type of job, users must have execute permissions for the namespace in which the model to be executed is registered. The second type of job requires additional write permissions as a new (temporary) model has to be created in order to run this job.

GAMS MIRO Engine distinguishes three types of users:

  • Users
  • Inviters
    Inviters are users with the additional privilege to invite new users to use GAMS MIRO Engine. However, inviters can only invite users who have the same or fewer permissions than themselves. For example, if an inviter has read and execute permissions on the namespace global, she is not allowed to invite a user with write permission on this namespace. Inviters can invite other inviters, but not admins.
  • Administrators
    Administrators are the most privileged users. They have full permissions for each namespace and are allowed to invite new users, even new administrators. Administrators can also add new namespaces or remove existing ones.
In order to add a new user to GAMS MIRO Engine, you need to generate an invitation code. Users can then register themselves by providing this invitation code, a username and a password. Invitation codes can be generated by administrators and inviters. When creating an invitation code, permissions to namespaces can be assigned so that the new user can start interacting with the system directly. Note that the invitee's permissions may be lower than the inviter's, but not higher. Furthermore, inviters are able to manage - i.e. modify permissions and delete - their children (invitees) as well as any grandchildren. In this way, you can set up several hierarchy levels.

INEX file

You can use the GAMS MIRO Engine to restrict the files contained in the results archive. Use cases for this function include reducing the size of the archive and restricting access to certain files. This INEX file has the following schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "include",
        "exclude"
      ]
    },
    "files": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "required": [
        "items"
      ]
    }
  },
  "required": [
    "type",
    "files"
  ]
}

Let's assume we register the trnsport model from the GAMS model library. We want users to be able to run this model, but not see our GAMS code. More specifically, we want to exclude all files with the extensions .gms and .inc from the results returned to the users of our model. We therefore register the model with the following INEX file:

{
  "type": "exclude",
  "files": ["*.gms", "*.inc"]
}

Note that glob patterns (sometimes also referred to as "wildcards") are supported here.

You can specify an INEX file both when registering a new model (as shown in the previous example) and when submitting an order. When you submit a new order for a registered model that contains an INEX file, the results are first filtered against the INEX file of the model. Only then is the INEX file sent with the job applied. This means that when you submit a new job, you cannot remove restrictions that are associated with the model.

GAMS MIRO Engine UI

GAMS MIRO Engine comes with a web user interface that implements most of the features. Via this interface you can manage users, models and data, but also submit new jobs. Depending on your role ("User", "Inviter" or "Administrator"), different elements of the UI are visible.

To use MIRO Engine, you must first register with the system. To register, you need an invitation code

  1. Open MIRO Engine UI
  2. Click 'Register' below the Login button
  3. Put your registration code, username and password
  4. Click 'Register'
  5. You will automatically be logged in

Components of the MIRO Engine web user interface

The UI consists of four views (the minimum user role required to see this view is appended in brackets):

  • Jobs (User)
  • Models (User)
  • Users (Inviter)
  • Cleanup (Administrator)

The Jobs view lists all the jobs you submitted (or all jobs submitted by all users if you are an administrator). You can sort your submissions by clicking on the desired column. From this view, you can also interact with your jobs (view more details, cancel running jobs or download results) as well as submit new ones.

The Models view lists all the namespaces as well as all the models registered in each namespace. To view the models registered in a particular namespace, click on this namespace and the table that lists the models will update. Just as in the Jobs view you can sort the table by clicking on the desired column. You can add or remove namespaces from this view as well as register new models.

The Users view is only visible to inviters and administrators. If you are an administrator, you can see all users registered in the system; if you are an inviter, only users invited either by you or by one of your invitees are displayed. You can edit user roles and permissions as well as remove a user. Additionally, new invitation codes can be created from here. Note that inviters can only invite people who have the same or less privileges as themselves. To learn more about user roles and permissions click here.

The Cleanup view is only visible to administrators. Here you can clean up the database to reduce the amount of storage used by GAMS MIRO Engine. You can either remove files one by one or clean up multiple files at once by clicking the "Run housekeeping" button. This "housekeeping" dialog allows you to remove all files created more than x days ago and/or files created by users who have been removed from the system.

API documentation

The (technical) API documentation can be found here.

Note:

GAMS MIRO Engine is documented using OpenAPI version 2.0. You can download the definition file for the latest version of GAMS MIRO Engine here!