Classes
enum	SymbolUpdateType
	GAMS Symbol update type. More...

Public Member Functions
GAMSModelInstance	copyModelInstance ()
	Copies this ModelInstance to a new ModelInstance.

GAMSModelInstance	copyModelInstance (String modelInstanceName)
	Copies this ModelInstance to a new ModelInstance.

void	instantiate (String modelDefinition, GAMSModifier ... modifiers)
	Instantiate the GAMSModelInstance.

void	instantiate (String modelDefinition, GAMSOptions options, GAMSModifier ... modifiers)
	Instantiate the GAMSModelInstance.

void	solve ()
	Solve model instance.

void	solve (GAMSModelInstance.SymbolUpdateType updateType)
	Solve model instance.

void	solve (PrintStream output)
	Solve model instance.

void	solve (GAMSModelInstanceOpt miOpt)
	Solve model instance.

void	solve (GAMSModelInstance.SymbolUpdateType updateType, PrintStream output)
	Solve model instance.

void	solve (GAMSModelInstance.SymbolUpdateType updateType, GAMSModelInstanceOpt miOpt)
	Solve model instance.

void	solve (PrintStream output, GAMSModelInstanceOpt miOpt)
	Solve model instance.

void	solve (GAMSModelInstance.SymbolUpdateType updateType, PrintStream output, GAMSModelInstanceOpt miOpt)
	Solve model instance.

String	getName ()
	Retrieve GAMSCheckpoint Retrieve name of GAMSModelInstance.

GAMSDatabase	SyncDB ()
	Retrieve GAMSDatabase used to synchronize modifiable data.

GAMSGlobals.ModelStat	getModelStatus ()
	Status of the model (available after a solve).

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

void	dispose ()
	Release external resources hold by non-java library.

void	interrupt ()
	Send interrupt signal to running GAMSModelInstance.

Protected Member Functions
void	finalize () throws Throwable
	Release resources used by non-java library.

Detailed Description

