// 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. 
   <ul>
   <li> Empty; doesn't do anything and immediately returns. (E.g., 
   pack_module_data().
   <li> 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.)
   <li> A default is given. Frequently there are multiple defaults and
   parameters govern which one is selected (e.g.,
   compare_tree_nodes()).
   </ul>
*/

class BCP_tm_user : public BCP_user_class {
private:
  mutable 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() const { 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;
  /** Return a global lower bound.
      This value is the minimum of the true lower bounds in the candidate list
      and the true lower bounds of the nodes currently processed */
  double lower_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 <code>unpack_module_data()</code> method
      of the user defined class in the appropriate process. <br>
      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<BCP_var_core*>& vars,
		  BCP_vec<BCP_cut_core*>& 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<BCP_var*>& added_vars,
	      BCP_vec<BCP_cut*>& 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.
      This method is deprecated in favor of the one with 3 args.
  */
  virtual void
  display_node_information(BCP_tree& search_tree,
			   const BCP_tm_node& node);
    
  //--------------------------------------------------------------------------
  /** Display user information. This method is called just before a node is
      sent ot for processing (or diving into the node is acknowledged) and
      just after a node description has been received. */
  virtual void
  display_node_information(BCP_tree& search_tree,
			   const BCP_tm_node& node,
			   bool after_processing_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
      <code>phase</code>-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
