gams::GAMSModelInstance Class Reference

#include <gamsmodelinstance.h>

Public Member Functions

 GAMSModelInstance ()
 Standard constructor. More...
 
GAMSModelInstanceoperator= (const GAMSModelInstance &other)
 
bool operator!= (const GAMSModelInstance &other) const
 
bool operator== (const GAMSModelInstance &other) const
 
bool isValid () const
 
GAMSDatabase syncDb ()
 Retrieve GAMSDatabase used to synchronize modifiable data. More...
 
void instantiate (const std::string &modelDefinition, const gams::GAMSOptions &options, const std::vector< gams::GAMSModifier > &modifiers={ })
 
void instantiate (const std::string &modelDefinition, const gams::GAMSOptions &options, const GAMSModifier &modifier1=GAMSModifier(), const GAMSModifier &modifier2=GAMSModifier(), const GAMSModifier &modifier3=GAMSModifier())
 
void instantiate (const std::string &modelDefinition, const std::vector< gams::GAMSModifier > &modifiers={ })
 
void instantiate (const std::string &modelDefinition, const GAMSModifier &modifier1, const GAMSModifier &modifier2=GAMSModifier(), const GAMSModifier &modifier3=GAMSModifier())
 
void solve (GAMSEnum::SymbolUpdateType updateType, std::ostream &output, GAMSModelInstanceOpt miOpt)
 
void solve (GAMSModelInstanceOpt miOpt)
 
void solve (std::ostream &output)
 
void solve (GAMSEnum::SymbolUpdateType updateType=GAMSEnum::SymbolUpdateType::BaseCase)
 
GAMSEnum::ModelStat modelStatus ()
 Get model state. More...
 
std::string modelStatusAsString ()
 Get model state as string. More...
 
GAMSEnum::SolveStat solveStatus ()
 Get solve state. More...
 
std::string solveStatusAsString ()
 Get solve state as string. More...
 
GAMSModelInstance copyModelInstance (std::string modelInstanceName="")
 
void interrupt ()
 Send interrupt signal to running GAMSModelInstance. More...
 
GAMSCheckpoint checkpoint ()
 
std::string name ()
 
LogId logID ()
 

Detailed Description

The GAMSJob class is the standard way of dealing with a GAMS model and the corresponding solution provided by a solver. The GAMS language provides programming flow that allows to solve models in a loop and do other sophisticated tasks, like building decomposition algorithms.

In rare cases, the GAMS model generation time dominates the solver solution time and GAMS itself becomes the bottleneck in an optimization application. For a model instance which is a single mathematical model generated by a GAMS solve statement, the GAMSModelInstance class provides a controlled way of modifying a model instance and solving the resulting problem in the most efficient way, by communicating only the changes of the model to the solver and doing a hot start (in case of a continuous model like LP) without the use of disk IO.

The GAMSModelInstance requires a GAMSCheckpoint that contains the model definition. Significant parts of the GAMS solve need to be provided for the instantiation of the GAMSModelInstance. The modification of the model instance is done through data in SyncDB (a property of GAMSModelInstance of type GAMSDatabase). One needs to create GAMSModifiers which contain the information on how to modify the GAMSModelInstance. Such a GAMSModifier consists either of a GAMSParameter or of a triple with the GAMSVariable or GAMSEquation to be updated, the modification action (e.g. Upper, Lower or Fixed for updating bounds of a variable, or Primal/Dual for updating the level/marginal of a variable or equation mainly used for starting non-linear models from different starting points), and a GAMSParameter that holds the data for modification. GAMSSymbols of a GAMSModifier must belong to SyncDB. The list of GAMSModifiers needs to be supplied on the Instantiate call. The use of GAMSParameters that are GAMSModifiers is restricted in the GAMS model source. For example, the parameter cannot be used inside $(). Such parameters become endogenous to the model and will be treated by the GAMS compiler as such. Moreover, the rim of the model instance is fixed: No addition of variables and equations is possible.

