The goal of this tutorial is to provide a compact overview of the basic functionality of the GAMS Matlab Control API. It allows the user to start immediately working with the API by providing a set of examples based on the well-known transportation problem. Those examples are also part of the GAMS system directory, see [PathToGAMS]/api/matlab/examples/control. These examples introduce several API features step by step.

We recommend to open the aforementioned files to gain a complete overview of the examples. Down below we explain the examples with the help of selected code snippets.

Choose the GAMS system

Example: transport1

By default the GAMS system is determined automatically. In case of having multiple GAMS systems on your machine, the desired system can be specified via an additional argument when the workspace is created. When running the examples, we can provide an additional command line argument in order to define the GAMS system directory that should be used. By executing transport1 with C:/GAMS/48 we use GAMS 48.3 to run transport1 even if our default GAMS system might be a different one. This is managed by the following code:

wsInfo = gams.control.WorkspaceInfo();
if nargin > 0
  wsInfo.systemDirectory = varargin{1};
end
ws = gams.control.Workspace(wsInfo);

Note: The API can detect GAMS automatically from the PATH environment variable. Please note that this is not the MATLABPATH. You can inspect the PATH with getenv("PATH").; In Matlab you can import the GAMS Control package by import gams.control.*. Then, you don't need to call the GAMS classes with the preceding gams.control..

Export data to GDX

Example: transport_gdx

Although the Matlab Control API offers much more than exchanging data between Matlab and GDX, a common use case is the export and import of GDX files. The central class for this purpose is Database. We assume that the data to be exported is available in Matlab data structures.

plants = {'Seattle', 'San-Diego'};
markets = {'New-York', 'Chicago', 'Topeka'};
 
capacity = containers.Map();
capacity('Seattle') = 350;
capacity('San-Diego') = 600;
 
demand = containers.Map();
demand('New-York') = 325;
demand('Chicago') = 300;
demand('Topeka') = 275;
 
distance = containers.Map();
distance('Seattle.New-York') = 2.5;
distance('Seattle.Chicago') = 1.7;
distance('Seattle.Topeka') = 1.8;
distance('San-Diego.New-York') = 2.5;
distance('San-Diego.Chicago') = 1.8;
distance('San-Diego.Topeka') = 1.4;

Different type of GAMS symbols are represented using different Matlab data structures. The data for the GAMS sets is represented using a cell of strings (e.g. plants and markets). On the other hand, GAMS parameters are represented by a containers.Map (e.g. capacity and demand). Note that the representation of the two dimensional parameter distance uses a dot notation for storing the keys. The choice of data structures can also be different, but the used structures in this example fit well for representing GAMS data with Matlab data structures.

A new Database instance can be created using Workspace.addDatabase.

db = ws.addDatabase();

We start adding GAMS sets using the method Database.addSet which takes the name and the dimension as arguments. The third argument is an optional explanatory text. A for-loop iterates through plants and adds new records to the recently created Set instance i using Set.addRecord.

i = db.addSet('i', 1, 'canning plants');
for p = plants
    i.addRecord(p{1});
end

Parameter instances can be added by using the method Database.addParameter. In this example we use the overloaded method which takes a list of Set instances instead of the dimension for creating a parameter with domain information.

a = db.addParameter('a', 'capacity of plant i in cases', i);
for p = plants
    rec = a.addRecord(p{1});
    rec.value = capacity(p{1});
end

As soon as all data is prepared in the Database, the method Database.export can be used to create a GDX file.

db.export('data.gdx');

Import data from GDX

Example: transport_gdx

Data can be imported from a GDX file using Workspace.addDatabaseFromGDX. The method takes a path to a GDX file and creates a Database instance.

gdxdb = ws.addDatabaseFromGDX('data.gdx');

Reading the data from the Set i into a cell of strings can be done as follows:

gdxPlantsRecords = gdxdb.getSet('i').records;
gdxPlants = cell(size(gdxPlantsRecords));
for i = 1:numel(gdxPlants)
  gdxPlants{i} = gdxPlantsRecords{i}.key(1);
end

i is retrieved by calling Database.getSet on gdxdb. The returned Set object has an attribute records with an cell array of SetRecords. Each record can be asked for its keys.

You can do the same for Parameter. Instead of creating a cell, we want to have the data in the form of a containers.Map. ParameterRecord can not only be asked for its keys, but also for its value. The following code snippet shows how to read the one dimensional parameter a into a map.

