Using the Gams Manuals in Gams-Mode

You can call the help and solver files from within Gams.mode hitting C-c Enter. Be sure that the directory for the help files is properly set (choose Customize Gams mode for Emacs from the Gams menu) and search for the following entry in the buffer:
 
If you hit enter, the gams manual is shown in your PDF viewer, but you can also search for another file. For example: type path and hit tab for completion: Gams-mode will show you two completions for ‘path’: PATH-Solver and PATH-LP-Solver.
You should also set the path of the PDF file viewer (the variable gams-docs-view-programs):
 

Do not forget to save the settings, which you can do at the beginning of the settings buffer.
You can set them for the current or/and for all future settings:
 

Indenting with Gams-mode

The new version of Gams-mode has a nice feature that helps you in formatting your model.
You can automatically indent GAMS programs according to GAMS syntax.
 
M-C-\        =       Indent region.  Specify region and type M-C-\.
TAB          =       Indent the current line.
 
On the left you see the model before using the indent feature of Gams-mode. I selected the region and typed M-C-\ (`indent-region’).
You can see on the right side what happened. The set and parameter declarations are nicely formatted and the loop is clearly visible because all assignments in the loop are indented.
This example was taken from the file gams-sample.gms which resides in the gams-mode directory (and contains lots of useful tricks with Gams-mode).
 
 
 
Another nice feature is indenting a region (examples taken from the sample-text.gms file from Gams-mode.
Just mark the region you wan to indent and hit c-c c-y. Choose “t” if it is a table and “o” for other text.
Here an example (once again taken from the sample file):
 
or a table

Version 3.5 of Gams-mode released

There is a new version of Gams-mode for Emacs (Release 3.5). >When I install a new version on my Windows machine, I usually rename the old Gams-mode directory (on my computer this is ‘C:\Program Files\Emacs\site-lisp\gams’ in ‘C:\Program Files\Emacs\site-lisp\gamsOld’ and put the downloaded Gams-mode files in a directory with the original name (C:\Program Files\Emacs\site-lisp\gams). This way I can check if the new version runs without problems (all settings are preserved) and go back to the old version if there are any problems (just by renaming the directories again). The new version has a great feature for aligning blocks in Gams code.
Changes are:
  • new function gams-align-block' (C-cC-y). By this command, you can align table and other blocks in GAMS code. See Section "Align block" in gams-sample.gms for the details.
  • Changed default value of gams-statement-file’ from “~/.gams-statement” to “~/gams-statement.txt”.
  • Changed default value of `gams-template-file’ from “~/.gams-template” to “~/gams-template.txt”.
  • Minor changes to GAMS-TEMPLATE mode.

You can download it from Gams mode.
 

GAMS mode goodies: Looking up the identifier part of a parameter, variable or set

One of the nice features of Gams-Mode for Emacs is the possibility to quickly look up the identifier part of a variable, parameter or set. This is a nice feature in big models or when you haven’t worked with the model for some time. Just put the cursor somewhere on the parameter in the code you are looking at and hit F7. The screen will split and an additional side pane will appear.
Here is an example: in the lower pane you see the file readdata.gms, where I am working on, and the cursor is on the parameter “total” (red arrow in the figure). After hitting F7 the upper pane appears and shows the name of “total” in green (blue arrow) and one can read the identifier text (“total employment”).

 

On the left side a pane appears with the file structure. In this case the file readdata.gms has two files included: directorysettings.gms and set.gms. It also shows you where you are in the file.

This works fine if you are in the master file (readdata.gms) but not if you are in one of the included files. For this you need to add a comment line in the included files telling gams-mode where it can find the master file. This is done with the following line:
 
* gams-master-file: readdata.gms
 
By the actual version of GAMS mode for Emacs is 3.4 and you can download it from http://shirotakeda.org/home/gams/gams-mode.html.
 

Golden Rule 2: Comments and Descriptions

The next golden rule might also be obvious:Always add comments to your work and label your sets, variables, parameters and equations
Now this might be obvious if you have a lot of time, but usually the rule is forgotten if you are stressed and want to finish what you are working on. Not writing comments will probably cost you a lot of time, if you take your model a year from now and see your code: Wow, that looks interesting and very ingenious, but what the %*?!  did I do here? If you send your model to somebody else for help, this person usually don”t want to dechiffer your code. Comments make her life easier too and the chance you get an answer will increase.
In Gams you have many options to add comments:
  • Start a line with a “*” and write your comment, like
* This is a comment
You can change the character “*” in a different character with this command
$comment #
# This is a comment with the new character
  • Put your comment between $ontext and $offtext:
  • Put your comment after some code using  the end-of-line comment possibility after the two characters “!!”
C = IOT(”H”,”CONS”)   !! This is the consumption initialization
Note that this possibility of setting comments is turned off by default. You have to activate it by inserting $oneolcom (on end of line comment)  or $inlinecom (inline comment)
You can also change the default setting of “!!” to two other characters by using $eolcom
Gams-mode for Emacs has a nice feature that allows you to hide multi-line comments (just use Ctrl-c Ctrl-h to hide or show the comments). Hiding the comments gives you a good view on your code
Before hiding:
After hiding:
Writing comments is good practice.
Adding descriptions to your parameters, variables and equations is also good practice. If you use short variable or parameter names, this might save your time, but once again, will make life hard if you look at your model after some time or if your model is big. Was “y” domestic production level or was it income?
If you use descriptions your output is easier to read:
compared with:
Gams-mode for Emacs has another nice feature: if you put your cursor on a parameter or variable in your code and hit F7, another window opens and shows you the description.

Outline Mode in Gams-Mode for Emacs

Let’s get to know the great things you can do with Gams-mode. In the previous post I showed how Gams-mode nicely colors your code, the syntax-highlighting. In this post we will look at the great way Gams-mode shows the results of your model run. This is done in the Gams-Outline mode.
First run your model by hitting C-c C-s (C stands for Ctrl) or use the same command from the menu. Emacs will open a new window and you see how Gams solves your model. When Gams is finished you can hit F10 (or C-c C-v)  to show the listing file in a new buffer. We will however assume that the model solved without errors and we are interested in the results. Of course: you can scroll through your listing file using the search commandos from Emacs. Gams-mode however has a great way of showing all your results in a nice outline mode. This mode also allows you to jump from one result (for example the output of a variable to the definition of a set). Instead of jumping to the listing file, we therefore jump with F11 to the outline-view of Gams-mode.
You can also jump to the outline-mode from your gams file by hitting C-c Tab or hitting C-c C-ii (this command cycles through gams-, listing- and outline-mode).
As soon as you are in outline-mode you will see that the menu bar will have changed and the menu item GAMS-OUTLINE appears. Here you will find all the commands related to the outline-mode (with the short-cuts after the command name):
You will see a buffer with a grouped list of your variables, sets, parameters, etc. The next picture shows you the outline-mode for the library file abel.gms
First notice, that the information is grouped and colors are used to make a distinction between the different groups.
If you put your cursor on one of the items, for example on PAR w, your screen is split in two halfs: the upper part is still the list with all the items. The lower buffer shows the part of the listing file with the output for the chosen item. You can jump to the next item by pressing the key “n” (for next) and to the previous by pressing “p” (yes: for previous…).
Often you want to have a look at two items at the same time: just press the key “m” for the first item (you will see a “*” in front of this item). Now choose the next item by hitting the space bar: both items will be show in separate buffers.
Gams-outline allows to split the window horizontally or vertically (I prefer the vertical version). If you are in outline-mode and you have selected an item, you will
See in the status bar at the bottom of your Emacs help: on outline mode:
Hit the “x” key and you are in vertical mode. Hit it another time and you are back to horizontal mode.
If you don’t want all the items being listed, you hit the “t”-key and define if you want to have the summaries (SUM), variables (VAR) etc. being listed or not.

Syntax Coloring in Gams-Mode

I suppose you have installed emacs and gams-mode for emacs (if not see my preceding posts) and now are eager to start working on your model.
Let us start simple and get a model from the Gams-library. If you started emacs you are not in gams-mode (you can check this by looking at the menu bar: there is no gams-entry). If you load a gams model (with the extension “gms”), Emacs automatically turns on gams-mode and the gams entry appears in the menu bar (blue arrow). The first thing you probably notice is the syntax coloring. The coloring you will see might slightly differ from what you see in the picture. Gams-mode is highly adjustable and I changed some of the settings for syntax coloring. All gams keywords are  bold blue, the comments in a $ontext-$offtext block are green, etc.
This feature is of great help: if you are writing your code and mistype a keyword it doesn’t get colored and you know that mistyped something. In the picture you see that I mistyped “Table”. Compare it to the picture above and you see the difference.
If you don’t like the default syntax coloring (like I did), you can change the settings easily: go to the menu entry “Customize Gams Mode for Emacs“. Emacs now opens a new buffer with all the settings for Gams mode. Go to the end of the buffer to the group “Gams Facesand click on the buttonGo  to Group“. The  first setting you will see is the one for coloring comments. The green arrow shows you how comments will appear (green). Now click on the button “Show Face“. There are many options that can be adjusted.
I usually adjust only two of them: “Weight” (bold, normal, etc) and “Foreground”, the color. For the weight property you can choose from a drop down menu. For the color property you can either enter the Hexadecimal Color Code or just use the plain names for colors (green, red, etc.). Here is a site that shows you the hexadecimal color codes (http://www.december.com/html/spec/colorhslhex6.html#66).
If you are finished adjusting the settings, you finally have to save them. Scroll up to the beginning of the buffer and set the new settings for the current session and save them for future sessions.

Installing Gams-Mode for Emacs

After installing Emacs (see my previous post), the next thing to do is install gams-mode. If you got Emacs running, installing gams-mode is not so difficult.
First of all download gams-mode from Shiro Takeda’s website: You will find it here: gams-mode-download.
Update: you can now directly install gams-mode from the package repository:
  • Alt-x and type ‘list-packages’
  • search for gams-mode
  • click on it and install.

That’s all.

The files are zipped and should be unzipped to a directory Emacs will find. I show you my settings (as usual, you can do it in another way).
I have all my additional features in a directory that resides in the Emacs program directory:

The full name of the directory is C:\Programme\Emacs\site-lisp\gams. Notice that I don’t call the directory “..\gams-2.7.1” (the actual version). If there is a new version of gams-mode out, I just drop the files in this directory, and I do not have to adjust any settings I make in Emacs. You can see the other modes I use (for example python-mm, ess, planner, and auctex).

The next thing is to tell Emacs where it can find gams-mode. For this open your “.emacs” (dot-emacs) file that will be in your home directory (see my previous post). If there is no .emacs-file, you just create one.
Add the following text:
(setq load-path
(cons “c:/Programme/Emacs/site-lisp/gams/” ;; Set the installed directory!
load-path))
(require ‘gams)
The first 3 lines tell Emacs where to find gams-mode and the fourth line loads gams-mode.
Now you are ready to start using gams-mode. Open a gams-file in Emacs, and if all worked fine, you will see the gams-mode menu items (the red arrow in the next picture). In the picture, you can also see that I have some features installed that do not come with Emacs (blue arrow). I will talk about that in another post.
In the next post, I will tell you something about the great things that you can do with gams-mode and which will make your programming life more relaxed…

Installation of Emacs and Gams-Mode

There are quite a few ways to install Emacs on your Windows machine. On Linux it is rather easy: just use for example on Ubuntu your package manager. For the Mac you can have a look at Aquamacs, a version of Emacs that complies with the Human Interface Guidelines. More information on Aquamacs can be found at http://aquamacs.org/.
On Windows it is a different story. Emacs is coming from the Unix world and on Windows installing asks for a little bit more knowledge of Windows basics. You can’t for example install an additional feature (like Gams-mode for Emacs) by just double-clicking on a file. You have to move the downloaded files to a certain directory and add some lines of code to the file with the start-up settings of Emacs. This start-up file with the for Windows-users funny name of “.emacs” (dot emacs) resides in the home directory, which is on Unix a kind of “Documents and Settings”-directory. The good thing is that everything is well documented either in the readme-files that come along with the packages or some Windows user wrote a blog on it or answered a question in a forum.
Emacs comes in lots of flavors. You can download the standard version from one of the mirrors at http://www.gnu.org/prep/ftp.html and install it . This is the “hard way”: you have to add features like AucTex or ESS that are not part of the standard Emacs distribution yourself. Another way is to download a version that has already some additional features like LaTeX or ESS prepackaged. Finallly, there is a version that is geared specially to Windows (take a look at http://ourcomments.org/Emacs/EmacsW32.html) . Until now there is no version that already has Gams-mode in it.
Let us have a look at the three different ways of setting up your Emacs (only the first step is different)
  1. Choose your version:
    1. Download the windows installer packages from the Emacs homepage and just double click on it.
    2. Download the version geared to Windows
    3. Download a version with some features (in Emacs these are called modes) already prepackaged. A real good one is maintained by Vincent Goulet (http://vgoulet.act.ulaval.ca/en/ressources/emacs/windows). It already contains LaTeX, ESS (Emacs Speaks Statistics for R/S or Stata), windows-printing and some more features. You will find also a good instruction on how to set up Emacs.
  2. Double click on the downloaded file and install Emacs.
  3. Emacs wants to have a home directory and we have to tell it where it is.
    1. First decide where your home directory will be and create it (this can be anywhere on your computer. I have it in my Emacs directory: (c:\program files\emacs\home)
    2. Define a user variable called home with the full path name of your newly created home directory:
    3. Go to your system settings – click on the system icon”- click on “advanced settings”. Choose “environmental variables”
    4. Define a new user variable and call it “HOME”
That’s all! You probably will have a window icon on your desktop and you can start Emacs (if you haven’t an icon go to the “bin” directory where Emacs resides and double click on the file runemacs.exe).
There is a nice introduction to Emacs to be found at http://old.pubhealth.ku.dk/bsa/software/applications/index.html.
Have fun with Emacs!

Emacs and Gams (and R and LaTeX and …)

GAMS users probably spend most of their time editing their models. Just before project deadlines they may sit more than 8 hours a day in front of their computer hacking through their code. The choice of a good editor can therefore be crucial. After years of trying different editors I finally stuck (xxx) with the open-source editor Emacs.
For those of you who want to stop reading because they heard about the disadvantages of Emacs (“It has a steep learning curve”, “It is more a program for hackers” or “You have to learn all kind of key bindings by heart”), I can only say, that most of the disadvantages of Emacs are true. But: using Emacs in combination with Gams-Mode (an extension of Emacs developed by Shiro Takeda) can make your programming life so much easier and you will increase your efficiency so much, that reading on might save you hours of editing time.
For those of you who need more reasons for switching to Emacs, here are some of the advantages (in upcoming posts I will talk about all of these advantages in more detail):
  1. The editing facilities of the GAMS IDE are nothing compared to Emacs.
  2. The Gams Mode in Emacs is heaven on earth for doing Gams coding
  3. If you write your reports with LaTeX Emacs is probably one of the best editors around .
  4. For those of you who work with R (statistics) or Stata: Emacs Speaks Statistics (ESS) lets you do your statistics from within Emacs.
  5. If you write your statistics reports with LaTeX, you can use Sweave allowing you to embed your R-Code in your LaTeX document and let Emacs generate reports while running your analysis, generating graphs and tables for your report at the same time.
  6. Emacs has many extensions for working with other programming languages (Python, Perl, PHP, etc.).
  7. Emacs allows you to integrate your versioning system. I use Subversion and can from within Emacs use all commands like commit, update, etc.
  8. Making quick notes is easy in Emacs: you can generate a note and Emacs adds automatically a hyperlink to the file you are working on. This is a great feature if you want to keep working on the main issues in your model, but don’t want to forget to do some minor tasks. Instead of writing those tasks on a peace of paper of making it a task in Outlook, you can keep on working in Emacs and the next day it is easy to jump back to the place where the task refers to.
  9. Emacs runs on Windows, Linux and Mac.
For me the most important reason was the possibility to use one and only one editor for completely different tasks (R, Gams, LaTex, Note taking, Pytyhon and PHP). Instead of having to learn several different editors like WinEdt, the editor of GAMS IDE, Tinn-R, Beans, OneNote, I now have one editor.