Tutorial

Table of Contents

The goal of this tutorial is to provide a compact overview of the basic functionality of the GAMS Java 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.

Getting started

Since GAMS 44.1.0, a Java program that uses GAMS Java API requires at least Java SE 11 to compile and run. For a Java program that still requires Java SE 8 to compile and run, it is possible to use a separate version of GAMS Java API that targets Java SE 8, but the new or updated functionalities that are released after GAMS 43 are not avaiable in this Java API version.

For all platforms, assume GAMS system has been installed at [PathToGAMS] directory, called GAMS directory. The directory [PathToGAMS] denotes the path setting according to your GAMS installation on targeted platforms. For instance

  • on Windows-based platforms with GAMS distribution 48.3 installed, [PathToGAMS] denotes C:\GAMS\win64\48.3
  • on Unix-based platforms with GAMS distribution 48.3 installed, [PathToGAMS] denotes /usr/gams/gams48.3_linux_x64_64_sfx

All GAMS Java API classes are contained within one single jar file GAMSJavaAPI.jar (or GAMSJavaAPI-8.jar for Java SE 8) with a namespace com.gams.api. The jar files are distributed with the current GAMS distribution and located at

  • on Windows-based platforms: 
    [PathToGAMS]\apifiles\Java\api\GAMSJavaAPI.jar
  • on Unix-based platforms: 
    [PathToGAMS]/apifiles/Java/api/GAMSJavaAPI.jar
Note
Since GAMS 44.1.0, GAMS Java API has an additional dependency on JSON.simple, a simple Java library for JSON processing, read and write JSON data. Compiling and running a program that uses GAMSJavaAPI.jar requires json-simple-1.1.1.jar to be in the same directory as GAMSJavaAPI.jar (This is not the case for GAMSJavaAPI-8.jar). Missing json-simple-1.1.1.jar from the same directory might raise runtime exception when using related functionality in the GAMS Java API.

There are two different approaches of how to use the GAMS Java API. Either the Java source files can be edited with any common editor and compiled from command line or a Java IDE can be used. The following sections give a quick introduction about the different possibilities.

Compiling a Program

To compile a Java program, one usually provides the following information to Java compiler:

  • the directory(ies) containing all required Java class files
  • the directory to place the generated class files
  • the name of the Java source file

A Java program that uses GAMS Java API requires class files that are contained in GAMSJavaAPI.jar for compilation (or in GAMSJavaAPI-8.jar for Java SE 8).

Compiling a Program from Command Line

To compile a Java program that uses GAMS Java API, for instance HelloAPI.java, at the command line:

javac -cp [CLASSPATH] -d [TARGETDIR] HelloAPI.java

where 

[CLASSPATH]  is 'GAMSJavaAPI.jar' (or `GAMSJavaAPI-8.jar` for Java SE 8) with its location, 
             as it contains class files that are used by 'HelloAPI.java'.
             On Windows-based platform, [CLASSPATH] denotes 
                 [PathToGAMS]\apifiles\Java\api\GAMSJavaAPI.jar
             On Unix-based platforms, [CLASSPATH] denotes 
                 [PathToGAMS]/apifiles/Java/api/GAMSJavaAPI.jar

[TARGETDIR]  is the directory to place the generated classe file.
Note
  • it is possible to add [CLASSPATH] to your CLASSPATH environment variable of the operating system as an alternative to specifying -cp [CLASSPATH].
  • -d [TARGETDIR] is optional. In case -d [TARGETDIR] is omited and the compilation is successful, the class file will be generated and located under the current directory.
  • GAMSJavaAPI.jar has an additional dependency on json-simple-1.1.1.jar (not the case for GAMSJavaAPI-8.jar). Though it is not necessary to add json-simple-1.1.1.jar to [CLASSPATH] as it already been added into the GAMSJavaAPI.jar's Classpath. It is important, however, for json-simple-1.1.1.jar to be in the same directory as GAMSJavaAPI.jar.

To compile other programs, change the arguments accordingly. See also How to compile and run examples from the GAMS system directory.

Compiling a Program from Java IDE

In case of compiling a program under a Java IDE (for instance, Eclipse, NetBeans, or IntelliJ), the location of the jar file GAMSJavaAPI.jar (or GAMSJavaAPI-8.jar for Java SE 8) shall be added into the Java build path of the IDE's project properties.

For an Eclipse user, see How to import an Eclipse Java Project from the GAMS system directory.

Running a Program

To run a Java program, one usually provide the following information to Java Virtual Machine:

  • the directory(ies) containing all required Java classes
  • the directory(ies) containing all required shared libraries
  • the name of an entry point class (in most case containing main method)

A Java program that uses GAMS Java API requires a number of shared libraries for establishing a connection with GAMS software components during run time. These shared libraries are platform dependent and they are located at [PathToGAMS]/apifiles/Java/api directory.

Running a Program from Command Line

To run a Java program that uses GAMS Java API, for instance HelloAPI.class containing in [TARGETDIR] directory, at the command line type:

java -cp [CLASSPATH]  HelloAPI

where 

[CLASSPATH]  is the list of two paths, a path of 'GAMSJavaAPI.jar' (or `GAMSJavaAPI-8.jar` for Java SE 8)
             and a path of targeted directory containing 'HelloAPI.class', separated by path separator 
             on the targeted platform. 
             On Windows-based platform, [CLASSESPATHS] denotes 
                 [PathToGAMS]\apifiles\Java\api\GAMSJavaAPI.jar;[TARGETDIR]
             On Unix-based platform, [CLASSESPATHS] denotes 
                 [PathToGAMS]/apifiles/Java/api/GAMSJavaAPI.jar:[TARGETDIR]

HelloAPI     is the name of an entry point class containing main method

Please note that it is possible to add [CLASSPATH] to your CLASSPATH environment variable of the operating system as an alternative to specify -cp [CLASSPATH].

Attention
Most operations performed by GAMS Java API such as gdx or options operations require shared libraries (located in the folder [PathToGAMS]/apifiles/Java/api by default) when running a program. It is recommended to specify the path to shared libraries when running a program. In case no java.library.path has been specified when running a program, the Java API will determine the path of the shared libraries from the java class path containing GAMSJavaAPI.jar.

