Oracle interface (abstract class). For each of your functions, provide an instance of a derived class. More...
#include <MatrixCBSolver.hxx>
Public Member Functions | |
| virtual int | evaluate (const CH_Matrix_Classes::Matrix ¤t_point, CH_Matrix_Classes::Real relprec, CH_Matrix_Classes::Real &objective_value, std::vector< Minorant *> &minorants, PrimalExtender *&primal_extender)=0 |
| Called by the solver. Has to Return function value and at least one (epsilon) subgradient and, possibly for Lagrangean relaxation, some primal data. More... | |
| virtual bool | check_correctness () const |
| switch on/off some correctnes checks on the oracle | |
 Public Member Functions inherited from ConicBundle::ModifiableOracleObject | |
| virtual | ~ModifiableOracleObject () |
| virtual destructor | |
| virtual int | apply_modification (const OracleModification &oracle_modification, const CH_Matrix_Classes::Matrix *new_center, const CH_Matrix_Classes::Matrix *old_center, bool &discard_objective_in_center, bool &discard_model, bool &discard_aggregates, MinorantExtender *&minorant_extender) |
| This routine need not be implemented unless variables (constraints in Lagrangean relaxation) are added or deleted on the fly. More... | |
Detailed Description
Oracle interface (abstract class). For each of your functions, provide an instance of a derived class.
The oracle interface is used to describe and pass convex objective functions to the ConicBundle::MatrixCBSolver. The dimension of the argument vector of the function (or, if an ConicBundle::AffineFunctionTransformation is supplied for this function, the dimension of the transformation argument) must be set in ConicBundle::MatrixCBSolver::init_problem() and the functions are then added to the solver by ConicBundle::MatrixCBSolver::add_function().
If the sum of several such functions is to be minimized it is the task of the user to guarantee, that all dimensions match, e.g. by using an appropriate AffineFunctionTransformation for each.
If the function corresponds to Lagrangean relaxation of a primal maximization problem one may want to generate a primal approximate solution. In this case, return in the function evaluate() the generating primal objects within each minorant. If no primal objects are included, there will be no primal aggregation.
If primal aggregation is used then it is possible to implement a primal cutting plane framework. This requires the introduction of new (dual) variables in the design space of the function. In this case the function MinorantExtender returned in apply_modification() serves the purpose of filling in the missing coordinates in existing subgradients. If this feature is not needed, the function may be used as is and need not be reimplemented.
Member Function Documentation
◆ evaluate()
|
pure virtual |
Called by the solver. Has to Return function value and at least one (epsilon) subgradient and, possibly for Lagrangean relaxation, some primal data.
The evaluation method is the main interface to the bundle solver. The solver calls this method to obtain for the current_point (its dimension is set in ConicBundle::CBSolver::init_problem() or via a AffineFunctionTransformation specified in MatrixCBSolver::add_function()) the objective_value and (epsilon) subgradient information. In any call several epsilon subgradients may be returned in minorants along with their offset, but at least one has to be returend. Each subgradient and offset describes a linear minorant to the convex function and is used by the bundle method to form a cutting model of the convex function.
In many applications, computing the function value is an iterative process that approaches the true function value from below. On input the code offers a bound in objective_value for the function value, above which it is certain that the code will reject the current point. If in the iterative process a lower bound on the function value exceeds this bound, then it is sufficient to return, instead of the true function value and a subgradient, the current lower bound and a vector so that together they describe a supporting hyperplane (i.e. a linear minorant) to the function at this point.
If the function corresponds to Lagrangean relaxation of a primal maximization problem one may want to generate a primal approximate solution. For this purpose the minorants may also hold information on the primal data. If at each call and for each epsilon subgradient the corresponding generating primal object (must be derived from ConicBundle::PrimalData, e.g., a ConicBundle::PrimalDVector) is stored, then the code automatically performs the aggregation corresponding to the aggregation of the subgradients on the primal data objects. The primal approximate solution is finally delivered by the methods ConicBundle::CBSolver::get_approximate_primal() or ConicBundle::CBSolver::get_center_primal().
All minorants passed to the solver must be objects allocated on the heap. The ownership of these objects is transferred to the solver and the solver will destroy them eventually, so DO NOT delete them yourself!
If no primal aggregation is desired, simply do not touch primal_data or clear it.
- Parameters
-
[in] current_point (const Matrix&) argument of the function as a column vector (e.g. the Lagrange multipliers) [in] relprec (double) relative precision requirement for objective values that may lead to descent steps (this precision is not required if it is already certain that the function value will be too poor) [in,out] objective_value (double&) - on input: value gives the threshold for a null step; you may stop, if a cutting plane yields at least this;
- on output: return an upper bound on the true function value within relprec *(abs(objval)+1.), if there is no linear minorant cutting above the threshold specified in objective_value on input. Otherwise the return value should be the max of cut_values.
[out] minorants (std::vector<Minorant*>) for returning linear minorants (subgradients and their offset values). At least one must be returned and the one at index 0 must maximize the value at the current point over all further ones given here. In particular its value at point should be above the threshold or be within relprec *(abs(objval)+1.) of the true objective. Within the minorants primal data may be supplied if this should be aggregated along. [out] primal_extender (PrimalExtender*&) if primal_data of previous calls has now to be updated due to changes in the primal problem – e.g., this may happen in column generation – one may return a pointer to PrimalExtender object on the heap. This object will be used by ConicBundle to update all its internally stored primal_data objects by calling PrimalExtender::extend on each of these, afterwards ConicBundle deletes primal_extender If this is not needed, the variable holds 0.
- Returns
- 0, all correct
- !=0, failure. This does not necessarily terminate the bundle method. Termination is forced only if no new subgradient is returned.
Implemented in ConicBundle::NNCBoxSupportFunction, and ConicBundle::CFunction.
The documentation for this class was generated from the following file:
