# How to use GAMS with Octeract Engine

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

## GAMS on Windows

Before reaching this guide, you’ll have:

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.

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

### 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 programocteract-install-for-gams. If the system is unable to find it, you can also locate it in thebindirectory 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 thegamsconfig.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". ### 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 calledlinux_x64_64_sfx.exewill 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.

### Step 5: Install GAMS

Choose a location for the GAMS directory. To create a directory that will contain the GAMS system, type the commandmkdir /home/$USER/Documents/gamsin 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 thecdcommand and ensure the name of directory is returned correctly by typingpwd.   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 programocteract-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 thegamsconfig.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



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