The Jobs view lists all the jobs you submitted and all jobs shared with you via groups (User groups). Furthermore, an administrator sees all jobs submitted by all users and inviters can see all jobs submitted by their invitees. 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 Namespaces 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.

If you open the Users view as a user, you can only see yourself here. 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. The table displays the role, inviter and date of creation of the users. Additionally, here you can delete users or create new invitation codes. 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. To edit user roles, permissions and quota as well as view the usage, and for inviters their invitees, click on the underlined usernames to access the User Page of the selected user.

User Page

The User Page contains all information and settings for the seleced user. This page is reachable wherever a username is mentioned (if you have the permission to see that user's page). Depending on your permissions the page contains a different amount of tabs. If you are a user you have only the permission to view your own page and will find your Usage here. As an inviter you can view the User Page of all your invited users, and the users they invited. For them you have the option to edit the password, license, instance, quota, identity provider, permissions, and view their usage. For yourself you will find your own usage and an invitee tree. As an admin you will find the same options as an inviter, but for all existing users.

If you select the Usage tab a more detailed view of the usage of that user is displayed. Here you will find the user's remaining quota and an overview of the jobs generated by that user. First, select the timeframe you are interested in and if you are an admin or an inviter, whether you want to include invitees in the data. The Dashboard allows a more detailed view of the individual jobs. The table will by default be grouped by username. It is possible to change this to no grouping at all, or by instance, or by pool label. If at least two users/instances/pool labels exist in the selected timeframe, the data will also be displayed in pie diagrams. If Instance Pools are used, the second table will display the idle times of these pools. Under the second tab Timeline a graphical visualization shows either the jobs weighted by their multipliers, or just the number of parallel jobs over time.

Webhooks can be added/updated and removed via the Webhooks view. This view may not be visible to you if you are a user or an inviter and the administrator has not enabled this feature for you. As an administrator, you can also enable/disable the Webhook feature from this view.

To clean up the results of your model runs and free up space in the database, use the Cleanup view. 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.

The Administration view can be used to add/update the GAMS Engine license as well as the system-wide GAMS license. Here it is also possible for administrators to manage identity providers and instances. Furthermore, it is possible for the administrator to set a password policy for all users who use Engine as an identity provider.

If you are working with Python and your main goal is to submit jobs to Engine, you can use the GAMS Python API. This approach eliminates the need to manually handle individual HTTP requests.

First make sure to install gamsapi[engine] to the environment your are working with:

Next, you need to define the model you want to submit to Engine. You can either read it directly from a file, or, if your model is small, define it as a string within your Python code. In this example, we will use a simple transportation model.

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

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 /;

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

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

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;
"""
                                            

First you need to set up a GamsWorkspace:

import os
import sys
from gams import GamsWorkspace, GamsEngineConfiguration

sys_dir = sys.argv[1] if len(sys.argv) > 1 else None
work_dir = sys.argv[2] if len(sys.argv) > 2 else None
ws = GamsWorkspace(system_directory=sys_dir, working_directory=work_dir)
                                        

To connect to Engine, you need to define a GamsEngineConfiguration object. This requires specifying the ENGINE_URL and ENGINE_NAMESPACE. Additionally, you must choose an authentication method. You can authenticate using either a username and password combination, or by providing a JWT token, as demonstrated in this example.

# set up configuration required for any job on GAMS Engine
engine_configuration = GamsEngineConfiguration(
    host=os.environ["ENGINE_URL"],
    jwt=os.environ["ENGINE_JWT"],
    namespace=os.environ["ENGINE_NAMESPACE"],
)
                                        

With everything configured to run the model on Engine, we simply need to add the model to our workspace and execute the job using our configurations. Finally, we will print some of the results:

job = ws.add_job_from_string(GAMS_MODEL)

job.run_engine(engine_configuration)

for rec in job.out_db["x"]:
    print(f"x({rec.key(0)},{rec.key(1)}): level={rec.level} marginal={rec.marginal}")
                                        

If your model run requires additional parameters, you can define them within the run_engine() method:

run_engine(
    engine_configuration,
    extra_model_files=None,
    engine_options=None,
    gams_options=None,
    checkpoint=None,
    output=None,
    create_out_db=True,
    databases=None,
    remove_results=True
)
                                        

Depending on your goals, you can now run multiple jobs with slightly modified parameters, or based on the results of previous jobs. For more examples, please refer here.

In the previous example, the run_engine() method handles the job submission automatically. However, if you have specific requirements or need more customization, its capabilities may be limiting. For finer control and access to all API endpoints, you can use the requests library to make direct HTTP requests.

We will use a contrived example to show the bare minimum of what you can do with GAMS Engine, in order to give you an idea of how straight-forward it is to use (if you know some Python and understand the requests library).

Assume we have a user called jon_doe registered on Engine SaaS. This user has access to the namespace tests, and to two different instance sizes with 16GB and 32GB labelled 'GAMS_z1d.large_A' and 'GAMS_z1d.xlarge_A', respectively. We will use the requests library to explore the REST API, and submit a simple GAMS job and fetch the results.

Authentication

import requests
from requests.auth import HTTPBasicAuth
import time


au = HTTPBasicAuth("john_doe","some_password")
url = "https://engine.gams.com/api"
                                            

Making the First Request

with requests.get(url + '/usage/instances/john_doe', auth=au) as r:
    r.raise_for_status()
    r.json()
                                            

{
    'instances_inherited_from': 'john_doe',
    'default_inherited_from': 'john_doe',
    'instances_available': [
        {
            'label': 'GAMS_z1d.large_A',
            'cpu_request': 1.8,
            'memory_request': 15070,
            'workspace_request': 50000,
            'node_selectors': [{'key': 'gams.com/instanceType', 'value': 'z1d.large'}],
            'tolerations': [],
            'multiplier': 1.0
        },
        {
            'label': 'GAMS_z1d.xlarge_A',
            'cpu_request': 3.8,
            'memory_request': 30710,
            'workspace_request': 50000,
            'node_selectors': [{'key': 'gams.com/instanceType', 'value': 'z1d.xlarge'}],
            'tolerations': [],
            'multiplier': 1.1
        }
    ],
    'default_instance': {
        'label': 'GAMS_z1d.large_A',
        'cpu_request': 1.8,
        'memory_request': 15070,
        'workspace_request': 50000,
        'node_selectors': [{'key': 'gams.com/instanceType', 'value': 'z1d.large'}],
        'tolerations': [],
        'multiplier': 1.0
    }
}
                                            

with requests.get(url + 'usage/pools/john_doe', auth=au) as r:
    r.raise_for_status()
    r.json()
                                            

Submitting a Job

from zipfile import ZipFile

with ZipFile('model.zip','w') as zip:
    zip.write('trnsport.gms')

query_params = {
    'model': 'trnsport',
    'namespace': 'tests',
    'labels': 'instance=GAMS_z1d.large_A'
}

# Create dict with model zip file
job_files = {'model_data': open('model.zip','rb')}

with requests.post(url + '/jobs/', params=query_params, files=job_files, auth=au) as r:
    r.raise_for_status()
    token = r.json()['token']
                                            

Getting Job Results

with requests.get(url + '/jobs/' + token, auth=au) as r:
    r.raise_for_status()
    r.json()
                                            

{'token': '842b85cd-d7e2-42dc-8268-cc25ed3d66ce',
'model': 'trnsport',
'is_temporary_model': True,
'is_data_provided': False,
'status': 10,
'process_status': 0,
'stdout_filename': 'log_stdout.txt',
'namespace': 'tests',
'stream_entries': [],
'arguments': [],
'submitted_at': '2022-01-13T15:46:32.749866+00:00',
'finished_at': '2022-01-13T15:48:39.520392+00:00',
'user': {'username': 'john_doe', 'deleted': False, 'old_username': None},
'text_entries': [],
'dep_tokens': [],
'labels': {'cpu_request': 1.8,
'memory_request': 15070,
'workspace_request': 50000,
'tolerations': [],
'node_selectors': [{'key': 'gams.com/instanceType', 'value': 'z1d.large'}]},
'result_exists': True}
                                            

with requests.get(f'{url}/jobs/{token}/result', auth=au, stream=True) as r:
    r.raise_for_status()
    with open('results.zip', 'wb') as f:
        # Iterate over the response in 8KB chunks
        for chunk in r.iter_content(chunk_size=8192):
            # Write the chunk to the file
            f.write(chunk)
                                        

Iteration Dual Objective In Variable Out Variable
1 73.125000 x(seattle,new-york) demand(new-york) slack
2 119.025000 x(seattle,chicago) demand(chicago) slack
3 153.675000 x(san-diego,topeka) demand(topeka) slack
4 153.675000 x(san-diego,new-york) supply(seattle) slack

--- LP status (1): optimal.
--- Cplex Time: 0.11sec (det. 0.01 ticks)


Optimal solution found
Objective: 153.675000
                                            

For information about the other API endpoints, please refer here.