It is possible to specify the path to shared libraries by passing the following argument to Java Virtual Machine: 

-Djava.library.path=[LIBRARYPATH]

where [LIBRARYPATH] describes the list of paths containing all required shared libraries (as previously mentioned, it is [PathToGAMS]/apifiles/Java/api by default). In such case, the Java API will give priority to the java library path when loading all required JNI libraries during run time. The java API will raise an exception when either the java virtual machine fails to load the required libraries from the specified java library path or there is a version conflict of shared libraries during run time.

To run other programs, change the arguments accordingly. See also How to compile and run examples from the GAMS system directory.

Running a Program from Java IDE

In case of running a program under a Java IDE (for instance, Eclipse, NetBeans, or IntelliJ), it is possible to set the nessary arguments via the properties of the IDE project.

For an Eclipse user, see How to import an Eclipse Java Project from the GAMS system directory.

Setting Up Your Environment

Since 24.3, the GAMS system directory can be specified within the program during run time. Therefore the setting up of execution environment before running a program is no longer required (see also Release Notes 24.3).

Nevertheless, it is still possible to preconfigure the GAMS system directory before running a program and use the default workspace setting within a program. In the default setting, GAMS system directory is not specified by a user within the program. The directory will be searched during run time from environment variable in the following order (depends on the target platform):

  • On Windows-based platform: first from PATH environment variable. If not found, from the platform windows registry gams.location,
  • On macOS-based platform: first from PATH environment variable. If not found, from DYLD_LIBRARY_PATH,
  • On other Unix-based platfrom: from PATH environment variable. If not found, from LD_LIBRARY_PATH.

The following examples illustrate how to add [PathToGAMS] into the environment variable PATH on different platforms:

  • On Windows 2000, XP, Vista, or Windows 7 desktop: 
    > right-click on 'My Computer'
> choose 'Properties' (alternatively, click on 'System' icon in the control panel)
> click on 'Advanced' tab (or 'Advance system settings') 
> click on 'Environment Variables' 
> edit 'PATH' by adding [PathToGAMS] to the variable using a semi-colon as a separator.
  • On Window-based platform via command line terminal: 
    set PATH=[PathToGAMS];%PATH%
  • On Unix-based platform via command line terminal using Bourne shell and its derivatives: 
    export PATH=[PathToGAMS]:${PATH}
  • On Unix-based platform via command line terminal using C Shell: 
    setenv PATH [PathToGAMS]:${PATH}

How to compile and run examples from the GAMS system directory

GAMS provides several examples to demonstrate how to use GAMS Java API. These examples are located in the [PathToGAMS]/apifiles/Java directory containing various examples based on the different optimization problems. The following explanations guide you through the compilation and execution process of one example based on the well-known transportation problem, assuming that Java Runtime System is already installed on your machine.

For instance, Transport1.java under the directory [PathToGAMS]/apifiles/Java/transport demonstrates how to retrieve GAMS transport model from GAMS Model Library, execute the model with various GAMS options, and extract results after execution.

To compile Transport1.java at the command line under the directory [PathToGAMS]/apifiles/Java/transport:

javac -cp [CLASSPATH] -d [TARGETDIR] Transport1.java

where 

[CLASSPATH]  is a location of 'GAMSJavaAPI.jar' (or `GAMSJavaAPI-8.jar` for Java SE 8),
             as it contains classes files that are used by 'Transport1.java'. 
             On Windows-based platform, [CLASSPATH] denotes 
                [PathToGAMS]\apifiles\Java\api\GAMSJavaAPI.jar; 
             On Unix-based platforms, [CLASSESPATHS] denotes 
                [PathToGAMS]/apifiles/Java/api/GAMSJavaAPI.jar

[TARGETDIR]  is the destination directory to place the generated classed file.

As Transport1.java is declared under package com.gams.examples.transport, the output class file will be located in [TARGETDIR] under the directory structure corresponding to package information. This means the compiled output file Transport1.class is located under:

  • [TARGETDIR]\com\gams\examples\transport on Windows-based platform, or
  • [TARGETDIR]/com/gams/examples/transport on Unix-based platforms.

To run Transport1.class from the command line:

java -cp [CLASSPATH] com.gams.examples.transport.Transport1

where 

[CLASSPATH]  is the list of two paths, 'GAMSJavaAPI.jar' (or `GAMSJavaAPI-8.jar`
             for Java SE 8) with its path and a directory containing 'Transport1.class'
             and (in this case [TARGETDIR] from the compliation step), separated by 
             path separator on the targeted platform. 
             On Windows-based platform, [CLASSESPATHS] denotes 
                [PathToGAMS]\apifiles\Java\api\GAMSJavaAPI.jar;[TARGEDIR] 
             On Unix-based platforms, [CLASSESPATHS] denotes 
                [PathToGAMS]/apifiles/Java/api/GAMSJavaAPI.jar:[TARGEDIR]

Please note that the path [TARGETDIR] can be either absolute or relative path representing the directory that contains Transport1.class.

To compile and run other examples under the directory [PathToGAMS]/apifiles/Java, adjust the arguments accordingly.

See How to use API for detailed explanations on the series of transportation problem examples located in the folder [PathToGAMS]/apifiles/Java/transport.

How to import an Eclipse Java Project from the GAMS system directory

Since GAMS version 24.2 there is an prepared Java project that can be imported into Eclipse. The project is located in folder [PathToGAMS]/apifiles/Java/Eclipse and contains the examples based on the transportation problem. The following explanations guide you through the import and preparation process, assuming that the Eclipse Java IDE is already installed on your machine.

