1 /*===========================================================================*
2  * This file is part of the Abstract Library for Parallel Search (ALPS).     *
3  *                                                                           *
4  * ALPS is distributed under the Eclipse Public License as part of the       *
5  * COIN-OR repository (http://www.coin-or.org).                              *
6  *                                                                           *
7  * Authors:                                                                  *
8  *                                                                           *
9  *          Yan Xu, Lehigh University                                        *
10  *          Aykut Bulut, Lehigh University                                   *
11  *          Ted Ralphs, Lehigh University                                    *
12  *                                                                           *
13  * Conceptual Design:                                                        *
14  *                                                                           *
15  *          Yan Xu, Lehigh University                                        *
16  *          Ted Ralphs, Lehigh University                                    *
17  *          Laszlo Ladanyi, IBM T.J. Watson Research Center                  *
18  *          Matthew Saltzman, Clemson University                             *
19  *                                                                           *
20  *                                                                           *
21  * Copyright (C) 2001-2019, Lehigh University, Yan Xu, Aykut Bulut, and      *
22  *                          Ted Ralphs.                                      *
23  * All Rights Reserved.                                                      *
24  *===========================================================================*/
25 
26 
27 #ifndef AlpsParams_h_
28 #define AlpsParams_h_
29 
30 #include "AlpsKnowledge.h"
31 #include "AlpsParameterBase.h"
32 
33 // TODO: remove largeSize, mediumSize, smallSize
34 
35 //#############################################################################
36 
37 //class AlpsEncoded;
38 
39 //** Parameters used in Alps. */
40 class AlpsParams : public AlpsParameterSet {
41  public:
42   /** Character parameters. All of these variable are used as booleans
43       (ture = 1, false = 0). */
44   enum boolParams
45   {
46       /** Check memory.
47           Default: false */
48       checkMemory,
49       /** Remove dead nodes or not.
50           Default: true. */
51       deleteDeadNode,
52       /** Master balances the workload of hubs: centralized.
53           Default: true. */
54       interClusterBalance,
55       /** Hub balances the workload of workers: receiver initialized.
56           Default: true*/
57       intraClusterBalance,
58       /** Print solution to screen and log if have a solution and msgLevel and
59           logFileLevel permits.
60           Default: false. */
61       printSolution,
62       /***/
63       endOfBoolParams
64   };
65 
66   /** Integer paramters. */
67   enum intParams
68   {
69       /** The size of extra memory allocated to a message buffer.
70           Default: 256 byte */
71       bufSpare,
72       /** Type of clock when timing rampup, rampdown, etc.
73           CPU or Wallclock.
74           default: wallclock */
75       clockType,
76       /** Number of the "elite" nodes that are used in determining workload.
77           Default: 1 */
78       eliteSize,
79       /** The number of nodes initially generated by each hub.
80           Default: 2 */
81       hubInitNodeNum,
82       /** Message level of the hub specific messages.
83           (0: no print to screen; 1: summary; 2: moderate; 3: verbose)
84           Default: 0
85       */
86       hubMsgLevel,
87       /** The number of hubs.
88           Default: 1 */
89       hubNum,
90       /** The size of memory allocated for large size message.
91           Default: 10485760 */
92       largeSize,
93       /** The level of log file.
94           (0: no log file; 1: summary; 2: moderate; 3: verbose)
95           Default: 0 */
96       logFileLevel,
97       /** The number of nodes initially generated by the master.
98           Default: 2 */
99       masterInitNodeNum,
100       /** The interval between master report system status.
101           Default: 10 */
102       masterReportInterval,
103       /** If the number of processes in a cluster is less than it, the hub
104           also work as a worker.
105           Default: 0 (Hub does NOT work) */
106       hubWorkClusterSizeLimit,
107       /** The size of memory allocated for medium size message.
108           Default: 4096 */
109       mediumSize,
110       /** The level of printing messages on screen. Used to control master and
111           general messages.
112           (0: no print to screen; 1: summary; 2: moderate; 3: verbose)
113           Default: 2*/
114       msgLevel,
115       /** The max number of nodes can be processed.
116           Default: ALPS_INT_MAX */
117       nodeLimit,
118       /** Node log interval.
119           Default: 100 */
120       nodeLogInterval,
121       /** Print system status: 0: do not print, 1: print.
122           Default: 1;*/
123       printSystemStatus,
124       /** The total number of processes that are launched for parallel code.
125           Default: 2
126           Not used since can get actual number of processes from MPI. */
127       processNum,
128       /** Static load balancing scheme
129           -- root initialization (0)
130           -- spiral (1)
131       */
132       staticBalanceScheme,
133       /** Search strategy
134           -- best-first (0)
135           -- best-first-estimate (1)
136           -- breadth-first (2)
137           -- depth-first (3)
138           -- hybrid (4)
139           Default: hybrid
140       */
141       searchStrategy,
142       searchStrategyRampUp,
143       /** The size of memory allocated for small size message.
144           Default: 1024 */
145       smallSize,
146       /** The max num of solution can be stored in a solution pool.
147           Default: ALPS_INT_MAX */
148       solLimit,
149       /** The size/number of nodes of a unit work.
150           Default: 50 */
151       unitWorkNodes,
152       /** Message level of the worker specific messages.
153           (0: no print to screen; 1: summary; 2: moderate; 3: verbose)
154           Default: 0
155       */
156       workerMsgLevel,
157       ///
158       endOfIntParams
159   };
160 
161   /** Double parameters. */
162   enum dblParams
163   {
164       /** The threshold of workload below which a worker will change the subtree
165           that is working on.
166           Default: 0.05 */
167       changeWorkThreshold,
168       /** It is between 1.0 - infty. When the workload in process is more than
169           the average workload timing donorThreshold, it is a donor in load
170           balancing.
171           Defaut: 0.1 */
172       donorThreshold,
173       /** The time period (sec) for hubs to process messages.
174           Default: 0.1 */
175       hubReportPeriod,
176       /** The time period for master to do loading balance/termination check.
177           Default: 0.05 */
178       masterBalancePeriod,
179       /** The threshold of workload below which a process will ask for workload
180           Default: 2 */
181       needWorkThreshold,
182       /** It is between 0.0 - 1.0. When the workload in process is less than
183           the average workload timing receiverThreshold, it is a receiver.
184           Default: 0.1 */
185       receiverThreshold,
186       /** The time limit (in seconds) of search.
187           Default: ALPS_DBL_MAX */
188       timeLimit,
189       /** The numeric tolerance.
190           Default: 1e-6 */
191       tolerance,
192       /** The time length of a unit work.
193           Default: 0.5 */
194       unitWorkTime,
195       /** If less than this number, it is considered zero workload.
196           Default: 1e-6 */
197       zeroLoad,
198       /***/
199       endOfDblParams
200   };
201 
202   /** String parameters. */
203   enum strParams
204   {
205       /** The instance to be solved.
206           Default: "NONE" */
207       instance,
208       /** The name of log file.
209           Default: "Alps.log "*/
210       logFile,
211       ///
212       endOfStrParams
213   };
214 
215   /** There are no string array parameters. */
216   enum strArrayParams
217   {
218       // The dummy is needed so the allocation won't try for 0 entries.
219       strArrayDummy,
220       ///
221       endOfStrArrayParams
222   };
223 
224  public:
225 
226   /**@name Constructors. */
227   /*@{*/
228   /** The default constructor creates a parameter set with from the template
229       argument structure. The keyword list is created and the defaults are
230       set. */
AlpsParams()231   AlpsParams() :
232       AlpsParameterSet(
233           static_cast<int>(endOfBoolParams),
234           static_cast<int>(endOfIntParams),
235           static_cast<int>(endOfDblParams),
236           static_cast<int>(endOfStrParams),
237           static_cast<int>(endOfStrArrayParams)
238           )
239   {
240       createKeywordList();
241       setDefaultEntries();
242   }
243       /*@}*/
244 
~AlpsParams()245       virtual ~AlpsParams(){ /**/ }
246 
247 
248       AlpsParams& operator=(const AlpsParams& x) {
249           // no need to delete anything, since the size of (almost) everything is
250           // the same, just copy over
251           // -- The static_cast is needed to satisfy the more picky IBM Visual Age
252           //    C++ compiler
253           std::copy(x.bpar_, x.bpar_ + static_cast<int>(endOfBoolParams),
254                     bpar_);
255           std::copy(x.ipar_, x.ipar_ + static_cast<int>(endOfIntParams),
256                     ipar_);
257           std::copy(x.dpar_, x.dpar_ + static_cast<int>(endOfDblParams),
258                     dpar_);
259           std::copy(x.spar_, x.spar_ + static_cast<int>(endOfStrParams),
260                     spar_);
261           std::copy(x.sapar_,
262                     x.sapar_ + static_cast<int>(endOfStrArrayParams),
263                     sapar_);
264           return *this;
265       }
266 
267       /** Method for creating the list of keyword looked for in the parameter
268           file. */
269       virtual void createKeywordList();
270       /** Method for setting the default values for the parameters. */
271       virtual void setDefaultEntries();
272 
273 public:
274       //====================================================
275       /** For user's application:
276        *    Copy following code exactly (till the end of this class) and
277        *    do NOT change anything.
278        *
279        *  The reason can not put following functions in base class
280        *  <CODE> AlpsParameterSet </CODE> is:
281        *
282        *    <CODE> boolParams </CODE> and <CODE> endOfBoolParams </CODE> etc.
283        *    can NOT be declared in base class. They are different types for
284        *    each derived classes.
285        */
286       //====================================================
287 
288 
289       /**@name Query methods
290          The members of the parameter set can be queried for using the
291          overloaded entry() method. Using the example in the class
292          documentation the user can get a parameter with the
293          "<code>param.entry(USER_par::parameter_name)</code>" expression.
294       */
295       /*@{*/
296       ///
entry(const boolParams key)297       inline bool entry(const boolParams key) const { return bpar_[key]; }
298       ///
entry(const intParams key)299       inline int entry(const intParams key) const { return ipar_[key]; }
300       ///
entry(const dblParams key)301       inline double entry(const dblParams key) const { return dpar_[key]; }
302       ///
303       inline const std::string&
entry(const strParams key)304           entry(const strParams key) const { return spar_[key]; }
305       ///
306       inline const std::vector<std::string>&
entry(const strArrayParams key)307           entry(const strArrayParams key) const { return sapar_[key]; }
308       /*@}*/
309 
310       //----------------------------------------------------
311 
312       /// char* is true(1) or false(0), not used
setEntry(const boolParams key,const char * val)313       void setEntry(const boolParams key, const char * val) {
314                   bpar_[key] = atoi(val) ? true : false; }
315       /// char is true(1) or false(0), not used
setEntry(const boolParams key,const char val)316       void setEntry(const boolParams key, const char val) {
317                   bpar_[key] = val ? true : false; }
318       /// This method is the one that ever been used.
setEntry(const boolParams key,const bool val)319       void setEntry(const boolParams key, const bool val) {
320           bpar_[key] = val; }
321       ///
setEntry(const intParams key,const char * val)322       void setEntry(const intParams key, const char * val) {
323           ipar_[key] = atoi(val); }
324       ///
setEntry(const intParams key,const int val)325       void setEntry(const intParams key, const int val) {
326           ipar_[key] = val; }
327       ///
setEntry(const dblParams key,const char * val)328       void setEntry(const dblParams key, const char * val) {
329           dpar_[key] = atof(val); }
330       ///
setEntry(const dblParams key,const double val)331       void setEntry(const dblParams key, const double val) {
332           dpar_[key] = val; }
333       ///
setEntry(const strParams key,const char * val)334       void setEntry(const strParams key, const char * val) {
335           spar_[key] = val; }
336       ///
setEntry(const strArrayParams key,const char * val)337       void setEntry(const strArrayParams key, const char *val) {
338           sapar_[key].push_back(val); }
339 
340       //----------------------------------------------------
341 
342       /**@name Packing/unpacking methods */
343       /*@{*/
344       /** Pack the parameter set into buf. */
pack(AlpsEncoded & buf)345       void pack(AlpsEncoded& buf) {
346           buf.writeRep(bpar_, endOfBoolParams)
347               .writeRep(ipar_, endOfIntParams)
348               .writeRep(dpar_, endOfDblParams);
349           for (int i = 0; i < endOfStrParams; ++i)
350               buf.writeRep(spar_[i]);
351           for (int i = 0; i < endOfStrArrayParams; ++i) {
352               buf.writeRep(sapar_[i].size());
353               for (size_t j = 0; j < sapar_[i].size(); ++j)
354                   buf.writeRep(sapar_[i][j]);
355           }
356       }
357 
358       /** Unpack the parameter set from buf. */
unpack(AlpsEncoded & buf)359       void unpack(AlpsEncoded& buf) {
360           int dummy;
361           // No need to allocate the arrays, they are of fixed length
362           dummy = static_cast<int>(endOfBoolParams);
363           buf.readRep(bpar_, dummy, false);
364           dummy = static_cast<int>(endOfIntParams);
365           buf.readRep(ipar_, dummy, false);
366           dummy = static_cast<int>(endOfDblParams);
367           buf.readRep(dpar_, dummy, false);
368           for (int i = 0; i < endOfStrParams; ++i)
369               buf.readRep(spar_[i]);
370           for (int i = 0; i < endOfStrArrayParams; ++i) {
371               size_t str_size;
372               buf.readRep(str_size);
373               sapar_[i].reserve(str_size);
374               for (size_t j = 0; j < str_size; ++j){
375                   //	sapar_[i].unchecked_push_back(std::string());
376                   sapar_[i].push_back(std::string());
377                   buf.readRep(sapar_[i].back());
378               }
379           }
380       }
381       /*@}*/
382 };
383 
384 #endif
385