Model Definition and Description

Index to all Optimization Libarary Modules

EKKDSCA - Describe a Mathematical Programming Application

EKKDSCM - Describe a Mathematical Programming Model

EKKDSCB - Describe One Block of the Problem Matrix for a Model

EKKRPTB - Repeat an Existing Matrix Block As a New Block in the Current

EKKLMDL - Specify the Linear Part of a Model

EKKIMDL - Specify the Integer Parts of a MIP Model

EKKNMDL - Specify a Network Model

EKKQMDL - Specify the Quadratic Parts of a QP Model

EKKPMDL - Specify a Parametric Model

EKKSMDL - Specify a Model in Spreadsheet Format

EKKEMDL - Specify an Empty Model

EKKDSCA - Describe a Mathematical Programming Application

This subroutine should be called once at the beginning of each application. It is the way for you to describe your application to the Optimization Library modules. It also allows you to specify the number of models in your application. EKKDSCA reserves space at the bottom of dspace for model information for the number of models specified. See "OSL Terms and Concepts" for more information on applications, models, and storage.

Syntax

FORTRAN	CALL EKKDSCA(rtcod,dspace,ndwords,nmodel)
C	ekkdsca(&rtcod,dspace,ndwords,nmodel);

On Entry

dspace: is the user-provided work area.
ndwords: is the number of doublewords in dspace.
nmodel: is the number of models in the application.

On Return

rtcod: is the return code for the subroutine, where:
dspace: is the user-provided work area.

Note

All but the first call to EKKDSCA should be preceded by a call to EKKINIT.

Examples

Refer to the following sample programs for examples of using EKKDSCA:

EKKDSCM - Describe a Mathematical Programming Model

This subroutine allows you to describe the models in your application to the Optimization Library. The solver modules use the model information supplied by the most recent call to EKKDSCM or EKKGTMI.

This subroutine should be called once for each model in your application. If you do not call EKKDSCM, the model input subroutine (such as EKKMPS, EKKLMDL, EKKNMDL, or EKKSMDL) will call EKKDSCM for you with model=1 and nblock=1.

If your matrix is made up of multiple blocks, use EKKDSCB or EKKRPTB to describe these blocks to the Optimization Library. See "OSL Terms and Concepts" for more information on applications, models, and blocks.

Syntax

FORTRAN	CALL EKKDSCM(rtcod,dspace,model,nblock)
C	ekkdscm(&rtcod,dspace,model,nblock);

On Entry

dspace: is the user-provided work area.
model: is the model number to describe.
nblock: is the number of blocks used to define the matrix for the model.

On Return

rtcod: is the return code for the subroutine, where:
dspace: is the user-provided work area.

Notes

EKKDSCM calls EKKPTMI if there already is a current model.
A minimum of five blocks is required for each quadratic programming model.
A call to EKKDSCM resets the values of all the control variables to whatever they were after the first call to EKKDSCM in the program. The reset values will be the default values, unless the control variables had been set prior to the very first call to EKKDSCM. For example, if an application consists of several models, and each model is a maximization problem, it is possible to set Rmaxmin after a call to EKKDSCA, but before any calls to EKKDSCM. This sets the initial value of Rmaxmin for the entire application.

This procedure works for all control variables except those integer control variables that determine the sizes of arrays, such as Imaxcols, Imaxrows, Imaxints, Imaxsets, and Imaxintinfo. These control variables cannot be set to an initial value that will persist for the entire application. Within each model, these can be set only once.

Examples

Refer to the following sample programs for examples of using EKKDSCM:

EKKDSCB - Describe One Block of the Problem Matrix for a Model

This subroutine is used to describe one block of the problem matrix for a model stored as a collection of blocks. "OSL Terms and Concepts" gives more information about how blocks are used to form a constraint matrix.

EKKMPS, EKKLMDL, EKKNMDL, or EKKSMDL must be called before calling this subroutine.

Syntax

FORTRAN	CALL EKKDSCB(rtcod,dspace,type,block,mrow,mcol,dels,rbas, cbas, ncol, nel)
C	ekkdscb(&rtcod,dspace,type,block,mrow,mcol,dels,rbas, cbas, ncol, nel);