The Instantiate call will only query the symbol information of the GAMSModifiers, not the data of SyncDB, e.g. to retrieve the dimension of the modifiers. That's why the modifier symbols have to exist (but don't have to have data) in SyncDB when Instantiate is called. The GAMSParameters that contain the update data in SyncDB can be filled at any time before executing the Solve method. The Solve method uses this data to update the model instance. The Solve method will iterate through all records of modifier symbols in the model instance and try to find update data in SyncDB. If a record in SyncDB is found, this data record will be copied into the model instance. If no corresponding record is found in SyncDB there are different choices: 1) the original data record is restored (UpdateType=BaseCase) which is the default, 2) the default record of a GAMSParameter (which is 0) is used (UpdateType=Zero, and 3) no copy takes place and we use the previously copied record value (UpdateType=Accumulate). After the model instance has been updated, the model is passed to the selected solver.

After the completion of the Solve method, the SyncDB will contain the primal and dual solution of the model just solved. Moreover, the GAMSParameters that are GAMSModifiers are also accessible in SyncDB as GAMSVariables with the name of the GAMSParameter plus "_var". The Marginal of this GAMSVariable can provide sensitivity information about the parameter setting. The status of the solve is accessible through the ModelStatus and SolveStatus properties.

In general, file operations in GAMS C++ take place in the WorkingDirectory defined in the GAMSWorkspace. Execptions to this rule are files read or created due to solver specific options in the solve routine of GAMSModelInstance. These files are written to (or read from) the current directory, meaning the directory where the application gets executed.

Example on how to create a GAMSModelInstance from a GAMSCheckpoint that was generated by the method GAMSJob.run().

GAMSWorkspace ws;
GAMSCheckpoint cp;
ws.gamsLib("trnsport");
GAMSJob job = ws.addJobFromFile("trnsport.gms");
job.run(cp);
GAMSModelInstance mi = cp.addModelInstance();
GAMSParameter b = mi.syncDB.addParameter("b", 1, "demand");
mi.instantiate("transport use lp min z", GAMSModifier(b));
vector<double> bmult = { 0.7, 0.9, 1.1, 1.3 };
for (double bm : bmult)
{
b.clear();
for (GAMSParameterRecord rec : job.outDB.getParameter("b"))
b.addRecord(rec.keys()).setValue(rec.value() * bm);
mi.solve();
cout << "Scenario bmult=" << bm << ":" << endl;
cout << " Modelstatus: " << mi.modelStatus << endl;
cout << " Solvestatus: " << mi.SolveStatus <<endl;
cout << " Obj: " << mi.syncDB.getVariable("z").findRecord().level() << endl;
}

Definition at line 125 of file gamsmodelinstance.h.

Constructor & Destructor Documentation

◆ GAMSModelInstance()

gams::GAMSModelInstance::GAMSModelInstance ( )

Standard constructor.

Member Function Documentation

◆ checkpoint()

GAMSCheckpoint gams::GAMSModelInstance::checkpoint ( )

Retrieve GAMSCheckpoint.

Returns
Returns the GAMSCheckpoint.

◆ copyModelInstance()

GAMSModelInstance gams::GAMSModelInstance::copyModelInstance ( std::string  modelInstanceName = "")

Copies this ModelInstance to a new ModelInstance.

Parameters
modelInstanceNameIdentifier of GAMSModelInstance (determined automatically if omitted).
Returns
Returns the new ModelInstance.

◆ instantiate() [1/4]

void gams::GAMSModelInstance::instantiate ( const std::string &  modelDefinition,
const gams::GAMSOptions options,
const std::vector< gams::GAMSModifier > &  modifiers = { } 
)

Instantiate the GAMSModelInstance.

Parameters
modelDefinitionModel definition.
optionsGAMSOptions.
modifiersVector of GAMSModifiers.

◆ instantiate() [2/4]

void gams::GAMSModelInstance::instantiate ( const std::string &  modelDefinition,
const gams::GAMSOptions options,
const GAMSModifier modifier1 = GAMSModifier(),
const GAMSModifier modifier2 = GAMSModifier(),
const GAMSModifier modifier3 = GAMSModifier() 
)

Instantiate the GAMSModelInstance.

