Modifying a model instance and solving the resulting problem in the most efficient way.

A Job 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 instances which is a single mathematical model generated by a GAMS solve statement, the ModelInstance 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 ModelInstance requires a Checkpoint that contains the model definition. Significant parts of the GAMS solve need to be provided for the instantiation of the ModelInstance. The modification of the model instance is done through data in syncDB (a property of ModelInstance of type Database). One needs to create Modifier which contain the information on how to modify the ModelInstance. Such a Modifier consists either of a Parameter or of a triple with the Variable or Equation 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 Parameter that holds the data for modification. Symbol instances of a Modifier must belong to syncDB. The list of Modifier instances needs to be supplied on the Instantiate call. The use of Parameter instancess that are Modifier instances 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 Modifier, 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 Parameter instances 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:

• the original data record is restored (globals.SymbolUpdateType = globals.SymbolUpdateType.BASECASE) which is the default,
• the default record of a Parameter (which is 0) is used (globals.SymbolUpdateType = globals.SymbolUpdateType.ZERO), and
• no copy takes place and we use the previously copied record value (globals.SymbolUpdateType=globals.SymbolUpdateType.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 Modifier are also accessible in syncDB as Variable with the name of the Parameter plus "_var". The Marginal of this Variable can provide sensitivity information about the parameter setting. The status of the solve is accessible through the modelStatus and solveStatus properties (see Globals).

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

Example on how to create a ModelInstance from a Checkpoint that was generated by the Run method of Job.

* ws = GAMS.\ref matlab.gams.control.Workspace "Workspace"();
* cp = ws.addCheckpoint();
* 
* job = ws.addJobFromGamsLib('trnsport');
* job.run(cp);
* 
* mi = cp.addModelInstance();
* b = mi.syncDB.addParameter('b', 1, 'demand');
* 
* mi.instantiate('transport us lp min z', GAMS.\ref matlab.gams.control.Modifier "Modifier"(b));
* 
* bmultlist = [0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3];
* for i = 1:numel(bmultlist)
* b.clear();
* for rec = job.outDB.getParameter('b').records
* b.addRecord(rec{1}.keys).value = rec{1}.value bmultlist(i);
* mi.solve();
* fprintf('Scenario bmult=%f:\n', bm);
* fprintf('  Modelstatus: %s\n', mi.modelStatus);
* fprintf('  Solvestatus: %s\n', mi.solveStatus);
* fprintf('  Obj: %g\n', mi.syncDB.getVariable('z').findRecord().level);
* end
* 

See also

Checkpoint, Checkpoint.addModelInstance, ModelInstanceOpt, Modifier, Symbol