To import the project located in folder [PathToGAMS]/apifiles/Java/Eclipse into the workspace:

  1. open the Eclipse IDE with the chosen workspace location, click on File menu and choose Import.
  2. In the Import window, choose General > Existing Projects into Workspace then click Next.

  3. In the next page of Import window, click Browse.. and select the folder with the prepared project ([PathToGAMS]/apifiles/Java/Eclipse) as root directory.

    We recommend to check for option Copy projects into workspace. Click Finish to finish the Import window.

  4. Now the project is imported, and appears in the Package Explorer window on the left hand side of of the IDE (shown below with its elements expanded).
  5. As every example in the project requires GAMS Java API classes files to compile (all classes are packaged in GAMSJavaAPI.jar located in the folder [PathToGAMS]/apifiles/Java/api), you need to tell eclipse where to find GAMSJavaAPI.jar. To do this, either click on the project then choose Project > Properties or right click on the project name and choose Properties .

  6. The Properties window of the proejct appears. Click Java Build Path on the left of the window, choose Libraries tab, choose Add External JARs....

    select GAMSJavaAPI.jar located in the folder [PathToGAMS]/apifiles/Java/api to be opened.

    and click OK to finish addding [PathToGAMS]/apifiles/Java/api/GAMSJavaAPI.jar to Java Build Path.

  7. Now all the java files should be successfully compiled without errors except for Transport10 (unsuccessful compilation is denoted with red x mark in front of the file name). This is because Transport10 requires an additional jexcelapi JAR file jxl.jar from jexcelapi. It can be downloaded and unzipped the downloaded archive into a local directory e.g. C:\tools. Then the jar file C:\tools\jexcelapi\jxl.jar can be added to the the Java Build Path of the project in a similar way as explained in 6.

  8. To run a transport example, for example Transport1, you need to create a Run Configuration.

    To do this, either click Run menu and choose Run Configurations...

    or open the drop down menu next to the run button and click on Run Configurations....

    Then create a new run configuration by either press the New button in the left hand side of the window or right click at Java Application in the left hand side of the window and choose New.

  9. The run configuration for Transport1 appears.

    For each run configuration it is possible to configure the execution of a program, such as the arguments of the virtual machine, class paths, environment variables and so on.

    For instance, to specify the java.library.path for Transport1 run configuration, choose Arguments tab in the run configuration and specify -Djava.library.path=[PathToGAMS]/apifiles/Java/api as one of the VM arguments. Then Click Apply and Run.

Note that the run configuration described in 8. and 9. is needed to be set for every single example. Once this is done you should be able to use the run configuration to repeat the execution of all the transport examples.

For a more detailed explanations on each transport examples see How to use API.

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. All GAMS Java API classes are contained within one single jar file GAMSJavaAPI.jar (or GAMSJavaAPI-8.jar for Java SE 8) with a namespace com.gams.api. It provides objects to interact with the General Algebraic Modeling System (GAMS). Objects in this namespace allow convenient exchange of input data and model results (GAMSDatabase) and help to create and run GAMS models (GAMSJob), that can be customized by GAMS options (GAMSOptions). Furthermore, it introduces a way to solve a sequence of closely related models in the most efficient way (GAMSModelInstance).

Other classes are GAMSWorkspace, GAMSOptions, GAMSSymbol, and GAMSException.

How to use API

