gams.database.GamsDatabase Class Reference

An instance of GamsDatabase communicates data between the Python world and the GAMS world. More...

Inherits object.

Public Member Functions

def __len__ (self)
 Retrieve the number of symbols in the GamsDatabase.
 
def __del__ (self)
 Use this to explicitly free unmanaged resources associated with this GamsDatabase.
 
def get_symbol (self, symbol_identifier)
 Get GamsSymbol by name. More...
 
def get_equation (self, equation_identifier)
 Get GamsEquation by name. More...
 
def get_parameter (self, parameter_identifier)
 Get GamsParameter by name. More...
 
def get_variable (self, variable_identifier)
 Get GamsVariable by name. More...
 
def get_set (self, set_identifier)
 Get GamsSet by name. More...
 
def add_equation (self, identifier, dimension, equtype, explanatory_text="")
 Add equation symbol to database. More...
 
def add_equation_dc (self, identifier, equtype, domains, explanatory_text="")
 Add equation symbol to database using domain information. More...
 
def add_variable (self, identifier, dimension, vartype, explanatory_text="")
 Add variable symbol to database. More...
 
def add_variable_dc (self, identifier, vartype, domains, explanatory_text="")
 Add variable symbol to database using domain information. More...
 
def add_set (self, identifier, dimension, explanatory_text="")
 Add set symbol to database. More...
 
def add_set_dc (self, identifier, domains, explanatory_text="")
 Add set symbol to database using domain information. More...
 
def add_parameter (self, identifier, dimension, explanatory_text="")
 Add parameter symbol to database. More...
 
def add_parameter_dc (self, identifier, domains, explanatory_text="")
 Add parameter symbol to database using domain information. More...
 
def export (self, file_path=None)
 Write database into a GDX file. More...
 
def clear (self)
 Clear all symbols in GamsDatabase.
 
def compact (self)
 This function is obsolete and has no effect anymore. More...
 
def check_domains (self)
 Check for all symbols if all records are within the specified domain of the symbol. More...
 
def get_database_dvs (self, max_viol=0, max_viol_per_symbol=0)
 return all GamsDatabaseDomainViolations More...
 

Properties

 number_symbols = property(get_nr_symbols)
 Retrieve the number of symbols in the GamsDatabase. More...
 
 workspace = property(get_workspace)
 Get GamsWorkspace containing GamsDatabase.
 
 name = property(get_name)
 Get GamsDatabase name.
 
 suppress_auto_domain_checking = property(get_suppress_auto_domain_checking, set_suppress_auto_domain_checking)
 Controls whether domain checking is called in GamsDatabase export.
 

Detailed Description

An instance of GamsDatabase communicates data between the Python world and the GAMS world.

A GamsDatabase consists of a collection of symbols (GamsDatabase implements __iter__() and next() to allow iterating conveniently through the symbols in a GamsDatabase). The symbol types available for a GamsDatabase correspond to the symbol types known from the GAMS language: Set, Parameter, Variable, and Equation are represented in Python by a derived class (e.g. GamsSet, GamsParameter, etc). Besides the type, a GamsSymbol has a name (this has to match the name inside the GAMS model), a dimension (currently up to 20 or GMS_MAX_INDEX_DIM) and some explanatory text.

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

GamsDatabases can be created empty, or initialized from existing GDX files or from another GamsDatabase (copy). Symbols can be added at any time (e.g. GamsDatabase.add_parameter), but once a symbol is part of a GamsDatabase, it cannot be removed. Only its associated data (GamsSymbolRecord) can be purged (see GamsSymbol.clear()) or individually removed (GamsSymbol.delete_record). 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 exception. Similar, the unsuccessful search for a record also results in an exception.

GamsSymbol implements __iter__() and next() to conveniently iterate through the records of a symbol. There are also sliced access methods to symbol records that allow to iterate through all records with a fixed index at some positions. GamsDatabases can be exported as GDX files for permanent storage.

GamsJob.out_db and GamsModelInstance.sync_db 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 GamsWorkspace.add_database can be used to initialize a GamsDatabase from another database by specifying the optional parameter source_database (e.g. newdb = workspace.add_database(GamsJob.out_db)).