A GAMSJob 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 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 GAMSModifier 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. GAMSSymbol instances of a GAMSModifier must belong to SyncDB. The list of GAMSModifier instances 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 GAMSParameter 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 (SymbolUpdateType=BASECASE) which is the default,
the default record of a GAMSParameter (which is 0) is used (SymbolUpdateType=ZERO), and
no copy takes place and we use the previously copied record value (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 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 (see GAMSGlobals).

A GAMSModelInstance 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 GAMSModelInstance from a GAMSCheckpoint that was generated by the Run method of GAMSJob.

 GAMSWorkspace ws = new GAMSWorkspace();
 GAMSCheckpoint cp = ws.addCheckpoint();

 GAMSJob job = ws.addJobFromGamsLib("trnsport");
 job.run(cp);

 GAMSModelInstance mi = cp.addModelInstance();
 GAMSParameter b = mi.SyncDB().addParameter("b", 1, "demand");

 mi.Instantiate("transport us lp min z", new GAMSModifier(b));

 double[] bmultlist = new double[] { 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3 };
 for (double bm : bmult)
 {
     b.clear();
     for (GAMSParameterRecord rec : job.OutDB().getParameter("b"))
          b.addRecord(rec.getKeys()).setValue( rec.getValue() * bm );
     mi.solve();
     System.out.println("Scenario bmult=" + bm + ":");
     System.out.println("  Modelstatus: " + mi.getModelStatus());
     System.out.println("  Solvestatus: " + mi.getSolveStatus());
     System.out.println("  Obj: " + mi.SyncDB().getVariable("z").findRecord().getLevel());
 }

See also: GAMSCheckpoint; GAMSCheckpoint.addModelInstance(); GAMSCheckpoint.addModelInstance(String); GAMSModelInstanceOpt; GAMSModifier; GAMSSymbol

Member Function Documentation

◆ copyModelInstance() [1/2]

GAMSModelInstance com.gams.api.GAMSModelInstance.copyModelInstance ( )

Copies this ModelInstance to a new ModelInstance.

Returns: Reference to new ModelInstance

◆ copyModelInstance() [2/2]

GAMSModelInstance com.gams.api.GAMSModelInstance.copyModelInstance ( String modelInstanceName )

Copies this ModelInstance to a new ModelInstance.

Parameters

modelInstanceName Identifier of GAMSModelInstance (determined automatically if omitted

Returns: Reference to new ModelInstance

◆ dispose()

void com.gams.api.GAMSModelInstance.dispose ( )

Release external resources hold by non-java library.

A subsequent call on the object after disposed potentially causes an unexpected error or exception.

Call this method either when the object is no longer needed and/or when resource management is a critical issue in the application.

◆ finalize()

void com.gams.api.GAMSModelInstance.finalize ( ) throws Throwable

protected

Release resources used by non-java library.

Advanced Used only.

Exceptions

exception or error raised by calling finalize().

◆ getModelStatus()

GAMSGlobals.ModelStat com.gams.api.GAMSModelInstance.getModelStatus ( )

Status of the model (available after a solve).

Exceptions

GAMSException If this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSGlobals.ModelStat

◆ getName()

String com.gams.api.GAMSModelInstance.getName ( )

Retrieve GAMSCheckpoint Retrieve name of GAMSModelInstance.

◆ getSolveStatus()

GAMSGlobals.SolveStat com.gams.api.GAMSModelInstance.getSolveStatus ( )

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

Exceptions

GAMSException If this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSGlobals.SolveStat

◆ instantiate() [1/2]

void com.gams.api.GAMSModelInstance.instantiate	(	String	modelDefinition,
		GAMSModifier ...	modifiers
	)

Instantiate the GAMSModelInstance.

Parameters

modelDefinition	Model definition
modifiers	List of GAMSModifier(s)

Exceptions

GAMSException If either GAMSModelInstance object could not be instantiated or this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSModifier

◆ instantiate() [2/2]

void com.gams.api.GAMSModelInstance.instantiate	(	String	modelDefinition,
		GAMSOptions	options,
		GAMSModifier ...	modifiers
	)

Instantiate the GAMSModelInstance.

Parameters

modelDefinition	Model definition
options	An instance of GAMSOptions
modifiers	List of GAMSModifier(s)

Exceptions

GAMSException If either GAMSModelInstance object could not be instantiated or this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSOptions; GAMSModifier

◆ interrupt()

void com.gams.api.GAMSModelInstance.interrupt ( )

Send interrupt signal to running GAMSModelInstance.

This method is useful for interrupting the long running GAMSModelInstance.

◆ solve() [1/8]

void com.gams.api.GAMSModelInstance.solve ( )

Solve 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, the original data record is restored (UpdateType=BASECASE). After the model instance has been updated, the model is passed to the selected solver.

Exceptions

GAMSException If either the model instance is not yet instantiated or there is a problem updating API component or there is a problem calling a solver or there is a problem writing file into a directory or the model could not be solved or this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSModelInstance.SymbolUpdateType

◆ solve() [2/8]

void com.gams.api.GAMSModelInstance.solve ( GAMSModelInstance.SymbolUpdateType updateType )

Solve 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 (UpdateType=BASECASE) which is the default,
the default record of a GAMSParameter (which is 0) is used (UpdateType=ZERO), and
no copy takes place and we use the previously copied record value (UpdateType=ACCUMULATE).

Other symbol types (e.g., UpdateType=INHERIT) is an invalid update type for solve statement. After the model instance has been updated, the model is passed to the selected solver.

Parameters

updateType Update type

Exceptions

GAMSException If either the model instance is not yet instantiated or there is a problem updating API component or there is a problem calling a solver or there is a problem writing file into a directory or the model could not be solved or the symbol update type parameter is invalid or this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSModelInstance.SymbolUpdateType

◆ solve() [3/8]

void com.gams.api.GAMSModelInstance.solve	(	GAMSModelInstance.SymbolUpdateType	updateType,
		GAMSModelInstanceOpt	miOpt
	)

Solve 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 (UpdateType=BASECASE) which is the default,
the default record of a GAMSParameter (which is 0) is used (UpdateType=ZERO), and
no copy takes place and we use the previously copied record value (UpdateType=ACCUMULATE).

Other symbol types (e.g., UpdateType=INHERIT) is an invalid update type for solve statement. After the model instance has been updated, the model is passed to the selected solver.

Parameters

updateType	Update type
miOpt	GAMSModelInstance option

Exceptions

GAMSException If either the model instance is not yet instantiated or there is a problem updating API component or there is a problem calling a solver or there is a problem writing file into a directory or the model could not be solved or the symbol update type parameter is invalid or this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSModelInstance.SymbolUpdateType; GAMSModelInstanceOpt

◆ solve() [4/8]

void com.gams.api.GAMSModelInstance.solve	(	GAMSModelInstance.SymbolUpdateType	updateType,
		PrintStream	output
	)

Solve 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 (UpdateType=BASECASE) which is the default,
the default record of a GAMSParameter (which is 0) is used (UpdateType=ZERO), and
no copy takes place and we use the previously copied record value (UpdateType=ACCUMULATE).

Other symbol types (e.g., UpdateType=INHERIT) is an invalid update type for solve statement. After the model instance has been updated, the model is passed to the selected solver.

Parameters

updateType	Update type
output	Stream to capture GAMS log

Exceptions

GAMSException If either the model instance is not yet instantiated or there is a problem updating API component or there is a problem calling a solver or there is a problem writing file into a directory or the model could not be solved or the symbol update type parameter is invalid or this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSModelInstance.SymbolUpdateType

◆ solve() [5/8]

void com.gams.api.GAMSModelInstance.solve	(	GAMSModelInstance.SymbolUpdateType	updateType,
		PrintStream	output,
		GAMSModelInstanceOpt	miOpt
	)

Solve 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 (UpdateType=BASECASE) which is the default,
the default record of a GAMSParameter (which is 0) is used (UpdateType=ZERO), and
no copy takes place and we use the previously copied record value (UpdateType=ACCUMULATE).

Other symbol types (e.g., UpdateType=INHERIT) is an invalid update type for solve statement. After the model instance has been updated, the model is passed to the selected solver.

Parameters

updateType	Update type
output	Stream to capture GAMS log
miOpt	GAMSModelInstance option

Exceptions

GAMSException If either the model instance is not yet instantiated or there is a problem updating API component or there is a problem calling a solver or there is a problem writing file into a directory or the model could not be solved or the symbol update type parameter is invalid or this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSModelInstance.SymbolUpdateType; GAMSModelInstanceOpt

◆ solve() [6/8]

void com.gams.api.GAMSModelInstance.solve ( GAMSModelInstanceOpt miOpt )

Solve 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, the original data record is restored (UpdateType=BASECASE). After the model instance has been updated, the model is passed to the selected solver.

Parameters

miOpt GAMSModelInstance option

Exceptions

GAMSException If either the model instance is not yet instantiated or there is a problem updating API component or there is a problem calling a solver or there is a problem writing file into a directory or the model could not be solved or this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSModelInstance.SymbolUpdateType; GAMSModelInstanceOpt

◆ solve() [7/8]

void com.gams.api.GAMSModelInstance.solve ( PrintStream output )

Solve 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, the original data record is restored (UpdateType=BASECASE). After the model instance has been updated, the model is passed to the selected solver.

Parameters

output Stream to capture GAMS log

Exceptions

GAMSException If either the model instance is not yet instantiated or there is a problem updating API component or there is a problem calling a solver or there is a problem writing file into a directory or the model could not be solved or this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSModelInstance.SymbolUpdateType

◆ solve() [8/8]

void com.gams.api.GAMSModelInstance.solve	(	PrintStream	output,
		GAMSModelInstanceOpt	miOpt
	)

Solve 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, the original data record is restored (UpdateType=BASECASE). After the model instance has been updated, the model is passed to the selected solver.

Parameters

output	Stream to capture GAMS log
miOpt	GAMSModelInstance option

Exceptions

GAMSException If either the model instance is not yet instantiated or there is a problem updating API component or there is a problem calling a solver or there is a problem writing file into a directory or the model could not be solved or this GAMSModelInstance instance has already been disposed, therefore resources are no longer available.

See also: GAMSModelInstance.SymbolUpdateType; GAMSModelInstanceOpt

◆ SyncDB()

GAMSDatabase com.gams.api.GAMSModelInstance.SyncDB ( )

Retrieve GAMSDatabase used to synchronize modifiable data.

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ copyModelInstance() [1/2]

◆ copyModelInstance() [2/2]

◆ dispose()

◆ finalize()

◆ getModelStatus()

◆ getName()

◆ getSolveStatus()

◆ instantiate() [1/2]

◆ instantiate() [2/2]

◆ interrupt()

◆ solve() [1/8]

◆ solve() [2/8]

◆ solve() [3/8]

◆ solve() [4/8]

◆ solve() [5/8]

◆ solve() [6/8]

◆ solve() [7/8]

◆ solve() [8/8]

◆ SyncDB()