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

Option Description Default
All Generates all supported file formats
Ampl Generates Ampl input file ampl.mod
AmplNL Generates Ampl .nl file ampl.nl
CplexLP Generates CPLEX LP format input file cplex.lp
CplexMPS Generates CPLEX MPS format input file cplex.mps
Dict Generates Convert to GAMS Dictionary dict.txt
DictMap Generates Convert to GAMS Dictionary Map dictmap.gdx
DumpGDX Generates GDX with model data incl. Jacobian and Hessian evaluated at current point dump.gdx
FileList Generates file list of file formats generated files.txt
FixedMPS Generates fixed format MPS file fixed.mps
Gams Generates GAMS scalar model. This is the default conversion format used. gams.gms
JuMP Generates JuMP scalar model jump.jl
Lingo Generates Lingo input file lingo.lng
NLP2dual Generates 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 pyomo.py

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