Matlab.GAMS.GAMSDatabase Class Reference

Communicates data between the Matlab world and the GAMS world. More...

Public Member Functions

 [instance initializer]
 (read only) (read only) list of GAMSSymbol instances contained in GAMSDatabase More...
 
GAMSEquation addEquation (varargin)
 Add equation symbol to database. More...
 
GAMSParameter addParameter (varargin)
 Add parameter symbol to database. More...
 
GAMSSet addSet (varargin)
 Add set symbol to database. More...
 
GAMSVariable addVariable (varargin)
 Add variable symbol to database. More...
 
logical checkDomains ()
 Check domains of all GAMSSymbol instances in the database. More...
 
void clear ()
 Clear all symbol records in the database. More...
 
void dispose ()
 Release external resources hold by non-java library. More...
 
void export (varargin)
 Write database into a GDX file. More...
 
 [instance initializer]
 Check all GAMSSymbol instances in the database if all their records are within the specified domain of the symbol. More...
 
GAMSEquation getEquation (string identifier)
 Get GAMSEquation by name. More...
 
GAMSParameter getParameter (string identifier)
 Get GAMSParameter by name. More...
 
GAMSSet getSet (string identifier)
 Get GAMSSet by name. More...
 
GAMSSymbol getSymbol (string identifier)
 Get GAMSSymbol by name. More...
 
GAMSVariable getVariable (string identifier)
 Get GAMSVariable by name. More...
 
logical isDisposed ()
 Inquire if this database has already been disposed. More...
 
GAMSIterator iterator ()
 Returns an iterator over a set of GAMSSymbol. More...
 

Public Attributes

string name
 (read only) GAMSDatabase name
 
integer numberOfSymbols
 (read only) Number of symbols in GAMSDatabase More...
 
logical suppressAutoDomainChecking
 Controls whether domain checking will be called when export GAMSDatabase.
 

Detailed Description

Communicates data between the Matlab world and the GAMS world.

A GAMSDatabase consists of a collection of symbols that allows to iterate conveniently through the symbols in a GAMSDatabase. The symbol types available for a GAMSDatabase correspond to the symbols types known from the GAMS language (Set, Parameter, Variable, and Equation) are represented in Matlab by a derived class (correspondingly GAMSSet, GAMSParameter, GAMSVariable, and GAMSEquation) of GAMSSymbol class. Besides the type, a GAMSSymbol has a name (this has to match the name inside the GAMS model), a dimension (currently up to 20, see also GAMSGlobals.MAXDIM) and explanatory text.

Variables and equations also have a subtype: e.g. Binary, Positive, etc. for variables (see VarType) and e.g. E, G etc. for equations (see EquType).

A GAMSDatabase can be created empty, or initialized from existing GDX files or from another GAMSDatabase (copy). Symbols can be added at any time (e.g. with GAMSDatabase.addParameter method), but once a symbol is part of a GAMSDatabase, it cannot be removed. Only its associated data (GAMSSymbolRecord) can be purged (see GAMSSymbol.clear method) or individually removed (with GAMSSymbol.deleteRecord method). A symbol with name '*' is reserved as a special symbol of type GAMSSet representing universe set. Individual data elements are accessed record by record. A record is identified by the keys (a vector of strings). The record data varies by symbol type. For example, a parameter record has a Value property, a variable has the properties Level, Lower, Upper, Marginal, and Scale. Adding a record with keys that already exist results in an error. Similar, the unsuccessful search for a record also results in an error.

GAMSSymbol implements the Java java.lang.Iterable interface to conveniently iterate through the records of a symbol. However, it is also possible to query all records at once using the Records property (using the Iterator in the background). There are also sliced access methods to symbol records that allow to iterate through all records with a fixed index at some positions. GAMSDatabase instances can be exported as GDX files for permanent storage. They also manage external resources and need to be properly disposed before the Java garbage collector reclaims the instance (see GAMSDatabase.dispose()).

GAMSJob.outDB and GAMSModelInstance.syncDB provide instances of GAMSDatabase to communicate results from a GAMS run or a solve. These databases should only be used in the context of the base object (GAMSJob or GAMSModelInstance). If a copy of such a database is required the GAMSDatabase constructor that initializes a GAMSDatabase from another database should be used. For instance:

* db = job.outDB;
* newdb = workspace.addDatabase(db);
* 

