### Table of Contents

# Introduction

CONVERT is a utility which transforms a GAMS model instance into a scalar model where all confidential information has been removed or into formats used by other modeling and solution systems. CONVERT is designed to achieve the following goals:

- Permit users to convert a confidential model into GAMS scalar format so that any idenifiable structure is removed. It can then be passed on to others for investigation without confidentiality being lost.
- A way of sharing GAMS test problems for use with other modeling systems or solvers.

CONVERT comes free of charge with any licensed GAMS system and can convert GAMS models into a number of formats, see Section Target languages and formats for a list.

# How to use CONVERT

CONVERT is run like any other GAMS solver. From the command line this is:

>> gams modelname modeltype=convert

where `modelname`

is the GAMS model name and `modeltype`

the solver indicator for a particular model type (e.g. LP, MIP, RMIP, QCP, MIQCP, RMIQCP, NLP, DNLP, CNS, MINLP, or MCP). CONVERT can also be specified via the option statement within the model itself before the solve statement:

option modeltype=convert;

# The GAMS Scalar Format

By default, CONVERT generates a scalar GAMS model (`gams.gms`

) from the input model. The scalar model exhibits the following characteristics:

- A model without sets or indexed parameters. It does not exhibit any of the advanced characteristics of modeling systems and is easily transformable.
- A model with a new set of individual variables, depicting each variable in the GAMS model as one of 3 types: positive, integer or binary. Each variable is numbered sequentially, i.e. all positive GAMS variables are mapped into n single variables
`x1, x2, ..., xn`

. - A model with individual equations depicting each variable in the GAMS model. All equations are also numbered sequentially, that is equations
`e1, e2, ..., em`

.

Equation and variable bounds, as well as variable starting values are preserved from the original GAMS formulation.

As an example, suppose the user wishes to translate the GAMS Model Library model trnsport into scalar format, One would run

gams trnsport.gms lp=convert

which would generate the following scalar model `gams.gms`

:

* LP written by GAMS Convert at 11/19/20 15:28:05 * * Equation counts * Total E G L N X C B * 6 1 3 2 0 0 0 0 * * Variable counts * x b i s1s s2s sc si * Total cont binary integer sos1 sos2 scont sint * 7 7 0 0 0 0 0 0 * FX 0 * * Nonzero counts * Total const NL * 19 19 0 * Solve m using LP minimizing x7; Variables x1,x2,x3,x4,x5,x6,x7; Positive Variables x1,x2,x3,x4,x5,x6; Equations e1,e2,e3,e4,e5,e6; e1.. -0.225 * x1 - 0.153 * x2 - 0.162 * x3 - 0.225 * x4 - 0.162 * x5 - 0.126 * x6 + x7 =E= 0; e2.. x1 + x2 + x3 =L= 350; e3.. x4 + x5 + x6 =L= 600; e4.. x1 + x4 =G= 325; e5.. x2 + x5 =G= 300; e6.. x3 + x6 =G= 275; Model m / all /; m.limrow = 0; m.limcol = 0; Solve m using LP minimizing x7;

Note that the resulting scalar model does not contain any of the descriptive information about the data or the context of the constraints.

Additionally, a dictionary file (`dict.txt`

) is created by default which specifies a mapping between the variable and equation names in the scalar model and their corresponding names in the original model.

For the above example, the dictionary file is

LP written by GAMS Convert at 11/19/20 15:28:05 Equation counts Total E G L N X C B 6 1 3 2 0 0 0 0 Variable counts x b i s1s s2s sc si Total cont binary integer sos1 sos2 scont sint 7 7 0 0 0 0 0 0 FX 0 Nonzero counts Total const NL 19 19 0 Equations 1 to 6 e1 cost e2 supply(seattle) e3 supply(san-diego) e4 demand(new-york) e5 demand(chicago) e6 demand(topeka) Variables 1 to 7 x1 x(seattle,new-york) x2 x(seattle,chicago) x3 x(seattle,topeka) x4 x(san-diego,new-york) x5 x(san-diego,chicago) x6 x(san-diego,topeka) x7 z

Conversion of a GAMS model to a scalar one may be handy for model debugging. However, in this case, it may be good to retain the original variable and equation names. The following simple sed command attempts to achieve this:

sed -n -e "s:^ *\([exbi][0-9][0-9]*\) \(.*\):s/\1/\2/g:gp" dict.txt | sed -n '1!G;h;$p' > mod.txt sed -f mod.txt gams.gms

For the above example, this outputs:

Variables x(seattle,new-york),x(seattle,chicago),x(seattle,topeka),x(san-diego,new-york),x(san-diego,chicago),x(san-diego,topeka),z; Positive Variables x(seattle,new-york),x(seattle,chicago),x(seattle,topeka),x(san-diego,new-york),x(san-diego,chicago),x(san-diego,topeka); Equations cost,supply(seattle),supply(san-diego),demand(new-york),demand(chicago),demand(topeka); cost.. -0.225 * x(seattle,new-york) - 0.153 * x(seattle,chicago) - 0.162 * x(seattle,topeka) - 0.225 * x(san-diego,new-york) - 0.162 * x(san-diego,chicago) - 0.126 * x(san-diego,topeka) + z =E= 0; supply(seattle).. x(seattle,new-york) + x(seattle,chicago) + x(seattle,topeka) =L= 350; supply(san-diego).. x(san-diego,new-york) + x(san-diego,chicago) + x(san-diego,topeka) =L= 600; demand(new-york).. x(seattle,new-york) + x(san-diego,new-york) =G= 325; demand(chicago).. x(seattle,chicago) + x(san-diego,chicago) =G= 300; demand(topeka).. x(seattle,topeka) + x(san-diego,topeka) =G= 275;

Of course, this is not a valid GAMS code and cannot be compiled, but it may be sufficient to view the model algebra as generated by the GAMS compiler.

By using

sed -n -e "y/(),-/____/" -e "s:^ *\([exbi][0-9][0-9]*\) \(.*\):s/\1/\2/g:gp" dict.txt | sed -n '1!G;h;$p' > mod.txt sed -f mod.txt gams.gms

one gets for this example

Variables x_seattle_new_york_,x_seattle_chicago_,x_seattle_topeka_,x_san_diego_new_york_,x_san_diego_chicago_,x_san_diego_topeka_,z; Positive Variables x_seattle_new_york_,x_seattle_chicago_,x_seattle_topeka_,x_san_diego_new_york_,x_san_diego_chicago_,x_san_diego_topeka_; Equations cost,supply_seattle_,supply_san_diego_,demand_new_york_,demand_chicago_,demand_topeka_; cost.. -0.225 * x_seattle_new_york_ - 0.153 * x_seattle_chicago_ - 0.162 * x_seattle_topeka_ - 0.225 * x_san_diego_new_york_ - 0.162 * x_san_diego_chicago_ - 0.126 * x_san_diego_topeka_ + z =E= 0; supply_seattle_.. x_seattle_new_york_ + x_seattle_chicago_ + x_seattle_topeka_ =L= 350; supply_san_diego_.. x_san_diego_new_york_ + x_san_diego_chicago_ + x_san_diego_topeka_ =L= 600; demand_new_york_.. x_seattle_new_york_ + x_san_diego_new_york_ =G= 325; demand_chicago_.. x_seattle_chicago_ + x_san_diego_chicago_ =G= 300; demand_topeka_.. x_seattle_topeka_ + x_san_diego_topeka_ =G= 275;

This can even be compiled by GAMS and gives the correct solution.

The proposed commands come with several limitations and may not produce in all cases the desired output. For example, wrong results would be printed if the original model contains variable or equation names that start with `{b,i,e,x}[digit]`

. Also semicontinuous or semiinteger variables or special ordered sets are not supported by the above. We leave it to the experienced user to extend the command appropriately.

# The OSiL Format

The Optimization Services Instance Language (OSiL) [69] specifies an XML-based format to represent optimization problem instances. GAMS/CONVERT can write MINLP model instances in OSiL format. Expression trees are written in OSnL format.

Next to the indexed operations for sum, product, minimum, and maximum, and the operations for subtraction and division, the following intrinsic functions are mapped to their OSnL counterparts: `sqr`

, `sqrt`

, `exp`