On Entry

dspace: is the user-provided work area.
type: is the type of block, where:
block: is the block number.

mrow
mcol
dels: the elements of the matrix block.
rbas: is the row base to be added to all row numbers.
cbas: is the column base to be added to all of the column numbers.
ncol: is the number of columns.
nel: is the number of elements in the block.

On Return

rtcod: is the return code for the subroutine, where:
dspace: is the user-provided work area.

Notes

If there are overlapping entries in two or more blocks, the corresponding entry in the composite matrix will be the sum of the entries in the overlapping blocks.
If you add a block to a matrix that has been scaled, you must scale the elements in the block. The scale factors for the matrix begin in dspace at the locations pointed to by the index control variables, Nrowscales and Ncolscales. See "Sample FORTRAN Program EXNGET" for an example use of the scaling factors.
rbas and cbas are automatically added to the indices specified by the mrow and mcol arrays. You do not need to do so before calling EKKDSCB.
EKKDSCB will accept and maintain any zero coefficients in the dels array. A warning message is issued to indicate the number of zero coefficients passed to EKKDSCB.
In all Optimization Library modules, 10³¹ is used as an operational value for +infinity, and -10³¹ is used as an operational value for -infinity.
EKKDSCB cannot be used to describe a block of a network problem unless a column or index copy of the constraint matrix exists.

Examples

Refer to the following sample programs for examples of using EKKDSCB:

EKKRPTB - Repeat an Existing Matrix Block as a New Block in the Current Problem Matrix

This subroutine copies a specified matrix block into your matrix. If you are working on a model that requires a block that is similar to one you previously specified, you can copy it to the current model, even if the block you are copying is from a different model. After you copy the block, you can modify it to create the block you need.

Syntax

FORTRAN	CALL .br EKKRPTB(rtcod,dspace,modelin,blockin, blockout, rbas, cbas, copy)
C	ekkrptb (&rtcod, dspace, modelin, blockin, blockout, rbas, cbas, copy);

On Entry

dspace: is the user-provided work area.
modelin: is the number of the model that contains the block to be repeated.

blockin: is the number of the block in model modelin to be repeated.

blockout: is the number of the block to create in the current model that will hold the repeated block.

rbas: is the number of rows down to place the new block (that is, the offset). A value of 0 indicates that the new block is to be put in the first row.
cbas: is the number of columns over to place the new block (that is, the offset). A value of 0 indicates that the new block is to be put in the first column.
copy: specifies whether the actual block data should be copied, where:

On Return

rtcod: is the return code for the subroutine, where:
dspace: is the user-provided work area.

Notes

If you need to limit your use of dspace and you do not need the data for a block, specify copy=0.
Any changes to a block that is copied into other models by the use of pointers (that is, copy=0) will affect all copies of the block. Any changes to a block that is directly copied into other models (that is, copy=1) will affect only that block.

Example

Refer to "Sample FORTRAN Program EXRPTB" for an example of using EKKRPTB.

EKKLMDL - Specify the Linear Part of a Model

This subroutine specifies the linear part of a model. It creates the necessary data structures in dspace. See "Passing Your Model Using Library Data Structures" for additional information on its use.

Syntax

FORTRAN	CALL EKKLMDL(rtcod,dspace,type,nr,nc,nel,dobj,drlo,drup, dclo, dcup, mrow, mcol, dels)
C	ekklmdl(&rtcod,dspace,type,nr,nc,nel,dobj,drlo,drup, dclo, dcup, mrow, mcol, dels);

On Entry

dspace: is the user-provided work area.
type: is the format the matrix is stored in, where:
nr: is the number of rows.
nc: is the number of columns.
nel: is the number of nonzero elements.
dobj: the coefficients of the objective function.
drlo: is the lower bounds on the rows.
drup: is the upper bounds on the rows.
dclo: is the lower bounds on the columns.
dcup: is the upper bounds on the columns.
mrow
mcol
dels: is the elements of the matrix.

On Return

rtcod: is the return code for the subroutine, where:
dspace: is the user-provided work area.

Notes