gdxCapacity = containers.Map();
for rec = gdxdb.getParameter('a').records
  gdxCapacity(rec{1}.key(1)) = rec{1}.value;
end

For a key of multi dimensional symbol, we choose a dot based concatenation of keys.

gdxDistance = containers.Map();
for rec = gdxdb.getParameter('d').records
  gdxCapacity([rec{1}.key(1), '.', rec{1}.key(2)]) = rec{1}.value;
end

Scalar can be read into a variable of type double by accessing the value of the first and only record.

gdxFreight = gdxdb.getParameter('f').record.value;

Run a Job from file

Example: transport1

At first we create our workspace using Workspace ws = gams.control.Workspace();. Afterwards, we can create a Job t1 using the Workspace.addJobFromGamsLib method and run it.

Apparently you can create a Job with any other gms file you might have created on your own as long as it is located in the current working directory. Then the Job t1 can be defined using the Workspace.addJobFromFile method.

% create Workspace "ws" with default working directory
ws = gams.control.Workspace();
 
% create Job "t1" from "trnsport" model in GAMS Model Libraries
t1 = ws.addJobFromGamsLib('trnsport');
% run Job "t1"
t1.run();

Retrieve a solution from an output database

Example: transport1

The following lines create the solution output and illustrate the usage of the Job.outDB property to get access to the Database created by the Job.run method. To retrieve the content of variable x we use the Database.getVariable method and the VariableRecord class.

% retrieve Variable "x" from Job's output databases
fprintf('Ran with Default:\n');
for x = t1.outDB.getVariable('x').records
    fprintf('x(%s,%s): level=%g marginal=%g\n', x{1}.keys{:}, x{1}.level, x{1}.marginal);
end

Specify solver using Options

Example: transport1

The solver can be specified via the Options class and the Workspace.addOptions method. The Options.setAllModelTypes property sets xpress as default solver for all model types which the solver can handle. Then we run our Job t1 with the new Options.

% create Options 'opt1'
opt1 = ws.addOptions();
% set all model types of 'opt1' for 'xpress'
opt1.setAllModelTypes('xpress');
% run Job 't1' with Options 'opt1'
t1.run(opt1);

Run Job with solver option file and capture log

Example: transport1

At first we create the file xpress.opt with content algorithm=barrier which will be used as solver option file and is stored in the current working directory. Afterward we use Options just like in the preceding example and Options.optFile property to 1 to tell the solver to look for a solver option file. We specify the argument output in order to stream the log of the Job into the file transport1_xpress.log. When the output argument is omitted then the log will be written to standard output.

% write file 'xpress.opt' under Workspace's working directory
fid = fopen(fullfile(ws.workingDirectory, 'xpress.opt'), 'w');
fprintf(fid, 'algorithm=barrier');
fclose(fid);
 
% create Options 'opt2'
opt2 = ws.addOptions();
% set all model types of 'opt2' for 'xpress'
opt2.setAllModelTypes('xpress');
% for 'opt2', use 'xpress.opt' as solver's option file
opt2.optFile = 1;
 
% run Job 't2' with Options 'opt2' and capture log into 'transport1_xpress.log'.
output = gams.control.PrintStream(fullfile(ws.workingDirectory, 'transport1_xpress.log'));
t1.run(opt2, output);

Use include files

Example: transport2

In this example, as in many succeeding, the data text and the model text are separated into two different strings. Note that these strings data and model are using GAMS syntax.

At first we write an include file tdata.gms that contains the data but not the model text:

% write 'data' into file 'tdata.gms' under Workspace's working directory
fid = fopen(fullfile(ws.workingDirectory, 'tdata.gms'), 'w');
fprintf(fid, data);
fclose(fid);

Afterwards we create a Job using the Workspace.addJobFromString method. Options.defines is used like the the 'double dash' GAMS parameters, i.e. it corresponds to --incname=tdata on the command line where incname is used as name for the include file in the model string.

% create Job 't2' from the 'model' string variable
t2 = ws.addJobFromString(model);
% create Options 'opt' and define 'incname' as 'tdata'
opt = ws.addOptions();
opt.defines('incname', 'tdata');
% run Job 't2' with Options 'opt'
t2.run(opt);

The string model contains the following lines to read in the data.

$if not set incname $abort 'no include file name for data file provided'

$include %incname%

Set non-default working directory

Example: transport3

At first we create a new directory. Once this is done we can use this directory when creating the Workspace and make it the working directory.

% create a directory
workingDirectory = fullfile(pwd, 'transport3');
mkdir(workingDirectory);
 
% create a workspace
wsInfo = gams.control.WorkspaceInfo();
wsInfo.workingDirectory = workingDirectory;
ws = gams.control.Workspace(wsInfo);

Read data from string and export to GDX

Example: transport3

We read the data from the string data. Note that this contains no model but only data definition in GAMS syntax. By running the corresponding Job a Database is created that is available via the Job.outDB property. We can use the Database.export method to write the content of this database to a gdx file tdata.gdx.

% create and run a job from a data file, then explicitly export to a GDX file
t3 = ws.addJobFromString(data);
t3.run();
t3.outDB.export(fullfile(ws.workingDirectory, 'tdata.gdx'));

Run Job using data from GDX

Example: transport3

This works quite similar to the usage of an include file explained in transport2 - Use include files .

% run a job using an instance of Options that defines the data include file
t3 = ws.addJobFromString(model);
opt = ws.addOptions();
opt.defines('gdxincname', 'tdata');
t3.run(opt);

Note that there are some minor changes in the model due to the usage of a gdx instead of an include file.

$if not set gdxincname $abort 'no include file name for data file provided'
$gdxin %gdxincname%
$load i j a b d f
$gdxin

Run Job using implicit database communication

Example: transport3

This example does basically the same as the two preceding examples together. We create two Jobs t3a and t3b where the first one contains only the data and the second one contains only the model without data. After running t3a the corresponding Job.outDB can be read in directly just like a gdx file. Note that the database needs to be passed to the Job.run method as additional argument.

t3a = ws.addJobFromString(data);
t3b = ws.addJobFromString(model);
opt = ws.addOptions();
t3a.run();
opt.defines('gdxincname', t3a.outDB.name);
t3b.run(opt, t3a.outDB);

Define data using Matlab data structures

Example: transport4

We use cell arrays and containers.Map to define Matlab data structures that correspond to the sets, parameters and tables used for the data definition in GAMS.

plants = {'Seattle', 'San-Diego'};
markets = {'New-York', 'Chicago', 'Topeka'};
 
capacity = containers.Map();
capacity('Seattle') = 350;
capacity('San-Diego') = 600;
 
demand = containers.Map();
demand('New-York') = 325;
demand('Chicago') = 300;
demand('Topeka') = 275;
 
distance = containers.Map();
distance('Seattle.New-York') = 2.5;
distance('Seattle.Chicago') = 1.7;
distance('Seattle.Topeka') = 1.8;
distance('San-Diego.New-York') = 2.5;
distance('San-Diego.Chicago') = 1.8;
distance('San-Diego.Topeka') = 1.4;

Prepare Database from Matlab data structures

Example: transport4

At first we create an empty Database db using the Workspace.addDatabase method. Afterwards we prepare the database. To add a set to the database we use the Set class and the Database.addSet method with arguments describing the identifier, dimension and explanatory text. To add the records to the database we iterate over the elements of our Matlab data structure and add them by using the Set.addRecord method.

For parameters the procedure is pretty much the same. Note that the table that specifies the distances in GAMS can be treated as parameter with dimension 2 and that scalars can be treated as parameter with dimension 0.

The Job can be run like explained in the preceding example about implicit database communication.

db = ws.addDatabase();
 
i = db.addSet('i', 1, 'canning plants');
for p = plants
  i.addRecord(p{1});
end
 
j = db.addSet('j', 1, 'markets');
for m = markets
  j.addRecord(m{1});
end
 
a = db.addParameter('a', 'capacity of plant i in cases', i);
for p = plants
  rec = a.addRecord(p{1});
  rec.value = capacity(p{1});
end
 
b = db.addParameter('b', 'demand at market j in cases', j);
for m = markets
  rec = b.addRecord(m{1});
  rec.value = demand(m{1});
end
 
d = db.addParameter('d', 'distance in thousands of miles', i, j);
for p = plants
  for m = markets
    rec = d.addRecord(p{1}, m{1});
    rec.value = distance([p{1}, '.', m{1}]);
  end
end
 
f = db.addParameter('f', 'freight in dollars per case per thousand miles');
rec = f.addRecord();
rec.value = 90;
 
% create and run a job from the model and read gdx include file from the database
t4 = ws.addJobFromString(model);
opt = ws.addOptions();
opt.defines('gdxincname', db.name);
t4.run(opt, db);

Initialize Checkpoint by running Job

Example: transport5

The following lines of code conduct several operations. While the first line simply creates a Checkpoint, the second one uses the Workspace.addJobFromString method to create a Job containing the model text and data but no solve statement. Afterwards the run method gets the Checkpoint as argument. That means the Checkpoint cp captures the state of the Job.

cp = ws.addCheckpoint();
t5 = ws.addJobFromString(model);
t5.run(cp);

Initialize Job from Checkpoint

Example: transport5

Note that the string returned from function model contains the entire model and data definition plus an additional demand multiplier and scalars for model and solve status but no solve statement:

Scalar bmult demand multiplier /1/;
...
demand(j) .. sum(i, x(i,j)) =g= bmult*b(j) ;
...
Scalar ms 'model status', ss 'solve status';

In transport5 we create a list with eight different values for this demand multiplier.

bmultlist = [0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3];

For each entry of that list we create a Job t5 using the Workspace.addJobFromString method. Besides another string which resets the demand multiplier bmult, specifies the solve statement and assigns values to the scalars ms and ss we pass the checkpoint cp as additional argument. This results in a Job combined from the checkpoint plus the content provided by the string. We run the Job and echo some interesting data from the Job.outDB using the Database.getParameter and Database.getVariable methods and the Symbol.record attribute plus the ParameterRecord.value and the VariableRecord.level properties.

for i = 1:numel(bmultlist)
  job = sprintf('bmult=%f; solve transport min z use lp; ms=transport.modelstat; ss=transport.solvestat;', bmultlist(i));
  t5 = ws.addJobFromString(job, cp);
  t5.run();
 
  fprintf('Scenario bmult=%f:\n', bmultlist(i));
  fprintf('  Modelstatus: %s\n', gams.control.globals.ModelStat(t5.outDB.getParameter('ms').record.value).select);
  fprintf('  Solvestatus: %s\n', gams.control.globals.SolveStat(t5.outDB.getParameter('ss').record.value).select);
  fprintf('  Obj: %f\n', t5.outDB.getVariable('z').record.level);
end

Note: Some of the demand multipliers cause infeasibility. Nevertheless, GAMS keeps the incumbent objective function value. Therefore the model status and the solve status provide important information for a correct solution interpretation.

Create ModelInstance from Checkpoint

Example: transport7

In transport7 the usage of matlab::gams::control::ModelInstance is demonstrated.

At first Checkpoint cp is created as in the preceding examples. Then we create the ModelInstance mi using the Checkpoint.addModelInstance method. Note that the Job again contains no solve statement and the demand multiplier is already included with default value 1.

cp = ws.addCheckpoint();
 
% initialize a checkpoint by running a job
t7 = ws.addJobFromString(model);
t7.run(cp);
 
% create a ModelInstance and solve it multiple times with different scalar bmult
mi = cp.addModelInstance();

Modify parameter of ModelInstance using Modifier

Example: transport7

A ModelInstance uses a matlab::gams::control::ModelInstance::syncDB ModelInstance.syncDB to maintain the data. We define bmult as Parameter using the Parameter method and specify cplex as solver. Afterwards the ModelInstance is instantiated with 3 arguments, the solve statement, Options opt and Modifier bmult. The Modifier means that bmult is modifiable while all other parameters, variables and equations of ModelInstance mi stay unchanged. We use the Parameter.addRecord method and the ParameterRecord.value property to assign a value to bmult. That value can be varied afterwards using the Symbol.record property to reproduce our well-known example with different demand multipliers.

bmult = mi.syncDB.addParameter('bmult', 'demand multiplier');
opt = ws.addOptions();
opt.setAllModelTypes('cplex');
 
% instantiate the ModelInstance and pass a model definition and Modifier to declare bmult mutable
mi.instantiate('transport use lp min z', opt, gams.control.Modifier(bmult));
 
rec = bmult.addRecord();
rec.value = 1.0;
bmultlist = [0.6, 0.7 , 0.8, 0.9, 1.0, 1.1, 1.2, 1.3];
 
for i = 1:numel(bmultlist)
  rec.value = bmultlist(i);
  mi.solve();
 
  fprintf('Scenario bmult=%f:\n', bmultlist(i));
  fprintf('  Modelstatus: %s\n', mi.modelStatus);
  fprintf('  Solvestatus: %s\n', mi.solveStatus);
  fprintf('  Obj: %f\n', mi.syncDB.getVariable('z').record.level);
