source: trunk/Cbc/src/Cbc_C_Interface.h @ 2457

Last change on this file since 2457 was 2457, checked in by unxusr, 2 years ago

updated doxygen documentation for C api

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 19.9 KB
Line 
1/* $Id: Cbc_C_Interface.h 2457 2018-12-30 18:35:23Z unxusr $ */
2/*
3  Copyright (C) 2004 International Business Machines Corporation and others.
4  All Rights Reserved.
5
6  This code is licensed under the terms of the Eclipse Public License (EPL).
7*/
8#ifndef CbcModelC_H
9#define CbcModelC_H
10
11/* include all defines and ugly stuff */
12#include "Coin_C_defines.h"
13#include <stddef.h>
14
15/*
16 * Original version contributed by Bob Entriken,
17 * significantly updated by Miles Lubin.
18 * 2018: several updates by Haroldo
19 */
20
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26/** Current version of Cbc */
27COINLIBAPI const char* COINLINKAGE Cbc_getVersion(void)
28;
29
30/** \name Problem creation and modification routines */
31//@{
32
33    /** @brief Creates an empty problem */
34    COINLIBAPI Cbc_Model * COINLINKAGE
35    Cbc_newModel(void)
36    ;
37
38    /** @brief Sets problem name.
39     *
40     * @param model problem object
41     * @param array string with problem name
42     **/
43    COINLIBAPI int COINLINKAGE
44    Cbc_setProblemName(Cbc_Model * model, const char *array)
45    ;
46
47    /** @brief Creates a new column
48     *
49     * Creates a new column (variable)
50     *
51     * @param model problem object
52     * @param name variable name
53     * @param lb column lower bound
54     * @param ub column upper bound
55     * @param obj objective function coefficient
56     * @param isInteger 1 if variable is integral, 0 otherwise
57     * @param nz number of rows (constraints) where this column appears, can be 0 if constraints will be added later
58     * @param rows index of rows where this column appears, NULL if rows will be added later
59     * @param coefs coefficients that this column appears in its rows, NULL if rows will be added later
60     ***/
61    COINLIBAPI void COINLINKAGE
62    Cbc_addCol( Cbc_Model *model, const char *name, double lb, 
63            double ub, double obj, char isInteger,
64            int nz, int *rows, double *coefs )
65    ;
66
67    /** @brief Adds a new row
68     *
69     *  Adds a new row (linear constraint) to the problem
70     *
71     *  @param model problem object
72     *  @param name constraint name
73     *  @param nz number of variables with non-zero coefficients in this row
74     *  @param cols index of variables that appear in this row
75     *  @param coefs cofficients that that variables appear
76     *  @param sense constraint sense: L if <=, G if >=, E if =, R if ranged and N if free
77     *  @param rhs right hand size
78     * */
79    COINLIBAPI void COINLINKAGE
80    Cbc_addRow( Cbc_Model *model, const char *name, int nz,
81            const int *cols, const double *coefs, char sense, double rhs )
82    ;
83 
84    /** @brief Add SOS constraints to the model using row-order matrix */
85    COINLIBAPI void  COINLINKAGE
86    Cbc_addSOS(Cbc_Model * model, int numRows, const int * rowStarts,
87               const int * colIndices, const double * weights, const int type)
88    ;
89 
90
91    /** Loads a problem (the constraints on the
92        rows are given by lower and upper bounds). If a pointer is NULL then the
93        following values are the default:
94        <ul>
95        <li> <code>colub</code>: all columns have upper bound infinity
96        <li> <code>collb</code>: all columns have lower bound 0
97        <li> <code>rowub</code>: all rows have upper bound infinity
98        <li> <code>rowlb</code>: all rows have lower bound -infinity
99        <li> <code>obj</code>: all variables have 0 objective coefficient
100        </ul>
101
102     The constraint matrix is
103     given in standard compressed sparse column (without gaps).
104     <ul>
105     <li> <code>start[i]</code> stores the starting index of the ith column
106     <li> <code>index[k]</code> stores the row index of the kth nonzero element
107     <li> <code>value[k]</code> stores the coefficient of the kth nonzero element
108     </ul>
109    */
110    COINLIBAPI void COINLINKAGE
111    Cbc_loadProblem (Cbc_Model * model,  const int numcols, const int numrows,
112                     const CoinBigIndex * start, const int* index,
113                     const double* value,
114                     const double* collb, const double* colub,
115                     const double* obj,
116                     const double* rowlb, const double* rowub)
117    ;
118
119    /** @brief Set the name of a column
120     *
121     * @param model problem object
122     * @param iColumn column index
123     * @param column name
124     **/
125    COINLIBAPI void COINLINKAGE
126    Cbc_setColName(Cbc_Model * model, int iColumn, const char * name)
127    ;
128
129    /** @brief Set the name of a row
130     *
131     * @param model problem object
132     * @param iRow row index
133     * @param name row name
134     **/
135    COINLIBAPI void COINLINKAGE
136    Cbc_setRowName(Cbc_Model * model, int iRow, const char * name)
137    ;
138
139   /** @brief Sets optimization direction
140    *
141    * @param model problem object
142    * @param sense: direction of optimization (1 - minimize, -1 - maximize, 0 - ignore)
143    **/
144    COINLIBAPI void COINLINKAGE
145    Cbc_setObjSense(Cbc_Model * model, double sense)
146    ;
147
148    /** @brief Set the lower bound of a single constraint
149     *
150     * @param model problem object
151     * @param index row index
152     * @param value new row lower bound
153     **/
154    COINLIBAPI void COINLINKAGE
155    Cbc_setRowLower(Cbc_Model * model, int index, double value)
156    ;
157
158    /** @brief  Set the upper bound of a single constraint
159     *
160     * @param model problem object
161     * @param index row index
162     * @param value new row upper bound
163     **/
164    COINLIBAPI void COINLINKAGE
165    Cbc_setRowUpper(Cbc_Model * model, int index, double value)
166    ;
167
168    /** @brief Set the objective coefficient of a single variable
169     *
170     * @param model problem object
171     * @param index variable index
172     * @param value new objective function coefficient for this variable
173     **/
174    COINLIBAPI void COINLINKAGE
175    Cbc_setObjCoeff(Cbc_Model * model, int index, double value)
176    ;
177
178    /** @brief Set the lower bound of a single variable
179     *
180     * @param model problem object
181     * @param index variable index
182     * @param value variable lower bound
183     **/
184    COINLIBAPI void COINLINKAGE
185    Cbc_setColLower(Cbc_Model * model, int index, double value)
186    ;
187
188    /** @brief Set the upper bound of a single variable
189     *
190     * @param model problem object
191     * @param index variable index
192     * @param value new variable upper bound
193     **/
194    COINLIBAPI void COINLINKAGE
195    Cbc_setColUpper(Cbc_Model * model, int index, double value)
196    ;
197   
198    /** @brief Set this variable to be continuous
199     *
200     * @param model problem object
201     * @param iColumn column index
202     **/
203    COINLIBAPI void COINLINKAGE
204    Cbc_setContinuous(Cbc_Model * model, int iColumn)
205    ;
206
207    /** @brief Set this variable to be integer
208     *
209     * @param model problem object
210     * @param iColumn column index
211     **/
212    COINLIBAPI void COINLINKAGE
213    Cbc_setInteger(Cbc_Model * model, int iColumn)
214    ;
215
216    /** @brief Cbc_Model destructor */
217    COINLIBAPI void COINLINKAGE
218    Cbc_deleteModel(Cbc_Model * model)
219    ;
220
221    //@}
222   
223    /** \name Routines to query problem contents
224    */
225    //@{
226
227 
228    /** @brief Queries problem name
229     *
230     * @param model problem object
231     * @param maxNumberCharacters space in string array
232     * @param array string where problem name will be saved
233     **/
234    COINLIBAPI void COINLINKAGE
235    Cbc_problemName(Cbc_Model * model, int maxNumberCharacters, char * array)
236    ;
237
238    /** @brief Number of nonzero elements in constraint matrix
239     *
240     * @param model problem object
241     * @return number of non-zero entries in constraint matrix
242     **/
243    COINLIBAPI int COINLINKAGE
244    Cbc_getNumElements(Cbc_Model * model)
245    ;
246
247    /** @brief Number of variables in the model
248     * @param model problem object
249     * @return number of columns (variables)
250     **/
251    COINLIBAPI int COINLINKAGE
252    Cbc_getNumCols(Cbc_Model * model)
253    ;
254
255    /** @brief Number of integer variables in the model
256     *
257     * @param model problem object
258     * @return number of integer variables in this model
259     **/
260    COINLIBAPI int COINLINKAGE
261    Cbc_getNumIntegers(Cbc_Model * model)
262    ;
263
264    /** Number of constraints in the model
265     * @param model problem object
266     * @return number of rows (constraints) in the model
267     **/
268    COINLIBAPI int COINLINKAGE
269    Cbc_getNumRows(Cbc_Model * model)
270    ;
271 
272    /** @brief Queries row name
273     *
274     * @param model problem object
275     * @param row index
276     * @param name string where row name will be stored
277     * @param string where row name will be stored
278     **/
279    COINLIBAPI void COINLINKAGE
280    Cbc_getRowName(Cbc_Model * model, int iRow, char * name, size_t maxLength)
281    ;
282
283    /** Queries column name
284     *
285     * @param model problem object
286     * @param iColumn column index
287     * @param name where name will be stored
288     * @param maxLength maximum length of name string
289     **/
290    COINLIBAPI void COINLINKAGE
291    Cbc_getColName(Cbc_Model * model, int iColumn, char * name, size_t maxLength)
292    ;
293
294    /** @brief Number of non-zero entries in a row
295     *
296     * @param model problem object
297     * @param row row index
298     * @return number of non-zero entries in row
299     **/
300    COINLIBAPI int COINLINKAGE
301    Cbc_getRowNz(Cbc_Model * model, int row)
302    ;
303
304    /** @brief Indices of variables that appear on a row
305     *
306     * @param model problem object
307     * @param row row index
308     * @return vector with indexes of columns that appear on this row
309     **/
310    COINLIBAPI const int * COINLINKAGE
311    Cbc_getRowIndices(Cbc_Model * model, int row)
312    ;
313
314    /** @brief Coefficients of variables that appear on this row
315     *
316     * @param model problem object
317     * @param row row index
318     * @return coefficients of variables that appear on this row
319     **/
320    COINLIBAPI const double * COINLINKAGE
321    Cbc_getRowCoeffs(Cbc_Model * model, int row)
322    ;
323
324    /** @brief Number of non-zero entries in a column
325     *
326     * @param model problem object
327     * @param col column index
328     * @return numbef of rows that this column appears
329     **/
330    COINLIBAPI int COINLINKAGE
331    Cbc_getColNz(Cbc_Model * model, int col)
332    ;
333
334    /** @brief Indices of rows that a column appears
335     *
336     * @param model problem object
337     * @param col column index
338     * @return indices of rows that this column appears
339     **/
340    COINLIBAPI const int * COINLINKAGE
341    Cbc_getColIndices(Cbc_Model * model, int col)
342    ;
343
344    /** @brief Coefficients that a column appear in rows
345     *
346     * @param model problem object
347     * @param col column index
348     * @return coefficients of this column in rows
349     **/
350    COINLIBAPI const double * COINLINKAGE
351    Cbc_getColCoeffs(Cbc_Model * model, int col)
352    ;
353
354    /** @brief Right hand side of a row
355     *
356     * @param model problem object
357     * @param row row index
358     * @return row right hand side
359     **/
360    COINLIBAPI double COINLINKAGE
361    Cbc_getRowRHS(Cbc_Model * model, int row)
362    ;
363
364    /** @brief Sense a row
365     * @param model problem object
366     * @param row row index
367     * @return row sense: E for =, L for <=, G for >= and R for ranged row
368     **/
369    COINLIBAPI char COINLINKAGE
370    Cbc_getRowSense(Cbc_Model * model, int row)
371    ;
372 
373    /** @brief Direction of optimization
374     *
375     * @param model problem object
376     * @return Direction of optimization (1 - minimize, -1 - maximize, 0 - ignore)
377     **/
378    COINLIBAPI double COINLINKAGE
379    Cbc_getObjSense(Cbc_Model * model)
380    ;
381
382    /** @brief Constraint lower bounds
383     *
384     * @param model problem object
385     * @return vector with lower bounds of constraints
386     **/
387    COINLIBAPI const double* COINLINKAGE
388    Cbc_getRowLower(Cbc_Model * model)
389    ;
390
391    /** @brief Constraint upper bounds
392     *
393     * @param model problem object
394     * @return constraint upper bounds
395     **/
396    COINLIBAPI const double* COINLINKAGE
397    Cbc_getRowUpper(Cbc_Model * model)
398    ;
399
400    /** @brief Objective vector
401     *
402     * @param model problem object
403     * @return vector with coefficients of variables in the objective function
404     **/
405    COINLIBAPI const double * COINLINKAGE
406    Cbc_getObjCoefficients(Cbc_Model * model)
407    ;
408
409    /** @brief Variable lower bounds
410     *
411     * @param model problem object
412     * @return vector with lower bounds of variables
413     **/
414    COINLIBAPI const double * COINLINKAGE
415    Cbc_getColLower(Cbc_Model * model)
416    ;
417
418    /** @brief Variable upper bounds
419     *
420     * @param model problem object
421     * @return vector with column upper bounds
422     **/
423    COINLIBAPI const double * COINLINKAGE
424    Cbc_getColUpper(Cbc_Model * model)
425    ;
426
427    /** @brief Determine whether the ith variable is integer restricted
428     *
429     * @param model problem object
430     * @param i variable index
431     * @return 1 if variable is integer, 0 otherwise
432     **/
433    COINLIBAPI int COINLINKAGE
434    Cbc_isInteger(Cbc_Model * model, int i)
435    ;
436 
437    //@}
438
439/** \name Routines to load and save problems from disk
440*/
441//@{
442
443
444   /** @brief Read an mps file from the given filename
445    *
446    * @param model problem object
447    * @param fileName file name
448    **/
449    COINLIBAPI int COINLINKAGE
450    Cbc_readMps(Cbc_Model * model, const char *filename)
451    ;
452
453    /** @brief Read an lp file from the given filename
454     *
455     * @param model problem object
456     * @param fileName file name
457     **/
458    COINLIBAPI int COINLINKAGE
459    Cbc_readLp(Cbc_Model * model, const char *filename)
460    ;
461
462    /** @brief Write an mps file from the given filename
463     *
464     * @param model problem object
465     * @param fileName file name
466     **/
467    COINLIBAPI void COINLINKAGE
468    Cbc_writeMps(Cbc_Model * model, const char *filename)
469    ;
470
471    /** @brief Write an lp file from the given filename
472     *
473     * @param model problem object
474     * @param fileName file name
475     **/
476    COINLIBAPI void COINLINKAGE
477    Cbc_writeLp(Cbc_Model * model, const char *filename)
478    ;
479 
480//@}
481
482    /**@name Getting and setting model data
483     Note that problem access and modification methods,
484       such as getColLower and setColLower,
485       are *not valid* after calling Cbc_solve().
486       Therefore it is not recommended to reuse a Cbc_Model
487       object for multiple solves. A workaround is to call Cbc_clone()
488       before solving.
489     * */
490    /*@{*/
491
492   /** Provide an initial feasible solution to accelerate branch-and-bound
493     Note that feasibility of the solution is *not* verified.
494    */
495    COINLIBAPI void COINLINKAGE
496    Cbc_setInitialSolution(Cbc_Model *model, const double * sol)
497    ;
498   /** "Column start" vector of constraint matrix. Same format as Cbc_loadProblem() */
499    COINLIBAPI const CoinBigIndex * COINLINKAGE
500    Cbc_getVectorStarts(Cbc_Model * model)
501    ;
502    /** "Row index" vector of constraint matrix */
503    COINLIBAPI const int * COINLINKAGE
504    Cbc_getIndices(Cbc_Model * model)
505    ;
506    /** Coefficient vector of constraint matrix */
507    COINLIBAPI const double * COINLINKAGE
508    Cbc_getElements(Cbc_Model * model)
509    ;
510
511    /** Maximum lenght of a row or column name */
512    COINLIBAPI size_t COINLINKAGE
513    Cbc_maxNameLength(Cbc_Model * model)
514    ;
515    /** Print the model */
516    COINLIBAPI void COINLINKAGE
517    Cbc_printModel(Cbc_Model * model, const char * argPrefix)
518    ;
519    /** Return a copy of this model */
520    COINLIBAPI Cbc_Model * COINLINKAGE
521    Cbc_clone(Cbc_Model * model)
522    ;
523    /*@}*/
524
525    /**@name Solver parameters */
526    /*@{*/
527    /** Set parameter "name" to value "value". Note that this
528     * translates directly to using "-name value" as a
529     * command-line argument to Cbc.*/
530    COINLIBAPI void COINLINKAGE
531    Cbc_setParameter(Cbc_Model * model, const char * name, const char * value)
532    ;
533
534   
535    /*@}*/
536    /**@name Message handling.  Call backs are handled by ONE function */
537    /*@{*/
538    /** Pass in Callback function.
539     Message numbers up to 1000000 are Clp, Coin ones have 1000000 added */
540    COINLIBAPI void COINLINKAGE
541    Cbc_registerCallBack(Cbc_Model * model,
542                         cbc_callback userCallBack)
543    ;
544    /** Unset Callback function */
545    COINLIBAPI void COINLINKAGE
546    Cbc_clearCallBack(Cbc_Model * model)
547    ;
548
549    /*@}*/
550
551
552    /**@name Solving the model */
553    /*@{*/
554    /* Solve the model with Cbc (using CbcMain1).
555    */
556    COINLIBAPI int COINLINKAGE
557    Cbc_solve(Cbc_Model * model)
558    ;
559    /*@}*/
560
561
562    /**@name Accessing the solution and solution status */
563    /*@{*/
564
565    /** Sum of primal infeasibilities */
566    COINLIBAPI double COINLINKAGE
567    Cbc_sumPrimalInfeasibilities(Cbc_Model * model)
568    ;
569    /** Number of primal infeasibilities */
570    COINLIBAPI int COINLINKAGE
571    Cbc_numberPrimalInfeasibilities(Cbc_Model * model)
572    ;
573
574    /** Just check solution (for external use) - sets sum of
575        infeasibilities etc */
576    COINLIBAPI void COINLINKAGE
577    Cbc_checkSolution(Cbc_Model * model)
578    ;
579
580    /** Number of iterations */
581    COINLIBAPI int COINLINKAGE
582    Cbc_getIterationCount(Cbc_Model * model)
583    ;
584    /** Are there a numerical difficulties? */
585    COINLIBAPI int COINLINKAGE
586    Cbc_isAbandoned(Cbc_Model * model)
587    ;
588    /** Is optimality proven? */
589    COINLIBAPI int COINLINKAGE
590    Cbc_isProvenOptimal(Cbc_Model * model)
591    ;
592    /** Is infeasiblity proven (or none better than cutoff)? */
593    COINLIBAPI int COINLINKAGE
594    Cbc_isProvenInfeasible(Cbc_Model * model)
595    ;
596    /** Was continuous solution unbounded? */
597    COINLIBAPI int COINLINKAGE
598    Cbc_isContinuousUnbounded(Cbc_Model * model)
599    ;
600    /** Node limit reached? */
601    COINLIBAPI int COINLINKAGE
602    Cbc_isNodeLimitReached(Cbc_Model * model)
603    ;
604    /** Time limit reached? */
605    COINLIBAPI int COINLINKAGE
606    Cbc_isSecondsLimitReached(Cbc_Model * model)
607    ;
608    /** Solution limit reached? */
609    COINLIBAPI int COINLINKAGE
610    Cbc_isSolutionLimitReached(Cbc_Model * model)
611    ;
612    /** Are there numerical difficulties (for initialSolve) ? */
613    COINLIBAPI int COINLINKAGE
614    Cbc_isInitialSolveAbandoned(Cbc_Model * model)
615    ;
616    /** Is optimality proven (for initialSolve) ? */
617    COINLIBAPI int COINLINKAGE
618    Cbc_isInitialSolveProvenOptimal(Cbc_Model * model)
619    ;
620    /** Is primal infeasiblity proven (for initialSolve) ? */
621    COINLIBAPI int COINLINKAGE
622    Cbc_isInitialSolveProvenPrimalInfeasible(Cbc_Model * model)
623    ;
624    /** "row" solution
625     *  This is the vector A*x, where A is the constraint matrix
626     *  and x is the current solution. */
627    COINLIBAPI const double * COINLINKAGE
628    Cbc_getRowActivity(Cbc_Model * model)
629    ;
630    /** Best feasible solution vector */
631    COINLIBAPI const double * COINLINKAGE
632    Cbc_getColSolution(Cbc_Model * model)
633    ;
634    /** Objective value of best feasible solution */
635    COINLIBAPI double COINLINKAGE
636    Cbc_getObjValue(Cbc_Model * model)
637    ;
638    /** Best known bound on the optimal objective value */
639    COINLIBAPI double COINLINKAGE
640    Cbc_getBestPossibleObjValue(Cbc_Model * model)
641    ;
642    /** Best integer feasible solution or NULL if no integer feas sol found */
643    COINLIBAPI double*  COINLINKAGE
644    Cbc_bestSolution(Cbc_Model * model)
645    ;
646    /** Number of nodes explored in B&B tree */
647    COINLIBAPI int COINLINKAGE
648    Cbc_getNodeCount(Cbc_Model * model)
649    ;
650    /** Print the solution */
651    COINLIBAPI void  COINLINKAGE
652    Cbc_printSolution(Cbc_Model * model)
653    ;
654    /** Final status of problem
655        Some of these can be found out by is...... functions
656        -1 before branchAndBound
657        0 finished - check isProvenOptimal or isProvenInfeasible to see if solution found
658        (or check value of best solution)
659        1 stopped - on maxnodes, maxsols, maxtime
660        2 difficulties so run was abandoned
661        (5 event user programmed event occurred)
662    */
663    COINLIBAPI int COINLINKAGE
664    Cbc_status(Cbc_Model * model)
665    ;
666    /** Secondary status of problem
667        -1 unset (status_ will also be -1)
668        0 search completed with solution
669        1 linear relaxation not feasible (or worse than cutoff)
670        2 stopped on gap
671        3 stopped on nodes
672        4 stopped on time
673        5 stopped on user event
674        6 stopped on solutions
675        7 linear relaxation unbounded
676        8 stopped on iteration limit
677    */
678    COINLIBAPI int COINLINKAGE
679    Cbc_secondaryStatus(Cbc_Model * model)
680    ;
681    /*@}*/
682#ifdef __cplusplus
683}
684#endif
685#endif
Note: See TracBrowser for help on using the repository browser.