aipreqres.h

aiParts is a set of C++ classes that can be used to develop artificial intelligence for multi-decisi

//**********************************************************************
//  aipReqRes.h  -   Requirement-Resource problems
//
//  An aiprrProblem is a subclass of aipHHProblem.  
//  solve_rr_problem()  uses the  High-Hope technique.  
//  See aipHighHope.h
//
//  A aiprrProblem has a set of decisions, each of which has a set 
//  of options.
//
//  In this version, a Decision is associated with a Requirement-Day;
//  an Option refers to a Resource that can satisfy it.
//
//  Everything to do with a decision being trivial is commented out.
//  It will be implemented in a later release.
//
//  Copyright (c)  2008  Brian Marshall
//
//  See the license at end of this file.
//
//  Developers/Contributers:
//    [BRM] Brian Marshall - Calgary - [e-mail]
//
//  08/01/20  [BRM] began development: split out layer from rr_solve
//
//----------------------------------------------------------------------
//  The Data Model
//
//  In this version, only Requirements have Decisions, which means
//  that Resources always have an Option.
//
//                            [Problem]
//                                +           [Requirements]
//                                |              +
//                                v              v
//                                v              v 
//                          [Decisions]<---+[Req-Days]
//                       v----o   +
//                       v        |
//              [chosen_opts]     |           [Resources]
//                       ^        |              +
//                       |        v              v
//                       |        v              v
//                       ----o[Options]<<--+[Res-Days]
//
//  Notes:
//   - Problems have Decisions, which have Options
//   - Requirements and Resources may have a Decision
//   - Decisions may be decided multiple times, so they have a list
//        of chosen Options.
//
//----------------------------------------------------------------------
//  Important Note
//
//  In this file, the functions in aiprrOption:
//  virtual aipG g_opt_cmp() { return g_user_constant() + m_g_dynamic; }
//  virtual aipG g_opt_usr() { return g_user_constant() + m_g_dynamic; }
//  override functions in the HighHope classes - g_dynamic affects 
//  making decisions, comparing solutions and the goodness that can
//  be reported to the user.
//
//  To solve a particular type of Requirement-Resource problem,
//  you develop a set of sub-classes of aipReqRes classes and 
//  they call option.set_g_dynamic(aipG x) based on aspects of 
//  your particular problem.
//
//----------------------------------------------------------------------

#ifndef aipReqRes_h_guard
#define aipReqRes_h_guard

#include "aipHighHope.h"
#include "aipTime.h"

//----------------------------------------------------------------------
//  Classes.  Sub-classing is shown by indentation.

//  class  aipG  is a typedef for  aipGoodness

// class aipBase;                        ( in aipBase.h )
//   class aipImportance;                ( in aipImportance.h )
//     class aipHHImportance;            ( in aipHighHope.h )
         class aiprrReqImp;        // importance of a requirement
//   class aipProblem;                   ( in aipProblem.h )
//     class aipHHProblem;               ( in aipHighHope.h )
         class aiprrProblem;       // rr-solve problem
//   class aipDemon;                     ( in aipPandemonium.h )
//     class aipDecision;                ( in aipDecision.h )
//       class aipHHDecision;            ( in aipHighHope.h )
           class aiprrDecision;    // decision: for a requirement
//     class aipOption;                  ( in aipDecision.h )
//       class aipHHOption;              ( in aipHighHope.h )
           class aiprrOption;      // option: a resource
       class aiprrRequirement;     // requirement to be satisfied
       class aiprrReqDay;          // requirement on a day
       class aiprrResource;        // resource to satisfy requirement
       class aiprrResDay;          // resource on a day
// class aipDemonItr;                    ( in aipPandemonium.h )
     class aiprrRequirementItr;    // requirement iterator
     class aiprrReqDayItr;         // requirement-day iterator
     class aiprrResourceItr;       // resource iterator
     class aiprrResDayItr;         // resource-day iterator
     class aiprrDecisionItr;       // decision iterator
// class aipMsg                          ( in aipBase.h )
     class aiprrMsg;               // message for rr-solve solving

//======================================================================
//  aiprrReqImp  -  Importance of a position

class aiprrReqImp : public aipHHImportance {

  long    m_left_bhnd;  // being left behind

public:

  aiprrReqImp () { m_left_bhnd = 0; }
  virtual ~aiprrReqImp () {}

  virtual long val () const {
    return aipHHImportance::val() + m_left_bhnd;
  }

  virtual void take_msg (aipMsg *m);
  virtual void note_aiprr_decide (aiprrDecision *d, aiprrOption *o);

};


