Loading...
Searching...
No Matches
GAMS.GAMSModelInstance Class Reference

Inherits IDisposable.

Public Types

enum  SymbolUpdateType { Zero , BaseCase , Accumulate , Inherit }
 Symbol update type. More...
 

Public Member Functions

GAMSModelInstance CopyModelinstance (string modelInstanceName=null)
 Copies this ModelInstance to a new ModelInstance.
 
void Dispose ()
 Free unmanaged ressources.
 
void Instantiate (string modelDefinition, params GAMSModifier[] modifiers)
 Instantiate the GAMSModelInstance.
 
void Instantiate (string modelDefinition, GAMSOptions options, params GAMSModifier[] modifiers)
 Instantiate the GAMSModelInstance.
 
void Solve (SymbolUpdateType updateType=SymbolUpdateType.BaseCase, TextWriter output=null, GAMSModelInstanceOpt miOpt=null)
 Solve model instance.
 
void Interrupt ()
 Send interrupt signal to running GAMSModelInstance.
 

Properties

GAMSCheckpoint Checkpoint [get]
 Retrieve GAMSCheckpoint.
 
string Name [get]
 Retrieve name of GAMSModelInstance.
 
GAMSDatabase SyncDB [get]
 Retrieve GAMSDatabase used to synchronize modifiable data.
 
ModelStat ModelStatus [get]
 Status of the model. (available after a solve)
 
SolveStat SolveStatus [get]
 Solve status of the model. (available after a solve)
 

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.

A GAMSModelInstance is connected to external resources and needs to be properly disposed before the .NET garbage collector can claim the instance.

In general, file operations in GAMS .Net 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. If required, the current directory can be changed inside an application using the method System.IO.Directory.SetCurrentDirectory(string path).

Example on how to create a GAMSModelInstance from a GAMSCheckpoint that was generated by the Run method of GAMSJob.

ws.GamsLib("trnsport");
GAMSJob job = ws.AddJobFromFile("trnsport.gms");
job.Run(cp);
GAMSParameter b = mi.SyncDB.AddParameter("b", 1, "demand");
mi.Instantiate("transport use lp min z", new GAMSModifier(b));
double[] bmult = new double[] { 0.7, 0.9, 1.1, 1.3 };
foreach (double bm in bmult)
{
b.Clear();
foreach (GAMSParameterRecord rec in job.OutDB.GetParameter("b"))
b.AddRecord(rec.Keys).Value = rec.Value * bm;
mi.Solve();
Console.WriteLine("Scenario bmult=" + bm + ":");
Console.WriteLine(" Modelstatus: " + mi.ModelStatus);
Console.WriteLine(" Solvestatus: " + mi.SolveStatus);
Console.WriteLine(" Obj: " + mi.SyncDB.GetVariable("z").FindRecord().Level);
}
A GAMSCheckpoint class captures the state of a GAMSJob after the GAMSJob.Run method has been carried ...
Definition: GAMSCheckpoint.cs:17
GAMSModelInstance AddModelInstance(string modelInstanceName=null)
Create model instance.
Definition: GAMSCheckpoint.cs:84
GAMSVariable GetVariable(string variableIdentifier)
Get GAMSVariable by name.
Definition: GAMSDatabase.cs:454
GAMSParameter GetParameter(string parameterIdentifier)
Get GAMSParameter by name.
Definition: GAMSDatabase.cs:410
GAMSParameter AddParameter(string identifier, int dimension, string explanatoryText="")
Add parameter symbol to database.
Definition: GAMSDatabase.cs:588
Definition: GAMSJob.cs:34
GAMSDatabase OutDB
Get GAMSDatabase created by Run method.
Definition: GAMSJob.cs:160
Definition: GAMSModelInstance.cs:221
SolveStat SolveStatus
Solve status of the model. (available after a solve)
Definition: GAMSModelInstance.cs:759
GAMSDatabase SyncDB
Retrieve GAMSDatabase used to synchronize modifiable data.
Definition: GAMSModelInstance.cs:415
void Solve(SymbolUpdateType updateType=SymbolUpdateType.BaseCase, TextWriter output=null, GAMSModelInstanceOpt miOpt=null)
Solve model instance.
Definition: GAMSModelInstance.cs:632
void Instantiate(string modelDefinition, params GAMSModifier[] modifiers)
Instantiate the GAMSModelInstance.
Definition: GAMSModelInstance.cs:424
ModelStat ModelStatus
Status of the model. (available after a solve)
Definition: GAMSModelInstance.cs:746
Instances of this class are input to GAMSModelInstance.Instatiate. A GAMSModifier consists either of ...
Definition: GAMSModelInstance.cs:58
This is the representation of a single record of a GAMSParameter.
Definition: GAMSParameterRecord.cs:10
double Value
Get: Retrieve the value of this GAMSParameterRecord Set: Set the value of this GAMSParameterRecord.
Definition: GAMSParameterRecord.cs:38
This is the representation of a parameter symbol in GAMS. It exists in a GAMSDatabase and contains GA...
Definition: GAMSParameter.cs:14
new GAMSParameterRecord AddRecord(params string[] keys)
Add record to GAMSParameter.
Definition: GAMSParameter.cs:99
string[] Keys
Retrieve keys of GAMSSymbolRecord.
Definition: GAMSSymbolRecord.cs:58
bool Clear()
Clear symbol.
Definition: GAMSSymbol.cs:230
double Level
Get: Retrieve the the level of this GAMSVariableRecord Set: Set the the level of this GAMSVariableRec...
Definition: GAMSVariableRecord.cs:38
new GAMSVariableRecord FindRecord(params string[] keys)
Find record in GAMSVariable.
Definition: GAMSVariable.cs:132
Definition: GAMSWorkSpace.cs:239
void GamsLib(string model)
Retrieves model from GAMS Model Library.
Definition: GAMSWorkSpace.cs:306
GAMSCheckpoint AddCheckpoint(string checkpointName=null)
Create GAMSCheckpoint.
Definition: GAMSWorkSpace.cs:1169
GAMSJob AddJobFromFile(string fileName, GAMSCheckpoint checkpoint=null, string jobName=null)
Create GAMSJob from model file.
Definition: GAMSWorkSpace.cs:1055