The basis is set to all logical variables if a basis does not already exist.
If you want to use EKKxGET and EKKxSET to set any control variables before the call to EKKLMDL, EKKMPS, EKKNMDL, or EKKSMDL, you must call EKKDSCM before the call to EKKxGET and EKKxSET. This is especially true if you are setting Imaxrows and Imaxcols.
EKKLMDL accepts and maintains any zero coefficients that are in the dels array. A warning message is issued to indicate the number of zero coefficients that were passed to EKKLMDL.
If you are storing your matrix by indices, a nonpositive value in the mrow or mcol arrays will end processing of the matrix coefficients. An informational message will be issued indicating the difference between the number of elements that were read and nel. If this is not what you expected, check your specification of the mrow or mcol arrays.
If you do not want to enter the elements of your matrix when you call EKKLMDL, set nel to zero. You may then enter the elements of your matrix using EKKDSCB or EKKRPTB. See "Sample FORTRAN Program EXDSCB" for an example of how to do this.
10³¹ is used as an operational value for +infinity, and -10³¹ is used as an operational value for -infinity.
If Imaxrows and Imaxcols are positive, they have their usual meanings. If they are negative, they act as increments, that is, Imaxrows will be set to Inumrows + '('-Imaxrows ')'. This is useful if you want to have spare rows.

Examples

Refer to the following sample programs for examples of using EKKLMDL:

EKKIMDL - Specify the Integer Parts of a Model

This subroutine gives you flexibility in defining the integer parts of a mixed-integer programming problem. Previously, your only choice was to use MPS format (EKKMPS) to define such a problem. Now, if you want to use another format, first use EKKLMDL or EKKMPS to specify the linear problem, and then use EKKIMDL to describe the integer information.

Syntax

FORTRAN	CALL EKKIMDL(rtcod,dspace,nints,intnums,nsets,type, priority, ntotinfo, setindx, sets, dnpcost, uppcost)
C	ekkimdl(&rtcod,dspace,nints,intnums,nsets,type, priority, ntotinfo, setindx, sets, dnpcost, uppcost);

On Entry

dspace: is the user-provided work area.
nints: is the number of integer variables. If nints = 0, then all variables will be identified as integer variables; some may be general integer variables and some may be 0-1 integer variables, depending on their upper and lower bounds.
intnums: is the variable numbers of the integer variables.
nsets: is the number of sets of integer variables. If nsets=0, all integer variables are regular and put in one set.
type: is the type of each set, where:
priority: is the priority of each set. If the ith entry of priority = 0, then all sets numbered i or greater get a default priority of 1000.
ntotinfo: is the sum of the sizes of all the sets, plus the number of integer variables not in sets. (Thus, if a variable is a member of more than one set, it should be counted for each occurrence.)
setindx: is the array of starting points of the variable numbers of each set in the sets array. This is explained more fully in the discussion of the sets parameter, which follows.
sets: the variable numbers of the variables in sets. The variable numbers of the members of a particular set appear in adjacent entries of the sets array. The variable numbers are addressed indirectly, by means of the setindx array. The ith entry of the setindx array is the sequence number (i.e. FORTRAN index) in the sets array of the variable number of the first member of the ith set. The variable number of the last member of the ith set is the (p-1)th entry of the sets array where p is the (i+1)th entry of the setindx array.
dnpcost: is the "down pseudocost" of each variable in a set. If ith entry of dnpcost = 0, then all variables numbered i or greater in the set get a default down pseudocost of 0.001.
uppcost

On Return

rtcod: is the return code for the subroutine, where:
dspace: is the user-provided work area.

Notes

