source: branches/dev/Common/IpRegOptions.hpp @ 501

Last change on this file since 501 was 501, checked in by claird, 15 years ago

Cleaned up all the Copyright comments.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 20.9 KB
Line 
1// Copyright (C) 2004, 2005 International Business Machines and others.
2// All Rights Reserved.
3// This code is published under the Common Public License.
4//
5// $Id: IpRegOptions.hpp 501 2005-08-26 15:43:07Z claird $
6//
7// Authors:  Carl Laird, Andreas Waechter     IBM    2005-06-18
8
9#ifndef __IPREGOPTIONS_HPP__
10#define __IPREGOPTIONS_HPP__
11
12#include "IpUtils.hpp"
13#include "IpReferenced.hpp"
14#include "IpException.hpp"
15#include "IpSmartPtr.hpp"
16#include <map>
17
18#ifdef OLD_C_HEADERS
19# include <stdio.h>
20#else
21# include <cstdio>
22#endif
23
24namespace Ipopt
25{
26
27  enum RegisteredOptionType
28  {
29    OT_Number,
30    OT_Integer,
31    OT_String,
32    OT_Unknown
33  };
34
35  /** Base class for registered options. The derived types are more
36   *  specific to a string option or a Number (real) option, etc.
37   */
38  class RegisteredOption : public ReferencedObject
39  {
40  public:
41    /** Constructors / Destructors */
42    //@{
43    RegisteredOption()
44        :
45        type_(OT_Unknown),
46        has_lower_(false),
47        has_upper_(false),
48        counter_(0)
49    {}
50
51    RegisteredOption(const std::string& name,
52                     const std::string& short_description,
53                     const std::string& long_description,
54                     const std::string& registering_category)
55        :
56        name_(name),
57        short_description_(short_description),
58        long_description_(long_description),
59        registering_category_(registering_category),
60        type_(OT_Unknown),
61        has_lower_(false),
62        has_upper_(false),
63        counter_(next_counter_++)
64    {}
65
66    RegisteredOption(const RegisteredOption& copy)
67        :
68        name_(copy.name_),
69        short_description_(copy.short_description_),
70        long_description_(copy.long_description_),
71        registering_category_(copy.registering_category_),
72        type_(copy.type_),
73        has_lower_(copy.has_lower_),
74        lower_(copy.lower_),
75        has_upper_(copy.has_upper_),
76        upper_(copy.upper_),
77        valid_strings_(copy.valid_strings_),
78        counter_(copy.counter_)
79    {}
80
81    virtual ~RegisteredOption()
82    {}
83    //@}
84
85    DECLARE_STD_EXCEPTION(ERROR_CONVERTING_STRING_TO_ENUM);
86
87    /** Standard Get / Set Methods */
88    //@{
89    /** Get the option's name (tag in the input file) */
90    const std::string& Name() const
91    {
92      return name_;
93    }
94    /** Set the option's name (tag in the input file) */
95    void SetName(const std::string& name)
96    {
97      name_ = name;
98    }
99    /** Get the short description */
100    const std::string& ShortDescription() const
101    {
102      return short_description_;
103    }
104    /** Get the long description */
105    const std::string& LongDescription() const
106    {
107      return long_description_;
108    }
109    /** Set the short description */
110    void SetShortDescription(const std::string& short_description)
111    {
112      short_description_ = short_description;
113    }
114    /** Set the long description */
115    void SetLongDescription(const std::string& long_description)
116    {
117      long_description_ = long_description;
118    }
119    /** Get the registering class */
120    const std::string& RegisteringCategory() const
121    {
122      return registering_category_;
123    }
124    /** Set the registering class */
125    void SetRegisteringCategory(const std::string& registering_category)
126    {
127      registering_category_ = registering_category;
128    }
129    /** Get the Option's type */
130    const RegisteredOptionType& Type() const
131    {
132      return type_;
133    }
134    /** Get the Option's type */
135    void SetType(const RegisteredOptionType& type)
136    {
137      type_ = type;
138    }
139    /** Counter */
140    Index Counter() const
141    {
142      return counter_;
143    }
144    //@}
145
146    /** @name Get / Set methods valid for specific types - NOTE: the Type
147     *  must be set before calling these methods.
148     */
149    //@{
150    /** check if the option has a lower bound - can be called for
151     *  OT_Number & OT_Integer*/
152    const bool& HasLower() const
153    {
154      DBG_ASSERT(type_ == OT_Number || type_ == OT_Integer);
155      return has_lower_;
156    }
157    /** check if the lower bound is strict - can be called for
158    OT_Number */
159    const bool& LowerStrict() const
160    {
161      DBG_ASSERT(type_ == OT_Number && has_lower_ == true);
162      return lower_strict_;
163    }
164    /** get the Number version of the lower bound - can be called for
165     *  OT_Number */
166    Number LowerNumber() const
167    {
168      DBG_ASSERT(has_lower_ == true && type_ == OT_Number);
169      return lower_;
170    }
171    /** set the Number version of the lower bound - can be called for
172     *  OT_Number */
173    void SetLowerNumber(const Number& lower, const bool& strict)
174    {
175      DBG_ASSERT(type_ == OT_Number);
176      lower_ = lower;
177      lower_strict_ = strict, has_lower_ = true;
178    }
179    /** get the Integer version of the lower bound can be called for
180     *  OT_Integer*/
181    Index LowerInteger() const
182    {
183      DBG_ASSERT(has_lower_ == true && type_ == OT_Integer);
184      return (Index)lower_;
185    }
186    /** set the Integer version of the lower bound - can be called for
187     *  OT_Integer */
188    void SetLowerInteger(const Index& lower)
189    {
190      DBG_ASSERT(type_ == OT_Integer);
191      lower_ = (Number)lower;
192      has_lower_ = true;
193    }
194    /** check if the option has an upper bound - can be called for
195     *  OT_Number & OT_Integer*/
196    const bool& HasUpper() const
197    {
198      DBG_ASSERT(type_ == OT_Number || type_ == OT_Integer);
199      return has_upper_;
200    }
201    /** check if the upper bound is strict - can be called for
202     *  OT_Number */
203    const bool& UpperStrict() const
204    {
205      DBG_ASSERT(type_ == OT_Number && has_upper_ == true);
206      return upper_strict_;
207    }
208    /** get the Number version of the upper bound - can be called for
209     *  OT_Number */
210    Number UpperNumber()
211    {
212      DBG_ASSERT(has_upper_ == true && type_ == OT_Number);
213      return upper_;
214    }
215    /** set the Number version of the upper bound - can be called for
216     *  OT_Number */
217    void SetUpperNumber(const Number& upper, const bool& strict)
218    {
219      DBG_ASSERT(type_ == OT_Number);
220      upper_ = upper;
221      upper_strict_ = strict;
222      has_upper_ = true;
223    }
224    /** get the Integer version of the upper bound - can be called for
225     *  OT_Integer*/
226    Index UpperInteger() const
227    {
228      DBG_ASSERT(has_upper_ == true && type_ == OT_Integer);
229      return (Index)upper_;
230    }
231    /** set the Integer version of the upper bound - can be called for
232     *  OT_Integer */
233    void SetUpperInteger(const Index& upper)
234    {
235      DBG_ASSERT(type_ == OT_Integer);
236      upper_ = (Number)upper;
237      has_upper_ = true;
238    }
239    /** method to add valid string entries - can be called for
240     *  OT_String */
241    void AddValidStringSetting(const std::string value,
242                               const std::string description)
243    {
244      DBG_ASSERT(type_ == OT_String);
245      valid_strings_.push_back(string_entry(value, description));
246    }
247    /** get the default as a Number - can be called for OT_Number */
248    Number DefaultNumber() const
249    {
250      DBG_ASSERT(type_ == OT_Number);
251      return default_number_;
252    }
253    /** Set the default as a Number - can be called for OT_Number */
254    void SetDefaultNumber(const Number& default_value)
255    {
256      DBG_ASSERT(type_ == OT_Number);
257      default_number_ = default_value;
258    }
259    /** get the default as an Integer - can be called for OT_Integer*/
260    Index DefaultInteger() const
261    {
262      DBG_ASSERT(type_ == OT_Integer);
263      return (Index)default_number_;
264    }
265    /** Set the default as an Integer - can be called for
266    OT_Integer */
267    void SetDefaultInteger(const Index& default_value)
268    {
269      DBG_ASSERT(type_ == OT_Integer);
270      default_number_ = (Number)default_value;
271    }
272    /** get the default as a string - can be called for OT_String */
273    std::string DefaultString() const
274    {
275      DBG_ASSERT(type_ == OT_String);
276      return default_string_;
277    }
278    /** get the default as a string, but as the index of the string in
279     *  the list - helps map from a string to an enum- can be called
280     *  for OT_String */
281    Index DefaultStringAsEnum() const
282    {
283      DBG_ASSERT(type_ == OT_String);
284      return MapStringSettingToEnum(default_string_);
285    }
286    /** Set the default as a string - can be called for OT_String */
287    void SetDefaultString(const std::string& default_value)
288    {
289      DBG_ASSERT(type_ == OT_String);
290      default_string_ = default_value;
291    }
292    /** Check if the Number value is a valid setting - can be called
293     *  for OT_Number */
294    bool IsValidNumberSetting(const Number& value) const
295    {
296      DBG_ASSERT(type_ == OT_Number);
297      if (has_lower_ && ((lower_strict_ == true && value <= lower_) ||
298                         (lower_strict_ == false && value < lower_))) {
299        return false;
300      }
301      if (has_upper_ && ((upper_strict_ == true && value >= upper_) ||
302                         (upper_strict_ == false && value > upper_))) {
303        return false;
304      }
305      return true;
306    }
307    /** Check if the Integer value is a valid setting - can be called
308     *  for OT_Integer */
309    bool IsValidIntegerSetting(const Index& value) const
310    {
311      DBG_ASSERT(type_ == OT_Integer);
312      if (has_lower_ && value < lower_) {
313        return false;
314      }
315      if (has_upper_ && value > upper_) {
316        return false;
317      }
318      return true;
319    }
320    /** Check if the String value is a valid setting - can be called
321     *  for OT_String */
322    bool IsValidStringSetting(const std::string& value) const;
323
324    /** Map a user setting (allowing any case) to the case used when
325     *  the setting was registered.
326     */
327    std::string MapStringSetting(const std::string& value) const;
328
329    /** Map a user setting (allowing any case) to the index of the
330     *  matched setting in the list of string settings. Helps map a
331     *  string setting to an enumeration.
332     */
333    Index MapStringSettingToEnum(const std::string& value) const;
334    //@}
335
336    /** output a description of the option */
337    void OutputDescription(const Journalist& jnlst) const;
338    /** output a more concise version */
339    void OutputShortDescription(const Journalist& jnlst) const;
340    /** output a latex version */
341    void OutputLatexDescription(const Journalist& jnlst) const;
342
343  private:
344    std::string name_;
345    std::string short_description_;
346    std::string long_description_;
347    std::string registering_category_;
348    RegisteredOptionType type_;
349
350    bool has_lower_;
351    bool lower_strict_;
352    Number lower_;
353    bool has_upper_;
354    bool upper_strict_;
355    Number upper_;
356    Number default_number_;
357
358    void MakeValidLatexString(std::string source, std::string& dest) const;
359    std::string MakeValidLatexNumber(Number value) const;
360
361    /** Compare two strings and return true if they are equal (case
362    insensitive comparison) */
363    bool string_equal_insensitive(const std::string& s1,
364                                  const std::string& s2) const;
365
366    /** class to hold the valid string settings for a string option */
367    class string_entry
368    {
369    public:
370      string_entry(const std::string& value, const std::string& description)
371          : value_(value), description_(description)
372      {}
373      std::string value_;
374      std::string description_;
375    };
376
377    std::vector<string_entry> valid_strings_;
378    std::string default_string_;
379
380    /** Has the information as how many-th option this one was
381     *  registered. */
382    const Index counter_;
383
384    static Index next_counter_;
385  };
386
387  /** Class for storing registered options. Used for validation and
388   *  documentation.
389   */
390  class RegisteredOptions : public ReferencedObject
391  {
392  public:
393    /** Constructors / Destructors */
394    //@{
395    /** Standard Constructor */
396    RegisteredOptions()
397        :
398        current_registering_category_("Uncategorized")
399    {}
400
401    /** Standard Destructor */
402    ~RegisteredOptions()
403    {}
404    //@}
405
406    DECLARE_STD_EXCEPTION(OPTION_ALREADY_REGISTERED);
407
408    /** Methods to interact with registered options */
409    //@{
410    /** set the registering class. All subsequent options will be
411     *  added with the registered class */
412    void SetRegisteringCategory(const std::string& registering_category)
413    {
414      current_registering_category_ = registering_category;
415    }
416
417    /** retrieve the value of the current registering category */
418    std::string RegisteringCategory()
419    {
420      return current_registering_category_;
421    }
422
423    /** Add a Number option (with no restrictions) */
424    void AddNumberOption(const std::string& name,
425                         const std::string& short_description,
426                         Number default_value,
427                         const std::string& long_description="");
428    /** Add a Number option (with a lower bound) */
429    void AddLowerBoundedNumberOption(const std::string& name,
430                                     const std::string& short_description,
431                                     Number lower, bool strict,
432                                     Number default_value,
433                                     const std::string& long_description="");
434    /** Add a Number option (with a upper bound) */
435    void AddUpperBoundedNumberOption(const std::string& name,
436                                     const std::string& short_description,
437                                     Number upper, bool strict,
438                                     Number default_value,
439                                     const std::string& long_description="");
440    /** Add a Number option (with a both bounds) */
441    void AddBoundedNumberOption(const std::string& name,
442                                const std::string& short_description,
443                                Number lower, bool lower_strict,
444                                Number upper, bool upper_strict,
445                                Number default_value,
446                                const std::string& long_description="");
447    /** Add a Integer option (with no restrictions) */
448    void AddIntegerOption(const std::string& name,
449                          const std::string& short_description,
450                          Index default_value,
451                          const std::string& long_description="");
452    /** Add a Integer option (with a lower bound) */
453    void AddLowerBoundedIntegerOption(const std::string& name,
454                                      const std::string& short_description,
455                                      Index lower, Index default_value,
456                                      const std::string& long_description="");
457    /** Add a Integer option (with a upper bound) */
458    void AddUpperBoundedIntegerOption(const std::string& name,
459                                      const std::string& short_description,
460                                      Index upper, Index default_value,
461                                      const std::string& long_description="");
462    /** Add a Integer option (with a both bounds) */
463    void AddBoundedIntegerOption(const std::string& name,
464                                 const std::string& short_description,
465                                 Index lower, Index upper,
466                                 Index default_value,
467                                 const std::string& long_description="");
468
469    /** Add a String option (with no restrictions) */
470    void AddStringOption(const std::string& name,
471                         const std::string& short_description,
472                         const std::string& default_value,
473                         const std::vector<std::string>& settings,
474                         const std::vector<std::string>& descriptions,
475                         const std::string& long_description="");
476    /** Methods that make adding string options with only a few
477     *  entries easier */
478    void AddStringOption1(const std::string& name,
479                          const std::string& short_description,
480                          const std::string& default_value,
481                          const std::string& setting1,
482                          const std::string& description1,
483                          const std::string& long_description="");
484    void AddStringOption2(const std::string& name,
485                          const std::string& short_description,
486                          const std::string& default_value,
487                          const std::string& setting1,
488                          const std::string& description1,
489                          const std::string& setting2,
490                          const std::string& description2,
491                          const std::string& long_description="");
492    void AddStringOption3(const std::string& name,
493                          const std::string& short_description,
494                          const std::string& default_value,
495                          const std::string& setting1,
496                          const std::string& description1,
497                          const std::string& setting2,
498                          const std::string& description2,
499                          const std::string& setting3,
500                          const std::string& description3,
501                          const std::string& long_description="");
502    void AddStringOption4(const std::string& name,
503                          const std::string& short_description,
504                          const std::string& default_value,
505                          const std::string& setting1,
506                          const std::string& description1,
507                          const std::string& setting2,
508                          const std::string& description2,
509                          const std::string& setting3,
510                          const std::string& description3,
511                          const std::string& setting4,
512                          const std::string& description4,
513                          const std::string& long_description="");
514    void AddStringOption5(const std::string& name,
515                          const std::string& short_description,
516                          const std::string& default_value,
517                          const std::string& setting1,
518                          const std::string& description1,
519                          const std::string& setting2,
520                          const std::string& description2,
521                          const std::string& setting3,
522                          const std::string& description3,
523                          const std::string& setting4,
524                          const std::string& description4,
525                          const std::string& setting5,
526                          const std::string& description5,
527                          const std::string& long_description="");
528    void AddStringOption6(const std::string& name,
529                          const std::string& short_description,
530                          const std::string& default_value,
531                          const std::string& setting1,
532                          const std::string& description1,
533                          const std::string& setting2,
534                          const std::string& description2,
535                          const std::string& setting3,
536                          const std::string& description3,
537                          const std::string& setting4,
538                          const std::string& description4,
539                          const std::string& setting5,
540                          const std::string& description5,
541                          const std::string& setting6,
542                          const std::string& description6,
543                          const std::string& long_description="");
544    void AddStringOption7(const std::string& name,
545                          const std::string& short_description,
546                          const std::string& default_value,
547                          const std::string& setting1,
548                          const std::string& description1,
549                          const std::string& setting2,
550                          const std::string& description2,
551                          const std::string& setting3,
552                          const std::string& description3,
553                          const std::string& setting4,
554                          const std::string& description4,
555                          const std::string& setting5,
556                          const std::string& description5,
557                          const std::string& setting6,
558                          const std::string& description6,
559                          const std::string& setting7,
560                          const std::string& description7,
561                          const std::string& long_description="");
562
563    /** Get a registered option - this will return NULL if the option
564     *  does not exist */
565    SmartPtr<const RegisteredOption> GetOption(const std::string& name);
566
567    /** Output documentation for the options - gives a description,
568     *  etc. */
569    void OutputOptionDocumentation(const Journalist& jnlst, std::list<std::string>& categories);
570
571    /** Output documentation in Latex format to include in a latex file */
572    void OutputLatexOptionDocumentation(const Journalist& jnlst, std::list<std::string>& categories);
573    //@}
574
575  private:
576    std::string current_registering_category_;
577    std::map<std::string, SmartPtr<RegisteredOption> > registered_options_;
578  };
579} // namespace Ipopt
580
581#endif
Note: See TracBrowser for help on using the repository browser.