In the GAMS system directory there are some examples provided that illustrate the usage of the Java API. [PathToGAMS]/apifiles/Java/transport contains multiple examples dealing with the well-known transportation problem. In further course of this tutorial we discuss these examples step by step and introduce new elements of the API in detail.

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 choose the GAMS system (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/win64/48.3 we use the 64-bit version of GAMS 48.3 to run Transport1 even if our default GAMS system might be a different one. This is managed by the following code:

...
GAMSWorkspaceInfo wsInfo = new GAMSWorkspaceInfo();
if (args.length > 0)
wsInfo.setSystemDirectory( args[0] );
GAMSWorkspace ws = new GAMSWorkspace(wsInfo);
...
ws
GamsWorkspace ws
args
args

Remember that the bitness of the GAMS system has to match the bitness of your Java Runtime Environment.

How to export data to GDX (TransportGDX)

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

...
List<String> plants = Arrays.asList("Seattle", "San-Diego");
List<String> markets = Arrays.asList("New-York", "Chicago", "Topeka");
Map<String, Double> capacity = new HashMap<String, Double>();
{
capacity.put("Seattle", Double.valueOf(350.0));
capacity.put("San-Diego", Double.valueOf(600.0));
}
Map<String, Double> demand = new HashMap<String, Double>();
{
demand.put("New-York", Double.valueOf(325.0));
demand.put("Chicago", Double.valueOf(300.0));
demand.put("Topeka", Double.valueOf(275.0));
}
Map<Vector<String>, Double> distance = new HashMap<Vector<String>, Double>();
{
distance.put( new Vector<String>( Arrays.asList(new String[]{"Seattle", "New-York"}) ), Double.valueOf(2.5));
distance.put( new Vector<String>( Arrays.asList(new String[]{"Seattle", "Chicago"}) ), Double.valueOf(1.7));
distance.put( new Vector<String>( Arrays.asList(new String[]{"Seattle", "Topeka"}) ), Double.valueOf(1.8));
distance.put( new Vector<String>( Arrays.asList(new String[]{"San-Diego", "New-York"}) ), Double.valueOf(2.5));
distance.put( new Vector<String>( Arrays.asList(new String[]{"San-Diego", "Chicago"}) ), Double.valueOf(1.8));
distance.put( new Vector<String>( Arrays.asList(new String[]{"San-Diego", "Topeka"}) ), Double.valueOf(1.4));
}
...
demand
GamsWorkspace demand
capacity
dict capacity
markets
list markets
distance
dict distance
plants
list plants

Different type of GAMS symbols are represented using different Java data structures. The data for the GAMS sets is represented using List of Strings (e.g. plants and markets). On the other hand, GAMS parameters are represented by Map (e.g. capacity and demand). Note that the representation of the two dimensional parameter distance uses Vectors 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 Java data structures.

A new GAMSDatabase instance can be created using GAMSWorkspace.addDatabase.

...
// create new GAMSDatabase instance
GAMSDatabase db = ws.addDatabase();
...
db
GamsWorkspace db

We start adding GAMS sets using the method GAMSDatabase.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 GAMSSet instance i using GAMSSet.addRecord.

...
GAMSSet i = db.addSet("i", 1, "canning plants");
for(String p : plants)
i.addRecord(p);
...
i
GamsWorkspace i

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

...
GAMSParameter a = db.addParameter("a", "capacity of plant i in cases", i);
for (String p : plants)
a.addRecord(p).setValue( capacity.get(p) );
...
a
GamsWorkspace a

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

...
db.export("data.gdx");
...

How to import data from GDX (TransportGDX)

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

...
GAMSDatabase gdxdb = ws.addDatabaseFromGDX("data.gdx");
...

Reading the data from the GAMSSet i into a List of Strings can be done as follows:

...
List<String> gdxPlants = new ArrayList<String>();
for(GAMSSetRecord rec : gdxdb.getSet("i"))
gdxPlants.add(rec.getKey(0));
...

A new List gdxPlants is created. i is retrieved by calling GAMSDatabase.getSet on gdxdb. The returned GAMSSet object can be iterated using a for-loop to access the records of the set. Each record is of type GAMSSetRecord and can be asked for its keys.

You can do the same for GAMSParameter. Instead of creating a List, we want to have the data in the form of a Map. GAMSParameterRecord 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<String, Double>.

...
Map<String, Double> gdxCapacity = new HashMap<String, Double>();
for(GAMSParameterRecord rec : gdxdb.getParameter("a"))
gdxCapacity.put(rec.getKey(0), rec.getValue());
...

For a key of multi dimensional symbol, we choose Vector of String instead of String.

...
Map<Vector<String>, Double> gdxDistance = new HashMap<Vector<String>, Double>();
for(GAMSParameterRecord rec : gdxdb.getParameter("d"))
gdxDistance.put( new Vector<String>( Arrays.asList(new String[]{rec.getKey(0), rec.getKey(1)}) ), rec.getValue());
...

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

...
double gdxFreight = gdxdb.getParameter("f").getFirstRecord().getValue();
...

How to run a GAMSJob from file (Transport1)

At first we create our workspace using GAMSWorkspace ws = new GAMSWorkspace();. Afterward we can create a GAMSJob t1 using the addJobFromGamsLib method and run it.

Apparently you can create a GAMSJob 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 can be defined using the GAMSJob.addJobFromFile method.

...
// create GAMSWorkspace "ws" with default working directory
// (the directory named with current date and time under System.getProperty("java.io.tmpdir"))
GAMSWorkspace ws = new GAMSWorkspace();
// create GAMSJob "t1" from "trnsport" model in GAMS Model Libraries
GAMSJob t1 = ws.addJobFromGamsLib("trnsport");
// run GAMSJob "t1"
t1.run();
...

See also Transport1.java.

How to retrieve a solution from an output database (Transport1)

The following lines create the solution output and illustrate the usage of the GAMSJob.OutDB property to get access to the GAMSDatabase created by the run method. To retrieve the content of variable x we use the getVariable method and the GAMSVariableRecord class.

...
// retrieve GAMSVariable "x" from GAMSJob's output databases
System.out.println("Ran with Default:");
GAMSVariable x = t1.OutDB().getVariable("x");
for (GAMSVariableRecord rec : x)
{
System.out.print("x(" + rec.getKeys()[0] + ", " + rec.getKeys()[1] + "):");
System.out.print(", level = " + rec.getLevel());
System.out.println(", marginal = " + rec.getMarginal());
}
...
x
GamsWorkspace x

See also Transport1.java.

How to specify the solver using GAMSOptions (Transport1)

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

...
// create GAMSOptions "opt1"
GAMSOptions opt1 = ws.addOptions();
// set all model types of "opt1" for "xpress"
opt1.setAllModelTypes("xpress");
// run GAMSJob "t1" with GAMSOptions "opt1"
t1.run(opt1);
...

See also Transport1.java.

How to run a job with a solver option file and capture its log output (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 a GAMSOptions just like in the preceding example and GAMSOptions.setOptFile 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 GAMSJob 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 GAMSWorkspace's working directory
try {
BufferedWriter optFile = new BufferedWriter(new FileWriter(
ws.workingDirectory() + GAMSGlobals.FILE_SEPARATOR + "xpress.opt"
));
optFile.write("algorithm=barrier");
optFile.close();
} catch(IOException e) {
e.printStackTrace();
System.exit(-1);
}
// create GAMSOptions "opt2"
GAMSOptions 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.setOptFile(1);
try {
// run GAMSJob "t2" with GAMSOptions "opt2" and capture log into "transport1_xpress.log".
PrintStream output = new PrintStream(new File(ws.workingDirectory() + GAMSGlobals.FILE_SEPARATOR +"transport1_xpress.log"));
t1.run(opt2, output);
} catch (FileNotFoundException e) {
// run GAMSJob "t2" with GAMSOptions "opt2" and log is written to standard output
t1.run(opt2);
}
...
output
output

See also Transport1.java.

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 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:

...
try {
BufferedWriter file = new BufferedWriter(new FileWriter(
ws.workingDirectory() + GAMSGlobals.FILE_SEPARATOR + "tdata.gms"
));
file.write(data);
file.close();
} catch(IOException e) {
e.printStackTrace();
System.exit(-1);
}
...

Afterwards we create a GAMSJob using the GAMSWorkspace.addJobFromString method. GAMSOptions.defines is used like 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 GAMSJob "t2" from the "model"
GAMSJob t2 = ws.addJobFromString(model);
// create GAMSOption "opt" and define "incname" as "tdata"
GAMSOptions opt = ws.addOptions();
opt.defines("incname", "tdata");
// run GAMSJob "t2" with GAMSOptions "opt"
t2.run(opt);
...
opt
GamsWorkspace 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%
...

See also Transport2.java.

How to set a non-default working directory (Transport3)

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

...
// create a directory
File workingDirectory = new File(System.getProperty("user.dir"), "Transport3");
workingDirectory.mkdir();
// create a workspace
GAMSWorkspaceInfo wsInfo = new GAMSWorkspaceInfo();
wsInfo.setWorkingDirectory(workingDirectory.getAbsolutePath());
GAMSWorkspace ws = new GAMSWorkspace(wsInfo);
...

See also Transport3.java.

How to read data from string and export to GDX (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 GAMSJob a GAMSDatabase is created that is available via the GAMSJob.OutDB property. We can use the GAMSDatabase.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
GAMSJob t3 = ws.addJobFromString(data);
t3.run();
t3.OutDB().export( ws.workingDirectory() + GAMSGlobals.FILE_SEPARATOR + "tdata.gdx" );
...

See also Transport3.java.

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) .

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

Note that there are some minor changes in 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
...
d
dict d
j
GamsSet j
b
GamsWorkspace b
f
GamsWorkspace f

See also Transport3.java.

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.

...
GAMSVariable x = t3.OutDB().getVariable("x");
for (GAMSVariableRecord rec : x)
System.out.println("x(" + rec.getKeys()[0] + ", " +rec.getKeys()[1] + "): level=" + rec.getLevel() + " marginal=" + rec.getMarginal());
System.out.println();
// similar to the previous run but without exporting database into a file
GAMSJob t3a = ws.addJobFromString(data);
GAMSJob t3b = ws.addJobFromString(model);
opt = ws.addOptions();
t3a.run();
opt.defines("gdxincname", t3a.OutDB().getName());
t3b.run(opt, t3a.OutDB());
...

See also Transport3.java.

How to define data using Java data structures (Transport4)

We use the List<E> class and the Map<Key,Value>to define Java data structures that correspond to the sets, parameters and tables used for the data definition in GAMS.

...
// prepare input data
List<String> plants = Arrays.asList("Seattle", "San-Diego");
List<String> markets = Arrays.asList("New-York", "Chicago","Topeka");
Map<String, Double> capacity = new HashMap<String, Double>();
{
capacity.put("Seattle", Double.valueOf(350.0));
capacity.put("San-Diego", Double.valueOf(600.0));
}
Map<String, Double> demand = new HashMap<String, Double>();
{
demand.put("New-York", Double.valueOf(325.0));
demand.put("Chicago", Double.valueOf(300.0));
demand.put("Topeka", Double.valueOf(275.0));
}
Map<Vector<String>, Double> distance = new HashMap<Vector<String>, Double>();
{
distance.put( new Vector<String>( Arrays.asList(new String[]{"Seattle", "New-York"}) ), Double.valueOf(2.5));
distance.put( new Vector<String>( Arrays.asList(new String[]{"Seattle", "Chicago"}) ), Double.valueOf(1.7));
distance.put( new Vector<String>( Arrays.asList(new String[]{"Seattle", "Topeka"}) ), Double.valueOf(1.8));
distance.put( new Vector<String>( Arrays.asList(new String[]{"San-Diego", "New-York"}) ), Double.valueOf(2.5));
distance.put( new Vector<String>( Arrays.asList(new String[]{"San-Diego", "Chicago"}) ), Double.valueOf(1.8));
distance.put( new Vector<String>( Arrays.asList(new String[]{"San-Diego", "Topeka"}) ), Double.valueOf(1.4));
}
...

See also Transport4.java.

How to prepare a GAMSDatabase from Java 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 Java data structure and add them by using the GAMSSet.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 GAMSJob can be run like explained in the preceding example about implicit database communication.

...
// add a database and add input data into the database
GAMSDatabase db = ws.addDatabase();
GAMSSet i = db.addSet("i", 1, "canning plants");
for(String p : plants)
i.addRecord(p);
GAMSSet j = db.addSet("j", 1, "markets");
for(String m : markets)
j.addRecord(m);
GAMSParameter a = db.addParameter("a", 1, "capacity of plant i in cases");
for (String p : plants)
a.addRecord(p).setValue( capacity.get(p) );
GAMSParameter b = db.addParameter("b", 1, "demand at market j in cases");
for(String m : markets)
b.addRecord(m).setValue( demand.get(m) );
GAMSParameter d = db.addParameter("d", 2, "distance in thousands of miles");
for(Vector<String> vd : distance.keySet())
d.addRecord(vd).setValue( distance.get(vd).doubleValue() );
GAMSParameter f = db.addParameter("f", 0, "freight in dollars per case per thousand miles");
f.addRecord().setValue( 90 );
// create and run a job from the model and read gdx include file from the database
GAMSJob t4 = ws.addJobFromString(model);
GAMSOptions opt = ws.addOptions();
opt.defines("gdxincname", db.getName());
t4.run(opt, db);
...

See also Transport4.java.

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

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

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

See also Transport5.java.

How to initialize a GAMSJob from a GAMSCheckpoint (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';
...
bmult
GamsWorkspace bmult

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

...
double[] bmultlist = new double[] { 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3 };
...
bmultlist
list bmultlist

For each entry of that list we create a GAMSJob t5 using the GAMSWorkspace.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 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.getValue property and the GAMSVariableRecord.getLevel method.

...
// create a new GAMSJob that is initialized from the GAMSCheckpoint
for(double b : bmultlist)
{
t5 = ws.addJobFromString(
"bmult=" + b + "; solve transport min z use lp; ms=transport.modelstat; ss=transport.solvestat;",
cp
);
t5.run();
System.out.println("Scenario bmult=" + b + ":");
System.out.println(
" Modelstatus: " + GAMSGlobals.ModelStat.lookup(
(int) t5.OutDB().getParameter("ms").findRecord().getValue()
)
);
System.out.println(
" Solvestatus: " + GAMSGlobals.SolveStat.lookup(
(int)t5.OutDB().getParameter("ss").findRecord().getValue()
)
);
System.out.println(" Obj: " + t5.OutDB().getVariable("z").findRecord().getLevel());
}
...
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.

See also Transport5.java.

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

This example illustrates how to run the jobs known from Transport5 in parallel. We initialize the GAMSCheckpoint cp and introduce a demand multiplier as we did before :

...
GAMSJob t6 = ws.addJobFromString(model);
t6.run(cp);
double[] bmultlist = new double[] { 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3 };
...

Furthermore, we introduce a new object lockObject that will be used to avoid mixed up output from the parallel jobs. We create one scenario for each entry of bmultlist and cause a thread to begin execution.

...
// run multiple parallel jobs using the created checkpoint
Object lockObject = new Object();
Scenario[] scenarios = new Scenario[bmultlist.length];
for (int i=0; i<bmultlist.length; i++)
{
scenarios[i] = new Scenario(ws, cp, lockObject, bmultlist[i]);
scenarios[i].start();
}
...

In class Scenario a GAMSJob t6 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 the object lockObject which means that the output section cannot be executed simultaneously for multiple demand multipliers.

...
static class Scenario extends Thread
{
GAMSWorkspace workspace;
GAMSCheckpoint checkpoint;
Object lockObject;
double bmult;
public Scenario(GAMSWorkspace ws, GAMSCheckpoint cp, Object lockObj, double b)
{
workspace = ws;
checkpoint = cp;
lockObject = lockObj;
bmult = b;
}
public void run()
{
GAMSJob t6 = workspace.addJobFromString(
"bmult=" + bmult +"; solve transport min z use lp; ms=transport.modelstat;ss=transport.solvestat;",
checkpoint
);
t6.run();
// we need to make the output a critical section to avoid messed up report information
synchronized (lockObject)
{
System.out.println("Scenario bmult=" + bmult + ":");
System.out.println(
" Modelstatus: " + GAMSGlobals.ModelStat.lookup(
(int) t6.OutDB().getParameter("ms").findRecord().getValue()
)
);
System.out.println(
" Solvestatus: " + GAMSGlobals.SolveStat.lookup(
(int)t6.OutDB().getParameter("ss").findRecord().getValue()
)
);
System.out.println(" Obj: " + t6.OutDB().getVariable("z").findRecord().getLevel());
}
}
}
...
checkpoint
checkpoint

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 lockObject.

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

...
// synchronized (lockObject)
// {
System.out.println("Scenario bmult=" + bmult + ":");
System.out.println(
" Modelstatus: " + GAMSGlobals.ModelStat.lookup(
(int) t6.OutDB().getParameter("ms").findRecord().getValue()
)
);
System.out.println(
" Solvestatus: " + GAMSGlobals.SolveStat.lookup(
(int)t6.OutDB().getParameter("ss").findRecord().getValue()
)
);
System.out.println(" Obj: " + t6.OutDB().getVariable("z").findRecord().getLevel());
// }
...

See also Transport6.java.

How to create a GAMSModelInstance from a GAMSCheckpoint (Transport7)

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

At first checkpoint cp is created 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();
// initialize a checkpoint by running a job
GAMSJob t7 = ws.addJobFromString(model);
t7.run(cp);
GAMSModelInstance mi = cp.addModelInstance();
...
mi
GamsWorkspace mi

See also Transport7.java.

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 GAMSParameter method and specify gurobi as solver. Afterwards the GAMSModelInstance is instantiated with 3 arguments, the solve statement, GAMSOptions opt and GAMSModifier bmult. The GAMSModifier means that bmult is modifiable while all other parameters, variables and equations of ModelInstance mi stay unchanged. We use the GAMSParameter.addRecord method and the setValue function to assign a value to bmult. That value can be varied afterwards using the GAMSParameter.getFirstRecord method to reproduce our well-known example with different demand multipliers.

...
GAMSParameter bmult = mi.SyncDB().addParameter("bmult", 0,"demand multiplier");
GAMSOptions opt = ws.addOptions();
opt.setAllModelTypes("gurobi");
// instantiate the ModelInstance and pass a model definition and Modifier to declare bmult mutable
mi.instantiate("transport use lp min z", opt, new GAMSModifier(bmult));
bmult.addRecord().setValue( 1.0 );
double[] bmultlist = new double[] { 0.6, 0.7 , 0.8, 0.9, 1.0,1.1, 1.2, 1.3 };
for (double b : bmultlist)
{
bmult.getFirstRecord().setValue( b );
mi.solve();
System.out.println("Scenario bmult=" + b + ":");
System.out.println(" Modelstatus: " + mi.getModelStatus());
System.out.println(" Solvestatus: " + mi.getSolveStatus());
System.out.println(" Obj: " + mi.SyncDB().getVariable("z").findRecord().getLevel());
}
...

See also Transport7.java.

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

We create a GAMSModelInstance just like in the next to last example. We define x as GAMSVariable and its upper bound as GAMSParameter xup. At the following instantiate method GAMSModifier 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 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, GAMSGlobals.VarType.POSITIVE, "");
GAMSParameter 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", new GAMSModifier(x, GAMSGlobals.UpdateAction.UPPER, xup));
for (GAMSSetRecord i : t7.OutDB().getSet("i"))
{
for (GAMSSetRecord j : t7.OutDB().getSet("j"))
{
xup.clear();
String[] keys = { i.getKeys()[0], j.getKeys()[0] };
xup.addRecord(keys).setValue(0);
mi.solve();
System.out.println("Scenario link blocked: " + i.getKeys()[0] + " - " + j.getKeys()[0]);
System.out.println(" Modelstatus: " + mi.getModelStatus());
System.out.println(" Solvestatus: " + mi.getSolveStatus());
System.out.println(" Obj: " + mi.SyncDB().getVariable("z").findRecord().getLevel());
}
}
...
keys
tuple keys
xup
GamsWorkspace xup

See also Transport7.java.

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

We initialize a GAMSCheckpoint cp from a GAMSJob. Then we define a queue that represents the different values of the demand multiplier. A queue follows the first-in-first-out principle The object IOLockObject is used later to avoid messed up output. Then we call Scenarios multiple times in parallel. The number of parallel calls is specified by numberOfWorkers.

...
GAMSJob t8 = ws.addJobFromString(model);
t8.run(cp);
Queue<Double> bmultQueue = new LinkedList<Double>(
Arrays.asList( Double.valueOf(0.6), Double.valueOf(0.7),
Double.valueOf(0.8), Double.valueOf(0.9),
Double.valueOf(1.0), Double.valueOf(1.1),
Double.valueOf(1.2), Double.valueOf(1.3) )
);
// solve multiple model instances in parallel
Object IOLockObject = new Object();
int numberOfWorkers = 2;
Scenarios[] scenarios = new Scenarios[numberOfWorkers];
for (int i=0; i<numberOfWorkers; i++)
{
scenarios[i] = new Scenarios( ws, cp, bmultQueue, IOLockObject, i );
scenarios[i].start();
}
...

In class Scenarios we create and instantiate a GAMSModelInstance as in the preceding examples and make parameter bmult modifiable. Note that we chose cplex as solver because it is thread safe (gurobi would also be possible). Once the queue is empty the loop terminates.

...
static class Scenarios extends Thread
{
GAMSWorkspace workspace;
GAMSCheckpoint checkpoint;
Object IOLockObject;
Queue<Double> bmultQueue;
int workerNumber;
public Scenarios(GAMSWorkspace ws, GAMSCheckpoint cp, Queue<Double> que, Object IOLockObj, int i)
{
workspace = ws;
checkpoint = cp;
IOLockObject = IOLockObj;
bmultQueue = que;
workerNumber = i;
}
public void run()
{
GAMSModelInstance mi = checkpoint.addModelInstance();
{
GAMSParameter bmult = mi.SyncDB().addParameter("bmult", 0, "demand multiplier");
GAMSOptions opt = workspace.addOptions();
opt.setAllModelTypes("cplex");
// instantiate the GAMSModelInstance and pass a model definition and GAMSModifier to declare bmult mutable
mi.instantiate("transport use lp min z", opt, new
GAMSModifier(bmult));
bmult.addRecord().setValue( 1.0 );
while (true)
double b = 0.0;
// dynamically get a bmult value from the queue instead of passing it to the different threads at creation time
synchronized (bmultQueue)
if (bmultQueue.isEmpty())
break;
else
b = bmultQueue.remove();
}
bmult.getFirstRecord().setValue(b);
mi.solve();
// we need to make the output a critical section to avoid messed up report informations
synchronized (IOLockObject)
{
System.out.println("#"+workerNumber+":Scenario bmult=" + b + ":");
System.out.println(" Modelstatus: " + mi.getModelStatus());
System.out.println(" Solvestatus: " + mi.getSolveStatus());
System.out.println(" Obj: " + mi.SyncDB().getVariable("z").findRecord().getLevel());
}
}
}
}
}
...