To add integer variables, or to change continuous variables to integer variables, you need to reserve space for "spares," using the Imaxints control variable, before any calls to EKKMPS, EKKIMDL, EKKLMDL, or EKKSMDL. If you do this before calling EKKMPS, EKKIMDL, or EKKSMDL, a negative value for Imaxints indicates that space for (-Imaxints) extra integer variables will be allocated. Also, if you want to set Imaxints before calling EKKMPS, EKKIMDL, EKKLMDL, or EKKSMDL, you must call EKKDSCM before calling EKKIGET or EKKISET.
The integer parts of a spreadsheet mixed-integer programming problem can be defined by EKKSMDL. For more information, see "Passing Your Model Using Spreadsheet Format".
If any variables are not put in a set (that is, they appear in nints but not in sets), they are placed in a set of their own at the end of EKKIMDL processing. A warning message is issued when this happens. This set has a priority of 1000, and the pseudocosts are set to 0.001.
If multiple calls are made to EKKIMDL, each new call overwrites the previous one. That is, the earlier calls no longer apply. Note that if the integer control variable Imaxints was not set before the first call to EKKIMDL, then Imaxints will be set to nints by the first call and it cannot be changed.
10³¹ is used as an operational value for +infinity, and -10³¹ is used as an operational value for -infinity. However, you should not use 10³¹ as a large upper bound for a general integer variable whose lower bound is 0. If a variable is identified in the call to EKKIMDL as an integer variable, its lower bound is 0, and its upper bound is 10³¹, then EKKIMDL will reset the upper bound to 1, thus specifying that the variable is a 0-1 integer variable.
To formulate special ordered sets using EKKIMDL, convexity constraints often must be added to your formulation. For example, to define an SOS of type 3 in which exactly one member must have the value 1 and all other members must have the value 0, the following constraint should be added:

x1+x2+x3+...+xn=1

x1...xn

If the integer control variable Imaxints has been set to a positive number before the call to EKKIMDL, then nints must satisfy 0 <= nints <= Imaxints, and the restriction that the number of integer variables cannot exceed the value of Imaxints will be imposed, even if nints = 0. If the integer control variable Imaxints has not been set before the call to EKKIMDL, then EKKIMDL will set the value of Imaxints to the number of integer variables in the problem (as determined by the value of nints). If the integer control variable Imaxints has been set to a negative number before the call to EKKIMDL, then EKKIMDL will reset the value of Imaxints to the number of integer variables in the problem plus the negative of the previous value of Imaxints.

Examples

Refer to the following sample programs for examples of using EKKIMDL:

EKKNMDL - Specify a Network Model

This subroutine specifies a pure network model allowing you to enter the problem in a more concise format that the EKKMPS format, it also saves storage, and improves performance. You can also use EKKMPS, EKKLMDL, or EKKSMDL to load a network problem, if you prefer.

See "Passing Your Model Using Library Data Structures" for information on using EKKNMDL.

Syntax

FORTRAN	CALL EKKNMDL(rtcod,dspace,type, action, narc, nnode, from, to, cost, alo, aup, nlo, nup, res1, res2)
C	ekknmdl(&rtcod,dspace,type, action, narc, nnode, from, to, cost, alo, aup, nlo, nup, res1, res2);

On Entry

dspace: is the user-provided work area.
type: is the type of problem to solve, where:
action: is the action to be taken, where
narc: the number of arcs.
nnode: the number of nodes.
from: the array of "from" nodes.
to: the array of "to" nodes.
cost: the array of costs.
alo: an array of lower bounds on arc flows.
aup: an array of upper bounds on arc flows.
nlo: the array of lower bounds on node exogenous flows.
nup: the array of upper bounds on node exogenous flows.
res1: a reserved variable.
res2: a reserved variable.

On Return

rtcod: is the return code for the subroutine, where:
dspace: is the user-provided work area.

Notes

For network flow problems, columns represent arcs and rows represent nodes.
Option action=3 is provided for applications that do not require a factorized basis (that is, applications that involve a call to EKKSSLV, EKKQSLV, EKKSPAR, EKKSBND, or EKKSOBJ). If action=3, the constraint matrix is not created. This reduces use of dspace.
10³¹ is used as an operational value for +infinity, and -10³¹ is used as an operational value for -infinity.

Example

Refer to "Sample FORTRAN Program EXNMDL" for an example of using EKKNMDL.

EKKQMDL - Specify the Quadratic Parts of a Model

This subroutine specifies a quadratic matrix for a quadratic programming model. It creates data structures in dspace. See "Passing Your Model Using Library Data Structures" for more information on its use. EKKLMDL or EKKMPS must be called before you call EKKQMDL.

Syntax