//======================================================================
//  aiprrProblem  -  rrSolve problem - assigning resources to requirements
//
//  solve_rr_problem () returns 1 (true) if a solution is found,
//  zero otherwise.
//
//  log_this_try() works best if decisions are stored in Req,Day order

class aiprrProblem : public aipHHProblem {

  aipPandemonium  * m_requirements;
  aipPandemonium  * m_resources;

  int  m_should_log_options;  // 1 (true) = log to cout

protected:

  virtual aipHHDecision * next_decision();

  virtual aipG too_bad_to_go_on() const;

  virtual void log_this_try ();  // to cout

  aipPandemonium  * requirement_pandemonium () const { // for iterators
    return m_requirements; 
  }

  aipPandemonium  * resource_pandemonium () const {    // for iterators
    return m_resources;
  }

public:

  aiprrProblem ();
  virtual ~aiprrProblem ();

  void set_num_try (long x) { aipHHProblem::set_num_try(x); }

  void add_requirement (aiprrRequirement *x);
  void add_resource    (aiprrResource *x);
  void add_decision    (aiprrDecision *x);

  void enable_log_options  () { m_should_log_options = 1; }
  void disable_log_options () { m_should_log_options = 0; }

  int should_log_options () const { return m_should_log_options; }

  aiprrRequirementItr   requirement_iterator() const;
  aiprrResourceItr      resource_iterator() const;
  aiprrDecisionItr      decision_iterator() const;

  virtual void take_msg (aipMsg *m);
  virtual void note_decide (aipHHDecision *d, aipHHOption *o);

//  aiprrReqDay * trivial_reqday () const;

  virtual int solve_rr_problem ();       // use this, not solve()

};


//======================================================================
//  aiprrDecision  -  choosing a res for a reqday
//
//  inherits: importance, a set of options, more

class aiprrDecision : public aipHHDecision {

  aiprrReqDay   * m_reqday;        // reqday that needs resource-days

public:

  aiprrDecision (aiprrReqDay *a_reqday, long num_to_decide =1);
  virtual ~aiprrDecision();

                          // use this function, not add_hh_option
  void add_aiprr_option (aiprrOption *x);

  virtual void take_msg (aipMsg *m);

  aiprrProblem * prob () const { return (aiprrProblem*)owner(); }

  aiprrReqDay * reqday () const { return m_reqday; }

  virtual long imp () const;

  aiprrOption * aiprr_opt_cur  () const { 
    return (aiprrOption*)opt_cur();  
  }

  aiprrOption * aiprr_opt_bsf  () const { 
    return (aiprrOption*)opt_bsf();  
  }

};

//======================================================================
//  aiprrOption  - a resource assigned to a requirement on a day

class aiprrOption : public aipHHOption {

  aiprrResDay  * m_resday;        // the subject of this option

  aipG           m_g_dynamic;     // g of situational aspects

public:

  aiprrOption(aiprrResDay *a_resday, aipG g_constant);
  virtual ~aiprrOption ();

  virtual void take_msg (aipMsg *m);

  void set_g_dynamic (aipG x);
  void add_g_dynamic (aipG x);

  aiprrDecision * aiprr_chooser () const { 
    return (aiprrDecision*)hh_opt_chooser(); 
  }

  aiprrResDay * resday () const { return m_resday; }

  virtual aipG g_opt();
 
  virtual aipG g_opt_cmp();
  virtual aipG g_opt_usr();

};

//======================================================================
//  aiprrRequirement  -  a requirement requiring resources
//
//  A requirement is owned by a problem; it owns requirement-days.

class aiprrRequirement : public aipDemon {

  long              m_id;

  aiprrProblem    * m_prob;

  aipPandemonium  * m_reqdays;

  aipHHHope       * m_hope;         // how well this requirement is doing
  aiprrReqImp         m_importance;   // for choosing next decision

protected:

  aipPandemonium  * reqday_pandemonium () const {    // for iterators
    return m_reqdays; 
  }

public:

  aiprrRequirement(long a_id, aiprrProblem *a_prob);
  virtual ~aiprrRequirement();

  void add_reqday  (aiprrReqDay *x);

  long imp () const { return m_importance.val(); }

  virtual void take_msg (aipMsg *m);
  virtual void note_aiprr_decide (aiprrDecision *d, aiprrOption *o);

  int is_satisfied () const;

  aiprrReqDay * first_unsatisfied_reqday () const;

//  aiprrReqDay * trivial_reqday () const;

  aiprrProblem * prob () const { return m_prob; }
  long           id   () const { return m_id;   }

  aiprrReqDayItr  reqday_iterator() const;

};


//======================================================================
//  aiprrReqDay  -  a requirement on a day (requiring one or more resources)
//
//  set_dcsn() must be called after the decision is created.