ConicBundle
cb_cinterface.h
Go to the documentation of this file.
1 
2 
3 #ifndef CONICBUNDLE_CB_CINTERFACE_H
4 #define CONICBUNDLE_CB_CINTERFACE_H
5 
6 
90 
91 #ifdef __cplusplus
92 class CB_CSolver;
95 typedef CB_CSolver* cb_problemp;
96 #else
97 
99 typedef struct CB_CSolver* cb_problemp;
100 #endif
101 
102 #ifdef __cplusplus
103 extern "C" {
104 #endif
105 
106 
107 /* *****************************************************************
108  * function evaluation
109  * ***************************************************************** */
110 
205 typedef int (*cb_functionp)( /* input: */
206  void *function_key, /* supplied by the user */
207  /* on entering the function. May be useful */
208  /* if multiple copies of the same function are */
209  /* used with parameters */
210 
211  double *arg, /* argument/Lagrange multipliers */
212 
213  double relprec, /* relative precision requirement */
214  /* for objective values leading to descent steps */
215 
216  int max_subg, /* at most max_subg */
217  /* eps-subgradients and subg_values may be */
218  /* returend (but at least one!) */
219 
220 
221  /* output: */ /*memory provided by caller */
222 
223  double *objective_value, /* pointer to double */
224  /* on input: value gives the threshold for a */
225  /* null step; you may stop, if a cutting plane */
226  /* yields at least this; */
227  /* on output: return an upper bound on the true */
228  /* function value if there is no hyperplane */
229  /* cutting above the threshold (must be */
230  /* guaranteed within relprec*(abs(objval)+1.)) */
231 
232  int* n_subgrads, /* pointer to int */
233  /* must give number of epsilon subgrads returned */
234 
235  double *subg_values, /* pointer to double array */
236  /* for each eps subgradient the value at argument */
237 
238  double *subgradients, /* pointer to double array */
239  /* format: s1y1,...,s1ym,s2y1,...,s2ym,... */
240 
241  double *primal /* pointer to array, may be NULL */
242  /* if function arises from Lagrangean relaxation */
243  /* and a primal approximation is desired then */
244  /* set the primal dimension in cb_add_function */
245  /* and return the primal solutions corresponding */
246  /* to the eps-subgradients in the array pointed */
247  /* to by primal */
248  /* format p1x1,..,p1xn,p2x1,...,p2xn,... */
249  );
250 
251 
252 /* *****************************************************************
253  * subgradient_extension
254  * ***************************************************************** */
255 
306 typedef int (*cb_subgextp) ( /* input: */
307 
308  void *function_key, /* supplied by the user */
309  /* on entering the function. May be useful */
310  /* if multiple copies of the same function are */
311  /* used with parameters */
312 
313  double* generating_primal, /* pointer to array */
314  /* may be NULL if no primal supplied */
315 
316  int n_indices,
317 
318  int* variable_indices, /* pointer to array */
319 
320 
321  /*output*/ /* (storage provided by caller) */
322 
323  double* new_subgradient_values /* pointer to array */
324  );
325 
326 
327 
328 /* *****************************************************************
329  * cb_construct_problem
330  * ***************************************************************** */
331 
345  cb_problemp cb_construct_problem(int no_bundle);
346 
347 
348 /* *****************************************************************
349  * destruct_problem
350  * ***************************************************************** */
351 
363  int cb_destruct_problem(cb_problemp *p);
364 
365 
366 /* *****************************************************************
367  * clear
368  * ***************************************************************** */
369 
377  void cb_clear(cb_problemp p);
378 
379 
380 /* *****************************************************************
381  * set_defaults
382  * ***************************************************************** */
383 
391  void cb_set_defaults(cb_problemp p);
392 
393 
394 /* *****************************************************************
395  * cb_init_problem
396  * ***************************************************************** */
397 
435  int cb_init_problem(/* input: */
436  cb_problemp p,
437  int m, /* dimension of argument/number Lag mult */
438  double *lowerb, /* pointer to array, may be NULL */
439  double *upperb /* point to array, may be NULL */
440  );
441 
442 /* *****************************************************************
443  * cb_add_function
444  * ***************************************************************** */
445 
489  int cb_add_function(cb_problemp p,
490  void* function_key,
491  cb_functionp f,
492  cb_subgextp se,
493  int primaldim);
494 
495 
496 /* *****************************************************************
497  * set_lower_bound
498  * ***************************************************************** */
499 
521  int cb_set_lower_bound(cb_problemp p,int i, double lower_bound);
522 
523 
524 /* *****************************************************************
525  * set_upper_bound
526  * ***************************************************************** */
527 
550  int cb_set_upper_bound(cb_problemp p,int i, double upper_bound);
551 
552 
553 /* *****************************************************************
554  * append_variables
555  * ***************************************************************** */
556 
598  int cb_append_variables(cb_problemp p,
599  int n_append,double* lower_bound,double* upper_bound);
600 
601 
602 /* *****************************************************************
603  * delete_variables
604  * ***************************************************************** */
605 
648  int cb_delete_variables(cb_problemp p,
649  int n_del,int* delete_indices,int* map_to_old);
650 
651 /* return value:
652  * 0, all correct
653  * >0, failure
654  */
655 
656 
657 
658 /* *****************************************************************
659  * reassign_variables
660  * ***************************************************************** */
661 
696  int cb_reassign_variables(cb_problemp p,
697  int n_assign,int* assign_new_from_old);
698 
699 
700 /* *****************************************************************
701  * do_descent_step
702  * ***************************************************************** */
703 
762  int cb_solve(cb_problemp p,int maxsteps,int stop_at_descent_steps);
763 
764 
765 /* *****************************************************************
766  * termination_code
767  * ***************************************************************** */
768 
802 int cb_termination_code(cb_problemp p);
803 
804 /* *****************************************************************
805  * print_termination_code
806  * ***************************************************************** */
807 
819  int cb_print_termination_code(cb_problemp p);
820 
821 /* *****************************************************************
822  * get_objval
823  * ***************************************************************** */
824 
825 
839 double cb_get_objval(cb_problemp p);
840 
841 /* *****************************************************************
842  * get_center
843  * ***************************************************************** */
844 
865 int cb_get_center(cb_problemp p,double* center);
866 
867 
868 /* *****************************************************************
869  * get_sgnorm
870  * ***************************************************************** */
871 
882 double cb_get_sgnorm(cb_problemp p);
883 
884 /* *****************************************************************
885  * get_subgradient
886  * ***************************************************************** */
887 
902 int cb_get_subgradient(cb_problemp p,double* subgradient);
903 
904 
905 /* *****************************************************************
906  * get_candidate_value
907  * ***************************************************************** */
908 
918 double cb_get_candidate_value(cb_problemp p);
919 
920 /* *****************************************************************
921  * get_candidate
922  * ***************************************************************** */
923 
941 int cb_get_candidate(cb_problemp p,double* candidate);
942 
943 
944 /* *****************************************************************
945  * set_term_relprec
946  * ***************************************************************** */
947 
965  int cb_set_term_relprec(cb_problemp p,double term_relprec);
966 
967 
968 /* *****************************************************************
969  * set_new_center_point
970  * ***************************************************************** */
971 
989 int cb_set_new_center_point(cb_problemp p,double* center);
990 
991 
992 /* *****************************************************************
993  * get_function_status
994  * ***************************************************************** */
995 
1010  int cb_get_function_status(cb_problemp p,void* function_key);
1011 
1012 
1013 /* *****************************************************************
1014  * get_approximate_slacks
1015  * ***************************************************************** */
1016 
1033  int cb_get_approximate_slacks(cb_problemp p,double* slacks);
1034 
1035 
1036 /* *****************************************************************
1037  * get_approximate_primal
1038  * ***************************************************************** */
1039 
1070 int cb_get_approximate_primal(cb_problemp p,void* function_key,double* primal);
1071 
1072 
1073 /* *****************************************************************
1074  * get_center_primal
1075  * ***************************************************************** */
1076 
1101 int cb_get_center_primal(cb_problemp p,void* function_key,double* primal);
1102 
1103 
1104 /* *****************************************************************
1105  * get_center_candidate
1106  * ***************************************************************** */
1107 
1134 int cb_get_candidate_primal(cb_problemp p,void* function_key,double* primal);
1135 
1136 
1137 
1138 /* *****************************************************************
1139  * set_max_modelsize
1140  * ***************************************************************** */
1141 
1170  int cb_set_max_modelsize(cb_problemp p,void* function_key,
1171  int modelsize);
1172 
1173 
1174 /* *****************************************************************
1175  * set_max_bundlesize
1176  * ***************************************************************** */
1177 
1200  int cb_set_max_bundlesize(cb_problemp p,void* function_key,
1201  int bundlesize);
1202 
1203 
1204 /* *****************************************************************
1205  * set_max_new_subgradients
1206  * ***************************************************************** */
1207 
1233  int cb_set_max_new_subgradients(cb_problemp p,void* function_key,
1234  int max_new_subg);
1235 
1236 
1237 /* *****************************************************************
1238  * get_bundle_parameters
1239  * ***************************************************************** */
1240 
1266  int cb_get_bundle_parameters(cb_problemp p,void* function_key,
1267  int* max_modelsize,int* max_bundelsize);
1268 
1269 
1270 
1271  /* *****************************************************************
1272  * reinit_function_model
1273  * ***************************************************************** */
1274 
1296  int cb_reinit_function_model(cb_problemp p,void* function_key);
1297 
1298 
1299 /* *****************************************************************
1300  * get_last_weight
1301  * ***************************************************************** */
1302 
1313  double cb_get_last_weight(cb_problemp p);
1314 
1315 /* *****************************************************************
1316  * set_next_weight
1317  * ***************************************************************** */
1318 
1344  int cb_set_next_weight(cb_problemp p,double weight);
1345 
1346 
1347 /* *****************************************************************
1348  * set_min_weight
1349  * ***************************************************************** */
1350 
1369  int cb_set_min_weight(cb_problemp p,double min_weight);
1370 
1371 
1372 /* *****************************************************************
1373  * set_max_weight
1374  * ***************************************************************** */
1375 
1395  int cb_set_max_weight(cb_problemp p,double max_weight);
1396 
1397 
1398 /* *****************************************************************
1399  * cb_set_variable_metric
1400  * ***************************************************************** */
1401 
1420  int cb_set_variable_metric(cb_problemp p,int do_variable_metric);
1421 
1422 
1423 
1424 /* *****************************************************************
1425  * get_dim
1426  * ***************************************************************** */
1427 
1432  int cb_get_dim(cb_problemp p);
1433 
1434 
1435 /* *****************************************************************
1436  * get_n_functions
1437  * ***************************************************************** */
1438 
1442  int cb_get_n_functions(cb_problemp p);
1443 
1444 
1445 /* *****************************************************************
1446  * get_minus_infinity
1447  * ***************************************************************** */
1448 
1453  double cb_get_minus_infinity(void);
1454 
1455 /* *****************************************************************
1456  * get_plus_infinity
1457  * ***************************************************************** */
1458 
1463  double cb_get_plus_infinity(void);
1464 
1465 
1466 /* *****************************************************************
1467  * clear_fail_counts
1468  * ***************************************************************** */
1469 
1470 
1471 
1480  void cb_clear_fail_counts (cb_problemp p);
1481 
1482 /* *****************************************************************
1483  * set_eval_limit
1484  * ***************************************************************** */
1485 
1499  void cb_set_eval_limit(cb_problemp p,int eval_limit);
1500 
1501 /* *****************************************************************
1502  * set_inner_update_limit
1503  * ***************************************************************** */
1504 
1518  void cb_set_inner_update_limit(cb_problemp p,int update_limit);
1519 
1520 
1521 
1522 /* *****************************************************************
1523  * cb_set_active_bounds_fixing
1524  * ***************************************************************** */
1525 
1552 void cb_set_active_bounds_fixing(cb_problemp p, int allow_fixing );
1553 
1554 /* *****************************************************************
1555  * cb_get_fixed_active_bounds
1556  * ***************************************************************** */
1557 
1578  int cb_get_fixed_active_bounds(cb_problemp p,int* indicator);
1579 
1580 /* *****************************************************************
1581  * set_print_level
1582  * ***************************************************************** */
1583 
1645  void cb_set_print_level(cb_problemp p,int pril);
1646 
1647 
1648 
1649 
1650 #ifdef __cplusplus
1651 } /* extern "C" */
1652 #endif
1653 
1656 #endif
cb_clear_fail_counts
void cb_clear_fail_counts(cb_problemp p)
clears all fail counts on numerical function oder model failures, may be useful if this caused premat...
cb_get_last_weight
double cb_get_last_weight(cb_problemp p)
Returns the current weight for the quadratic term in the augmented subproblem (may be interpreted as ...
cb_set_new_center_point
int cb_set_new_center_point(cb_problemp p, double *center)
Set the starting point/center that will be used in the next call to cb_do_descent_step(). Each call to this routine causes an immediate evaluation of all oracles.
cb_clear
void cb_clear(cb_problemp p)
Clears all data structures and problem information but keeps ouptut settings and algorithmic paramete...
cb_get_approximate_primal
int cb_get_approximate_primal(cb_problemp p, void *function_key, double *primal)
Returns the current approximate primal solution for the function having this function_key.
CB_CSolver::no_bundle
bool no_bundle
if true, swith on the minimal sumbundle version
Definition: CB_CSolver.hxx:42
cb_get_function_status
int cb_get_function_status(cb_problemp p, void *function_key)
Returns the return value of the latest evaluation call to the function with this function_key.
cb_set_eval_limit
void cb_set_eval_limit(cb_problemp p, int eval_limit)
Sets an upper bound on the number of calls to the oracle (use negative numbers for no limit)...
cb_get_candidate
int cb_get_candidate(cb_problemp p, double *candidate)
Returns the last point, the "candidate", at which the function was evaluated in cb_do_descent_step()...
cb_get_objval
double cb_get_objval(cb_problemp p)
Returns the objective value resulting from last descent step (initially undefined).
cb_get_dim
int cb_get_dim(cb_problemp p)
Returns the current dimension of the design space/argument or -1 if no dimension is set...
cb_get_plus_infinity
double cb_get_plus_infinity(void)
Returns the value "plus infinity", i.e., all bounds >= this value are set to this value and are regar...
cb_functionp
int(* cb_functionp)(void *function_key, double *arg, double relprec, int max_subg, double *objective_value, int *n_subgrads, double *subg_values, double *subgradients, double *primal)
function oracle; describe your function as a function of this type to pass it to the solver ...
Definition: cb_cinterface.h:205
cb_get_minus_infinity
double cb_get_minus_infinity(void)
Returns the value "minus infinity", i.e., all bounds <= this value are set to this value and are rega...
cb_append_variables
int cb_append_variables(cb_problemp p, int n_append, double *lower_bound, double *upper_bound)
Append new variables (always in last postions in this order).
CB_CSolver
Interface class for implementing the language "C" interface.
Definition: CB_CSolver.hxx:38
cb_set_lower_bound
int cb_set_lower_bound(cb_problemp p, int i, double lower_bound)
set lower bound for variable i, use cb_get_minus_infinity() for unbounded from below.
cb_set_next_weight
int cb_set_next_weight(cb_problemp p, double weight)
Sets the weight (>0) to be used in the quadratic term of the next augmented subproblem (may be interp...
cb_get_fixed_active_bounds
int cb_get_fixed_active_bounds(cb_problemp p, int *indicator)
Returns the indicator vector of variables temporarily fixed to the center value due to significantly ...
cb_init_problem
int cb_init_problem(cb_problemp p, int m, double *lowerb, double *upperb)
Initializes the problem by setting the design space (the dimension and possible box constraints of th...
cb_get_subgradient
int cb_get_subgradient(cb_problemp p, double *subgradient)
Returns the latest aggregate subgradient.
cb_get_bundle_parameters
int cb_get_bundle_parameters(cb_problemp p, void *function_key, int *max_modelsize, int *max_bundelsize)
Retrieves the two bundle parameters specified in the routines cb_set_max_modelsize() and cb_set_max_b...
cb_get_candidate_value
double cb_get_candidate_value(cb_problemp p)
Returns the objective value computed in the last step of do_descent_step(), independent of whether th...
cb_reinit_function_model
int cb_reinit_function_model(cb_problemp p, void *function_key)
Clears cutting model, subgradients and stored function values for the function with this function_key...
cb_solve
int cb_solve(cb_problemp p, int maxsteps, int stop_at_descent_steps)
solves or does a prescribed number of
cb_set_max_modelsize
int cb_set_max_modelsize(cb_problemp p, void *function_key, int modelsize)
Sets the maximum number of subgradients used in forming the cutting model of the function having this...
cb_set_min_weight
int cb_set_min_weight(cb_problemp p, double min_weight)
Sets a lower bound on the weight for the quadratic term of the augmented subproblem.
cb_set_inner_update_limit
void cb_set_inner_update_limit(cb_problemp p, int update_limit)
Set an upper bound on the number of inner updates for the cutting model with primal slacks within one...
cb_set_print_level
void cb_set_print_level(cb_problemp p, int pril)
Specifies the output level (<0 no output at all, =0 errors and warnings, >0 increasingly detailed inf...
cb_set_max_bundlesize
int cb_set_max_bundlesize(cb_problemp p, void *function_key, int bundlesize)
Sets the maximum number of subgradients stored for use in forming the model or determining metric inf...
cb_get_candidate_primal
int cb_get_candidate_primal(cb_problemp p, void *function_key, double *primal)
Returns the best primal solution returned by the last evaluation of the function having this function...
cb_get_center
int cb_get_center(cb_problemp p, double *center)
Returns the next center point that was produced by the last call to cb_do_descent_step (in some probl...
cb_set_upper_bound
int cb_set_upper_bound(cb_problemp p, int i, double upper_bound)
set upper bound for variable i, use cb_get_plus_infinity() for unbounded above.
cb_get_center_primal
int cb_get_center_primal(cb_problemp p, void *function_key, double *primal)
Returns the best primal solution obtained in the current center point in evaluating the function havi...
cb_set_active_bounds_fixing
void cb_set_active_bounds_fixing(cb_problemp p, int allow_fixing)
If set to true (the default is false), some variables will be fixed automatically to the center value...
cb_reassign_variables
int cb_reassign_variables(cb_problemp p, int n_assign, int *assign_new_from_old)
Reassigns variables to new index positions by mapping to position i the variable that previously had ...
cb_termination_code
int cb_termination_code(cb_problemp p)
Returns the termination code of the bundle algorithm for the latest descent step. ...
cb_set_max_new_subgradients
int cb_set_max_new_subgradients(cb_problemp p, void *function_key, int max_new_subg)
Sets the maximum number of epsilon subgradients that can be returned in one call to the function havi...
cb_print_termination_code
int cb_print_termination_code(cb_problemp p)
Outputs a text version of termination code, see cb_termination_code().
cb_set_defaults
void cb_set_defaults(cb_problemp p)
Sets default values for algorithmic parameters that are not function specific (e.g., relative precision, weight and weight bounds for the augmentedproblem, etc.)
cb_destruct_problem
int cb_destruct_problem(cb_problemp *p)
Destructs and frees the problem object.
cb_subgextp
int(* cb_subgextp)(void *function_key, double *generating_primal, int n_indices, int *variable_indices, double *new_subgradient_values)
This routine is not needed unless variabls (constraints in Lagrangean relaxation) are added on the fl...
Definition: cb_cinterface.h:306
cb_get_sgnorm
double cb_get_sgnorm(cb_problemp p)
Returns Euclidean norm of the latest aggregate subgradient.
cb_construct_problem
cb_problemp cb_construct_problem(int no_bundle)
Creates a a new problem object and returns a pointer to it.
cb_get_n_functions
int cb_get_n_functions(cb_problemp p)
Returns the current number of functions in the problem.
cb_get_approximate_slacks
int cb_get_approximate_slacks(cb_problemp p, double *slacks)
Returns the multipliers for the bound constraints on the design variables; in Lagrangean relaxation t...
cb_set_max_weight
int cb_set_max_weight(cb_problemp p, double max_weight)
Sets an upper bound on the weight for the quadratic term of the augmented subproblem.
cb_set_term_relprec
int cb_set_term_relprec(cb_problemp p, double term_relprec)
Sets the relative precision requirements for successful termination (default 1e-5).
cb_problemp
struct CB_CSolver * cb_problemp
pointer to a ConicBundle problem
Definition: cb_cinterface.h:99
cb_delete_variables
int cb_delete_variables(cb_problemp p, int n_del, int *delete_indices, int *map_to_old)
Deletes variables corresponding to the specified indices.
cb_set_variable_metric
int cb_set_variable_metric(cb_problemp p, int do_variable_metric)
Use a variable metric heuristic or switch it off alltogether. (the variable metric heuristic resets t...
cb_add_function
int cb_add_function(cb_problemp p, void *function_key, cb_functionp f, cb_subgextp se, int primaldim)
Adds the function, the sum of which should be minimized, to the problem description.
Generated by   doxygen 1.8.13