Table of Contents
A Tool to generate a documentation from GAMS source code in LaTeX format.
Special thanks to Ingmar Schlecht for supporting us and sharing his gamsToLatex implementation.
Introduction
MODEL2TEX
is a tool to generate a documentation from GAMS source code in LaTeX format. This LaTeX output can then be further processed in order to generate pretty output files like PDF. The tool can be found in the root directory of GAMS. The tool allows to document one specific model symbol inside of a GAMS program. The resulting documentation contains two parts. The first part shows a list of symbols that are used by the model. The second part shows the actual algebra of the used equations and information about the types of used variables. An optional third part can contain additional notes.
Usage
MODEL2TEX
is a command line tool. The general command line usage is as follows:
model2tex baseName [-h] [-m MODEL] [-f] [-o OUTPUT]
Since it operates on output files generated by GAMS, the first step is to generate the required files using the docfile option. In order to to that, execute the following command line:
gams myModel.gms docfile=myModel
The second step is to call MODEL2TEX
: model2tex
is distributed as Python source code (model2tex.py
) and is executed via model2tex.cmd
on Windows and model2tex.sh
on all other platforms.
Windows:
model2tex myModel [-m MODEL] [-f] [-o OUTPUT]
Linux/macOS:
model2tex.sh myModel [-m MODEL] [-f] [-o OUTPUT]
The output file myModel.tex
can be further processed for example by calling pdflatex
in order to generate a PDF file.
pdflatex myModel.tex
Options
The following parameters can be used when calling MODEL2TEX
:
Parameter | Description |
---|---|
-m model | Since MODEL2TEX generates documentation for one model symbol, the model name needs to be specified explicitly, if the GAMS file contains more than one model symbol |
-f | MODEL2TEX does not allow the occurrence of suffixes in equations. This option can be used in order to force the creation of the tex file by skipping the checks for suffixes. |
-o output | Use this name for the generated TeX file instead of the base name. |
Using a JSON style file
MODEL2TEX
automatically creates a JSON file that can be modified in order to customize the output. If you want to get the default settings back, just delete the generated JSON file and let MODEL2TEX
create it again. The following list shows the available options in the JSON file:
Parameter | Default | Description |
---|---|---|
fontSize | 11 | The size of the used font |
hrules | true | Horizontal rules are added between equations. |
colors | black | Specifies the used colors in equations for variables, parameters, and sets. |
landscape | false | Allows to change the page format to landscape. |
noPowerFunc | false | Beside a power operator, GAMS offers several power functions. Setting this option to true will replace all power functions with the power operator. |
reduceFrac | false | Try to resolve unbalanced fractions. This means that fractions with an unbalanced length of denominator and numerator will be changed in order to shrink the fraction. |
reduceFracRatio | 5.0 | This number has only effect when reduceFrac is set to true. It specifies the ratio between denominator and numerator that is used as a threshold for reduceFrac . |
latexDescription | false | Explanatory text for symbols is expected to be arbitrary text. In order to display the text correctly in LaTeX, some automatic adjustments are applied. If all explanatory text already contains valid LaTeX strings, this option can be enabled. |
nameMap | the original names | This map allows to specify alternative names for symbols. |
extraSymbols | empty list | On default, only the required symbols in a GAMS model symbol are contained in the generated LaTeX file. This list can be used in order to specify further symbols that should be included as well. |
notes | empty list | Allows to specify additional notes for the documentation. Each list element will result in a new line. |
Example
This example creates a PDF file for the pump model from the GAMS Model Library.
- Retrieve model pump from GAMS Model Library
gamslib pump
- Generate required doc files
gams pump.gms docfile=pump
- Generate the LaTex files
model2tex pump -m=pump
- Generate PDF documentation
pdflatex pump.tex
The following pictures show snippets from the resulting PDF file: - Customizing the JSON style file In order to change the appearance of the PDF file, the generated JSON file
pump.json
can be modified. Changing the options inpump.json
according to the picture and executing the commands from step 3 and 4 again will result in a customized PDF output.