GamsDatabases often provide the input data for a GamsJob. Such GamsDatabases are listed in the GamsJob.run method. 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 (e.g. db = workspace.add_database(database_name="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 dictionary of a GamsOptions instance:

db = workspace.add_database()
opt = workspace.add_options()
opt.defines["SupplyDataFileName"] = db.name
...
gamsjob.run(gams_options=opt, databases=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 Python API we map the IEEE standard values for +/-infinity (float('inf')/float('-inf')) and NA (float('nan')) to the corresponding GAMS values. The special value for UNDEF gets unfiltered through the GAMS Python API. The internal double value of UNDEF is 1.0E300 (or better use the constant SV_UNDEF).

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(SV_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 Python 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 value EPS. Unlike the IEEE values (e.g. float("inf")), arithmetic operations in Python will modify EPS (e.g. 5*float("inf")==float("inf") but 5*EPS!=EPS). The same rules apply for preparing input data for GAMS in a GamsDatabase. If a value of EPS is written, GAMS will see the special value EPS. 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.add_parameter("b",1)
for i in range(1,11):
b.add_record(str(i)).value = 1
b.find_record("5").value = 1E-251
job.run(db)
$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.

Member Function Documentation

◆ add_equation()

def gams.database.GamsDatabase.add_equation (   self,
  identifier,
  dimension,
  equtype,
  explanatory_text = "" 
)

Add equation symbol to database.

Parameters
identifierEquation name
dimensionEquation dimension
equtypeEquation subtype (EquType.E: Equal, EquType.G: Greater, EquType.L: Less, EquType.N: No specification, EquType.X: External defined, EquType.C: Conic)
explanatory_textExplanatory text of equation
Returns
Instance of GamsEquation
See also
add_parameter(), add_set(), add_variable()

◆ add_equation_dc()

def gams.database.GamsDatabase.add_equation_dc (   self,
  identifier,
  equtype,
  domains,
  explanatory_text = "" 
)

Add equation symbol to database using domain information.

Parameters
identifierEquation name
equtypeEquation subtype (EquType.E: Equal, EquType.G: Greater, EquType.L: Less, EquType.N: No specification, EquType.X: External defined, EquType.C: Conic)
domainsA list containing GamsSet objects and strings for domain information. The length of the list specifies the dimension.
explanatory_textExplanatory text of equation
Returns
Instance of GamsEquation
See also
add_parameter_dc(), add_set_dc(), add_variable_dc()

◆ add_parameter()

def gams.database.GamsDatabase.add_parameter (   self,
  identifier,
  dimension,
  explanatory_text = "" 
)

Add parameter symbol to database.

Parameters
identifierParameter name
dimensionParameter dimension
explanatory_textExplanatory text of parameter
Returns
Instance of GamsParameter
See also
add_equation(), add_set(), add_variable()

◆ add_parameter_dc()

def gams.database.GamsDatabase.add_parameter_dc (   self,
  identifier,
  domains,
  explanatory_text = "" 
)

Add parameter symbol to database using domain information.

Parameters
identifierParameter name
domainsA list containing GamsSet objects and strings for domain information. The length of the list specifies the dimension.
explanatory_textExplanatory text of parameter
Returns
Instance of GamsParameter
See also
add_equation_dc(), add_set_dc(), add_variable_dc()

◆ add_set()

def gams.database.GamsDatabase.add_set (   self,
  identifier,
  dimension,
  explanatory_text = "" 
)

Add set symbol to database.

Parameters
identifierSet name
dimensionSet dimension
explanatory_textExplanatory text of set
Returns
Instance of GamsSet
See also
add_equation(), add_parameter(), add_variable()

◆ add_set_dc()

def gams.database.GamsDatabase.add_set_dc (   self,
  identifier,
  domains,
  explanatory_text = "" 
)

Add set symbol to database using domain information.

Parameters
identifierSet name
domainsA list containing GamsSet objects and strings for domain information. The length of the list specifies the dimension.
explanatory_textExplanatory text of set
Returns
Instance of GamsSet
See also
add_equation_dc(), add_parameter_dc(), add_variable_dc()

◆ add_variable()

def gams.database.GamsDatabase.add_variable (   self,
  identifier,
  dimension,
  vartype,
  explanatory_text = "" 
)

Add variable symbol to database.

Parameters
identifierVariable name
dimensionVariable dimension
vartypeVariable subtype (VarType.Binary, VarType.Integer, VarType.Positive, VarType.Negative, VarType.Free, VarType.SOS1, VarType.SOS2, VarType.SemiCont, VarType.SemiInt)
explanatory_textExplanatory text to variable
Returns
Instance of GamsVariable
See also
add_equation(), add_parameter(), add_set()

◆ add_variable_dc()

def gams.database.GamsDatabase.add_variable_dc (   self,
  identifier,
  vartype,
  domains,
  explanatory_text = "" 
)

Add variable symbol to database using domain information.

Parameters
identifierVariable name
vartypeVariable subtype (VarType.Binary, VarType.Integer, VarType.Positive, VarType.Negative, VarType.Free, VarType.SOS1, VarType.SOS2, VarType.SemiCont, VarType.SemiInt)
domainsA list containing GamsSet objects and strings for domain information. The length of the list specifies the dimension.
explanatory_textExplanatory text to variable
Returns
Instance of GamsVariable
See also
add_equation_dc(), add_parameter_dc(), add_set_dc()

◆ check_domains()

def gams.database.GamsDatabase.check_domains (   self)

Check for all symbols if all records are within the specified domain of the symbol.

Returns
True: Everything is correct, False: There is a domain violation

◆ compact()

def gams.database.GamsDatabase.compact (   self)

This function is obsolete and has no effect anymore.

It will be removed in the future

◆ export()

def gams.database.GamsDatabase.export (   self,
  file_path = None 
)

Write database into a GDX file.

Parameters
file_pathThe path used to write the GDX file. A relative path is relative to the GAMS working directory. If not present, the file is written to the working directory using the name of the database.

◆ get_database_dvs()

def gams.database.GamsDatabase.get_database_dvs (   self,
  max_viol = 0,
  max_viol_per_symbol = 0 
)

return all GamsDatabaseDomainViolations

Parameters
max_violThe maximum number of domain violations which should be stored (0 for no limit)
max_viol_per_symbolThe maximum number of domain violations which should be stored per Symbol (0 for no limit)
Returns
List containing GamsDatabaseDomainViolation objects

◆ get_equation()

def gams.database.GamsDatabase.get_equation (   self,
  equation_identifier 
)

Get GamsEquation by name.

Parameters
equation_identifierName of the equation to retrieve
Returns
Instance of GamsEquation
See also
get_symbol(), get_parameter(), get_set(), get_variable()

◆ get_parameter()

def gams.database.GamsDatabase.get_parameter (   self,
  parameter_identifier 
)

Get GamsParameter by name.

Parameters
parameter_identifierName of the parameter to retrieve
Returns
Instance of GamsParameter
See also
get_symbol(), get_set(), get_variable(), get_equation()

◆ get_set()

def gams.database.GamsDatabase.get_set (   self,
  set_identifier 
)

Get GamsSet by name.

Parameters
set_identifierName of the set to retrieve
Returns
Instance of GamsSet
See also
get_symbol(), get_parameter(), get_variable(), get_equation()

◆ get_symbol()

def gams.database.GamsDatabase.get_symbol (   self,
  symbol_identifier 
)

Get GamsSymbol by name.

symbol = database.get_symbol("a")
if isinstance(symbol, GamsParameter):
print "symbol is a GamsParameter"
if isinstance(symbol, GamsSet):
print "symbol is a GamsSet"
if isinstance(symbol, GamsVariable):
print "symbol is a GamsVariable
if isinstance(symbol, GamsEquation):
print "symbol is a GamsEquation
Parameters
symbol_identifierName of the symbol to retrieve
Returns
Instance of _GamsSymbol
See also
get_parameter(), get_set(). get_variable(), get_equation()

◆ get_variable()

def gams.database.GamsDatabase.get_variable (   self,
  variable_identifier 
)

Get GamsVariable by name.

Parameters
variable_identifierName of the variable to retrieve
Returns
Instance of GamsVariable
See also
get_symbol(), get_parameter(), get_set(), get_equation()

Property Documentation

◆ number_symbols

gams.database.GamsDatabase.number_symbols = property(get_nr_symbols)
static

Retrieve the number of symbols in the GamsDatabase.

Note
This is the same as calling len(database)