GAMSDatabase instances often provide the input data for a GAMSJob. Such instances are listed in GAMSJob.run. Inside the GAMS model source the GAMSDatabase is accessible through a GDX file. The GAMS model source requires a particular file name to connect to the proper GDX file (e.g. $GDXIN filename). A GAMSDatabase can be created with a given name which can be then used inside the model, for instance

* db = workspace.addDatabase('SupplyData');
* 

and then inside the GAMS model source:

* $GDXIN SupplyData
* 

or an automatically generated name can be used. This name can be passed down to the GAMS model by using the Defines list of a GAMSOptions instance:

* db = workspace.addDatabase();
* opt = workspace.addOptions();
* opt.defines('SupplyDataFileName', db.getName());
* ...
* job.run(opt, db);
* 

Inside the GAMS model source the name is accessed as follows:

* $GDXIN %SupplyDataFileName%
* 

One has to act with some caution when it comes to ordered sets which e.g. allow lag and lead. By not enforcing the 'domain checking' for the GAMSDatabase class we have aggravated the potential problems for ordered sets. For GAMS, the labels of set elements are just strings, so the order of a set is determined by the appearance of its elements. For example, if one has 'set k / 2,3,4,1,5 /', the order of k is exactly given by this sequence. So the lag (k-1) of k=4 is 3 and the lead (k+1) of k=4 is 1.

GAMS performs arithmetic with an extended number range. GAMS has special values for infinity (+INF, -INF), epsilon (EPS), not available (NA), and undefined (UNDEF). When GAMS evaluates expressions with these special values, the calculating engine ensures the correctness of the result (e.g. 5*eps=eps or 5+eps=5). The GAMS model CRAZY in the GAMS Model Library documents the results of the arithmetic operations with respect to special values.

In the GAMS Matlab API we map the IEEE standard values for +/-infinity (Inf and -Inf) and NA (NaN) to the corresponding GAMS values. The special value for UNDEF gets unfiltered through the GAMS Matlab API. The internal double value of UNDEF is 1.0E300 (or better use SpecialValues.UNDEFINED_VALUE).

Special attention needs to be given to the value of 0. Since GAMS is a sparse system it does not store (parameter) records with a true 0. If a record with numerical value of 0 is needed, EPS can help. For example:

* set j /1*10 /;
* parameter b(j);
* b(j) = 1; b('5') = 0;
* scalar s,c;
* s = sum(j, b(j));
* c = card(b);
* display s,c;
* 

will result in

* 
* ----      3 PARAMETER s                    =        9.000
* PARAMETER c                    =        9.000
* 

but

* b(j) = 1; b('5') = EPS;
* 

will result in

* ----      3 PARAMETER s                    =        9.000
* PARAMETER c                    =       10.000
* 

What are the consequences for the GAMS Matlab API? If we read parameter b in case of b('5')=0, the GAMSDatabase will not have a record for b('5'). In case of b('5')=EPS, the GAMSDatabase will have a record with SpecialValues.EPS value 4.94066E-324. Unlike the IEEE values (e.g. Inf), arithmetic operations in Matlab will modify the EPS value (e.g. 5*Inf==Inf but 5*4.94066E-324 != 4.94066E-324). The same rules apply for preparing input data for GAMS in a GAMSDatabase. If a value of 4.94066E-324 is written, GAMS will see the special value EPS (see SpecialValues). The value used for EPS can be reset using GAMSWorkspace.setMyEPS. All other small values (including 0) will be communicated unfiltered to GAMS. As mentioned before, zeros will not be entered as data records in GAMS. The compiler control $on/offEPS can help to automatically map zeros to EPS.

There is one oddity concerning values smaller than 1e-250 on GAMS input. Consider the following example:

* b = db.addParameter('b', 1, '');
* for i = 1:10
* b.addRecord(int2str(i)).value = 1;
* b.findRecord('5').value = 1E-251;
* job.run(db);
* 

with GAMS code:

* $load j b
* scalar card_b;
* card_b = card(b);
* display card_b;
* b(j) = 2*b(j);
* card_b = card(b);
* display card_b;
* 

A record with values smaller than 1E-250 exists on input in GAMS, but as soon as the record gets updated by GAMS and is still smaller than 1E-250, the record gets removed.

