#include <gamsdatabase.h>

Public Member Functions
	GAMSDatabase ()
	Standard constructor.

GAMSDatabase &	operator= (const GAMSDatabase &other)

bool	isValid () const

GAMSDatabaseIter	begin ()

GAMSDatabaseIter	end ()

int	getNrSymbols ()
	Retrieve the number of symbols in the GAMSDatabase.

void	setSuppressAutoDomainChecking (bool value)

bool	suppressAutoDomainChecking ()

std::string	name ()
	Get GAMSDatabase name.

GAMSWorkspace	workspace ()
	Get GAMSWorkspace containing GAMSDatabase.

void	doExport (const std::string &filePath="")

bool	checkDomains ()

GAMSSymbol	getSymbol (const std::string &name)

GAMSSet	getSet (const std::string &name)

GAMSParameter	getParameter (const std::string &name)

GAMSVariable	getVariable (const std::string &name)

GAMSEquation	getEquation (const std::string &name)

GAMSSet	addSet (const std::string &name, const int dimension, const std::string &explanatoryText="", GAMSEnum::SetType setType=GAMSEnum::SetType::Multi)

GAMSSet	addSet (const std::string &name, const std::string &explanatoryText, const std::vector< GAMSDomain > &domains=std::vector< GAMSDomain >(), GAMSEnum::SetType setType=GAMSEnum::SetType::Multi)

GAMSSet	addSet (const std::string &name, const std::string &explanatoryText, GAMSDomain domain1, GAMSDomain domain2=GAMSDomain(), GAMSDomain domain3=GAMSDomain(), GAMSEnum::SetType setType=GAMSEnum::SetType::Multi)

GAMSParameter	addParameter (const std::string &name, const int dimension, const std::string &explanatoryText="")

GAMSParameter	addParameter (const std::string &name, const std::string &explanatoryText="", const std::vector< GAMSDomain > &domains=std::vector< GAMSDomain >())

GAMSParameter	addParameter (const std::string &name, const std::string &explanatoryText, GAMSDomain domain1, GAMSDomain domain2=GAMSDomain(), GAMSDomain domain3=GAMSDomain())

GAMSVariable	addVariable (const std::string &name, const int dimension, const GAMSEnum::VarType varType, const std::string &explanatoryText="")

GAMSVariable	addVariable (const std::string &name, const GAMSEnum::VarType varType, const std::string &explanatoryText="", const std::vector< GAMSDomain > &domains=std::vector< GAMSDomain >())

GAMSVariable	addVariable (const std::string &name, const GAMSEnum::VarType varType, const std::string &explanatoryText, GAMSDomain domain1, GAMSDomain domain2=GAMSDomain(), GAMSDomain domain3=GAMSDomain())

GAMSEquation	addEquation (const std::string &name, const int dimension, const GAMSEnum::EquType equType, const std::string &explanatoryText="")

GAMSEquation	addEquation (const std::string &name, const GAMSEnum::EquType equType, const std::string &explanatoryText="", const std::vector< GAMSDomain > &domains=std::vector< GAMSDomain >())

GAMSEquation	addEquation (const std::string &name, const GAMSEnum::EquType equType, const std::string &explanatoryText, GAMSDomain domain1, GAMSDomain domain2=GAMSDomain(), GAMSDomain domain3=GAMSDomain())

std::vector< GAMSDatabaseDomainViolation >	getDatabaseDVs (int maxViol=0, int maxViolPerSym=0)

	~GAMSDatabase ()
	Destructor.

bool	operator!= (const GAMSDatabase &other) const

bool	operator== (const GAMSDatabase &other) const

LogId	logID ()

void	clear ()
	Clears all `GAMSSymbol`'s of a `GAMSDatabase`.

Detailed Description

An instance of GAMSDatabase communicates data between the C++ world and the GAMS world. A GAMSDatabase consists of a collection of symbols, which can be iterated by using the GAMSDatabaseIter. The symbol types available for a GAMSDatabase correspond to the symbol types know from the GAMS language: Set, Parameter, Variable, and Equation are represented in C++ 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) and some explanatory text.

