How to use GAMS with Octeract Engine

engine   guidance   starter guide  
Would you like to solve a problem using GAMS? Let us take you through the steps.

Which operating system are you using?



GAMS on Windows

Before reaching this guide, you’ll have:
  • installed the Engine.
  • installed your authentication token.

Step 1: Download GAMS

Octeract Engine has been tested with version 34.3 of GAMS on Windows. To download GAMS, you’ll need to go to the GAMS downloads page. Scroll to the bottom of the page and choose GAMS 34, released January 29, 2021 (or click here). Select MS Windows from the Platform options. A licence agreement pop-up window will appear. Click download. An executable file will be downloaded to your PC.

gams.com Windows


Step 2: Get a Demo Licence

Before you go any further, scroll down the GAMS downloads page to where you see “Request a Free Demo License”. In order to use GAMS, you’ll need to complete this form. Once you’ve submitted your request, you’ll get an email from GAMS with the licence. Follow the instructions provided in the emails. Once this step has been completed you may continue to Step 3.

GAMS licence Windows

Step 3: Install GAMS

To install GAMS, double click the file you downloaded in Step 1 and the installer will start running. Choose either GAMS Studio or GAMS IDE in the installer. In this tutorial, we’ll be using GAMS Studio. Follow the onscreen instructions and use the license from Step 2.

Step 4: Add the Engine as a Solver in GAMS

To do this, locate the file gmscmpNT.txt in the GAMS folder on your PC. By Default this would be C:\GAMS\34. Open it with text editor. Caution: There are two files with the same name. You should edit the Text Document, not the GAMS File. Copy the snippet below and paste it in the file. Save the file.
                
OCTERACT 111 0 0001020304 1 0 2 LP MIP RMIP NLP MCP MPEC RMPEC CNS DNLP RMINLP MINLP QCP MIQCP RMIQCP EMP
gmsgennt.cmd
gmsgennx.exe
libocteract.dll oct 1 0
                
            

Step 5: Write a Model in GAMS

GAMS has two different interfaces: GAMS Studio and GAMS IDE. You can write your model directly in one of the interfaces as a new GAMS source. Copy and paste the snippet below to create a model in your GAMS Studio session. Then save the model as my_example.gms
                
$offdigit

*Declare variables
VARIABLES x1,x2,x3,x4,x5;

VARIABLES objvar;

*Declare equations (such as constraints, etc)
EQUATIONS con1,objeqn;

*Define what the equations declared above are equal to
con1    ..  4*x5+11*x3+7*x4+12*x2+20*x1+0=L=40;

objeqn  ..  (-50*(x5)**(2))+(-50*(x3)**(2))+(-50*(x2)**(2))
+(-50*(x1)**(2))+(-50*(x4)**(2))+47.5*x5+45*x3+
47*x4+44*x2+42*x1+0 - objvar =E= 0;

* set non default upper bounds
x1.up     = 1;
x2.up     = 1;
x3.up     = 1;
x4.up     = 1;
x5.up     = 1;

* set non default lower bounds
x1.lo     = 0;
x2.lo     = 0;
x3.lo     = 0;
x4.lo     = 0;
x5.lo     = 0;

*declare the model name and state that all equations should be included as part of it
Model m / all /;

m.limrow=0; m.limcol=0;
*setting 8 cores for usage with Octeract Engine
m.threads=8;

$if NOT '%gams.u1%' == '' $include '%gams.u1%'

*set Octeract as the solver to solve the problem
option nlp=octeract;

*state the model will be solved using the defined NLP solver and minimising the objective function
Solve m using NLP minimizing objvar;
                
            
Note that the number of cores has been set to 8 via the line:
                
*setting 8 cores for usage with Octeract Engine
m.threads=8;
                
            

Step 6: Solve the Model

In GAMS Studio press the green arrow to run the model. In GAMS IDE, press the button with the file and red arrow to achieve the same result.

If successful, it will print out the optimal solution for your model.

And that's it - you're done!
You've just solved an optimisation problem using GAMS.





GAMS on Linux

Before reaching this guide, you’ll have:
  • installed the Engine.
  • installed your authentication token.

Step 1: Download GAMS

Octeract Engine has been tested with version 31.2 on Linux. To download GAMS, you’ll need to go to the GAMS downloads page. Scroll to the bottom of the page and choose GAMS 31, released June 19, 2020 (or click here). Select Linux from the Platform options. A licence agreement pop-up window will appear. Click download.

gams.com Linux

Step 2: Launch a Terminal

Open your terminal of choice. You can search for "terminal" in your start menu or try the shortcut ctrl+shift+t.

