|
|
|
* This research supported by the GAMS Applied General Equilibrium Research Fund. The software described here operates only with GAMS 2.25.089 or later on the PC. The author remains responsible for any bugs which exist in this software. This software is not officially supported by GAMS Corporation.
The six GAMS routines listed below can be used to write out parameters or level values in GAMS-readable form to an external file. This document specifies calling syntax and provides some examples of their use. Contents:
Download inclib.pck into your GAMS system directory, and run GAMSINST.
Download the appropriate INFO-ZIP executables, unzip these files into a separate directory, and then copy zip.exe and unzip.exe into your GAMS system directory (or another directory on the path). See the Info-Zip home page for an overview of this software. They produce executables for a large number of platforms, including:
N.B. The Unzip distribution file is a self-extracting archive. Do not rename this file! Just execute it and it will expand to produce a file named unzip.exe.
The file inclib.pck contains all of the libinclude programs which have been developed at the University of Colorado during the past couple of years. These include files for report writing (GAMS2TBL), spreadsheet interface (SSLINK), plotting (GNUPLOT), and interactive modeling (GAMSCGI). Henceforth I will be keeping libinclude source files for all of these applications in a single archive in order to simplify maintenance. You will need to download additional batch and executable files in order to install these other packages.
FILE unit /name/; PUT unit; [$SETGLOBAL prefix "string"] [$SETGLOBAL timestamp "yes or no"] [$SETGLOBAL zeros "yes or no"] $LIBINCLUDE gams2txt [ ident1[.suffix] [ident2[.suffix] ...]]Some additional information:
(i) GAMS2TXT works for parameters, variables, equations and sets.
(ii) The first invocation must be outside of a loop or if block.
(iii) Use a blank invocation (without arguments) to initialize.
(iv) Explanatory text are written as the "data" for sets.
(v) Values of EPS are written as zero on the output file.
(vi) Global environment variable "prefix" can specify a prefix to the output label (see Examples 5 and 9).
(vii) Global environment variable "timestamp" controls whether header comments are written to the output file. (Default is "yes".)
(vii) Global environment variable "zeros" controls whether zeros are written to the output file. (Default is "no". See Example 6.)
FILE unit /name/; PUT unit; [$SETGLOBAL prefix "string"] [$SETGLOBAL timestamp "yes or no"] [$SETGLOBAL zeros "yes or no"] $LIBINCLUDE gams2prm [ ident[.suffix] [name ["description"]] ]Some additional information:
(i) GAMS2PRM works for parameters, variables, equations and sets.
(ii) Outputs only one item at a time.
(iii) The first invocation must be outside of a loop or if block.
(iv) Use a blank invocation (without arguments) to initialize.
(v) A name is required if the output item has a suffix.
(vi) Explanatory text are written as the "data" for SETs.
(vii) Values of EPS are written as zero on the output file.
(viii) Global environment variable "prefix" can specify a prefix to the output label (see Examples 5 and 9).
(ix) Global environment variable "timestamp" controls whether header comments are written to the output file. (Default is "yes".)
(x) Global environment variable "zeros" controls whether zeros are written to the output file. (Default is "no". See Example 6.)
$libinclude gams2zip [-m] archive [ ident1[.suffix1] [-m] [-n name1] [ ident2[.suffix2] [-m] [-n name2] ...]]Some additional information:
(i) Requires INFO-ZIP shareware to be in the GAMS directory or on your path.
(ii) GAMS2ZIP works for parameters, variables (level values or marginals), and equations (level values or marginals).
(iii) Output one or more items into a compressed archive.
(iv) The first invocation must be outside of a loop or if block.
(iv) Use a blank invocation (without arguments) to initialize.
(v) The item is written to the archive with a different name by including ("-n name") following the item.
(vi) When an archive already exists, the default operation is "replacement". Either one transfer or a single array may be entered with a "merge" by including an "-m" flag at the start of the command (for the entire set), or following an item (for a single array).
N.B. Specifying the -m flag for GAMS2ZIP is not equivalent to applying a -m flag for ZIP.EXE. In the GAMS2ZIP call, the -m flag indicates that the array is to be added (merged) to an existing zip file.
$libinclude zip2gams archive [ ident1 [-n name] [ident2 ...]]Some additional information:
(i) Requires INFO-ZIP shareware to be in the GAMS system directory.
(ii) Retrieves parameters, level values or marginals at compile time from an existing ZIP archive, as written by GAMS2ZIP.
(iii) Can retrieve multiple items at a time.
(iv) May only be invoked in a context which permits a parameter declaration. This means that every invocation must be outside of a loop or if block.
(iv) An item may be assigned values from an archive array which has a different name through use of the "-n" flag. When this is specified, the subsequent word defines the name of the archive array to be assigned to the item.
(1) For the output routines gams2txt and gams2prm, data is written to the currently active file. The user program must declare a file and make it current with a PUT statement prior to invoking either routine.
(2) The output may be a parameter, a variable or an equation. A variable or equation may only be output with a suffix, such as id.L (indicating level value), id.M (mararginal), id.LO (lower bound), or id.UP (upper bound).
(3) These routines may be used within a loop or if block only if they are first initialized with blank invocations ("$LIBINCLUDE gams2prm" or "$LIBINCLUDE gams2txt") in a context where set and parameter declarations are permitted (See Examples 3 and 5).
(4) The following names are used within these routines and may not be used in the calling program:
u__1,u__2,u__3,u__4,u__5,u__6,u__7,u__8,u__9,u__10,
gms2txt1,gms2txt2,gms2txt3,gms2txt4,gms2txt5,
gms2txt6,gms2txt7,gms2txt8,gms2txt9,gms2txt10
(5) To improve portability of GAMS code between PC and Unix platforms, use a lower case reference to the batch file, gams2txt, gams2prm, gams2zip or zip2gams.
(6) The routine gams2prm includes a generic parameter statement with no reference to the domain or dimension of the item. A program reading this data must provide an explicit domain declaration if the parameter is to be domain-checked.
(7) Some care is needed when saving empty parameters. If you save an empty (all zeroes) parameter to a file using gams2prm and subsequently read the data file into a different GAMS program, you must include the $ONEMPTY compiler directive before reading the data file. Otherwise, GAMS generates a compile-time error when it encounters an empty parameter data range. See Example 4.
(8) The global environment variable 'prefix' can be used to add some characters to the output label. (See Examples 5 and 9.)
(9) gams2zip and zip2gams are a pair of routines designed for storing a bunch of parameters or level values on an external file for subsequent retrieval.
set i /i1*i3/; parameter x(i); x(i) = uniform(0,1); file kout /x.gms/; put kout; $libinclude gams2prm x
Example1 writes the following lines to x.gms:
parameter x / *=>gams2prm x * Called from D:\TFR\GAMS\GAMS2TXT\EXAMPLE1.GMS, line 70 * 01/08/98 16:15:19 I1 1.71747132000000E-01 I2 8.43266708000000E-01 I3 5.50375356000000E-01 /;
This data may be read into a subsequent GAMS program with the statements:
set i /i1*i3/; parameter x(i); $include x.gms
or simply:
$include x
The input code which declares set i and gives x an explicit domain before reading x.gms is preferred because it induces domain-checking on x.
This example is identical to the previous, except that the name of the output parameter is modified when it is written to disk.
set i /i1*i3/; parameter x(i); x(i) = uniform(0,1); file kout /y.gms/; put kout; $libinclude gams2prm x y
Example2 writes the following lines to y.gms:
parameter y / *=>gams2prm x y * Called from D:\TFR\GAMS\GAMS2TXT\EXAMPLE2.GMS, line 70 * 01/08/98 16:16:26 I1 1.71747132000000E-01 I2 8.43266708000000E-01 I3 5.50375356000000E-01 /;
Note that this example uses gams2prm within an if block, so an initialization call is required.
set i /i1*i3/;
parameter x(i);
x(i) = uniform(0,1);
file kout /x.gms/;
put kout;
$libinclude gams2prm
if (x("i1") gt 10,
$libinclude gams2prm x
);
set i /i1*i2/; parameter x(i); $onempty $include x
The following batch file and GAMS program illustrate how to solve a sequence of scenarios. We use the DOS echo statement to write the file scenario.gms. This file is then read by example5.gms which then appends output to results.gms using the gams2txt.
This technique permits the solution of a sequence of scenarios without having the failure of one scenario interrupt the remaining cases. At the end, all the results are stored in a single GAMS-readable file, results.gms.
EXAMPLE5.BAT:
: A DOS batch file for solving a sequence of cases.
if exist results.gms del results.gms
echo run("sc1") = yes; >scenario.gms
call gams example5
echo run("sc2") = yes; >scenario.gms
call gams example5
echo run("sc3") = yes; >scenario.gms
call gams example5
EXAMPLE5.GMS:
* This program for solves a specified scenarios and appends
* the results to a GAMS-readable results file:
set i /i1*i3/,
sc set of all scenarios to solve / sc1*sc3/,
run(sc) identifies the current scenario;
parameter x(i) data parameter (solution values for current case);
* Read identifier for the current scenario:
$include scenario
* Open the file in append mode and make it current:
file kout /results.gms/; kout.ap=1; put kout;
* Initialize prior to calling gams2txt from within a loop:
$libinclude gams2txt
* Use the scenario label as the prefix:
$setglobal prefix "sc.tl'.'"
loop(sc$run(sc),
* Get the solution (this could be a solve statement):
x(i) = uniform(0,1);
* Write to the output file:
$libinclude gams2txt x
);
Example 5 writes the following lines to results.gms:
*=>gams2txt x * Called from D:\TFR\GAMS\GAMS2TXT\EXAMPLE5.GMS, line 287 * 01/08/98 16:00:19 SC1.I1 1.71747132000000E-01 SC1.I2 8.43266708000000E-01 SC1.I3 5.50375356000000E-01 *=>gams2txt x * Called from D:\TFR\GAMS\GAMS2TXT\EXAMPLE5.GMS, line 287 * 01/08/98 16:00:20 SC2.I1 1.71747132000000E-01 SC2.I2 8.43266708000000E-01 SC2.I3 5.50375356000000E-01 *=>gams2txt x * Called from D:\TFR\GAMS\GAMS2TXT\EXAMPLE5.GMS, line 287 * 01/08/98 16:00:20 SC3.I1 1.71747132000000E-01 SC3.I2 8.43266708000000E-01 SC3.I3 5.50375356000000E-01
Because the data was written with gams2txt instead of gams2prm, the output file does not include a PARAMETER statement. It may still be read into a GAMS program as follows:
set i /i1*i3/; set sc /sc1*sc2/; parameter x(sc,i); parameter x / $include x /;
A global environment variable "zeros" specifies whether gams2txt should write explicit zeros, as illustrated in this example:
set i /i1,i2/, j /j1,j2/, k /k1,k2,k3/;
table x(i,j,k)
k1 k2 k3
i1.j1 1
i2.j2 2;
file xd /xd.txt /; put xd;
$libinclude gams2txt x
is written (under defaults):
I1.J1.K1 1.00000000000000E+00
I2.J2.K2 2.00000000000000E+00
When "$setglobal zeros yes", x is written:
I1.J1.K1 1.00000000000000E+00 I1.J1.K2 0.00000000000000E+00 I2.J2.K1 0.00000000000000E+00 I2.J2.K2 2.00000000000000E+00Note in this example that rows which are entirely zero (I1.J2, I2.J1), and columns which are entirely zero (K3) are not written.
$title ziptest1.gms -- Illustrates syntax for libinclude GAMS2ZIP * Generate some parameters with data to export: set i/1*100/; parameter a(i), b; a(i) = uniform(0,1); b(i) = uniform(0,1); * Also save level values for a variable: variable v(i); v.l(i) = uniform(0,1); * Create a zip archive named test.zip. * Parameter A saved with no change in name * (default). * Parameter B saved as a parameter named "BB" * through specification of an optional id. * Variable level values V.L: $libinclude gams2zip test a b -n bb v.l display a, b, v.l;
Here is a second program which reads the archive produced in the previous example. Note that domain checking is invoked for parameter B because it is declared with an explicit domain, but parameters A and V0 are not declared and therefore not checked.
$title ziptest2.gms -- Illustrates syntax for libinclude ZIP2GAMS set i/1*100/; parameter b(i); * Retrieve three items from the archive. Retrieve archive * array v.l into a parameter named v0: $libinclude zip2gams test a b v0 -n v.l display a, b, v0;Finally, here is a program which illustrates how ZIP2GAMS reports an error in the event that an item is retrieved which does not exist in the archive:
$title ziptest3.gms -- Illustrates error reporting * Attempt to retrieve a parameter which is not in the archive: $libinclude zip2gams test aaWhen an error code is generated by UNZIP, ZIP2GAMS first produces an error message on the log file and then requests UNZIP prints an archive list:
Error retrieving item aa from ZIP archive test.zip Archive: test.zip Length Date Time Name ------ ---- ---- ---- 2731 01-09-98 09:46 a 2733 01-09-98 09:46 bb 2736 01-09-98 09:46 v.l ------ ------- 8200 3
The following GAMS program illustrates how GAMS2ZIP can be used to save level values and marginals from one model to use as a starting point in another. (For further information on how GAMS and associated solvers communicate basis information, see the appendix listed below.)
$title dattest1.gms -- Illustrates the use of GAMS2ZIP for saving a basis * Use GAMSLIB call to retrieve the transport model into the * local directory: $call "gamslib trnsport" * Run the model (it solves a linear program): $include trnsport.gms * Write out the level values and marginals for this model (this * defines the basis for a model in GAMS) to basis.zip: $libinclude gams2zip basis x.l z.l x.m cost.m supply.m demand.m
Here is how the saved basis information can be read into a subsequent program:
$title dattest2.gms -- Illustrates the use of ZIP2GAMS for retrieving a basis. * Use GAMSLIB call to retrieve the transport model into the * local directory: $call "gamslib trnsport" * Run the model (it solves a linear program): $include trnsport.gms * Extract the level values and marginals from the basis: $libinclude zip2gams basis x.l z.l x.m cost.m supply.m demand.m * When solving the model, GAMS uses the level values and * marginals which have been read to provide a starting point: SOLVE TRANSPORT USING LP MINIMIZING Z ;
The following batch file and GAMS program are virtually identical to Example 5, aside from the fact that in this example several arrays are saved in the results file for a sequence of scenarios. We use the DOS echo statement to write the file scenario.gms. This file is then read by example9.gms which then appends output to results.gms using the gams2txt.
This technique permits the solution of a sequence of scenarios without having the failure of one scenario interrupt the remaining cases. At the end, all the results are stored in a single GAMS-readable file, results.gms.
EXAMPLE9.BAT:
: A DOS batch file for solving a sequence of cases.
if exist results.zip del results.zip
echo run("sc1") = yes; >scenario.gms
call gams example9
echo run("sc2") = yes; >scenario.gms
call gams example9
echo run("sc3") = yes; >scenario.gms
call gams example9
call gams report9
EXAMPLE9.GMS:
* This program for solves a specified scenarios and appends
* the results to a GAMS-readable results file:
set i /i1*i3/,
sc set of all scenarios to solve / sc1*sc3/,
run(sc) identifies the current scenario;
* Let's pretend that these are variables computed by the model:
variable x(i) data parameter (one set of solution values for current case)
y(i) data parameter (a second set solution values)
z(i) data parameter (a third set solution values );
* Read identifier for the current scenario:
$include scenario
* First invocation of GAMS2ZIP must be outside a loop:
$libinclude gams2zip
* Use the scenario label as the prefix:
$setglobal prefix "sc.tl'.'"
loop(sc$run(sc),
* Get the solution (this could be a solve statement):
x.l(i) = uniform(0,1);
y.l(i) = uniform(0,1);
z.l(i) = uniform(0,1);
* Save results in the archive (merge all of them!)
$libinclude -m gams2zip results x.l y.l z.l
);
REPORT9.GMS:
* This program generates a report from the previous run:
set i /i1*i3/,
sc set of all scenarios to solve / sc1*sc3/;
* Retrieve the results -- note that in this context we
* treat them as two-dimensional parameters:
parameter x(sc,i) data parameter (one set of solution values for current case)
y(sc,i) data parameter (a second set solution values)
z(sc,i) data parameter (a third set solution values );
$libinclude zip2gams results x -n x.l y -n y.l z -n z.l
display x, y, z;
The output produced by REPORT9.GMS assembles results from all three sets of scenarios:
REPORT9.LST (partial listing):
---- 239 PARAMETER X data parameter (one set of solution values for current case)
I1 I2 I3
SC1 0.172 0.843 0.550
SC2 0.172 0.843 0.550
SC3 0.172 0.843 0.550
---- 239 PARAMETER Y data parameter (a second set solution values)
I1 I2 I3
SC1 0.301 0.292 0.224
SC2 0.301 0.292 0.224
SC3 0.301 0.292 0.224
---- 239 PARAMETER Z data parameter (a third set solution values )
I1 I2 I3
SC1 0.350 0.856 0.067
SC2 0.350 0.856 0.067
SC3 0.350 0.856 0.067