// Copyright (C) 2000, International Business Machines
// Corporation and others. All Rights Reserved.
#ifndef _BCP_TM_USER_FUN_H
#define _BCP_TM_USER_FUN_H
// This file is fully docified.
#include "BCP_math.hpp"
#include "BCP_enum.hpp"
#include "BCP_enum_process_t.hpp"
#include "BCP_vector.hpp"
#include "BCP_string.hpp"
#include "BCP_buffer.hpp"
#include "BCP_solution.hpp"
#include "BCP_warmstart.hpp"
#include "BCP_var.hpp"
#include "BCP_cut.hpp"
#include "BCP_matrix.hpp"
#include "BCP_tm_param.hpp"
#include "BCP_tm_node.hpp"
#include "BCP_enum_tm.hpp"
#include "BCP_enum_process_t.hpp"
#include "BCP_USER.hpp"
class BCP_lp_statistics;
//#############################################################################
/**
The BCP_tm_user class is the base class from which the user
can derive a problem specific class to be used in the TM process.
In that derived class the user can store data to be used in the methods she
overrides. Also that is the object the user must return in the
USER_initialize::tm_init() method.
There are two kind of methods in the class. The non-virtual methods are
helper functions for the built-in defaults, but the user can use them as
well. The virtual methods execute steps in the BCP algorithm where the user
might want to override the default behavior.
The default implementations fall into three major categories.
- Empty; doesn't do anything and immediately returns. (E.g.,
pack_module_data().
- There is no reasonable default, so throw an exception. This happens
if the parameter settings drive the flow of in a way that BCP can't
perform the necessary function. This behavior is correct since such
methods are invoked only if the parameter settings drive the flow of
the algorithm that way, in which case the user better implement those
methods. (At the momemnt there is no such method in TM.)
- A default is given. Frequently there are multiple defaults and
parameters govern which one is selected (e.g.,
compare_tree_nodes()).
*/
class BCP_tm_user : public BCP_user_class {
private:
BCP_tm_prob * p;
public:
/**@name Methods to set and get the pointer to the BCP_tm_prob
object. It is unlikely that the users would want to muck around with
these (especially with the set method!) but they are here to provide
total control.
*/
/*@{*/
/// Set the pointer
void setTmProblemPointer(BCP_tm_prob * ptr) { p = ptr; }
/// Get the pointer
BCP_tm_prob * getTmProblemPointer() { return p; }
/*@}*/
/**@name Informational methods for the user. */
/*@{*/
/// Return what is the best known upper bound (might be BCP_DBL_MAX)
double upper_bound() const;
/*@}*/
/**@name Methods to get/set BCP parameters on the fly */
/*@{*/
///
char get_param(const BCP_tm_par::chr_params key) const;
///
int get_param(const BCP_tm_par::int_params key) const;
///
double get_param(const BCP_tm_par::dbl_params key) const;
///
const BCP_string& get_param(const BCP_tm_par::str_params key) const;
///
void set_param(const BCP_tm_par::chr_params key, const bool val);
///
void set_param(const BCP_tm_par::chr_params key, const char val);
///
void set_param(const BCP_tm_par::int_params key, const int val);
///
void set_param(const BCP_tm_par::dbl_params key, const double val);
///
void set_param(const BCP_tm_par::str_params key, const char * val);
/*@}*/
//===========================================================================
/**@name Constructor, Destructor */
/*@{*/
BCP_tm_user() : p(0) {}
/** Being virtual, the destructor invokes the destructor for the real type
of the object being deleted. */
virtual ~BCP_tm_user() {}
/*@}*/
//===========================================================================
// Here are the user defined functions. For each of them a default is given
// which can be overridden when the concrete user class is defined.
//===========================================================================
/**@name Packing and unpacking methods */
/*@{*/
/** Pack the initial information (info that the user wants to send over)
for the process specified by the last argument. The information packed
here will be unpacked in the unpack_module_data()
method
of the user defined class in the appropriate process.
Default: empty method.
*/
virtual void
pack_module_data(BCP_buffer& buf, BCP_process_t ptype);
/** Unpack a MIP feasible solution that was packed by the
BCP_lp_user::pack_feasible_solution() method.
Default: Unpacks a BCP_solution_generic object. The built-in default
should be used if and only if the built-in default was used
in BCP_lp_user::pack_feasible_solution().
*/
virtual BCP_solution*
unpack_feasible_solution(BCP_buffer& buf);
/** Decide whether to replace old_sol with new_sol. When this method is
invoked it has already been tested that they have the same objective
function value. The purpose of the method is that the user can have a
secondary objective function. */
virtual bool
replace_solution(const BCP_solution* old_sol, const BCP_solution* new_sol);
/*@}*/
//--------------------------------------------------------------------------
/** What is the process id of the current process */
int process_id() const;
/** Send a message to a particular process */
void
send_message(const int target, const BCP_buffer& buf);
/** Broadcast the message to all processes of the given type */
void
broadcast_message(const BCP_process_t proc_type, const BCP_buffer& buf);
/** Process a message that has been sent by another process' user part to
this process' user part. */
virtual void
process_message(BCP_buffer& buf);
//--------------------------------------------------------------------------
/**@name Initial setup (creating core and root) */
/*@{*/
/** Create the core of the problem by filling out the last three arguments.
These variables/cuts will always stay in the LP relaxation and the
corresponding matrix is described by the specified matrix. If there is
no core variable or cut then the returned pointer for to the matrix
should be a null pointer.
Default: empty method, meaning that there are no variables/cuts in the
core and this the core matrix is empty (0 pointer) as well.
*/
virtual void
initialize_core(BCP_vec& vars,
BCP_vec& cuts,
BCP_lp_relax*& matrix);
//-------------------------------------------------------------------------
/** Create the set of extra variables and cuts that should be added to the
formulation in the root node. Also decide how variable pricing shuld be
done, that is, if column generation is requested in the
init_new_phase() method of this class then column
generation should be performed according to \c pricing_status.
Default: empty method, meaning that no variables/cuts are added, there
is no user data and no pricing should be done.
*/
virtual void
create_root(BCP_vec& added_vars,
BCP_vec& added_cuts,
BCP_user_data*& user_data);
/*@}*/
//--------------------------------------------------------------------------
/** Display a feasible solution */
virtual void
display_feasible_solution(const BCP_solution* sol);
//--------------------------------------------------------------------------
/** Display user information just before a new node is sent to the LP or
diving into a node is acknowledged. */
virtual void
display_node_information(BCP_tree& search_tree,
const BCP_tm_node& node);
//--------------------------------------------------------------------------
/** Display information after BCP finished processing the search tree. */
virtual void
display_final_information(const BCP_lp_statistics& lp_stat);
//---------------------------------------------------------------------------
/**@name Initialize new phase */
/*@{*/
/** Do whatever initialization is necessary before the
phase
-th phase. (E.g., setting the pricing strategy.) */
virtual void
init_new_phase(int phase,
BCP_column_generation& colgen,
CoinSearchTreeBase*& candidates);
/*@}*/
//---------------------------------------------------------------------------
/**@name Search tree node comparison */
/*@{*/
/**@name If desired, change the tree (the candidate list) in the search
tree manager using the setTree() method. This method is invoked after
every insertion into the candidate list and also whenever a new
solution is found. In the latter case \c new_solution is \c true.
The default invokes the newSolution() and the
reevaluateSearchStrategy() methods from CoinSearchTreeManager.
*/
virtual void
change_candidate_heap(CoinSearchTreeManager& candidates,
const bool new_solution);
/*@}*/
};
//#############################################################################
#endif