Tutorial

The goal of this tutorial is to provide a compact overview of the basic functionality of the GAMS C++ API. It allows the user to start immediately working with the API by providing a set of small examples based on the well-known transportation problem. These examples introduce several API features step by step. The GAMS distribution comes with a pre compiled binary version of the GAMS C++ API on Windows, Mac OS X and Linux. Futhermore, the C++ API itself and the provided examples are published under MIT license and are hosted at the GAMS GitHub organization. Therefore it is possible to compile the library manually (e.g. if a certain compiler is required) The GAMS C++ API is compatible with C++ 11 and is implemented using the Qt framework

Getting Started

This section guides you through the basic steps of compiling and running a program from scratch using either Qt Creator or Microsoft Visual Studio. If you want to have a look at the API itself you can directly start with the How to use API section instead. Note that you need to use at least C++ 11 in order to be able to use the GAMS C++ API. While this tutorial uses Qt Creator and Microsoft Visual Studio, other IDE's can be used as well.

Note
When using the pre compiled binary distribution of the GAMS C++ API as done in this section, one needs to use a compiler that is compatible with the one that was used during compilation of the library. Currently the GAMS C++ API is build using MSVC 2013 on Windows platforms and GCC on Linux and Mac OS X.

Getting Started using Qt Creator

After opening Qt Creator click on File > New File or Project. Choose Qt Console Application and click on Choose.... On the next page fill in the name and the location of the new project and click Next.

qtcreator1.png

Select the kits you want to use for the project and click on Next. If you use the precompiled library on Windows, you need to use MSVC2013 Confirm the creation of the new project by clicking on Finish.

qtcreator2.png

As soon as the project is created open the file GAMSApplication.pro by double clicking on it in the pane on the left hand side. Add the following two lines to the .pro file:

unix : LIBS += -ldl -L$$(HOME)/gams/gams24.9_linux_x64_64_sfx/ -lgamscpp
win32: LIBS += -LC:\GAMS\win64\24.9\ -lgamscpp
INCLUDEPATH += C:\GAMS\win64\24.9\apifiles\C++\api
Note
Depending on your operating system and the location of your GAMS system you need to adjust the paths respectively.

Save the changes, right click on the project and choose Run qmake.

The last step of creating a first small example is to write code that makes use of the GAMS C++ API. Open the file main.cpp and replace the content of the file with the following lines of code:

#include "gams.h"
#include <iostream>
using namespace gams;
using namespace std;
int main(int argc, char* argv[])
{
ws.gamsLib("trnsport");
// create a GAMSJob from file and run it with default settings
GAMSJob t1 = ws.addJobFromFile("trnsport.gms");
t1.run();
for (GAMSVariableRecord rec : t1.outDB().getVariable("x"))
cout << "x(" << rec.key(0) << "," << rec.key(1) << "):" << " level=" << rec.level() << " marginal=" << rec.marginal() << endl;
}

Make sure that MSVC2013 64bit is chosen as kit using the Release mode.

qtcreator3.png

Click on the play button below to run (and compile) the small example. If everything works, you should see the output of the example displaying results of the solved transportation problem.

Getting Started using Visual Studio 2013

After opening Visual Studio click on File > New > Project .... Choose Win32 Console Application and fill in the name and the location of the project and click on Next.

vs1.png

Turn off the Precompiled header and confirm with Finish in order to create the project.

vs5.png

As soon as the project is loaded, open the Configuration Manager:

vs3.png

Change the Active solution configuration to Release and the Active solution platform to x64.

vs4.png

The next step is to configure the project to find the GAMS C++ API. Rigth click on the project and choose Properties from the context menue. Go to Configuration Properties > C/C++ > General and add <GAMS system directory>\apifiles\c++\api to Additional Include Directories.

vs2.png

Go to Configuration Properties > Linker > General and add your <GAMS system directory> to Additional Library Directories (e.g. C:\gams\win64\24.9\apifiles). Make sure that %(AdditionalLibraryDirectories) is present as shown in the following picture.

vs6.png

Choose Input and add gamscpp.lib to Additional Dependencies and make sure that %(AdditionalDependencies) is present as well.

vs7.png