See also Transport8.java.

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

This example illustrates how to import data from Microsoft Access to a GAMSDatabase (on Windows platform only). There are a few prerequisites required to run Transport9 successfully.

  • Install a Microsoft access driver on your machine (if none is available) as the driver must be loaded at runtime to connect to a data source file.
  • To access the data source file go to Control Panel\System and Security\Administrative Tools\Data Sources (ODBC) and set up a data source name (DSN) as "transportdsn", leave out user ID and password, and select [PathToGAMS]/apfiles/Data/tansport.accdb as the data source file.
  • Note that an architecture mismatch between the Driver and Application might cause problems.

We call a function readDataFromAccess that finally returns a GAMSDatabase as shown below.

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

The function readDataFromAccess begins with the creation of an empty database. Afterwards we set up a connection to the MS Access database by specifying the aforementioned data source name (DSN). To finally read in GAMS sets and parameters we call the functions readSet and readParameter.

static GAMSDatabase readDataFromAccess(GAMSWorkspace ws)
{
GAMSDatabase db = ws.addDatabase();
try {
// loading the jdbc odbc driver
Class.forName("sun.jdbc.odbc.JdbcOdbcDriver");
// creating connection to database
Connection c = DriverManager.getConnection("jdbc:odbc:transportdsn","","");
// read GAMS sets
readSet(c, db, "SELECT Plant FROM Plant", "i", 1, "canning plants");
readSet(c, db, "SELECT Market FROM Market", "j", 1, "markets");
// read GAMS parameters
readParameter(c, db, "SELECT Plant, Capacity FROM Plant", "a", 1, "capacity of plant i in cases");
readParameter(c, db, "SELECT Market,Demand FROM Market", "b", 1, "demand at market j in cases");
readParameter(c, db, "SELECT Plant,Market,Distance FROM Distance", "d", 2, "distance in thousands of miles");
c.close();
} catch (ClassNotFoundException e) {
System.err.println("Error: Failed to find a driver for the database.");
e.printStackTrace();
System.exit(-1);
} catch (SQLException e) {
System.err.println("Error: Failed to retrieve data from the database.");
e.printStackTrace();
System.exit(-1);
}
return db;
}
c
GamsInteractive c
readSet
void readSet(QSqlDatabase sqlDb, GAMSDatabase db, string strAccessSelect, string setName, int setDim, string setExp="")
readParameter
void readParameter(QSqlDatabase sqlDb, GAMSDatabase db, string strAccessSelect, string parName, int parDim, string parExp="")

