GAMS.GAMSDatabase Class Reference

More...

Inherits IEnumerable, and IDisposable.

Public Member Functions

void Export (string filePath=null)
 Write database into a GDX file More...
 
GAMSSymbol GetSymbol (string symbolIdentifier)
 Get GAMSSymbol by name More...
 
GAMSParameter GetParameter (string parameterIdentifier)
 Get GAMSParameter by name More...
 
GAMSSet GetSet (string setIdentifier)
 Get GAMSSet by name More...
 
GAMSVariable GetVariable (string variableIdentifier)
 Get GAMSVariable by name More...
 
GAMSEquation GetEquation (string equationIdentifier)
 Get GAMSEquation by name More...
 
void Clear ()
 Clear all symbols in GAMSDatabase More...
 
void Dispose ()
 Free unmanaged ressources. More...
 
GAMSEquation AddEquation (string identifier, int dimension, EquType equType, string explanatoryText="")
 Add equation symbol to database More...
 
GAMSEquation AddEquation (string identifier, EquType equType, string explanatoryText, params object[] domains)
 Add equation symbol to database More...
 
GAMSParameter AddParameter (string identifier, int dimension, string explanatoryText="")
 Add parameter symbol to database More...
 
GAMSParameter AddParameter (string identifier, string explanatoryText, params object[] domains)
 Add parameter symbol to database More...
 
GAMSSet AddSet (string identifier, int dimension, string explanatoryText="")
 Add set symbol to database More...
 
GAMSSet AddSet (string identifier, string explanatoryText, params object[] domains)
 Add set symbol to database More...
 
GAMSVariable AddVariable (string identifier, int dimension, VarType varType, string explanatoryText="")
 Add variable symbol to database More...
 
GAMSVariable AddVariable (string identifier, VarType varType, string explanatoryText, params object[] domains)
 Add variable symbol to database More...
 
bool CheckDomains ()
 Check for all symbols if all records are within the specified domain of the symbol More...
 
List< GAMSDatabaseDomainViolationGetDatabaseDVs (int MaxViol=0, int MaxViolPerSym=0)
 Return all GAMSDatabaseDomainViolations More...
 
void Compact ()
 Obsolete More...
 
IEnumerator GetEnumerator ()
 Get Enumerator to iterate through the symbols of the database More...
 

Properties

bool SuppressAutoDomainChecking [get, set]
 Controls whether domain checking is called in GAMSDatabase export More...
 
int NrSymbols [get]
 Retrieve the number of symbols in the GAMSDatabase More...
 
GAMSWorkspace Workspace [get]
 Get GAMSWorkspace containing GAMSDatabase More...
 
string Name [get]
 Get GAMSDatabase name More...
 

Detailed Description

An instance of GAMSDatabase communicates data between the .NET world and the GAMS world. A GAMSDatabase consists of a collection of symbols (GAMSDatabase implements the IEnumerable interface, that allows to iterate conveniently through the symbols in a GAMSDatabase). The symbol types available for a GAMSDatabase correspond to the symbols types know from the GAMS language: Set, Parameter, Variable, and Equation are represented in .NET 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 gamsglobals.maxdim) and some explanatory text.

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

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.AddParameter), 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.DeleteRecord). 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 the IEnumerable interface 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. They also manage external resources and need to be properly disposed before the .NET garbage collector reclaims the instance.

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 (e.g. GAMSDatabase newdb = workspace.AddDatabase(GAMSJob.OutDB);).