Member Enumeration Documentation

◆ SymbolUpdateType

Symbol update type.

Enumerator
Zero 

If record does not exist use 0 (Zero)

BaseCase 

If record does not exist use values from instantiation.

Accumulate 

If record does not exist use value from previous solve.

Inherit 

Inherit setting from solve statement.

Member Function Documentation

◆ CopyModelinstance()

GAMSModelInstance GAMS.GAMSModelInstance.CopyModelinstance ( string  modelInstanceName = null)
inline

Copies this ModelInstance to a new ModelInstance.

Parameters
modelInstanceNameIdentifier of GAMSModelInstance (determined automatically if omitted)
Returns
Reference to new ModelInstance

◆ Dispose()

void GAMS.GAMSModelInstance.Dispose ( )
inline

Free unmanaged ressources.

◆ Instantiate() [1/2]

void GAMS.GAMSModelInstance.Instantiate ( string  modelDefinition,
GAMSOptions  options,
params GAMSModifier[]  modifiers 
)
inline

Instantiate the GAMSModelInstance.

Parameters
modelDefinitionModel definition
optionsGAMS options
modifiersList of GAMSModifiers

◆ Instantiate() [2/2]

void GAMS.GAMSModelInstance.Instantiate ( string  modelDefinition,
params GAMSModifier[]  modifiers 
)
inline

Instantiate the GAMSModelInstance.

Parameters
modelDefinitionModel definition
modifiersList of GAMSModifiers

◆ Interrupt()

void GAMS.GAMSModelInstance.Interrupt ( )
inline

Send interrupt signal to running GAMSModelInstance.

◆ Solve()

void GAMS.GAMSModelInstance.Solve ( SymbolUpdateType  updateType = SymbolUpdateType::BaseCase,
TextWriter  output = null,
GAMSModelInstanceOpt  miOpt = null 
)
inline

Solve model instance.

Parameters
updateTypeUpdate type
outputStream to capture GAMS log
miOptGAMSModelInstance options

Property Documentation

◆ Checkpoint

GAMSCheckpoint GAMS.GAMSModelInstance.Checkpoint
get

Retrieve GAMSCheckpoint.

◆ ModelStatus

ModelStat GAMS.GAMSModelInstance.ModelStatus
get

Status of the model. (available after a solve)

◆ Name

string GAMS.GAMSModelInstance.Name
get

Retrieve name of GAMSModelInstance.

◆ SolveStatus

SolveStat GAMS.GAMSModelInstance.SolveStatus
get

Solve status of the model. (available after a solve)

◆ SyncDB

GAMSDatabase GAMS.GAMSModelInstance.SyncDB
get

Retrieve GAMSDatabase used to synchronize modifiable data.