The function readSet adds a set to the GAMSDatabase that is filled with the data from the MS Access file afterwards. The function readParameter works quite similar.

static void readSet(Connection c, GAMSDatabase db, String queryString, String setName, int setDimension, String setExplanatoryText) throws SQLException
{
Statement st = c.createStatement();
ResultSet rs = st.executeQuery(queryString);
ResultSetMetaData rsmd = rs.getMetaData();
if (rsmd.getColumnCount() != setDimension)
{
System.err.println("Error: Number of fields in select statement does not match setDimemsion.");
c.close();
System.exit(-1);
}
GAMSSet set = db.addSet(setName, setDimension, setExplanatoryText);
String[] keys = new String[setDimension];
while (rs.next())
{
for (int idx=0; idx < setDimension; idx++)
keys[idx] = rs.getString(idx+1);
set.addRecord( keys );
}
st.close();
}

Once we read in all the data we can create a GAMSJob from the GAMSDatabase and run it as usual.

See also Transport9.java.

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 [PathToGAMS]\apifiles\Data\transport.xlsx.

At first we have to add an additional jar file to the [CLASSESPATH] since we use the Java Excel API which can be donwnloaded from jexcelapi. We unzipped the Java Excel API folder in C:\tools. To compile and run on a Windows platform from the command line go to C:\GAMS\win64\24.1\apifiles\Java\transport and use:

javac -cp C:\GAMS\win64\GAMS_VERSION\apifiles\Java\api\GAMSJavaAPI.jar;C:\tools\jexcelapi\jxl.jar;. -d . Transport10.java

and 

java -cp C:\GAMS\win64\GAMS_VERSION\apifiles\Java\api\GAMSJavaAPI.jar;C:\tools\jexcelapi\jxl.jar;. com.gams.examples.transport.Transport10

If you are using an IDE like Eclipse add C:\tools\jexcelapi\jxl.jar to the class path as explained in the Compiling a Program from Java IDE and Running a Program from Java IDE section.

The model is given as string without data like in many examples before and the Excel file transport.xlsx is located at [gamsdir]\apifiles\Data.

At first we define the input string and create the corresponding input file.

...
String input = gamsdir + "apifiles" +
GAMSGlobals.FILE_SEPARATOR + "Data" + GAMSGlobals.FILE_SEPARATOR + "transport.xlsx";
File inputFile = new File(input);
...

The following lines address the different worksheets and read in the contained data.

...
int iCount = 0;
int jCount = 0;
String[][] capacityData = null;
String[][] demandData = null;
String[][] distanceData = null;
Workbook w;
try {
w = Workbook.getWorkbook(inputFile);
Sheet capacity = w.getSheet("capacity");
capacityData = new String[capacity.getRows()][capacity.getColumns()];
iCount = capacity.getColumns();
for (int j = 0; j < capacity.getColumns(); j++)
for (int i = 0; i < capacity.getRows(); i++)
capacityData[i][j] = capacity.getCell(j, i).getContents();
Sheet demand = w.getSheet("demand");
demandData = new String[demand.getRows()][demand.getColumns()];
jCount = demand.getColumns();
for (int j = 0; j < demand.getColumns(); j++)
for (int i = 0; i < demand.getRows(); i++)
demandData[i][j] = demand.getCell(j, i).getContents();
Sheet distance = w.getSheet("distance");
distanceData = new String[distance.getRows()][distance.getColumns()];
for (int j = 0; j < distance.getColumns(); j++)
for (int i = 0; i < distance.getRows(); i++)
distanceData[i][j] = distance.getCell(j, i).getContents();
w.close();
} catch (IOException e) {
e.printStackTrace();
} catch (BiffException e) {
e.printStackTrace();
}
...
w
dict w