Parameters
modelDefinitionModel definition.
optionsGAMSOptions.
modifier1GAMSModifiers one.
modifier2GAMSModifiers two.
modifier3GAMSModifiers three.

◆ instantiate() [3/4]

void gams::GAMSModelInstance::instantiate ( const std::string &  modelDefinition,
const std::vector< gams::GAMSModifier > &  modifiers = { } 
)

Instantiate the GAMSModelInstance.

Parameters
modelDefinitionModel definition.
modifiersVector of GAMSModifiers.

◆ instantiate() [4/4]

void gams::GAMSModelInstance::instantiate ( const std::string &  modelDefinition,
const GAMSModifier modifier1,
const GAMSModifier modifier2 = GAMSModifier(),
const GAMSModifier modifier3 = GAMSModifier() 
)

Instantiate the GAMSModelInstance.

Parameters
modelDefinitionModel definition.
modifier1GAMSModifiers one.
modifier2GAMSModifiers two.
modifier3GAMSModifiers three.

◆ interrupt()

void gams::GAMSModelInstance::interrupt ( )

Send interrupt signal to running GAMSModelInstance.

◆ isValid()

bool gams::GAMSModelInstance::isValid ( ) const

Checks if a GAMSModelInstance is valid.

Returns
Returns true if the GAMSModelInstance is valid; otherwise false.

◆ logID()

LogId gams::GAMSModelInstance::logID ( )

Get the GAMS log ID.

Returns
Returns the GAMS log ID.

◆ modelStatus()

GAMSEnum::ModelStat gams::GAMSModelInstance::modelStatus ( )

Get model state.

◆ modelStatusAsString()

std::string gams::GAMSModelInstance::modelStatusAsString ( )

Get model state as string.

◆ name()

std::string gams::GAMSModelInstance::name ( )

Retrieve name of GAMSModelInstance

Returns
Returns the GAMSModelInstance name.

◆ operator!=()

bool gams::GAMSModelInstance::operator!= ( const GAMSModelInstance other) const

Compares two GAMSModelInstance objects.

Parameters
otherAnother GAMSModelInstance to compare to.
Returns
Returns true if the two GAMSModelInstance are different; otherwise false.

◆ operator=()

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

Assigns a GAMSModelInstance.

Parameters
otherAnother GAMSModelInstance used as data source.
Returns
Returns the assigned GAMSModelInstance (*this).

◆ operator==()

bool gams::GAMSModelInstance::operator== ( const GAMSModelInstance other) const

Compares two GAMSModelInstance objects.

Parameters
otherAnother GAMSModelInstance to compare to.
Returns
Returns true if the two GAMSModelInstance are equal; otherwise false.

◆ solve() [1/4]

void gams::GAMSModelInstance::solve ( GAMSEnum::SymbolUpdateType  updateType,
std::ostream &  output,
GAMSModelInstanceOpt  miOpt 
)

Solve model instance.

Parameters
updateTypeUpdate type.
outputStream to capture GAMS log.
miOptGAMSModelInstance options.

◆ solve() [2/4]

void gams::GAMSModelInstance::solve ( GAMSModelInstanceOpt  miOpt)

Solve model instance.

Parameters
miOptGAMSModelInstance options.

◆ solve() [3/4]

void gams::GAMSModelInstance::solve ( std::ostream &  output)

Solve model instance.

Parameters
outputStream to capture GAMS log.

◆ solve() [4/4]

void gams::GAMSModelInstance::solve ( GAMSEnum::SymbolUpdateType  updateType = GAMSEnum::SymbolUpdateType::BaseCase)

Solve model instance.

Parameters
updateTypeUpdate type.

◆ solveStatus()

GAMSEnum::SolveStat gams::GAMSModelInstance::solveStatus ( )

Get solve state.

◆ solveStatusAsString()

std::string gams::GAMSModelInstance::solveStatusAsString ( )

Get solve state as string.

◆ syncDb()

GAMSDatabase gams::GAMSModelInstance::syncDb ( )

Retrieve GAMSDatabase used to synchronize modifiable data.