Usage: oslstslv ["?"] [-keyword=value] [...] [@keyword_file] keyword_file: Name of file containing "-keyword=value" strings. Each "-keyword=value" string in this file must be on a separate line. Example : oslstslv -maxmin=max -presolve=no @optionf.001 -input=test01 -inputformat=spl The file "optionf.001" may contain additional options such as: -input=app0110 -inputformat=mps -scale=no -crash=yes -masteriter=20 ============================================================================= Valid keywords are: maxmin=min|max - default: min inputformat=mps|spl - default: none - a format type must be specified input=filename - default: none - a file name must be specified output=listing_file - default: standard output solve=yes|no - default: no alg=primal|dual|osl - default: primal presolve=yes|no - default: yes presolvetype=0|1|2|3 - default: 3 scale=yes|no - default: no crash=yes|no - default: yes decompose=yes|no - default: no samples=value - default: 0 masteriter=value - default: 1 cutperiod=value - default: 2 subproblems=value - default: 10 warnlevel=value - default: 100 largebounds=yes|no - default: no modelout=filename - default: none print=distn|stage - default: distn stage=value - default: 1 scenario=value - default: 1 roworcol=row|col - default: col ----------------------------------------------------------------------------- maxmin : Solve as a maximization or minimization problem. inputformat : Format of file containing input stochastic data = mps : MPS format = spl : Optimization Library internal format input : Name(s) of file(s) containing input data if inputformat = mps, there are 3 input files: <filename>.core <filename>.time, and <filename>.stoch if inputformat = spl, there is 1 input file: <filename>.spl output : Name of file to receive OSL messages. solve : Whether or not to solve the problem. alg : Simplex algorithm to be used. = primal : primal algorithm = dual : dual algorithm = osl : algorithm to be selected by OSL presolve : Use EKKPRSL function to pre-solve problem. presolvetype : Type of reduction to be performed by EKKPRSL. = 0 : the redundant rows are eliminated, the variables summing to zero are fixed. = 1 : type 0 reductions are done and the doubleton rows are eliminated. = 2 : type 0 reductions are done and variable substitutions performed. = 3 : all of type 0, 1, and 2 reductions are performed. scale : Use EKKSCAL function to scale the coefficient matrix. crash : Use EKKCRSH function to create a starting basis. decompose : Use EKKLPDC function to create a starting basis. samples : Maximum number of scenarios to be formed. = 0 : Explode the tree > 0 : Number of scenarios to be generated masteriter : The maximum number of Master iterations that OSL will perform. cutperiod : Period at which Benders' cuts are made. subproblems : The maximum number of Benders' subproblems. warnlevel : Number of scenarios beyond which the user is to be warned. largebounds : Use large bounds to avoid unboundedness. modelout : Name of file to store SP/OSL model. print : Type of solution to be generated. = stage : the stage solution = distn : the scenario distribution of objective values stage : Number of the stage for which solution is to be generated. scenario : Number of the scenario for which solution is to be generated. roworcol : Row or column activities to be generated. =============================================================================
typedef struct {
long nrow; /* number of rows */
long ncol; /* number of columns */
long nels; /* number of matrix elements */
long nstg; /* number of stages */
long nblocks; /* number of blocks in matrix */
double *drlo,*drup; /* row bounds */
double *dclo,*dcup; /* column bounds */
double *dobj; /* objective */
long *mrow; /* matrix row indices */
long *mcol; /* matrix column indices */
double *dels; /* matrix elements */
long *rowstart; /* starts for stage partition of rows */
long *colstart; /* starts for stage partition of cols */
long *elemstart; /* starts for stage partition of matrix
Matrix is partitioned by row blocks
and then by column blocks
thus t*(t+1)/2-1 is the matrix index for
the start of the t-th stage node block
(as would be obtained by numbering blocks
starting from the top and moving left to
right). The matrix is assumed full lower
block triangular. */
long *sortin2exr; /* in-to-external row index translation */
long *sortin2exc; /* in-to-external col index translation */
} usrCoreData;
The three arrays rowstart, colstart and elemstart
identify the starting indices for each time stage in the list of row, column,
and matrix entry indices respectively. Index numbering for matrix elements
always begins from one (for compatibility with IBM Optimization Library).
For example, if then the row indices 1,2,3,4 are first stage rows, and 5,6,7,8,9,10 are second stage rows. The first four entries in the row bounds arrays drlo and drup are the bounds for the first stage rows, and the second six entries are the second stage row bounds. Of course, the ordering here may not correspond to the user's original ordering in the calling sequence for the ekks_CreateCore subroutine that created the core data structure. The array sortin2exr provides the original row indices. Thus, the first element of sortin2exr gives the original index for the first row, etc. Similar comments hold for the column arrays colstart and sortin2exc.
The elemstart array has a more complex structure. The core matrix is sorted first into row blocks, within which each row belongs to the same stage, and then each row block sorted into column blocks, within which each column belongs to the same stage. For example, if the problem has 4 stages, then this method sorts the matrix into lower block triangular form with up to ten blocks in the following order: In this case the elemstart array has 11 entries. For example, if then the diagonal block 6 has 9 entries starting at the 26th entry of the matrix triple (mrow, mcol, dels), and the off-diagonal blocks 4, 7 and 8 have no entries at all. The matrix triple is stored "by indices," and thus the 26th entry has value dels[25] (using the indexing convention of the C programming language) row index mrow[25] and column index mcol[25].
typedef struct {
long nnode; /* number of nodes */
usrNode *node; /* array of node structures */
long nleaf; /* number of leaves */
long *leaf; /* list of leaf positions in node array (beg=1) */
void *user; /* (optional) pointer to user structure */
} usrStoch;
The nodes are described by an array of Node structures. The leaves
of the tree are identified by the leaf array. For example, if
one has then there are three scenarios in the model and the terminal nodes
of the scenarios are described by the 4th, 8th, and 9th entries in the
node
array. A pointer is provided to point to a user structure, if needed (this
information is for the user's purposes only; at this time it cannot be
stored or retrieved).
typedef struct {
double prob; /* probability of node in model */
long orig; /* original node name (numbered from 1) */
long par; /* parent's position in list (beg=1) */
long child; /* next-stage child (end=0) */
long sib_cous; /* same-stage sibling or cousin (end=0) */
long stag; /* original time stage */
long scen; /* original scenario number */
long rbas; /* row offset in matrix */
long cbas; /* column offset in matrix */
long nrow; /* number of rows */
long ncol; /* number of columns */
long virtual; /* = 1 if node not actually in model */
void *user; /* (optional) pointer to user structure */
} usrNode;
A node points to all information and data corresponding to a given time
stage along a given scenario. The prob field contains the node's
probability in the stochastic model. This probability multiplies the node's
objective in the stochastic model. The orig field identifies the
node's original numbering in the Stoch_Data structure, and must
be used when accessing the LP data for the node.
The next three fields allow the user to move around the tree. The numbers refer to the ordering in the node array of the Stoch structure. The par field identifies the node's parent, that is, the node from which it branched in the stage immediately preceding. If the node happens to be a root, then its par field is set equal to zero. The child field identifies one of the children of the node. If there are no children (i.e. this is a leaf node) the field is set to zero. The sib_cous field identifies one sibling (that is, sharing a common parent) or cousin (merely share the same time stage). The sib_cous fields of nodes sharing a common time stage are arranged in a ring. All children of a node node can be found by following the sib_cous fields of the child, checking to see that they all share the same parent. All nodes of a given stage can be found by following the sib_cous fields around until the starting point is reached again.
The stag field identifies the node's stage and the scen field the original scenario number. The two fields rbas and cbas are the row and column bases that give the node's offset in the (deterministic equivalent) stochastic model. Finally, the virtual field identifies whether the node was (=0) or was not (=1) included in the nodelist which generated the stochastic model. Nodes whose descendents are in a model but that do not themselves appear in the nodelist generating the model need to be identified as such when constructing the LP for the stochastic model, so that offsets may be allocated for the virtual node columns. A pointer is provided to point to a user structure, if needed (this information is for the user's purposes only; at this time it cannot be stored or retrieved).
typedef struct {
long stg; /* stage of node ( = number of partitions) */
long nrow; /* number of rows */
long ncol; /* number of columns */
long nels; /* number of node block elements */
double *drlo,*drup; /* row bounds */
double *dclo,*dcup; /* column bounds */
double *dobj; /* objective */
long *mrow; /* block row indices */
long *mcol; /* block column indices */
double *dels; /* block elements */
long *elemstart; /* starts for stage partition of node block:
thus t-1 is the index for the start of the
t-th stage arc block and stg-1 is the
index for the start of the node block.
The node block has (poss. empty) arc
blocks for all stages t < istg. */
} usrNodeData;
This data must be combined with the core data to construct the actual node
LP data. The convention in IBM Stochastic Solution is to add the
core and stochastic data.
When a user accesses node data, the incoming arc matrices are copied over in the same subroutine call. This should be taken into consideration when transferring large amounts of data from the SP-file into memory.
The matrix associated with a node is the stochastic row-block; that is, all the stochastic row data in the given time stage in the given scenario are found in this matrix. Of course, there may not be any elements in the stochastic row-block. The matrix is structured in similar fashion as that of the matrix in the CoreData stucture, that is, it has been sorted into column blocks, by stage. The column indices in each of the column-blocks have been normalized to begin with index 1. The actual column index of an off-diagonal block is found by locating the node's ancestor for that stage and adding the ancestor's column offset cbas to the matrix column index. The actual column index of the diagonal block is found by adding the current node's column offset cbas to the column index. The actual row index of all entries is found by adding the current node's row offset rbas.
extern int ekks_InitializeOSL(); extern int ekks_Initialize(); /* * Both initialize data structures. * * Returns: * integer return code **********************************************************************/
extern void ekks_AddEvent( long *rc, Stoch_Data *stoch, Tree **treep, long *index, double dp, long replace ); /* * ekks_AddEvent. * * Takes an event for a INDEP_DISCRETE distribution and adds it * as a scenario. ** * * Input: * Stoch_Data *sdata -- pointer to a Stoch_Data structure. * Tree **treep -- address of pointer to event tree under * construction (pointer must be NULL for first call) * long *index -- event indices. * double dp -- probability * long replace -- (0,1) means (add to, replace) core values * * Returns: * long *rc -- return code (2 is fatal) **********************************************************************/
extern void ekks_AddScenario( long *rc, Stoch_Data *stoch, long nscn, long ianc, long istg, double dprob, long itype, long nrow,long ncol,long nels, double *dobj, double *drlo, double *drup, double *dclo, double *dcup, long *mrow, long *mcol, double *dels, long replace ); /* * ekks_AddScenario. * * Adds a scenario to stochastic problem, sets the scenario * probability, the branching information, and stores the scenario data * by node in an SP-file. ** * Errors occur when branching information is inconsistent * or when dimensions are inconsistent with the core. * * If this call is repeated for the same scenario, the scenario * probability is incremented by the amount of the new probability. * No other data is changed. * * All scenario LP data is ADDED to the corresponding core data when * forming an LP. This requires a convention for dealing with infinite * bounds in the core. If the core value is infinite and the incoming * scenario value is nonzero, then a warning message is issued and the * incoming scenario value is set to zero. * * CORE VALUE SCENARIO VALUE ACTION MESSAGE RC * * finite infinite none none 0 * infinite nonzero scen value zeroed warning 1 * * The LP data is NOT kept in core memory. (It may be retrieved for * the user by a call to ekks_GetNodeData.) The LP matrix must be in * "indices" sparse format. * * If replace = 0: * * LP data should be the "difference" of the intended scenario LP data * with the core LP data. * * If replace = 1: * * Scenario LP data should "replace" the core LP data. In this case, * the subroutine calculates the difference for you. * * * Input: * Stoch_Data *stoch - pointer initialized by * ekks_InitializeApplication * long nscn - scenario number (1,2,...) * long ianc - ancestor scenario number * long istg - branching stage number * double dprob - probability of scenario * long itype - matrix type (MUST be 1 - by indices format) * long nrow - number of rows (must match core model) * long ncol - number of columns (must match core model) * long nels - number of elements in scenario matrix * double *dobj - array of objective entries * double *drlo - array of row lower bound entries * double *drup - array of row upper bound entries * double *dclo - array of column lower bound entries * double *drup - array of column upper bound entries * long *mrow - array of matrix row indices * long *mcol - array of matrix column indices * double *dels - array of matrix entries * long replace - (0,1) means (add to, replace) core values * * Output: * long *rc - return code (2 is fatal) * * Returns: * void * **********************************************************************/
extern void ekks_BendersLSolve( long *rc, Stoch_Model *omodel, long ipcut, long maxmod, long maxits, double rmaxmin, long inwmt, long icrsh, long ilpdc, long iscal, long iprsl, long iprsltype, long iprslunit, long isalg, long largebounds, long *optimal, double *optgap ); /* * ekks_BendersLSolve. * * Applies Benders/L-shaped decomposition to the stochastic model, * with cut made at the stage number IPCUT. ** * * Methodology: * * A single master problem is created and up to MAXMOD subproblems * corresponding to a cut made at stage IPCUT; that is, the master * problem contains all rows and columns for stages prior to IPCUT. * These problems are created in the same DSPACE as oModel. If MAXMOD * is not sufficient to hold all the subproblems, the subproblems are * distributed as evenly as possible among MAXMOD models. * * The program performs MAXITS iterations of Benders decomposition, * terminating if optimality, infeasibility, or unboundedness is * detected. * * At termination, the master and subproblem solution data is * transferred to the OSL model for oModel as appropriate, and the * local structures are freed. * * EKKSSLV (IRET,ds,1,3) is the appropriate continuation. * * Input: * * Stoch_Model *oModel - stochastic model created by OSL. * long ipcut - period at which Benders cuts are made * long maxmod - maximum number of subproblems * long maxits - maximum number of Master iterations * double rmaxmin - direction of optimization - max (-1.0) or min (1.0) * long inwmt - EKKNWMT type (0 => none EKKNWMT) for all problems * long iscal - (0,1) means (don't, do) call EKKSCAL for each submodel * long icrsh - EKKCRSH type (0 => none) for first solution of submodels * long ilpdc - (0,1) means (don't, do) call EKKLPDC for each submodel * long iprsl - (0,1) means (don't, do) call EKKPRSL for each submodel * long iprsltype - type of presolve * long iprslunit - presolve unit * long isalg - EKKSSLV algorithm for first solution of submodels * long large_bounds - (0,1) means (don't, do) add large bounds to master * double *optgap - Benders terminates when gap is less than optgap * * Output: * * long *iret - return code >= 2 indicates fatal error. * long *status - (0,1,2,3) means (optimal,infeasible,unbounded,unfinished). * double *optgap - Optimality gap at termination * **********************************************************************/
extern void ekks_GetCoreData( long *rc, Stoch_Data *stoch, usrCoreData **pcore); /* * ekks_GetCoreData. * * Copy core data pointers into the usrCoreData structure. ** * If *pcore is NULL, then a new usrCoreData structure is malloc'ed * and the pointer returned. * * The data pointed to by usrCoreData pointers is stable. * (It is the original data as formed by ekks_CreateCore.) * * Input: * Stoch_Data *stoch - pointer initialized by ekks_InitializeApplication and ekks_CreateCore * * Output: * usrCoreData **pcore - address of pointer to type usrCoreData. * **********************************************************************/
extern void ekks_CreateCore( long *rc, Stoch_Data *stoch, long nstg, long *Rstag, long *Cstag, long irow, long icol, long iels, double *dobj, double *drlo, double *drup, double *dclo, double *dcup, long *mrow, long *mcol, double *dels, double *dqdg); /* * ekks_CreateCore. * * Sorts core model row and column indices by stages, groups * core model data into blocks corresponding to stages, and stores * all model information, sort keys, and grouped data into a * SPL file. ** * * The data is held in core, and may be accessed by a ekks_GetCoreData call. * * Input: * * Stoch_Data stoch - pointer initialized by ekks_InitializeApplication * long nstg - number of stages in the core model * long *Rstag - array of stage numbers for rows * long *Cstag - array of stage numbers for columns * long irow - number of rows in core model * long icol - number of columns in core model * long iels - number of matrix elements in core model * double *dobj - array of objective entries * double *drlo - array of row lower bound entries * double *drup - array of row upper bound entries * double *dclo - array of column lower bound entries * double *drup - array of column upper bound entries * long *mrow - array of matrix row indices * long *mcol - array of matrix column indices * double *dels - array of matrix entries * double *dqdg - array of quadratic matrix diagonal entries * * Output: * * long *rc - return code (2 is fatal). * * Returns: * void **********************************************************************/
extern void ekks_ChangeProbability( long *rc, Stoch_Data *stoch, double *usrProb ); /* ekks_ChangeProbability. * * Updates leaf node probabilities with new scenario probabilities. * * Note: The original scenario probabilities are unaffected. * These can be restored by a call to ekks_ChangeProbability with a NULL * usrProb parameter. * * Input: * Stoch_Data *stoch -- pointer initialized by ekks_InitializeApplication. * double *usrProb -- points to array of new probabilities. * * Returns: * long *rc -- return code (2 is fatal) ***********************************************************************/
extern void ekks_GetPointerToDistribution( long *rc, Stoch_Data *stoch, Independent **s_indep ); /* * ekks_GetPointerToDistribution. * * Mallocs an independent data structure and sets it to point to the * information collected in a ekks_ReadMPS reading of a INDEPENDENT/DISCRETE * format. ** * Input: * Stoch_Data *sdata -- pointer to a Stoch_Data structure. * long type -- type of distribution pointed to (at the moment * only INDEP_DISCRETE implented) * * Output: * usrIndep **s_indp -- pointer to a usrIndep structure. * * Returns: * long *rc -- return code (2 is fatal) **********************************************************************/
extern void ekks_DescribeModel( long *rc, Stoch_Data *stoch, long nnodes, long *usrndlist, Stoch_Model **smodel, long *nblocks, long calcprob ); /* * ekks_DescribeModel. * * Creates model node information structures and offsets from * user-supplied nodelist. ** * If nodelist is empty (nnodes=0) * then all nodes in the Stoch_Data structure are included. * * Node probabilities are inherited from StochData structure. * Zero probability nodes (and their incoming arcs) are removed. * * Virtual nodes (ancestors not in model one of whose children are) * are recorded and are offset by the total number of real node columns. * * If calcprob is set, the probabilities for each node are * recomputed and normalized so that the probability totals to one. * * No matrix data is passed. * The number of blocks to be passed is returned. * * Input: * Stoch_Data *stoch -- stochastic data * long nnodes -- number of nodes * long *usrndlist -- list of nodes to be included in model * long calcprob -- (0,1) means (don't, do) recompute * node probabilities. * * Output: * Stoch_Model **smodel -- pointer to new stochastic model * long *nblocks -- number of blocks in model * * Returns: * void * **********************************************************************/
extern void ekks_GetPointerToSolution( long *rc, Stoch *stoch, long *nmod, double **dsoln); /* * ekks_GetPointerToSolution. * * Gets a pointer to the solution region for the stochastic model nmod. ** * * Input: * Stoch *stoch -- Stoch_Model or Stoch_Data pointer to be deleted * long *nmod -- number of the model * * Output: * long *rc -- return code * double **dsoln -- pointer to the solutions region * * Returns: * void * **********************************************************************/
extern void ekks_GetSolution(long *rc, Stoch_Model *stoch,long s, long colrowtype, double *solution, long *indx); /* * ekks_GetSolution. * * Gets a solution for a scenario. ** * * Input: * Stoch_Model *stoch -- Stoch_Model or Stoch_Data pointer * long s -- Scenario whose solution is to be retreived * long colrowtype -- type of solution (columns/rows) to be retrieved * * Output: * long *rc -- return code * double *solution -- pointer to the solution * long *indx -- pointer to the indices * * Returns: * void * **********************************************************************/
extern void ekks_FreeStructure( Stoch *stoch); /* * ekks_FreeStructure. * * Free all data structures and temporary files. ** * If a Stoch_Model structure is passed, then only structures created * for this model are deleted. * * Input: * Stoch *stoch -- Stoch_Model or Stoch_Data pointer to be deleted * **********************************************************************/
extern void ekks_GetStochasticData( long *rc, Stoch_Data *stoch, const char *filename ); /* * ekks_GetStochasticData. * * Copies Stoch_Data structures from SPL file. ** * Input: * Stoch_Data *stoch -- stochastic data pointer initialized by ekks_InitializeApplication. * char *filename -- name of SPL file. * * Output: * long *rc -- return code (2 is fatal) * * Returns: * void * **********************************************************************/
extern void ekks_InitializeApplication( long *rc, Stoch_Data **stoch, long maxscn ); /* * ekks_InitializeApplication. * * Allocates pointers for stochastic data structures, * opens SPL file, returns Stoch_Data pointer. ** * Input: * long maxscn - maximum number of scenarios * * Output: * Stoch_Data **stochdata - pointer to stochastic data structure * long *rc - return code (2 is fatal) * * Returns: * void * **********************************************************************/
extern void ekks_GetNodeData( long *rc, Stoch_Data *stoch, long node, usrNodeData **punode ); /* * ekks_GetNodeData. * * Get stochastic node data into usrNodeData structure. ** * Allocates new usrNodeData structure. * Accesses stochastic matrix and costs/bounds data from SPL file * and places them in volatile working memory. Costs and bounds are * expanded to their dense form. usrNodeData pointers are appropriately * set. * * NB: ALL matrix and costs/bounds arrays are volatile! The next call * to an SP/OSL routine WILL OVERWRITE THEM! (To protect * yourself, copy them to a memory region that you maintain.) * * NB: The matrix and costs/bounds arrays contain only the stochastic * part of the data. They must be ADDED to the relevant core data. * * Bug: returns NULL pointers for root node (node=1) * * Input: * Stoch_Data *stoch -- stochastic data pointer initialized by ekks_InitializeApplication * long node -- node number to be accessed * * Output: * usrNodeData **punode -- pointer to usrNodeData * long *rc -- return code (2 is fatal) * * Returns: * void **********************************************************************/
extern void ekks_PutStochasticData( long *rc, Stoch *stoch, char *filename ); /* * ekks_PutStochasticData. * * Puts the Stoch_Data structure into an SPL file to be called "filename". ** * Opens the file as a buffered direct access file, writes the data and * then closes it. * * File may be read by a call to ekks_GetStochasticData(). * * Input: * Stoch_Data *sdata -- stochastic data pointer initialized by ekks_InitializeApplication. * char *filename -- name of SPL file. * * Output: * long iret -- return code (2 is fatal) * * Returns: * void **********************************************************************/
extern void ekks_GetScenarioTree( long *rc, Stoch *stoch, usrStoch **pstree ); /* * ekks_GetScenarioTree. * * Creates a user accessible stochastic structure. ** * The user needs to copy over the information * to preserve it beyond the next Stochastic Solution call. * * The input can be either a Stoch_Data structure or a Stoch_Model * structure, in which case information for only those nodes in the * model is compiled. * * Input: * Stoch *stoch -- pointer to a Stoch_Data or a Stoch_Model structure. * Output: * usrStoch **pstree -- pointer to a usrStoch structure. * NB: arrays pointed to by pstree are volatile! * * Returns: * long *rc -- return code (2 is fatal) **********************************************************************/
extern void ekks_ReadMPS( long *rc, Stoch_Data *stoch, long *smpstype, long *replace, char *corefile, char *timefile, char *stochfile ); /* * ekks_ReadMPS. * * Processes the Stochastic MPS files <app>.core, <app>.time and <app>.stoch, * creates scenario data and stores it in the StochData structure. ** * The value of replace is set to 0 if STOCH file contains 'ADD' at * position 40 in the first line. * * Input: * * Stoch_Data *sdata -- pointer to Stoch_Data structure processed by ekks_ReadMPS. * char *corefile -- pointer to the core MPS filename. * char *timefile -- pointer to the time MPS filename. * char *stochfile -- pointer to the stoch MPS filename. * * Output: * long *smpstype -- integer identifying type of SMPS distribution. * long *replace -- (0,1) means (add to, replace) core values * rc - return code (2 is fatal). * * Returns: * void **********************************************************************/
extern void ekks_ProblemType( long *iret, Stoch_Data *stoch, CoreType type ); /* * ekks_ProblemType: * * Sets type of core model. Valid arguments are * linear * quadratic * * Input: * CoreType type -- type of core model * Stoch_Data *stochdata -- pointer to stochastic data structure * * Output: * long *iret - return code (2 is fatal) * * Returns: * void * * **********************************************************************/
extern void ekks_InitializeTree (long *rc, Tree **tree, long *arr, long narr, long mxsmp, double dp ); /* * ekks_InitializeTree. * * Creates tree and initializes structures. * Creates first scenario from data values in arr[]. ** * Input: * arr[] - integer array of data values * narr - number of data values (stages) in arr[] * mxsmp - maximum number of samples to be stored * dp - probability of events * * Output: * *tree - pointer to tree structure * rc - return code 0 * * Returns: * return value = 1 **********************************************************************/
extern long ekks_AddToTree (long *rc, Tree *tree, long *arr, long narr, double dp); /* * ekks_AddToTree. * * Updates scenario tree with data values in arr[]. ** * If arr[] is already in tree, then it increments counters * and returns the original scenario number, * otherwise it creates new scenario from data values in arr[] * and returns the newly created scenario number. * * Input: * tree - pointer to tree initialize by ekks_InitializeTree. * arr[] - integer array of data values * narr - number of data values (stages) in arr[] * dp - probability of events * * Output: * rc - return codes: * 1 if maximum number of samples exceeded * 2 if tree not initialized or corrupted * * Returns: * scenario number as described above, **********************************************************************/
extern void ekks_GetScenarioFromTree(long *rc, Tree *tree, long nsmp, long *ianc, long *istg, double *wgt, long *nscn, long **arr); /* * ekks_GetScenarioFromTree. * * Finds scenario information for sample number nsmp. ** * NB: if branching stage, "istg", has value 1, this means * that the scenario branches from the root (ianc=0). * * Input: * tree - pointer to tree initialized by ekks_InitializeTree. * nsmp - sample number (first sample is 0, etc) * * Output: * ianc - ancestor scenario number. * istg - branching stage number * wgt - scenario weight * nscn - scenario number * arr - pointer to data array for scenario * rc - return codes: * 1 if maximum number of samples exceeded * 2 if tree not initialized or corrupted * **********************************************************************/
| EKK0402 | Informational. | Entering Stochastic Solutions function M01. |
|---|---|---|
| EKK0403 | Informational. | Core model has I01 rows, I02 columns, and I03 stages. |
| EKK0404 | Informational. | Scenario I01 Ancestor I02 Stage I03 Probability D01. |
| EKK0405 | Informational. | Declaring stochastic model in OSL. Number of rows I01, number of columns I02. |
| EKK0406 | Informational. | Total number of blocks declared to OSL is I01. |
| EKK0407 | Informational. | Total number of C01 is I01. |
| EKK0408 | Informational. | Constructing stochastic model from original node list. |
| EKK0409 | Informational. | Process time for C01 is D01 seconds. |
| EKK0410 | Informational. | Beginning C01. |
| EKK0411 | Informational. | C01 C02 I01 ... |
| EKK0412 | Informational. | C01 C02 ... |
| EKK0413 | Informational. | C01 D01 ... |
| EKK0414 | Informational. | Beginning first pass of Benders decomposition. |
| EKK0415 | Informational. | Subproblem I01 did not solve. Exiting. |
| EKK0416 | Informational. | Master infeasible. Terminating. |
| EKK0417 | Informational. | Master unbounded. Generating ray. |
| EKK0418 | Informational. | Estimated subproblem value at new master proposal is E0126. |
| EKK0419 | Informational. | Beginning cycle I01. |
| EKK0420 | Informational. | Solving subproblem I01. |
| EKK0421 | Informational. | Unboundedness detected in subproblem I01 in cycle I02. |
| EKK0422 | Informational. | Subproblem actual value at master proposal E0126. |
| EKK0423 | Informational. | Problem is unbounded. Terminating. |
| EKK0424 | Informational. | Optimality gap for current master proposal is E0114. |
| EKK0425 | Informational. | Relative optimality gap is E0114. |
| EKK0426 | Informational. | Optimal solution found to within relative optimality gap E0114. |
| EKK0427 | Informational. | No new cuts from subproblems. Terminating. |
| EKK0428 | Informational. | Maximum cycles exceeded. Terminating. |
| EKK0429 | Informational. | No quadratic terms found in model. Resetting type to linear. |
| EKK0430 | Informational. | Master problem value is E0126. |
| EKK3401 | Warning. | Scenario I01 has already been defined. Probability is changed to D01. |
| EKK3402 | Warning. | Scenarios that branch from the root have branching stage = 2. |
| EKK3403 | Warning. | Scenario I01 branches prior to ancestor's branch stage: true ancestor is I02. |
| EKK3404 | Warning. | Data for current model-block contains elements for earlier stages. |
| EKK3405 | Warning. | SPL file is already opened for this application. No action taken. |
| EKK3406 | Warning. | No filename supplied. Opening temporary SPL file in /tmp. |
| EKK3407 | Warning. | Core C01 value at index I01 is infinite. Nonzero value in scenario I02 ignored. |
| EKK3408 | Warning. | Node list is non-empty. Ignored. |
| EKK3409 | Warning. | I01 zero probability nodes have been removed from model node list. |
| EKK3410 | Warning. | No ENDATA card in C01 file. Ignored. |
| EKK3416 | Warning. | Warning! No scenario C01. |
| EKK3417 | Warning. | Warning! No stage C01. |
| EKK3418 | Warning. | Warning! No column C01. |
| EKK3419 | Warning. | Warning! No row C01. |
| EKK3420 | Warning. | Warning! Ignored LB of Col I01 Scn I02. |
| EKK3421 | Warning. | Warning! Ignored UB of Col I01 Scn I02. |
| EKK3422 | Warning. | Warning! Ignored UB of Row I01 Scn I02. |
| EKK3423 | Warning. | Warning! End of File. |
| EKK7401 | Error. | Malloc failed in subroutine M01. Check maximum memory allocation for user. |
| EKK7402 | Error. | Zero allocation attempted in subroutine M01. Check subroutine arguments. |
| EKK7403 | Error. | C01 structures not initialized or corrupted. This was detected in subroutine M01. |
| EKK7404 | Error. | Sort of C01 failed in subroutine M01. |
| EKK7405 | Error. | Error detected while trying to open SPL file C01 in subroutine M01. |
| EKK7406 | Error. | Error detected while trying to close SPL file C01 in subroutine M01. |
| EKK7407 | Error. | Attempt to reposition within SPL file C01 failed in subroutine M01. |
| EKK7408 | Error. | Error detected in subroutine M01 while writing to SPL file C01. |
| EKK7409 | Error. | Error detected in subroutine M01 while reading from SPL file C01. |
| EKK7410 | Error. | Invalid mode specified in subroutine M01 for opening SPL file C01. |
| EKK7411 | Error. | Invalid mode specified in subroutine M01 for closing SPL file C01. |
| EKK7412 | Error. | Unable to allocate file pointer for SPL file C01 in subroutine M01. |
| EKK7413 | Error. | Unable to allocate filename storage for SPL file C01 in subroutine M01. |
| EKK7414 | Error. | Invalid SPL file pointer specified in subroutine M01. |
| EKK7415 | Error. | Error detected in subroutine M01 while attaching SPL file C01. |
| EKK7416 | Error. | Error detected in subroutine M01 while detaching SPL file C01. |
| EKK7417 | Error. | Invalid virtual record specified in subroutine M01 for SPL file C01. |
| EKK7418 | Error. | Negative virtual record size specified in subroutine M01 for SPL file C01. |
| EKK7419 | Error. | Empty string specified for SPL filename in subroutine M01. |
| EKK7420 | Error. | Existing SPL file C01 opened in subroutine M01 is improperly initialized. |
| EKK7421 | Error. | Error detected in subroutine M01 while deleting SPL file C01. |
| EKK7422 | Error. | File-size discrepancy for SPL file C01 detected in subroutine M01. |
| EKK7423 | Error. | Unknown error code for SPL file access used in subroutine M01. |
| EKK7424 | Error. | Unable to initialize C01 for SPL file C02 in subroutine M01. |
| EKK7425 | Error. | Error detected while attempting to save SPL file with name C01. |
| EKK7426 | Error. | Number of C01 requested, I01 exceeds declared maximum I02. |
| EKK7427 | Error. | Branching stage out of bounds. |
| EKK7428 | Error. | Scenario has negative probability. |
| EKK7429 | Error. | Ancestor scenario I01 does not exist. |
| EKK7430 | Error. | Number of C01 in CORE model I01 does not match number I02 in scenario. |
| EKK7431 | Error. | Data for current model-block is not block lower-triangular. |
| EKK7432 | Error. | Total probability in model is zero. |
| EKK7433 | Error. | Node list is empty. Cannot construct model. |
| EKK7434 | Error. | Error creating hash tables for C01 names. |
| EKK7435 | Error. | Not enough space in dspace for C01 file processing. |
| EKK7436 | Error. | Index error in C01 file. |
| EKK7437 | Error. | Error reading C01 file. |
| EKK7438 | Error. | Distribution type not implemented. |
| EKK7439 | Error. | Premature EOF reached in C01 file. |
| EKK7440 | Error. | Expecting C01 card in C02 file. |
| EKK7441 | Error. | Too many elements in scenario I01. Consider revising CORE file, so that more of these elements appear there. |
| EKK7442 | Error. | Ranges not implemented in SMPS format. |
| EKK7443 | Error. | OSL not initialized or corrupted. This was detected in subroutine M01. |
| EKK7444 | Error. | Not enough space in OSL for matrix. Need at least I01 more doublewords. |
| EKK7445 | Error. | Duplicate root node dhiscovered in model node tree. |
| EKK7446 | Error. | Master status is confused. Exiting. |
| EKK7447 | Error. | Bad return code from OSL solving subproblem I01 in cycle I02. |
Stephen E. Wright (now at Miami University of Ohio) was co-developer of SP/OSL during his postdoc years 1991-3 and during a summer visit in 1994. The elegant SP-file object and the flexible and robust implementation of the parallel decomposition were entirely designed and written by him.
Robert Entriken (now a consultant with PG&E) wrote the first version of SP/OSL, a matrix generator, in early 1990. The important node/arc metaphor basic to SP/OSL data structures is due to him. Hercules Vladimirou (now at University of Cyprus) developed and tested an early parallel implementation of single-cut Benders during his postdoc in 1991-2. Chris Donohue (University of Michigan) developed the prototype tree-generation software during his stint as a summer student in 1992. Shabbir Ahmed (now at the University of Illinois, Urbana Champaign) prepared the section on examples in this documentation. Special acknowledgement also is due to Roger Wets, for inspiration, guidance and support during his frequent visits throughout the development period.
Two significant corporate consulting engagements played a major role in the development of SP/OSL.
In 1990, the Frank Russell Corporation asked IBM Research to assess the solvability of certain stochastic programs generated by an asset/liability management system. In response, Robert Entriken quickly built a matrix generator capable of translating SMPS format to OSL problem structures, and Alan King and Robert Entriken working together solved the problem during several overnight runs on an IBM mainframe computer.
In 1992, the Allstate Corporation's Palo Alto Research Center asked IBM to assist them in the development of a multiperiod asset allocation pilot for their property and casualty portfolio. This relationship spurred major development of SP/OSL both as a model generator and as a decomposition solver.
In the period 1993 to 1997, SP/OSL was distributed under special agreement with principal investigators at selected universities and corporate research centers for field testing.
[ Top of Page | Previous (Users Guide) | Next (Examples) | Roadmap ]