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) [68] 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 file0 : Write no values1 : Write only nondefault values2 : Write all values | 1 |
AmplNlInitPrimal | Which initial variable level values to write to .nl file0 : Write no values1 : Write only nondefault values2 : Write all values | 2 |
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 filedefault : Use the traditional default timestampnone : Use no 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 interface0 : Automatic1 : 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 |