CONVERT

# 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 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 07/29/04 12:59:58
*
*  Equation counts
*     Total       E       G       L       N       X       C
*         6       1       3       2       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       0       0       0       0       0       0       0
*
*  Nonzero counts
*     Total   const      NL     DLL
*        19      19       0       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;

* set non default bounds

* set non default levels

* set non default marginals

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 07/29/04 12:59:59

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        0        0        0        0        0        0        0

Nonzero counts
Total    const       NL      DLL
19       19        0        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) [96] 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

Option Description Default
All Generates all supported file formats
AlphaECP Generates AlphaECP input file alpha.ecp
Ampl Generates Ampl input file ampl.mod
AmplNLC Generate Ampl NLC compatible file amplnlc.c
Analyze Generates three text files for rows columns and matrix analyze.txt
AnalyzeS Generates short form of Analyze analyzes.txt
Baron Generates Baron input file gams.bar
CplexLP Generate CPLEX LP format input file cplex.lp
CplexMPS Generate CPLEX MPS format input file cplex.mps
Dict Generate Convert to GAMS Dictionary dict.txt
DictMap Generate Convert to GAMS Dictionary Map dictmap.gdx
FileList Generate file list of file formats generated files.txt
FixedMPS Generate fixed format MPS file fixed.mps
Gams Generate GAMS scalar model. This is the default conversion format used. gams.gms
JuMP Generate JuMP scalar model gams.jl
Lgo Generate an LGO Fortran file lgomain.for
LindoMPI Generate Lindo MPI file lindo.mpi
Lingo Generate Lingo input file lingo.lng
LocalSolver Generate LocalSolver input file (only with ConvertD) localsolver.lsp
Memo Generate a memo file containing model statistics and files created. memo.txt
Minopt Generate Minopt input file minopt.dat
NLP2dual Generate the Wolfe dual of a smooth optimization model gamsdual.gms
NLP2MCP Generates GAMS scalar MCP model gamsmcp.gms
OSiL Generates Optimization Services instance Language (OSil) file osil.xml
Pyomo Generates Pyomo Concrete scalar model gams.py
SFS Generates Solver Foundation Services OML file sfs.oml
ViennaDag Generate Vienna Dag input file vienna.dag

## Other options

Option Description Default
ConeReform Reformulation of cone =C= constraints to NLP format
0: keep =C= format
1: convert conic constraints to NLP format
0
DualType Controls type of Wolfe dual to generate
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
GmsInsert Line to be inserted before the solve statement $if NOT 'gams.u1' == ''$include 'gams.u1'
None: Use no timestamp
default: Use the traditional default timestamp
svnId: Use the SVN keyword Id as a timestamp
svnLastChangedDate: Use the SVN keyword LastChangedDate as a timestamp
default
Hessian Writes GDX version of current point - Jacobian and Hessian hessian.gdx
Include Start reading from a new file
intervalEval Include interval evaluations in Jacobian and Hessian 0
intervalEvalDebug Turn on debug output for the interval evaluations 0
Jacobian Writes GDX version of current point - Jacobian jacobian.gdx
LSPSol Generate Output function in LocalSolver input file (only with ConvertD) lspsol.gms
Match Force a complete match for all MCP variable/equation pairs
ObjVar Name of objective variable GAMS index name, e.g. x1
PermuteEqus Random seed for permutation of equations (0: no permutation) (only with ConvertD and GAMS output) 0
PermuteVars Random seed for permutation of variables (0: no permutation) (only with ConvertD and GAMS output) 0
Reform Force reformulations 100
Terminate Force GAMS to terminate after conversion