The last required configuration step is to add a post-build event that copies required files next to the generated executable. Click on Build Events > Post-Build Event and add the following code to Command Line. Note that you might need to adjust the used path depending on the location of your GAMS installation:

xcopy /Y "C:\gams\win64\24.9\gamscpp.dll" "$(OutDir)"
xcopy /Y "C:\gams\win64\24.9\Qt*.dll" "$(OutDir)"

Open the file GAMSApplication.cpp and replace its content by the following code:

#include "gams.h"
#include <iostream>
using namespace gams;
using namespace std;
int main(int argc, char* argv[])
{
ws.gamsLib("trnsport");
// create a GAMSJob from file and run it with default settings
GAMSJob t1 = ws.addJobFromFile("trnsport.gms");
t1.run();
for (GAMSVariableRecord rec : t1.outDB().getVariable("x"))
cout << "x(" << rec.key(0) << "," << rec.key(1) << "):" << " level=" << rec.level() << " marginal=" << rec.marginal() << endl;
}

Click on DEBUG > Start Without Debugging in order to compile and run the example. If everything works, you should see the output of the example displaying results of the solved transportation problem.

Important Classes of the API

This section provides a quick overview of some fundamental classes of the gams namespace. Their usage is demonstrated by an extensive set of examples.

How to use API

In the GAMS system directory there are some examples provided that illustrate the usage of the C++ API. <GAMS system directory>\apifiles\C++ contains the Qt project examples.pro and the Visual Studio solution examples.sln. The code snippets that are explained in this tutorial are taken from these examples. Furthermore there is a CMakeLists.txt file that can be used for building the examples using CMake. The well-known transportation problem is discussed step by step and each example introduces new elements of the GAMS C++ API.

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.

How to run a GAMSJob from file (Transport1)

At first we create a GAMSWorkspace. Afterwards we load the model trnsport from the GAMS Model Library. In doing so it is made available in the current working directory and can be loaded by the GAMSWorkspace.AddJobFromFile Method afterwards. Apparently this method also works 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 GAMSJob t1 is defined from that file and run by the GAMSJob.run method. The following lines create the solution output and illustrate the usage of the GAMSJob.outDB method to get access to the GAMSDatabase created by the run method. To retrieve the content of variable x we use the GAMSVariableRecord class and the GAMSDatabase.getVariable method.

...
GAMSWorkspace ws;
ws.gamsLib("trnsport");
// create a GAMSJob from file and run it with default settings
GAMSJob t1 = ws.addJobFromFile("trnsport.gms");
// Default run
t1.run();
cout << "Ran with Defaults:" << endl;
for (GAMSVariableRecord rec : t1.outDB().getVariable("x"))
cout << "x(" << rec.key(0) << "," << rec.key(1) << "):" << " level=" << rec.level() << " marginal=" << rec.marginal() << endl;
...

How to specify the solver (Transport1)

The solver can be specified via the GAMSOptions class and the GAMSWorkspace.addOptions method. The GAMSOptions.setAllModelTypes method sets xpress as default solver for all model types which the solver can handle.

...
// Run the job again with another solver
GAMSOptions opt = ws.addOptions();
opt.setAllModelTypes("xpress");
t1.run(opt);
...

How to run a job with a solver option file (Transport1)

At first 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. We choose xpress as solver just like in the preceding example and call GAMSOptions.setOptFile in order to tell the solver to look for a solver option file.

...
// Run the job with a solver option file
ofstream xpressopt(ws.workingDirectory() + cPathSep + "xpress.opt");
xpressopt << "algorithm=barrier" << endl;
xpressopt.close();
opt.setAllModelTypes("xpress");
opt.setOptFile(1);
t1.run(opt);
...