, `log`

, `log2`

, `log10`

, `abs`

, `cos`

, `sin`

, `tan`

, `arccos`

, `arcsin`

, `arctan`

, `sinh`

, `cosh`

, `tanh`

, `pi`

, `div`

, `gamma`

, `loggamma`

, `floor`

, `ceil`

, `round`

, `trunc`

, `sign`

`fact`

, `binomial`

. The functions `cvPower`

, `power`

, `rpower`

, `vcpower`

are all mapped to OSnL's `power`

operator, thus conditions on arguments are not preserved. Functions `arctan2`

, `centropy`

, `edist`

, `errorf`

, and `poly`

are represented by an expression according to their algebraic definition. The intrinsic functions `signpower`

, `entropy`

, `sigmoid`

, `gammareg`

, `beta`

, `logbeta`

, and `betareg`

are also written to OSiL files, but do not follow the OSnL standard (as it currently does not offer these functions). Thus, OSiL readers may reject XML files that use these functions. Finally, also the logical functions are written to OSiL by using their OSnL counterpart.

# User-Specified Options

CONVERT options are passed on through option files. If you specify `<modelname>.optfile = 1;`

before the SOLVE statement in your GAMS model, CONVERT will look for and read an option file with the name `convert.opt`

(see The Solver Options File for general use of solver option files). The syntax for the CONVERT option file is

optname value

with one option on each line. For example,

ampl

This option file would tell CONVERT to produce an AMPL input file. For file format options, the user can specify the filename for the file to be generated. For example, the option file entry

lingo myfile.lng

would generate a LINGO input file format called `myfile.lng`

. Using the option `lingo`

by itself, would produce the default output file for that option (`lingo.lng`

).

All available options are listed in the following tables.

## Target languages and formats

## Other options

Option | Description | Default |
---|---|---|

AmplNLBin | Enables binary .nl file | `0` |

AmplNlInitDual | Which initial equation marginal values to write to .nl file`0` : Write no values`1` : Write only nondefault values`2` : Write all values | `1` |

AmplNlInitPrimal | Which initial variable level values to write to .nl file`0` : Write no values`1` : Write only nondefault values`2` : Write all values | `2` |

DualType | Controls type of Wolfe dual to generate in NLP2dual`None` : No Wolfe dual generated`NLPScalarBounds` : NLP dual where variable bounds become scalars used in equations`NLPConstantBounds` : NLP dual where finite variable bounds become constants in equations`BiLevel` : Bilevel model with outer problem optimizing over the duals`MPEC` : MPEC obtained by explicitly including FOC of BiLevel inner problem | `None` |

GDXHessian | Enable hessian information for DumpGDX | `0` |

GDXNames | Enable variable and equation names for DumpGDX | `1` |

GDXQuadratic | Enable quadratic information for DumpGDX | `0` |

GDXUELs | Enable UELs for DumpGDX | `1` |

GmsInsert | Line to be inserted before the solve statement | `$if NOT 'gams.u1' == '' $include 'gams.u1'` |

HeaderTimeStamp | Control format of time stamp in header of output file`None` : Use no timestamp`default` : Use the traditional default timestamp | `default` |

IntervalEval | Include interval evaluations in DumpGDX | `0` |

ObjVar | Name of objective variable | `GAMS index name, e.g. x1` |

PermuteEqus | Random seed for permutation of equations (0: no permutation) | `0` |

PermuteVars | Random seed for permutation of variables (0: no permutation) | `0` |

QExtractAlg | quadratic extraction algorithm in GAMS interface`0` : Automatic`1` : ThreePass: Uses a three-pass forward / backward / forward AD technique to compute function / gradient / Hessian values and a hybrid scheme for storage.`2` : DoubleForward: Uses forward-mode AD to compute and store function, gradient, and Hessian values at each node or stack level as required. The gradients and Hessians are stored in linked lists.`3` : Concurrent: Uses ThreePass and DoubleForward in parallel. As soon as one finishes, the other one stops. | `0` |

Reform | Force reformulations | `100` |

SkipNRows | Skip constraints of type =N= | `0` |

Width | Max line width of output format Range: { `40` , ..., ∞} | `80` |