Step 3: Set Permissions

A file called linux_x64_64_sfx.exe will be downloaded to your PC. For the purposes of this guide we will assume that the file is downloaded into the Downloads folder. To ensure that this file has the right permissions, insert the command found in the snippet below in the terminal.
                
chmod 755 /home/$USER/Downloads/linux_x64_64_sfx.exe
                
            

Step 4: Get a Demo Licence

Before you go any further, scroll down the GAMS downloads page to where you see “Request a Free Demo License”. In order to use GAMS, you’ll need to complete this form. Once you’ve submitted your request, you’ll get an email from GAMS with the licence. Follow the instructions provided in the emails. Once this step has been completed you may continue to Step 5.

GAMS licence Linux


Step 5: Install GAMS

Choose a location for the GAMS directory. To create a directory that will contain the GAMS system, type the command mkdir /home/$USER/Documents/gams in your Shell session. This will create a new folder called gams in the Documents folder of the current user. Alternatively, you may choose any location that you see fit. Change to this directory by using the cd command and ensure the name of directory is returned correctly by typing pwd.
                
mkdir /home/$USER/Documents/gams

cd /home/$USER/Documents/gams

pwd
                
            
Now you can run the executable file by providing the whole path where it can be found.
                
/home/$USER/Downloads/linux_x64_64_sfx_.exe
                
            
Go to the newly created directory with cd like in the snippet below.
                
cd /home/$USER/Documents/gams/gams31.2_linux_x64_64_sfx
                
            
Add the licence file you received in the newly created GAMS folder.

To start the installation, go into the GAMS installation folder and run ./gamsinst. You’ll find an example in the snippet.
                
./gamsinst
                
            
Follow the instructions on the Shell session during the installation. Once the installation is completed, add the licence file you received in the newly created GAMS folder.

Step 6: Include the Engine as a Solver in GAMS

To do this, go to where the Engine was installed on your PC and locate the bin folder.
                
cd location/to/octeract/engine/bin
                
            
In this folder, you’ll find a file called octeract-install-for-gams. Run it.
                
./octeract-install-for-gams
                
            
You’ll then be prompted to provide the whole path where GAMS is installed. You’ll find an example in the snippet below.
                
/home/$USER/Documents/gams/gams31.2_linux_x64_64_sfx
                
            
Once you’ve done this, the process of adding the Engine to GAMS will begin. You’ll see a message in your terminal when the Octeract library is installed in the GAMS directory.

Step 7: Write a Model in GAMS

In this tutorial, we’ll write the model in text editor. Copy and paste the snippet below to create a model in your session. Then save the model as my_example.gms
                
$offdigit

*Declare variables
VARIABLES x1,x2,x3,x4,x5;

VARIABLES objvar;

*Declare equations (such as constraints, etc)
EQUATIONS con1,objeqn;

*Define what the equations declared above are equal to
con1    ..  4*x5+11*x3+7*x4+12*x2+20*x1+0=L=40;

objeqn  ..  (-50*(x5)**(2))+(-50*(x3)**(2))+(-50*(x2)**(2))
+(-50*(x1)**(2))+(-50*(x4)**(2))+47.5*x5+45*x3+
47*x4+44*x2+42*x1+0 - objvar =E= 0;

* set non default upper bounds
x1.up     = 1;
x2.up     = 1;
x3.up     = 1;
x4.up     = 1;
x5.up     = 1;

* set non default lower bounds
x1.lo     = 0;
x2.lo     = 0;
x3.lo     = 0;
x4.lo     = 0;
x5.lo     = 0;

*declare the model name and state that all equations should be included as part of it
Model m / all /;

m.limrow=0; m.limcol=0;
*setting 8 cores for usage with Octeract Engine
m.threads=8;

$if NOT '%gams.u1%' == '' $include '%gams.u1%'

*set Octeract as the solver to solve the problem
option nlp=octeract;

*state the model will be solved using the defined NLP solver and minimising the objective function
Solve m using NLP minimizing objvar;
                
            
Note that the number of cores has been set to 8 via the line:
                
*setting 8 cores for usage with Octeract Engine
m.threads=8;
                
            

Step 8: Solve the Model in GAMS

To solve the model, navigate to where GAMS was installed using the whole path. You can run the problem from there using the command in the snippet below. The whole path to where the example file was saved needs to be included in the command. You’ll be able to see the Engine running in the Shell session.
                
./gams /whole/path/to/where/my_example.gms
                
            
If successful, it will print out the optimal solution for your model.

And that's it - you're done!
You've just solved an optimisation problem using GAMS.

htg/htg1003