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:



Step 1: Download GAMS

Octeract Engine has been tested with the latest version of GAMS on Windows. To download GAMS, you’ll need to go to the GAMS downloads page. Select MS Windows from the Platform options and download the latest version of GAMS. It's important to note that older versions of GAMS are not compatible with the Engine so we recommend using any version from 32 onwards. 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 licence from Step 2.




Step 4: Configure the Engine as a Solver for GAMS

In your terminal, run the helper program
octeract-install-for-gams
. If the system is unable to find it, you can also locate it in the
bin
directory of your Octeract Engine installation. You'll be prompted to provide the absolute path to your GAMS installation. You can find an example in the snippet below.
                
C:/GAMS/35
                
            
Once the program completes, you will be provided with a configuration that must be placed in the
gamsconfig.yaml
file of your GAMS installation. The program will indicate the exact location of the file, whether it exists, or if you need to create it.



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

It's important to note that if your installation of Octeract Engine is located in a system directory or a directory with restricted access, e.g.
"C:/Program Files (x86)"
, you might need to run GAMS/GAMS Studio as Administrator.

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:



Step 1: Download GAMS

Octeract Engine has been tested with the latest version on Linux. To download GAMS, you’ll need to go to the GAMS downloads page. Select Linux from the Platform options and download the latest version of GAMS. It's important to note that older versions of GAMS are not compatible with the Engine so we recommend using any version from 32 onwards. 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/gams35_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: Configure the Engine as a Solver for GAMS

In your terminal, run the helper program
octeract-install-for-gams
. If the system is unable to find it, you can also locate it in the bin directory of your Octeract Engine installation. You'll be prompted to provide the absolute path to your GAMS installation.

You can find an example of what this would look like in the snippet below.
                

/home/$USER/gams/gams35_linux_x64_sfx
                
            
Once the program completes, you will be provided with a configuration that must be placed in the
gamsconfig.yaml
file of your GAMS installation. The program will indicate the exact location of the file, whether it exists, or if you need to create it.



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.


Was this helpful?
Please make sure you fill the comments section before sending.

Thank you for your comments.
Please contact us if you need any further support.
htg/htg1003