FORTRAN	CALL EKKQMDL(rtcod,dspace,type, nelq, rowq, colq, delsq)
C	ekkqmdl(&rtcod,dspace,type, nelq, rowq, colq, delsq);

On Entry

dspace: is the user-provided work area.
type: is the storage format of the matrix, where:
nelq: is the number of nonzero elements in the quadratic matrix.

rowq
colq
delsq: is the elements of the matrix.

On Return

rtcod: is the return code for the subroutine, where:
dspace: is the user-provided work area.

Notes

EKKDSCM must be called with a minimum of five blocks for each quadratic programming model.
The quadratic parts of a spreadsheet quadratic programming problem can be defined by EKKSMDL. For more information, see "Passing Your Model Using Spreadsheet Format".
The quadratic matrix should be positive semidefinite. If it is not, the quadratic programming algorithm may find a local minimum instead of a global one, or it may fail altogether.
EKKQMDL resets the basis to a null basis. If you want to use EKKSSLV to solve the linear part of your quadratic programming problem and then use EKKQSLV to proceed with that basis, call EKKQMDL before calling EKKSSLV.

Similarly, you may want to have EKKQSLV solve your quadratic programming problem, then create a new quadratic matrix using EKKQMDL, and then proceed using the optimal basis from the first call to EKKQSLV. To do this, you must save and restore this basis by using EKKBASO and EKKBASI or by saving the status vectors and solution vectors using EKKNGET index control variables Nrowstat, Ncolstat, Nrowacts, and Ncolsol.

10³¹ is used as an operational value for ++infinity, and -10³¹ is used as an operational value for -infinity.

Examples

Refer to the following sample programs for examples of using EKKQMDL:

EKKPMDL - Specify a Parametric Model

This subroutine initializes five arrays that are used by the EKKSPAR subroutine to solve an LP parametric problem. EKKPMDL puts the arrays in dspace. See "Using LP Sensitivity Analysis and LP Parametrics" for more information on its use.

Syntax

FORTRAN	CALL EKKPMDL(rtcod,dspace,cdelta, lrdelta, urdelta, lcdelta, ucdelta, mask)
C	ekkpmdl(&rtcod,dspace,cdelta, lrdelta, urdelta, lcdelta, ucdelta, mask);

On Entry

dspace: is the user-provided work area.
cdelta: is the vector to be added to the objective function coefficients.
lrdelta: is the vector to be added to the lower bounds for rows.
urdelta: is the vector to be added to the upper bounds for rows.
lcdelta: is the vector to be added to the lower bounds for columns.
ucdelta: is the vector to add to the upper bounds for columns.
mask: is a bit mask to identify which of the above vectors are applicable, where:

On Return

rtcod: is the return code for the subroutine, where:
dspace: is the user-provided work area.

Notes

You must use one of four subroutines--EKKMPS, EKKLMDL, EKKNMDL, or EKKSMDL--to enter the LP model before you call EKKPMDL to build the arrays for a simplex parametric problem.
After your program calls EKKPMDL, the index control variables Nsparcost, Nsparrlo, Nsparrup, Nsparclo, and Nsparcup are set if mask has been set to indicate they were applicable.
If mask is set to ignore some vectors, those arrays in the calling sequence do not have to be of full length.
The arrays created by EKKPMDL in dspace are of the length specified by Imaxrows or Imaxcols, depending on whether they are row or column arrays. This means that if Inumrows is less than Imaxrows, or if Inumcols is less than Imaxcols, entries are reserved in the arrays to allow the addition of rows and columns up to the maximum.

Example

Refer to "Sample FORTRAN Program EXPARA2" for an example of using EKKPMDL.

EKKSMDL - Specify a Model in Spreadsheet Format

This subroutine specifies a file in spreadsheet format from a file created by a spreadsheet program, such as Lotus 1-2-3. For information on using Lotus 1-2-3 Version 3.0 in formulating linear, quadratic, and mixed-integer programming problems, see "Passing Your Model Using Spreadsheet Format".

Syntax

FORTRAN	CALL EKKSMDL(rtcod,dspace,unit, action, type, res)
C	ekksmdl(&rtcod,dspace,unit, action, type, res);