How to use include files (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 provided by the methods getDataText and getModelText are using GAMS syntax.

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

...
ofstream tdata(ws.workingDirectory() + cPathSep + "tdata.gms");
tdata << getDataText();
tdata.close();
...

Afterwards we create a GAMSJob using the GAMSWorkspace.addJobFromString method. The GAMSOptions.setDefine method is used like the 'double dash' GAMS parameters, i.e. it corresponds to --incname=tdata on the command line.

...
GAMSOptions opt = ws.addOptions();
opt.setDefine("incname", "tdata");
t2.run(opt);
...

Note that the string provided by getModelText contains the following lines to read in the data.

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

How to read data from string and export to GDX (Transport3)

We read the data from the string provided by getDataText as we did in the preceding example. Note that this contains no solve statement but only data definition in GAMS syntax. By running the corresponding GAMSJob a GAMSDatabase is created that is available via the GAMSJob.outDb method. We can use the GAMSDatabase.doExport method to write the content of this database to a gdx file tdata.gdx.

...
// data from a string with GAMS syntax with explicit export to GDX file
t3.run();
t3.outDB().doExport(ws.workingDirectory() + cPathSep + "tdata.gdx");
...

How to run a job using data from GDX (Transport3)

This works quite similar to the usage of an include file explained in Transport2 - How to use include files (Transport2).

...
GAMSOptions opt = ws.addOptions();
opt.setDefine("gdxincname", "tdata");
opt.setAllModelTypes("xpress");
t3.run(opt);
...

Note that there are some changes in getModelText due to the usage of a GDX file 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
...

How to run a job using implicit database communication (Transport3)

This example does basically the same as the two preceding examples together. We create two GAMSJobs 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 outDB can be read in directly just like a gdx file. Note that the database needs to be passed to the GAMSJob.run method as additional argument.

...
t3a.run();
opt.setDefine("gdxincname", t3a.outDB().name());
t3b.run(opt, t3a.outDB());
...

How to define data using C++ data structures (Transport4)

We use the vector<T> and map<Key, Value> to define C++ data structures that correspond to the sets, parameters and tables used for the data definition in GAMS.

...
vector<string> plants = {
"Seattle", "San-Diego"
};
vector<string> markets = {
"New-York", "Chicago", "Topeka"
};
map<string, double> capacity = {
{ "Seattle", 350.0 }, { "San-Diego", 600.0 }
};
map<string, double> demand = {
{ "New-York", 325.0 }, { "Chicago", 300.0 }, { "Topeka", 275.0 }
};
map<tuple<string, string>, double> distance = {
{ make_tuple("Seattle", "New-York"), 2.5 },
{ make_tuple("Seattle", "Chicago"), 1.7 },
{ make_tuple("Seattle", "Topeka"), 1.8 },
{ make_tuple("San-Diego", "New-York"), 2.5 },
{ make_tuple("San-Diego", "Chicago"), 1.8 },
{ make_tuple("San-Diego", "Topeka"), 1.4 }
};
...

How to prepare a GAMSDatabase from C++ data structures (Transport4)

At first we create an empty GAMSDatabase db using the GAMSWorkspace.addDatabase method. Afterwards we prepare the database. To add a set to the database we use the GAMSSet class and the GAMSDatabase.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 C++ data structure and add them by using the GAMSSet.addRecord method. We do pretty much the same thing for the parameters.

Note that the table that specifies the distances in GAMS can be treated as parameter with dimension 2 and that the scalars can be treated as parameter with dimension 0.

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

...
GAMSDatabase db = ws.addDatabase();
GAMSSet i = db.addSet("i", 1, "canning plants");
for (string p: plants)
i.addRecord(p);
...
GAMSParameter a = db.addParameter("a", "capacity of plant i in cases", i);
for (string p: plants)
a.addRecord(p).setValue(capacity[p]);
...
GAMSParameter d = db.addParameter("d", "distance in thousands of miles", i, j);
for (auto t : distance)
d.addRecord(get<0>(t.first), get<1>(t.first)).setValue(t.second);
GAMSParameter f = db.addParameter("f", "freight in dollars per case per thousand miles");
f.addRecord().setValue(90);
// run a job using data from the created GAMSDatabase
GAMSOptions opt = ws.addOptions();
opt.setDefine("gdxincname", db.name());
opt.setAllModelTypes("xpress");
t4.run(opt, db);
...

How to initialize a GAMSCheckpoint by running a GAMSJob (Transport5)

The following two lines of code conduct several operations. While the first line simply creates a GAMS checkpoint, the second one uses the GAMSWorkspace.addJobFromString method to create a GAMSJob containing the model text and data but no solve statement. In contrast to the preceding examples it runs the job immediately using the GAMSJob.run method. Furthermore, it passes an additional checkpoint argument to the run method. That means the GAMSCheckpoint cp captures the state of the GAMSJob.

...
GAMSCheckpoint cp = ws.addCheckpoint();
...
ws.addJobFromString(getModelText()).run(cp);
...

How to initialize a GAMSJob from a GAMSCheckpoint (Transport5)

Note that the string returned from function getModelText() 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';
...

We create a vector with eight different values for this demand multiplier.

vector<double> bmultlist = { 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3 };

For each entry of the vector we create a GAMSJob t5 using the GAMSWorkspace.addJobFromString method. Besides the 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 GAMSJob combined from the checkpoint plus the content provided by the string.

We run the GAMSJob and echo some interesting data from the outDB using the GAMSDatabase.getParameter and GAMSDatabase.getVariable methods, the GAMSParameter.findRecord and GAMSVariable.findRecord methods plus the GAMSParameterRecord.value and the GAMSVariableRecord.level methods.

...
for (double b : bmultlist)
{
GAMSJob t5 = ws.addJobFromString("bmult=" + to_string(b) + "; solve transport min z use lp; ms=transport.modelstat; ss=transport.solvestat;", cp);
t5.run();
cout << "Scenario bmult=" << b << ":" << endl;
cout << " Modelstatus: " << t5.outDB().getParameter("ms").findRecord().value() << endl;
cout << " Solvestatus: " << t5.outDB().getParameter("ss").findRecord().value() << endl;
cout << " Obj: " << t5.outDB().getVariable("z").findRecord().level() << endl;
}
...
Note
Some of 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.

How to run multiple GAMSJobs in parallel using a GAMSCheckpoint (Transport6)

This example illustrates how to run the jobs we already know from Transport5 in parallel. We create a GAMSCheckpoint cp and initialize it by running a GAMSJob. Furthermore we introduce a demand multiplier as we did before.

...
GAMSCheckpoint cp = ws.addCheckpoint();
vector<double> bmultlist = { 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3 };
...

Furthermore, we introduce a new object ioMutex that will be used to avoid mixed up output from the parallel jobs. For each element b from the vector of demand multipliers we create a thread executing the runScenario method.

...
// run multiple parallel jobs using the created GAMSCheckpoint
mutex ioMutex;
vector<thread> v;
for(double b : bmultlist)
v.emplace_back([&ws, cp, &ioMutex, b]{runScenario(&ws, cp,&ioMutex,b);});
for (auto& t : v)
t.join();
...

In function runScenario a GAMSJob is created and run just like in the preceding example of Transport5. The output section is also the same except for the fact that it is locked by using a lock_guard on the ioMutex. That means the threads of runScenario are running in parallel but the output block of different threads cannot be executed in parallel since it is locked using the same ioMutex.

...
void Transport6::runScenario(GAMSWorkspace* ws, const GAMSCheckpoint& cp, mutex* ioMutex, double b)
{
auto t6 = ws->addJobFromString("bmult=" + to_string(b) + "; solve transport min z use lp; ms=transport.modelstat; ss=transport.solvestat;", cp);
t6.run();
// we need to make the ouput a critical section to avoid messed up report information
lock_guard<mutex> lck(*ioMutex);
cout << "Scenario bmult=" << b << ":" << endl;
cout << " Modelstatus: " << t6.outDB().getParameter("ms").findRecord().value() << endl;
cout << " Solvestatus: " << t6.outDB().getParameter("ss").findRecord().value() << endl;
cout << " Obj: " << t6.outDB().getVariable("z").findRecord().level() << endl;
}
...

While the output in Transport5 is strictly ordered subject to the order of the elements of bmultlist, in Transport6 the output blocks might change their order but the blocks describing one scenario are still appearing together due to the lock_guard mechanism.

If you want a further impression of the impact of the lock_guard, just rerun Transport6 but comment out the lock_guard as follows and compare the output.

...
void Transport6::runScenario(GAMSWorkspace* ws, const GAMSCheckpoint& cp, mutex* ioMutex, double b)
{
auto t6 = ws->addJobFromString("bmult=" + to_string(b) + "; solve transport min z use lp; ms=transport.modelstat; ss=transport.solvestat;", cp);
t6.run();
// we need to make the ouput a critical section to avoid messed up report information
// lock_guard<mutex> lck(*ioMutex);
cout << "Scenario bmult=" << b << ":" << endl;
cout << " Modelstatus: " << t6.outDB().getParameter("ms").findRecord().value() << endl;
cout << " Solvestatus: " << t6.outDB().getParameter("ss").findRecord().value() << endl;
cout << " Obj: " << t6.outDB().getVariable("z").findRecord().level() << endl;
}
...

How to create a GAMSModelInstance from a GAMSCheckpoint (Transport7)

In Transport7 the usage of gams::GAMSModelInstance is demonstrated.

At first we create a checkpoint cp as in the preceding examples. Then we create the GAMSModelInstance mi using the GAMSCheckpoint.addModelInstance method. Note that the GAMSJob again contains no solve statement and the demand multiplier is already included with default value 1.

...
GAMSCheckpoint cp = ws.addCheckpoint();
GAMSJob t7 = ws.addJobFromString(getModelText());
t7.run(cp);
GAMSModelInstance mi = cp.addModelInstance();
...

How to modify a parameter of a GAMSModelInstance using GAMSModifier (Transport7)

A GAMSModelInstance uses a syncDB to maintain the data. We define bmult as GAMSParameter using the GAMSDatabase.addParameter method and specify cplexd as solver. Afterwards the GAMSModelInstance is instantiated with three arguments: the solve statement, the GAMSOptions object opt and bmult. The GAMSModifier means that bmult is modifiable while all other parameters, variables and equations of GAMSModelInstance mi stay unchanged.

We use the GAMSParameter.addRecord method to assign a value to bmult that can be varied afterwards using the GAMSParameter.firstRecord method to reproduce our well-known example with different demand multipliers.

...
GAMSModelInstance mi = cp.addModelInstance();
GAMSParameter bmult = mi.syncDb().addParameter("bmult", 0, "demand multiplier");
GAMSOptions opt = ws.addOptions();
opt.setAllModelTypes("cplexd");
// instantiate the GAMSModelInstance and pass a model definition and GAMSModifier to declare bmult mutable
mi.instantiate("transport use lp min z", opt, GAMSModifier(bmult));
bmult.addRecord().setValue(1.0);
vector<double> bmultlist = { 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3 };
for (double b : bmultlist) {
bmult.firstRecord().setValue(b);
mi.solve();
cout << "Scenario bmult=" << b << ":" << endl;
cout << " Modelstatus: " << mi.modelStatusAsString() << endl;
cout << " Solvestatus: " << mi.solveStatusAsString() << endl;
cout << " Obj: " << mi.syncDb().getVariable("z").findRecord().level() << endl;
}
...

How to modify a variable of a GAMSModelInstance using GAMSModifier (Transport7)

We create a GAMSModelInstance and define x as GAMSVariable and its upper bound as GAMSParameter xup. At the following instantiate method GAMSModifier has three 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 GAMSParameter 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();
GAMSVariable x = mi.syncDb().addVariable("x", 2, GAMSEnum::VarType::Positive, "");
GAMSParameter xup = mi.syncDb().addParameter("xup", 2, "upper bound on x");
// instantiate the GAMSModelInstance and pass a model definition and GAMSModifier to declare upper bound of X mutable
mi.instantiate("transport use lp min z", GAMSModifier (x, GAMSEnum::SymbolUpdateAction::Upper, xup));
for (GAMSSetRecord i : t7.outDB().getSet("i")) {
for (GAMSSetRecord j : t7.outDB().getSet("j")) {
xup.clear();
xup.addRecord(i.key(0), j.key(0)).setValue(0);
mi.solve();
cout << "Scenario link blocked=" << i.key(0) << "-" << j.key(0) << endl;
cout << " Modelstatus: " << mi.modelStatusAsString() << endl;
cout << " Solvestatus: " << mi.solveStatusAsString() << endl;
cout << " Obj: " << mi.syncDb().getVariable("z").findRecord().level() << endl;
}
}
...

How to use a queue to solve multiple GAMSModelInstances in parallel (Transport8)

We initialize a GAMSCheckpoint cp from a GAMSJob. Then we define a vector that represents the different values of the demand multiplier. While ioMutex is used to avoid messed up output, vectorMutex synchronizes the access to the vector. Then we start multiple thread executing the method scenSolve. The number of parallel executed threads is specified by nrThreads. All trheads share the same vector that provides the different values for bmult.

...
GAMSCheckpoint cp = ws.addCheckpoint();
ws.addJobFromString(getModelText()).run(cp);
vector<double> bmultVector = { 1.3, 1.2, 1.1, 1.0, 0.9, 0.8, 0.7, 0.6 };
int nrThreads = 2;
std::mutex vectorMutex;
std::mutex ioMutex;
vector<thread> v;
for (int i = 0; i < nrThreads; i++)
v.emplace_back([&ws, &cp, &bmultVector, &vectorMutex, &ioMutex] {scenSolve(&ws, &cp, &bmultVector, &vectorMutex, &ioMutex);});
for (auto& t : v)
t.join();
...

In scenSolve we create and instantiate a GAMSModelInstance as in the preceding examples and make bmult modifiable. As long as bmultVector is not empty, an elements is taken and removed from the vector. The value is used for the scalar bmult. Note that we chose cplexd as solver because it is thread safe (gurobi would also be possible). Once the vector is empty the loop terminates.

void Transport8::scenSolve(GAMSWorkspace* ws, GAMSCheckpoint* cp, vector<double>* bmultVector, std::mutex* vectorMutex, std::mutex* ioMutex)
{
unique_lock<mutex> vectorLock(*vectorMutex);
GAMSModelInstance mi = cp->addModelInstance();
vectorLock.unlock();
GAMSParameter bmult = mi.syncDb().addParameter("bmult", "demand multiplier");
GAMSOptions opt = ws->addOptions();
opt.setAllModelTypes("cplexd");
// instantiate the GAMSModelInstance and pass a model definition and GAMSModifier to declare bmult mutable
mi.instantiate("transport use lp min z", opt, GAMSModifier(bmult));
bmult.addRecord().setValue(1.0);
while (true)
{
double b;
// dynamically get a bmult value from the vector instead of passing it to the different threads at creation time
vectorLock.lock();
if (bmultVector->empty())
return;
b = bmultVector->back();
bmultVector->pop_back();
vectorLock.unlock();
bmult.firstRecord().setValue(b);
mi.solve();
// we need to make the output a critical section to avoid messed up report informations
unique_lock<mutex> ioLock(*ioMutex);
cout << "Scenario bmult=" << b << ":" << endl;
cout << " Modelstatus: " << mi.modelStatus() << endl;
cout << " Solvestatus: " << mi.solveStatus() << endl;
cout << " Obj: " << mi.syncDb().getVariable("z").findRecord().level() << endl;
ioLock.unlock();
}
}

How to fill a GAMSDatabase by reading from MS Access (Transport9)

This example illustrates how to import data from Microsoft Access to a GAMSDatabase. It can only be run on Windows since it makes use of the Microsoft Access Driver. Furthermore the example makes use of the Qt SQL module. Note that you need to have Microsoft Access installed and that its bitness needs to match the bitness of your GAMS version. In the example we call a function readFromAccess that finally returns a GAMSDatabase as shown below.

...
GAMSDatabase db = readFromAccess(ws);
...

The data we are going to read can be found in <GAMS system directory>\apifiles\Data\transport.accdb. It might be helpful to open this file for a better understanding. The function begins with the creation of an empty GAMSDatabase. Afterwards we create a QSqlDatabase, specify the connection string and open the connection to the database. If opening the connection was successful, data is read from the database into the GAMSDatabase using the methods readSet and readParameter.

GAMSDatabase readFromAccess(GAMSWorkspace ws)
{
GAMSDatabase db = ws.addDatabase();
QSqlDatabase sqlDb = QSqlDatabase::addDatabase("QODBC", "readConnection");
QString strAccessConn = ("Driver={Microsoft Access Driver (*.mdb, *.accdb)};DSN='';DBQ=" + ws.systemDirectory() \
+ cPathSep + "apifiles" + cPathSep + "Data" + cPathSep + "transport.accdb").c_str();
sqlDb.setDatabaseName(strAccessConn);
if(sqlDb.open())
{
// read GAMS sets
readSet(sqlDb, db, "SELECT Plant FROM Plant", "i", 1, "canning plants");
readSet(sqlDb, db, "SELECT Market FROM Market", "j", 1, "markets");
// read GAMS parameters
readParameter(sqlDb, db, "SELECT Plant,Capacity FROM Plant", "a", 1, "capacity of plant i in cases");
readParameter(sqlDb, db, "SELECT Market,Demand FROM Market", "b", 1, "demand at market j in cases");
readParameter(sqlDb, db, "SELECT Plant,Market,Distance FROM Distance", "d", 2, "distance in thousands of miles");
sqlDb.close();
}
else
{
cout << "Error: Failed to create a database connection. " << sqlDb.lastError().text().toStdString() << endl;
exit(1);
}
return db;
}

The function readSet creates a QSqlQuery that reads data from a table of the Access database. A GAMSSet is created and populated with the data.

void readSet(QSqlDatabase sqlDb, GAMSDatabase db, string strAccessSelect, string setName, int setDim, string setExp = "")
{
QSqlQuery query(sqlDb);
if (!query.exec(strAccessSelect.c_str()))
{
cout << "Error executing query on set '" << setName << "'" << endl;
cout << query.lastError().text().toStdString() << endl;
exit(1);
}
if (query.size() && (query.record().count() != setDim))
{
cout << "Number of fields in select statement does not match setDim" << endl;
exit(1);
}
GAMSSet i = db.addSet(setName, setDim, setExp);
vector<string> keys = vector<string>(setDim);
while (query.next())
{
for (int idx = 0; idx < setDim; idx++)
keys[idx] = query.value(idx).toString().toStdString();
i.addRecord(keys);
}
}

Once we read in all the data we can create a GAMSJob from the GAMSDatabase and run it as usual. Finally the results are written to transport.accdb.

How to fill a GAMSDatabase by reading from MS Excel (Transport10)

This example illustrates how to read data from Excel, or to be more specific, from <GAMS system directory>\apifiles\Data\transport.xls. It can only be run on Windows. Note that you need to have Microsoft Excel installed and that its bitness needs to match the bitness of your GAMS version. The model is given as string without data like in in many examples before. At first we have to add

#include <QAxObject>
#include <Windows.h>

to be able to use the QAxObject class, which serves as a wrapper for COM objects. Furthermore we include Windows.h to access the functions CoInitialize and CoUninitialize. In the main function we open the aforementioned file to get access to its content. Note that we need to call CoInitialize(0) first in order to initialize ActiveX. We create an instance of the class QAxObject and use the querySubObject method multiple times to get to the sheets of the workbook.

...
QAxObject* excel = new QAxObject( "Excel.Application", 0 );
QAxObject* workbooks = excel->querySubObject( "Workbooks" );
QAxObject* workbook = workbooks->querySubObject( "Open(const QString&)", fileName );
QAxObject* sheets = workbook->querySubObject( "Worksheets" );
...

The method sheetToParameter is used in order to transfer data from the workbook into GAMSParameter instances. In order to determine from which sheet the actual data needs to be read, the method takes the QAxObject instance referring to the sheets and the actual sheet name. A new GAMSParameter is added to the GAMSDatabase object db using set1 and set2 as domains. The next step is to determine the number of columns and the number of rows used. The for loop reads the actual data, adds the records to the new GAMSParameter and sets their values.

...
GAMSParameter sheetToParameter(QAxObject* sheets, string sheetName, GAMSDatabase db, string paramName, string paramText, GAMSSet set1, GAMSSet set2)
{
QAxObject* sheet = sheets->querySubObject( "Item( string )", sheetName.c_str() );
vector<GAMSDomain> sets {set1, set2};
GAMSParameter param = db.addParameter(paramName, paramText, sets);
QAxObject* usedrange = sheet->querySubObject( "UsedRange");
QAxObject * columns = usedrange->querySubObject("Columns");
int intCols = columns->property("Count").toInt();
QAxObject * rows = usedrange->querySubObject("Rows");
int intRows = rows->property("Count").toInt();
for (int j = 2; j <= intCols; j++) {
string namej = sheet->querySubObject("Cells( int, int )", 1, j)->dynamicCall("Value()").toString().toStdString();
for (int i = 2; i <= intRows; ++i) {
string namei = sheet->querySubObject("Cells( int, int )", i, 1)->dynamicCall("Value()").toString().toStdString();
GAMSParameterRecord rec = param.addRecord(namei, namej);
double value = sheet->querySubObject("Cells( int, int )", i, j)->dynamicCall("Value()").toDouble();
rec.setValue(value);
}
}
return param;
}
...

After all required data was read from the workbook, we need to close it and quit the Excel application.

...
workbook->dynamicCall("Close()");
excel->dynamicCall("Quit()");
...

Now we can create und run the GAMSJob using the created GAMSDatabase as usual.

...
GAMSOptions opt = ws.addOptions();
GAMSJob t10 = ws.addJobFromString(getModelText());
opt.setDefine("gdxincname", db.name());
opt.setAllModelTypes("xpress");
t10.run(opt, db);
for (GAMSVariableRecord record : t10.outDB().getVariable("x"))
cout << "x(" << record.key(0) << "," << record.key(1) << "): level=" << record.level() <<
" marginal=" << record.marginal() << endl;
...

Finally we need to call `CoUninitialize' in order to close the COM library.

...
::CoUninitialize();
...

How to create and use a save/restart file (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 GAMSCheckpoint. We start by creating the save/restart file by calling createSaveRestart.

...
std::string cpName = "tbase";
createSaveRestart(argc, argv, cpName);
...

In function createSaveRestart we choose the checkpointName as relative path to the current directory in order to create a GAMSWorkspace. Then we create a GAMSJob from a string. Note that the string given via getBaseModelText() contains the basic definitions of sets without giving them a content (that is what $onempty is used for). Afterwards we specify a GAMSOption to only compile the job without executing it. Then we create a checkpoint cp that is initialized by the following run of the GAMSJob and stored in the file given as argument to the function. This becomes possible because the addCheckpoint method accepts identifiers as well as file names as argument.

void createSaveRestart(int argc, char* argv[], const string &checkpointName)
{
GAMSWorkspaceInfo wsInfo;
if (argc > 1)
wsInfo.setSystemDirectory(argv[1]);
wsInfo.setWorkingDirectory("." +(cPathSep+ checkpointName));
GAMSWorkspace ws(wsInfo);
GAMSJob j1 = ws.addJobFromString(getBaseModelText());
GAMSOptions opt = ws.addOptions();
opt.setAction(GAMSOptions::EAction::CompileOnly);
auto checkpoint = ws.workingDirectory() + cPathSep + checkpointName;
GAMSCheckpoint cp = ws.addCheckpoint(checkpoint);
j1.run(opt, cp);
}

So what you should keep in mind before we return to further explanations of the main function is, that now the file tbase in folder tbase contains a checkpoint. Now in the main function we define some data using C++ data structures as we already did in Transport4 before we create another GAMSWorkspace.

...
GAMSWorkspaceInfo wsInfo;
if (argc > 1)
wsInfo.setSystemDirectory(argv[1]);
wsInfo.setWorkingDirectory("." +(cPathSep+ cpName));
GAMSWorkspace ws(wsInfo);
...

Afterwards we set up the GAMSDatabase like we already did in Transport4. Once this is done we run a GAMSJob using this data plus the checkpoint stored in file tbase.

...
GAMSCheckpoint cpBase = ws.addCheckpoint("tbase");
GAMSOptions opt = ws.addOptions();
GAMSJob t4 = ws.addJobFromString(getModelText(), cpBase);
opt.setDefine("gdxincname", db.name());
opt.setAllModelTypes("xpress");
t4.run(opt, db);
for (auto record : t4.outDB().getVariable("x"))
cout << "x(" << record.key(0) << "," << record.key(1) << "): level=" << record.level() <<
" marginal=" << record.marginal() << endl;
...

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