Now we can create the GAMSWorkspace as usual and afterwards create a GAMSDatabase and fill it with the workbook data as follows:

...
GAMSDatabase db = ws.addDatabase();
GAMSSet i = db.addSet("i", 1, "Plants");
GAMSSet j = db.addSet("j", 1, "Markets");
GAMSParameter capacityParam = db.addParameter("a", 1, "Capacity");
GAMSParameter demandParam = db.addParameter("b", 1, "Demand");
GAMSParameter distanceParam = db.addParameter("d", 2, "Distance");
for (int ic = 0; ic < iCount; ic++)
{
i.addRecord( capacityData[0][ic] );
capacityParam.addRecord( capacityData[0][ic] ).setValue( Double.valueOf(capacityData[1][ic]).doubleValue() );
}
for (int jc = 0; jc < jCount; jc++)
{
j.addRecord( demandData[0][jc] );
demandParam.addRecord( demandData[0][jc] ).setValue( Double.valueOf(demandData[1][jc]).doubleValue() );
String[] data = null;
for (int ic = 0; ic < iCount; ic++)
{
data = new String[] { distanceData[ic+1][0], distanceData[0][jc+1] };
distanceParam.addRecord( data ).setValue( Double.valueOf(distanceData[ic+1][jc+1]) );
}
}
data
GamsWorkspace data

Note that we can name sets and parameters just like in the database but we don't have to. Now we can run our GAMSJob as usual.

...
GAMSOptions opt = ws.addOptions();
GAMSJob t10 = ws.addJobFromString(model);
opt.defines("gdxincname", db.getName());
opt.setAllModelTypes("xpress");
t10.run(opt, db);
for (GAMSVariableRecord rec : t10.OutDB().getVariable("x"))
System.out.println("x(" + rec.getKeys()[0] + "," + rec.getKeys()[1] + "): level=" + rec.getLevel() + " marginal=" + rec.getMarginal());
...

See also Transport10.java.

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. From the main function we call the function CreateSaveRestart giving it the current working directory and the desired file name as arguments.

...
CreateSaveRestart( workingDirectory, "tbase" );
...

In function CreateSaveRestart create a workspace with the given working directory. Then we create a GAMSJob 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 GAMSOptions 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 GAMSJob and stored in the file given as argument to the function, in our case tbase. This becomes possible because the addCheckpoint method accepts identifiers as well as file names as argument.

static void CreateSaveRestart(File workingDirectory, String cpFileName)
{
GAMSWorkspaceInfo wsInfo = new GAMSWorkspaceInfo();
wsInfo.setWorkingDirectory(workingDirectory.getAbsolutePath());
GAMSWorkspace ws = new GAMSWorkspace(wsInfo);
GAMSJob j1 = ws.addJobFromString(baseModel);
GAMSOptions opt = ws.addOptions();
opt.setAction( GAMSOptions.EAction.CompileOnly );
GAMSCheckpoint cp = ws.addCheckpoint(cpFileName);
j1.run(opt, cp);
opt.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 Java data structures as we already did in Transport4 before we create the GAMSWorkspace and a GAMSDatabase.

...
GAMSWorkspaceInfo wsInfo = new GAMSWorkspaceInfo();
wsInfo.setWorkingDirectory(workingDirectory.getAbsolutePath());
GAMSWorkspace ws = new GAMSWorkspace(wsInfo);
GAMSDatabase db = ws.addDatabase();
...

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 t11 = ws.addJobFromString(model, cpBase);
opt.defines("gdxincname", db.getName());
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 GAMSDatabase correctly. The entire model definition is delivered by the checkpoint cpBase which is equal to the one we saved in tbase.

See also Transport11.java.