The ordering of a set in GAMS can be non-intuitive: Consider 'set i /5/, j /1*5/;'. Elements '5' gets internal number 1, '1' get 2, '2' gets 3 and so on. The last element of j '5' has already the internal number 1. The sequence of internal numbers in j is not ascending and hence GAMS considers set j as not sorted, i.e. one can't use the ord() function nor the lag or lead (-,–,+,++) operators. If 'j' would have been defined before 'i' in this example, the 'set not ordered' problem would have been avoided.

Please note that the GAMSDatabase actually does not implement a relational model for database management. It should be seen as a data storage or data container.

See also
GAMSEquation, GAMSGlobals, GAMSJob, GAMSSymbol, GAMSOptions, GAMSParameter, GAMSSet, GAMSVariable, GAMSWorkspace, GAMSWorkspace.addDatabase

Member Function Documentation

◆ [instance initializer]() [1/2]

Matlab.GAMS.GAMSDatabase.[instance initializer]

(read only) (read only) list of GAMSSymbol instances contained in GAMSDatabase

Performance Note: This cell is created from Java data records for every read. Thus, a loop like

* for i = 1:numel(db.symbols)
* disp(db.symbols{i}.name);
* end
* 

would create the symbols list numel(db.symbols)+1 times. Please use either of the following:

* syms = db.symbols;
* for i = 1:numel(syms)
* disp(syms{i}.name);
* end
* 
* for sym = db.symbols
* disp(sym{1}.name);
* end
* 

◆ [instance initializer]() [2/2]

Matlab.GAMS.GAMSDatabase.[instance initializer]

Check all GAMSSymbol instances in the database if all their records are within the specified domain of the symbol.

It returns a list of GAMSDatabaseDomainViolation instances containing a domain violation information for problematic symbols in a GAMSDatabase instance. Each GAMSDatabaseDomainViolation instance contains information of which GAMSSymbol instance whose domain is violated and a list of GAMSDatabaseDomainViolation instances containing all domain violation records of the GAMSSymbol instance.

Arguments:

  • maxViolation: The maximum number of domain violation records which should be stored (0 for no limit)
  • maxViolationPerSymbol: The maximum number of domain violations records which should be stored per Symbol (0 for no limit)

Return: list of GAMSDatabaseDomainViolation containing a domain violation information

See also
GAMSDatabase.checkDomains, GAMSSymbol.checkDomains, GAMSSymbol.getSymbolDomainViolations

◆ addEquation()

GAMSEquation Matlab.GAMS.GAMSDatabase.addEquation ( varargin  )

Add equation symbol to database.

Note that a symbol with name '*' could not be added to the database as it is reserved as a special symbol of type GAMSSet.

Valid VARARGIN signatures:

  • string identifier, integer dimension, EquType equType
  • string identifier, EquType equType, string explanatoryText, {any domain1, ..., any domainN}
  • string identifier, EquType equType, string explanatoryText, any domain1, ..., any domainN
  • string identifier, integer dimension, EquType equType, string explanatoryText

Arguments:

  • identifier: Equation name
  • dimension: Equation dimension
  • equType: Equation subtype
  • explanatoryText: Explanatory text of equation
  • domain1,...,domainN: Arbitrary arguments of equation domains

Return: Reference to a GAMSEquation instance

See also
EquType

◆ addParameter()

GAMSParameter Matlab.GAMS.GAMSDatabase.addParameter ( varargin  )

Add parameter symbol to database.

Note that a symbol with name '*' could not be added to the database as it is reserved as a special symbol of type GAMSSet.

Valid VARARGIN signatures:

  • string identifier, integer dimension
  • string identifier, string explanatoryText, {any domain1, ..., any domainN}
  • string identifier, string explanatoryText, any domain1, ..., any domainN
  • string identifier, integer dimension, EquType equType, string explanatoryText

Arguments:

  • identifier: Parameter name
  • dimension: Parameter dimension
  • explanatoryText: Explanatory text of parameter
  • domain1,...,domainN: Arbitrary arguments of parameter domains

Return: Reference to a GAMSParameter instance

◆ addSet()

GAMSSet Matlab.GAMS.GAMSDatabase.addSet ( varargin  )

Add set symbol to database.

Note that a symbol with name '*' could not be added to the database as it is reserved as a special symbol of type GAMSSet.

Valid VARARGIN signatures:

  • string identifier, integer dimension
  • string identifier, string explanatoryText, {any domain1, ..., any domainN}
  • string identifier, string explanatoryText, any domain1, ..., any domainN
  • string identifier, integer dimension, EquType equType, string explanatoryText