GAMSDatabases often provide the input data for a GAMSJob. Such GAMSDatabases are listed in the GAMSJob.Run methods. 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. GAMSDatabase db = workspace.AddDatabase(databaseName:"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:

GAMSDatabase db = workspace.AddDatabase();
GAMSOptions opt = workspace.AddOptions();
opt.Defines.Add("SupplyDataFileName",db.Name);
...
gamsjob.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 .NET 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 .NET API we map the IEEE standard values for +/-infinity (e.g. double.PositiveInfinity) and NA (double.NaN) to the corresponding GAMS values. The special value for UNDEF gets unfiltered through the GAMS .NET API. The internal double value of UNDEF is 1.0E300 (or better use the constant sv_valund from gamsglobals).

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 .NET 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 double.Epsilon. Unlike the IEEE values (e.g. double.PositivInfinity), arithmetic operations in .NET will modify double.Epsilon (e.g. 5*double.PositiveInfinity==double.PositiveInfinity but 5*double.Epsilon!=double.Epsilon). The same rules apply for preparing input data for GAMS in a GAMSDatabase. If a value of double.Epsilon is written, GAMS will see the special value EPS. The value used for EPS can be reset using the GAMSWorkspace property MyEPS. 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:

GAMSParameter b = db.AddGAMSParameter("b",1,"");
for(int i=1; i &lt; 11; i++) b.AddRecord(i.ToString()).Value = 1;
b.FindRecord("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

◆ AddEquation() [1/2]

GAMSEquation GAMS.GAMSDatabase.AddEquation ( string  identifier,
int  dimension,
EquType  equType,
string  explanatoryText = "" 
)
inline

Add equation symbol to database

Parameters
identifierEquation name
dimensionEquation dimension
equTypeEquation subtype (E: Equal, G: Greater, L: Less, N: No specification, X: External defined, C: Conic)
explanatoryTextExplanatory text of equation
Returns
Reference to equation
See also
AddParameter(string, int, string), AddSet(string, int, string), AddVariable(string, int, GAMS.VarType, string)

◆ AddEquation() [2/2]

GAMSEquation GAMS.GAMSDatabase.AddEquation ( string  identifier,
EquType  equType,
string  explanatoryText,
params object []  domains 
)
inline

Add equation symbol to database

Parameters
identifierEquation name
equTypeEquation subtype (E: Equal, G: Greater, L: Less, N: No specification, X: External defined, C: Conic)
explanatoryTextExplanatory text of equation
domainsEquation domains
Returns
Reference to equation
See also
AddParameter(string, string, object[]), AddSet(string, string, object[]), AddVariable(string, GAMS.VarType, string, object[])

◆ AddParameter() [1/2]

GAMSParameter GAMS.GAMSDatabase.AddParameter ( string  identifier,
int  dimension,
string  explanatoryText = "" 
)
inline

Add parameter symbol to database

Parameters
identifierParameter name
dimensionParameter dimension
explanatoryTextExplanatory text of parameter
Returns
Reference to parameter
See also
AddEquation(string, int, GAMS.EquType, string), AddSet(string, int, string), AddVariable(string, int, GAMS.VarType, string)

◆ AddParameter() [2/2]

GAMSParameter GAMS.GAMSDatabase.AddParameter ( string  identifier,
string  explanatoryText,
params object []  domains 
)
inline

Add parameter symbol to database

Parameters
identifierParameter name
explanatoryTextExplanatory text of parameter
domainsParameter domains
Returns
Reference to parameter
See also
AddEquation(string, GAMS.EquType, string, object[]), AddSet(string, string, object[]), AddVariable(string, GAMS.VarType, string, object[])

◆ AddSet() [1/2]

GAMSSet GAMS.GAMSDatabase.AddSet ( string  identifier,
int  dimension,
string  explanatoryText = "" 
)
inline

Add set symbol to database

Parameters
identifierSet name
dimensionSet dimension
explanatoryTextExplanatory text of set
Returns
Reference to set
See also
AddEquation(string, int, GAMS.EquType, string), AddParameter(string, int, string), AddVariable(string, int, GAMS.VarType, string)

◆ AddSet() [2/2]

GAMSSet GAMS.GAMSDatabase.AddSet ( string  identifier,
string  explanatoryText,
params object []  domains 
)
inline

Add set symbol to database

Parameters
identifierSet name
explanatoryTextExplanatory text of set
domainsSet domains
Returns
Reference to set
See also
AddParameter(string, string, object[]), AddVariable(string, GAMS.VarType, string, object[]), AddEquation(string, GAMS.EquType, string, object[])

◆ AddVariable() [1/2]

GAMSVariable GAMS.GAMSDatabase.AddVariable ( string  identifier,
int  dimension,
VarType  varType,
string  explanatoryText = "" 
)
inline

Add variable symbol to database

Parameters
identifierVariable name
dimensionVariable dimension
varTypeVariable subtype (Binary, Integer, Positive, Negative, Free, SOS1, SOS2, SemiCont, SemiInt,)
explanatoryTextExplanatory text to variable
Returns
Reference to variable
See also
AddEquation(string, int, GAMS.EquType, string), AddParameter(string, int, string), AddSet(string, int, string)

◆ AddVariable() [2/2]

GAMSVariable GAMS.GAMSDatabase.AddVariable ( string  identifier,
VarType  varType,
string  explanatoryText,
params object []  domains 
)
inline

Add variable symbol to database

Parameters
identifierVariable name
varTypeVariable subtype (Binary, Integer, Positive, Negative, Free, SOS1, SOS2, SemiCont, SemiInt,)
explanatoryTextExplanatory text of variable
domainsVariable domains
Returns
Reference to variable
See also
AddParameter(string, string, object[]), AddSet(string, string, object[]), AddEquation(string, GAMS.EquType, string, object[])

◆ CheckDomains()

bool GAMS.GAMSDatabase.CheckDomains ( )
inline

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

◆ Clear()

void GAMS.GAMSDatabase.Clear ( )
inline

Clear all symbols in GAMSDatabase

Returns

◆ Compact()

void GAMS.GAMSDatabase.Compact ( )
inline

Obsolete

◆ Dispose()

void GAMS.GAMSDatabase.Dispose ( )
inline

Free unmanaged ressources.

◆ Export()

void GAMS.GAMSDatabase.Export ( string  filePath = null)
inline

Write database into a GDX file

Parameters
filePathThe 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.

◆ GetDatabaseDVs()

List<GAMSDatabaseDomainViolation> GAMS.GAMSDatabase.GetDatabaseDVs ( int  MaxViol = 0,
int  MaxViolPerSym = 0 
)
inline

Return all GAMSDatabaseDomainViolations

Parameters
MaxViolThe maximum number of domain violations which should be stored (0 for no limit)
MaxViolPerSymThe maximum number of domain violations which should be stored per Symbol (0 for no limit)
Returns
List of GAMSDatabaseDomainViolations

◆ GetEnumerator()

IEnumerator GAMS.GAMSDatabase.GetEnumerator ( )
inline

Get Enumerator to iterate through the symbols of the database

Returns
database enumerator

◆ GetEquation()

GAMSEquation GAMS.GAMSDatabase.GetEquation ( string  equationIdentifier)
inline

Get GAMSEquation by name

Parameters
equationIdentifierName of the equation to retrieve
Returns
Reference to equation
See also
GetSymbol, GetParameter, GetSet, GetVariable

◆ GetParameter()

GAMSParameter GAMS.GAMSDatabase.GetParameter ( string  parameterIdentifier)
inline

Get GAMSParameter by name

Parameters
parameterIdentifierName of the parameter to retrieve
Returns
Reference to parameter
See also
GetSymbol, GetSet, GetVariable, GetEquation

◆ GetSet()

GAMSSet GAMS.GAMSDatabase.GetSet ( string  setIdentifier)
inline

Get GAMSSet by name

Parameters
setIdentifierName of the set to retrieve
Returns
Reference to set
See also
GetSymbol, GetParameter, GetVariable, GetEquation

◆ GetSymbol()

GAMSSymbol GAMS.GAMSDatabase.GetSymbol ( string  symbolIdentifier)
inline

Get GAMSSymbol by name

Parameters
symbolIdentifierName of the symbol to retrieve
Returns
Reference to symobl
GAMSSymbol symbol = database.getSymbol("a");
if(symbol is GAMSParameter)
{
GAMSParameter param = (GAMSParameter) symbol;
}
if(symbol is GAMSSet)
{
GAMSSet set = (GAMSSet) symbol;
}
if(symbol is GAMSVariable)
{
GAMSVariable variable = (GAMSVariable) symbol;
}
if (symbol is GAMSEquation)
{
GAMSEquation equation = (GAMSEquation)symbol;
}
See also
GetParameter, GetSet, GetVariable, GetEquation

◆ GetVariable()

GAMSVariable GAMS.GAMSDatabase.GetVariable ( string  variableIdentifier)
inline

Get GAMSVariable by name

Parameters
variableIdentifierName of the variable to retrieve
Returns
Reference to variable
See also
GetSymbol, GetParameter, GetSet, GetEquation

Property Documentation

◆ Name

string GAMS.GAMSDatabase.Name
get

Get GAMSDatabase name

◆ NrSymbols

int GAMS.GAMSDatabase.NrSymbols
get

Retrieve the number of symbols in the GAMSDatabase

◆ SuppressAutoDomainChecking

bool GAMS.GAMSDatabase.SuppressAutoDomainChecking
getset

Controls whether domain checking is called in GAMSDatabase export

◆ Workspace

GAMSWorkspace GAMS.GAMSDatabase.Workspace
get

Get GAMSWorkspace containing GAMSDatabase