end

Modify variable of ModelInstance using Modifier

Example: transport7

We create a ModelInstance just like in the next to last example. We define x as Variable and its upper bound as Parameter xup. At the following ModelInstance.instantiate method Modifier has 3 arguments. The first one says that x is modifiable, the second determines which part of the variable (lower bound, upper bound or level) can be modified and the third specifies the Parameter that holds the new value.

In the following loops we set the upper bound of one link of the network to zero, which means that no transportation between the corresponding plant and market is possible, and solve the modified transportation problem.

mi = cp.addModelInstance();
 
x = mi.syncDB.addVariable('x', 2, gams.control.globals.VarType.POSITIVE, '');
xup = mi.syncDB.addParameter('xup', 2, 'upper bound on x');
 
% instantiate the ModelInstance and pass a model definition and Modifier to declare upper bound of X mutable
mi.instantiate('transport use lp min z', gams.control.Modifier(x, gams.control.globals.UpdateAction.UPPER, xup));
 
for i = t7.outDB.getSet('i').records
  for j = t7.outDB.getSet('j').records
    xup.clear();
    keys = {i{1}.key(1), j{1}.key(1)};
    rec = xup.addRecord(keys);
    rec.value = 0;
    mi.solve();
 
    fprintf('Scenario link blocked: %s - %s\n', keys{:});
    fprintf('  Modelstatus: %s\n', mi.modelStatus);
    fprintf('  Solvestatus: %s\n', mi.solveStatus);
    fprintf('  Obj: %f\n', mi.syncDB.getVariable('z').record.level);
  end
end

Create and use save/restart file

Example: transport11

In transport11 we demonstrate how to create and use a save/restart file. Usually such a file should be supplied by an application provider but in this example we create one for demonstration purpose. Note that the restart is launched from a Checkpoint. From the main function we call the function create_save_restart giving it the current workspace settings and the desired file name as arguments.

create_save_restart(ws.workingDirectory, ws.systemDirectory, ws.debugLevel, 'tbase');

In function create_save_restart we create a workspace with the given workspace settings. Then we create a Job from a string. Note that the string given via basemodel contains the basic definitions of sets without giving them a content (that is what $onempty is used for). Afterwards we specify a Options to only compile the job but do not execute it. Then we create a Checkpoint cp that is initialized by the following run of the Job and stored in the file given as argument to the function, in our case tbase. This becomes possible because the Workspace.addCheckpoint method accepts identifiers as well as file names as argument.

ws = gams.control.Workspace(workdir, systemdir, debuglevel);
j1 = ws.addJobFromString(basemodel);
opt = ws.addOptions();
opt.action = gams.control.options.Action.CompileOnly;
cp = ws.addCheckpoint('tbase');
j1.run(opt, cp);
opt.dispose();
j1.outDB.dispose();

So what you should keep in mind before we return to further explanations of the main function is, that the file tbase is now in the current working directory and contains a checkpoint. Now in the main function we define some data using Matlab data structures as we already did in transport4 before we create the Workspace and a Database.

ws = gams.control.Workspace(wsInfo);

db = ws.addDatabase();

Afterwards we set up the Database like we already did in transport4. Once this is done we run a Job using this data plus the checkpoint stored in file tbase.

cpBase = ws.addCheckpoint('tbase');
opt = ws.addOptions();
t11 = ws.addJobFromString(model, cpBase);
opt.defines('gdxincname', db.name);
opt.setAllModelTypes('xpress');
t11.run(opt, db);

Note that the string from which we create Job t11 is different to the one used to prepare the checkpoint stored in tbase and is only responsible for reading in the data from the Database correctly. The entire model definition is delivered by the Checkpoint cpBase which is equal to the one we saved in tbase.

Table of Contents

Choose the GAMS system

Export data to GDX

Import data from GDX

Run a Job from file

Retrieve a solution from an output database

Specify solver using Options

Run Job with solver option file and capture log

Use include files

Set non-default working directory

Read data from string and export to GDX

Run Job using data from GDX

Run Job using implicit database communication

Define data using Matlab data structures

Prepare Database from Matlab data structures

Initialize Checkpoint by running Job

Initialize Job from Checkpoint

Create ModelInstance from Checkpoint

Modify parameter of ModelInstance using Modifier

Modify variable of ModelInstance using Modifier

Create and use save/restart file