Arguments:

  • identifier: Set name
  • dimension: Set dimension
  • explanatoryText: Explanatory text of set
  • domain1,...,domainN: Arbitrary arguments of set domains

Return: Reference to a GAMSSet instance

◆ addVariable()

GAMSVariable Matlab.GAMS.GAMSDatabase.addVariable ( varargin  )

Add variable symbol to database.

Note that a symbol with name '*' could not be added to the database as it is reserved as a special symbol of type GAMSSet.

Valid VARARGIN signatures:

  • string identifier, integer dimension, VarType varType
  • string identifier, VarType varType, string explanatoryText, {any domain1, ..., any domainN}
  • string identifier, VarType varType, string explanatoryText, any domain1, ..., any domainN
  • string identifier, integer dimension, VarType varType, string explanatoryText

Arguments:

  • identifier: Variable name
  • dimension: Variable dimension
  • varType: Variable subtype
  • explanatoryText: Explanatory text of variable
  • domain1,...,domainN: Arbitrary arguments of variable domains

Return: Reference to a GAMSVariable instance

See also
VarType

◆ checkDomains()

logical Matlab.GAMS.GAMSDatabase.checkDomains ( )

Check domains of all GAMSSymbol instances in the database.

Return: true if every symbol does not contain a domain violation, false otherwise

See also
GAMSDatabase.getDatabaseDomainViolations, GAMSSymbol.checkDomains, GAMSSymbol.getSymbolDomainViolations

◆ clear()

void Matlab.GAMS.GAMSDatabase.clear ( )

Clear all symbol records in the database.

The number of symbols in the database remains the same.

◆ dispose()

void Matlab.GAMS.GAMSDatabase.dispose ( )

Release external resources hold by non-java library.

A subsequent call on the object after disposed potentially causes an unexpected error or exception. Call this method either when the object is no longer needed and/or when resource management is a critical issue in the application.

◆ export()

void Matlab.GAMS.GAMSDatabase.export ( varargin  )

Write database into a GDX file.

If the file path is not given, the file will be written to the working directory using the name of the database.

Valid VARARGIN signatures:

  • [ ]
  • string filePath

Arguments:

  • filePath: The path used to write the GDX file. A relative path is relative to the GAMS working directory.

◆ getEquation()

GAMSEquation Matlab.GAMS.GAMSDatabase.getEquation ( string  identifier)

Get GAMSEquation by name.

Arguments:

  • identifier: Name of the equation to retrieve

Return: Reference to a GAMSEquation instance

◆ getParameter()

GAMSParameter Matlab.GAMS.GAMSDatabase.getParameter ( string  identifier)

Get GAMSParameter by name.

Arguments:

  • identifier: Name of the parameter to retrieve

Return: Reference to a GAMSParameter instance

◆ getSet()

GAMSSet Matlab.GAMS.GAMSDatabase.getSet ( string  identifier)

Get GAMSSet by name.

Arguments:

  • identifier: Name of the set to retrieve

Return: Reference to a GAMSSet instance

◆ getSymbol()

GAMSSymbol Matlab.GAMS.GAMSDatabase.getSymbol ( string  identifier)

Get GAMSSymbol by name.

Arguments:

  • identifier: Name of the symbol to retrieve

Return: Reference to a GAMSSymbol instance

◆ getVariable()

GAMSVariable Matlab.GAMS.GAMSDatabase.getVariable ( string  identifier)

Get GAMSVariable by name.

Arguments:

  • identifier: Name of the variable to retrieve

Return: Reference to a GAMSVariable instance

◆ isDisposed()

logical Matlab.GAMS.GAMSDatabase.isDisposed ( )

Inquire if this database has already been disposed.

Return: true if disposed, false otherwise

◆ iterator()

GAMSIterator Matlab.GAMS.GAMSDatabase.iterator ( )

Returns an iterator over a set of GAMSSymbol.

Return: an iterator over a set of GAMSSymbol

Member Data Documentation

◆ numberOfSymbols

integer Matlab.GAMS.GAMSDatabase.numberOfSymbols

(read only) Number of symbols in GAMSDatabase

Note that a symbol with name '*' is not included when counting the number of symbols as it is reserved as a special symbol of type GAMSSet representing universe set.