Variables and equations also have a subtype: e.g. Binary, Positive, etc. for variables (see type GAMSEnum.VarType) and e.g. E, G etc. for equations (see type GAMSEnum.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.

GAMSSymbolIter is used 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 (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.setDefines("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 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 C++ 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 C++ 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 C++ 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 EPS (numeric_limits<double>::min()). Unlike the IEEE values (e.g. numeric_limits<double>::infinity()), arithmetic operations in C++ will modify EPS (e.g. 5*numeric_limits<double>min()==numeric_limits<double>min() but 5*numeric_limits<double>min()!=numeric_limits<double>::min()). 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. 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:

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.

Definition at line 174 of file gamsdatabase.h.

Constructor & Destructor Documentation

◆ GAMSDatabase()

gams::GAMSDatabase::GAMSDatabase ( )

Standard constructor.

◆ ~GAMSDatabase()

gams::GAMSDatabase::~GAMSDatabase ( )

Destructor.

Member Function Documentation

◆ addEquation() [1/3]

GAMSEquation gams::GAMSDatabase::addEquation	(	const std::string &	name,
		const GAMSEnum::EquType	equType,
		const std::string &	explanatoryText,
		GAMSDomain	domain1,
		GAMSDomain	domain2 = `GAMSDomain()`,
		GAMSDomain	domain3 = `GAMSDomain()`
	)

Add equation symbol to database.

Parameters

name	Equation name.
equType	Equation subtype (E: Equal, G: Greater, L: Less, N: No specification, X: External defined, C: Conic).
explanatoryText	Explanatory text of equation.
domain1	Set domain for first index position.
domain2	Set domain for second index position.
domain3	Set domain for third index position.

Returns: Returns the GAMSEquation.

See also: addSet, addVariable, GAMSParameter

◆ addEquation() [2/3]

GAMSEquation gams::GAMSDatabase::addEquation	(	const std::string &	name,
		const GAMSEnum::EquType	equType,
		const std::string &	explanatoryText = `""`,
		const std::vector< GAMSDomain > &	domains = `std::vector< GAMSDomain >()`
	)

Add equation symbol to database.

Parameters

name	Equation name.
equType	Equation subtype (E: Equal, G: Greater, L: Less, N: No specification, X: External defined, C: Conic).
explanatoryText	Explanatory text of equation.
domains	Set domains.

Returns: Returns the GAMSEquation.

See also: addSet, addVariable, GAMSParameter

◆ addEquation() [3/3]

GAMSEquation gams::GAMSDatabase::addEquation	(	const std::string &	name,
		const int	dimension,
		const GAMSEnum::EquType	equType,
		const std::string &	explanatoryText = `""`
	)

Add equation symbol to database.

Parameters

name	Equation name.
dimension	Equation dimension.
equType	Equation subtype (E: Equal, G: Greater, L: Less, N: No specification, X: External defined, C: Conic).
explanatoryText	Explanatory text of equation.

Returns: Returns the GAMSEquation.

See also: addSet, addVariable, GAMSParameter

◆ addParameter() [1/3]

GAMSParameter gams::GAMSDatabase::addParameter	(	const std::string &	name,
		const int	dimension,
		const std::string &	explanatoryText = `""`
	)

Add parameter symbol to database.

Parameters

name	Parameter name.
dimension	Parameter dimension.
explanatoryText	Explanatory text of parameter.

Returns: Returns the GAMSParameter.

See also: addSet, addEquation, addVariable

◆ addParameter() [2/3]

GAMSParameter gams::GAMSDatabase::addParameter	(	const std::string &	name,
		const std::string &	explanatoryText,
		GAMSDomain	domain1,
		GAMSDomain	domain2 = `GAMSDomain()`,
		GAMSDomain	domain3 = `GAMSDomain()`
	)

Add set symbol to database.

Parameters

name	Parameter name.
explanatoryText	Explanatory text of parameter.
domain1	Set domain for first index position.
domain2	Set domain for second index position.
domain3	Set domain for third index position.

Returns: Returns the GAMSParameter.

See also: addSet, addEquation, addVariable

◆ addParameter() [3/3]

GAMSParameter gams::GAMSDatabase::addParameter	(	const std::string &	name,
		const std::string &	explanatoryText = `""`,
		const std::vector< GAMSDomain > &	domains = `std::vector< GAMSDomain >()`
	)

Add parameter symbol to database.

Parameters

name	Parameter name.
explanatoryText	Explanatory text of parameter.
domains	Set domains.

Returns: Returns the GAMSParameter.

See also: addSet, addEquation, addVariable

◆ addSet() [1/3]

GAMSSet gams::GAMSDatabase::addSet	(	const std::string &	name,
		const int	dimension,
		const std::string &	explanatoryText = `""`,
		GAMSEnum::SetType	setType = `GAMSEnum::SetType::Multi`
	)

Add set symbol to database.

Parameters

name	Set name.
dimension	Set dimension.
explanatoryText	Explanatory text of set.
setType	set subtype

Returns: Returns the GAMSSet.

See also: addEquation, addParameter, addVariable

◆ addSet() [2/3]

GAMSSet gams::GAMSDatabase::addSet	(	const std::string &	name,
		const std::string &	explanatoryText,
		const std::vector< GAMSDomain > &	domains = `std::vector< GAMSDomain >()`,
		GAMSEnum::SetType	setType = `GAMSEnum::SetType::Multi`
	)

Add set symbol to database.

Parameters

name	Set name.
explanatoryText	Explanatory text of set.
domains	Set domains.
setType	set subtype

Returns: Returns the GAMSSet.

See also: addEquation, addParameter, addVariable

◆ addSet() [3/3]

GAMSSet gams::GAMSDatabase::addSet	(	const std::string &	name,
		const std::string &	explanatoryText,
		GAMSDomain	domain1,
		GAMSDomain	domain2 = `GAMSDomain()`,
		GAMSDomain	domain3 = `GAMSDomain()`,
		GAMSEnum::SetType	setType = `GAMSEnum::SetType::Multi`
	)

Add set symbol to database.

Parameters

name	Set name.
explanatoryText	Explanatory text of set.
domain1	Set domain for first index position.
domain2	Set domain for second index position.
domain3	Set domain for third index position.
setType	set subtype

Returns: Returns the GAMSSet.

See also: addEquation, addParameter, addVariable

◆ addVariable() [1/3]

GAMSVariable gams::GAMSDatabase::addVariable	(	const std::string &	name,
		const GAMSEnum::VarType	varType,
		const std::string &	explanatoryText,
		GAMSDomain	domain1,
		GAMSDomain	domain2 = `GAMSDomain()`,
		GAMSDomain	domain3 = `GAMSDomain()`
	)

Add variable symbol to database.

Parameters

name	Variable name.
varType	Variable subtype (Binary, Integer, Positive, Negative, Free, SOS1, SOS2, SemiCont, SemiInt).
explanatoryText	Explanatory text of variable.
domain1	Set domain for first index position.
domain2	Set domain for second index position.
domain3	Set domain for third index position.

Returns: Returns the GAMSVariable.

See also: addSet, addEquation, addParameter

◆ addVariable() [2/3]

GAMSVariable gams::GAMSDatabase::addVariable	(	const std::string &	name,
		const GAMSEnum::VarType	varType,
		const std::string &	explanatoryText = `""`,
		const std::vector< GAMSDomain > &	domains = `std::vector< GAMSDomain >()`
	)

Add variable symbol to database.

Parameters

name	Variable name.
varType	Variable subtype (Binary, Integer, Positive, Negative, Free, SOS1, SOS2, SemiCont, SemiInt).
explanatoryText	Explanatory text of variable.
domains	Set domains.

Returns: Returns the GAMSVariable.

See also: addSet, addEquation, addParameter

◆ addVariable() [3/3]

GAMSVariable gams::GAMSDatabase::addVariable	(	const std::string &	name,
		const int	dimension,
		const GAMSEnum::VarType	varType,
		const std::string &	explanatoryText = `""`
	)

Add variable symbol to database.

Parameters

name	Variable name.
dimension	Variable dimension
varType	Variable subtype (Binary, Integer, Positive, Negative, Free, SOS1, SOS2, SemiCont, SemiInt).
explanatoryText	Explanatory text of variable.

Returns: Returns the GAMSVariable.

See also: addSet, addEquation, addParameter

◆ begin()

GAMSDatabaseIter gams::GAMSDatabase::begin ( )

Interator to the begining.

Returns: Iterator to the first GAMSEquation.

◆ checkDomains()

bool gams::GAMSDatabase::checkDomains ( )

Check for domain violations.

Returns: Returns true if there is any domain violation; otherwise false.

◆ clear()

void gams::GAMSDatabase::clear ( )

Clears all GAMSSymbol's of a GAMSDatabase.

◆ doExport()

void gams::GAMSDatabase::doExport ( const std::string & filePath = "" )

Write database into a GDX file.

Parameters

filePath The 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.

◆ end()

GAMSDatabaseIter gams::GAMSDatabase::end ( )

Iterator to end.

Returns: Iterator to the element following the last GAMSEquation.

◆ getDatabaseDVs()

std::vector< GAMSDatabaseDomainViolation > gams::GAMSDatabase::getDatabaseDVs	(	int	maxViol = `0`,
		int	maxViolPerSym = `0`
	)

Get all GAMSDatabaseDomainViolation's.

Parameters

maxViol	The maximum number of domain violations which should be stored (0 for no limit).
maxViolPerSym	The maximum number of domain violations which should be stored per Symbol (0 for no limit).

Returns: Returns a list of GAMSDatabaseDomainViolations.

◆ getEquation()

GAMSEquation gams::GAMSDatabase::getEquation ( const std::string & name )

Get GAMSEquation by name.

Parameters

name	Name of the equation to retrieve.

Returns: Returns the GAMSEquation.

See also: getSymbol, getSet, getParameter, getVariable, getEquation

◆ getNrSymbols()

int gams::GAMSDatabase::getNrSymbols ( )

Retrieve the number of symbols in the GAMSDatabase.

◆ getParameter()

GAMSParameter gams::GAMSDatabase::getParameter ( const std::string & name )

Get GAMSParameter by name.

Parameters

name	Name of the parameter to retrieve.

Returns: Returns the GAMSParameter.

See also: getSymbol, getSet, getParameter, getVariable, getEquation

◆ getSet()

GAMSSet gams::GAMSDatabase::getSet ( const std::string & name )

Get GAMSSet by name.

Parameters

name	Name of the set to retrieve.

Returns: Returns the GAMSSet.

See also: getSymbol, getSet, getParameter, getVariable, getEquation

◆ getSymbol()

GAMSSymbol gams::GAMSDatabase::getSymbol ( const std::string & name )

Get GAMSSymbol by name.

Parameters

name	Name of the symbol to retrieve.

Returns: Returns the GAMSSymbol.

See also: getSymbol, getSet, getParameter, getVariable, getEquation

◆ getVariable()

GAMSVariable gams::GAMSDatabase::getVariable ( const std::string & name )

Get GAMSVariable by name.

Parameters

name	Name of the variable to retrieve

Returns: Returns the GAMSVariable.

See also: getSymbol, getSet, getParameter, getVariable, getEquation

◆ isValid()

bool gams::GAMSDatabase::isValid ( ) const

Checks if a GAMSDatabase is valid.

Returns: Returns true if the GAMSDatabase is valid; otherwise false.

◆ logID()

LogId gams::GAMSDatabase::logID ( )

Check if a GAMSDatabase is valid.

Returns: Returns true if the GAMSDatabase is valid; otherwise false.

◆ name()

std::string gams::GAMSDatabase::name ( )

Get GAMSDatabase name.

◆ operator!=()

bool gams::GAMSDatabase::operator!= ( const GAMSDatabase & other ) const

Compares two GAMSDatabase objects.

Parameters

other Another GAMSDatabase to compare to.

Returns: Returns true if the two GAMSDatabase are different; otherwise false.

◆ operator=()

GAMSDatabase & gams::GAMSDatabase::operator= ( const GAMSDatabase & other )

Assigns a GAMSDatabase.

Parameters

other Another GAMSDatabase used as data source.

Returns: Returns the assigned GAMSDatabase (*this).

◆ operator==()

bool gams::GAMSDatabase::operator== ( const GAMSDatabase & other ) const

Compares two GAMSDatabase objects.

Parameters

other Another GAMSDatabase to compare to.

Returns: Returns true if the two GAMSDatabase are equal; otherwise false.

◆ setSuppressAutoDomainChecking()

void gams::GAMSDatabase::setSuppressAutoDomainChecking ( bool value )

Set the value for controlling whether domain checking is called in GAMSDatabase export.

Parameters

value true to suppress automatically domain checking; otherwise false.

◆ suppressAutoDomainChecking()

bool gams::GAMSDatabase::suppressAutoDomainChecking ( )

Get current state of the automatically domain checking.

Returns: Returns true if it is activated; otherwise false.

◆ workspace()

GAMSWorkspace gams::GAMSDatabase::workspace ( )

Get GAMSWorkspace containing GAMSDatabase.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ GAMSDatabase()

◆ ~GAMSDatabase()

Member Function Documentation

◆ addEquation() [1/3]

◆ addEquation() [2/3]

◆ addEquation() [3/3]

◆ addParameter() [1/3]

◆ addParameter() [2/3]

◆ addParameter() [3/3]

◆ addSet() [1/3]

◆ addSet() [2/3]

◆ addSet() [3/3]

◆ addVariable() [1/3]

◆ addVariable() [2/3]

◆ addVariable() [3/3]

◆ begin()

◆ checkDomains()

◆ clear()

◆ doExport()

◆ end()

◆ getDatabaseDVs()

◆ getEquation()

◆ getNrSymbols()

◆ getParameter()

◆ getSet()

◆ getSymbol()

◆ getVariable()

◆ isValid()

◆ logID()

◆ name()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ setSuppressAutoDomainChecking()

◆ suppressAutoDomainChecking()

◆ workspace()