On Entry

dspace: is the user-provided work area.
unit: is the unit number specifying where the input is read or the output is updated.
action: is the action to be taken, where:
type: is the type of spreadsheet, where:
res: is a reserved variable.

On Return

rtcod: is the return code for the subroutine, where:
dspace: is the user-provided work area.

Notes

Only nonempty, unprotected cells in the solution range(s) are updated.
To use EKKSMDL, the location in the spreadsheet of certain sets of cells--the adjustable cells, the constraint cells, and the objective cell--must be specified. Typically, these locations are specified by making assignments to the character control variables Cssolution, Csconstrts, and Csobjective. For more information, see "Passing Your Model Using Spreadsheet Format".
If an application that solves multiple optimization problems has multiple calls to EKKSMDL, it should include an assignment to Imaxrows and Imaxcols before the first call to EKKSMDL. This assignment saves extra space for columns and constraint rows. EKKSMDL includes a call to EKKLMDL, so the usage notes for EKKLMDL apply to EKKSMDL. See "EKKLMDL - Specify the Linear Part of a Model".
If an application program that solves multiple mixed-integer programming problems has multiple calls to EKKSMDL and EKKMSLV, it should include an assignment to Imaxints before the first call to EKKSMDL. This assignment saves extra space for integer variables. EKKSMDL includes a call to EKKIMDL if the model contains integer variables; so the usage notes for EKKIMDL apply to EKKSMDL. See "EKKIMDL - Specify the Integer Parts of a Model".
EKKSMDL includes a call to EKKQMDL if the model contains quadratic data; so the usage notes for EKKQMDL also apply to EKKSMDL. See "EKKQMDL - Specify the Quadratic Parts of a Model".
Many spreadsheet programs other than Lotus 1-2-3 provide a facility for producing Lotus 1-2-3 worksheet files. For information about whether your spreadsheet program can create a Lotus 1-2-3 work file, see your spreadsheet documentation.
Most spreadsheet files can be transferred between systems. See the Lotus 1-2-3 documentation for restrictions.
EKKSMDL includes a call to EKKLMDL if linear constraints are found in the worksheet file. The call to EKKLMDL is followed by a call to EKKNAME for the creation of row and column names. Control variables that apply to EKKNAME also apply to EKKSMDL.
Integer control variable Ismdltypemask will be set to indicate the type of model read in by EKKSMDL.
In library routines, 10³¹ is used as an operational value for +infinity, and -10³¹ is used as an operational value for -infinity.
If you are using MVS, the 1-2-3 worksheet file must be a contiguous file. This can be ensured by coding the space parameter as follows when creating the file:

SPACE=(TRK,(nnn),,CONTIG)

nnn

Since the library modules are written in C, a FORTRAN open statement can not be used to associate a named file with a unit to be supplied to any of the library I/O modules. The library routine EKKFOPN (which see at "EKKFOPN - Open and Connect Files to FORTRAN I/O Units") is provided to mimic the FORTRAN open statement without using the FORTRAN operating environment. Similarly, one can not use a FORTRAN close statement to dissociate a named file from the unit supplied to a library module, nor a FORTRAN rewind statement to reinitialize reading from a named file associated with a unit that has been supplied to a library module. EKKFCLS ("EKKFCLS - Close and Disconnect FORTRAN I/O Units") and EKKREW ("EKKFREW - Rewind Files Associated with FORTRAN I/O Unit numbers") have been provided for these purposes.

Example

Refer to "Sample FORTRAN Program EXSMDL" for an example of using EKKSMDL.

Syntax

FORTRAN	CALL EKKEMDL(rtcod,dspace,nrow,ncol,nels);
C	ekkemdl(&rtcod,dspace,nrow,ncol,nels);

On Entry

dspace: is the user-provided work area.
nrow: is the number of rows to be provided for in the empty model.; is the number of columns to be provided for in the empty model.; is the number of nonzero elements to be provided for in the empty model.

On Return

rtcod: is the return code for the subroutine, where:
dspace: is the user-provided work area.

Notes

Sometimes it is desired to create a model without necessarily having to populate it initially. This routine makes this possible.

[ Index to Modules ]