1 // $Id: HOPSPACK_ParameterList.hpp 203 2012-05-14 22:27:30Z tplante $ 2 // $URL: https://software.sandia.gov/svn/hopspack/trunk/src/src-shared/HOPSPACK_ParameterList.hpp $ 3 4 //@HEADER 5 // ************************************************************************ 6 // 7 // HOPSPACK: Hybrid Optimization Parallel Search Package 8 // Copyright 2009 Sandia Corporation 9 // 10 // Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation, 11 // the U.S. Government retains certain rights in this software. 12 // 13 // This file is part of HOPSPACK. 14 // 15 // HOPSPACK is free software; you can redistribute it and/or modify 16 // it under the terms of the GNU Lesser General Public License as 17 // published by the Free Software Foundation; either version 2.1 of the 18 // License, or (at your option) any later version. 19 // 20 // This library is distributed in the hope that it will be useful, but 21 // WITHOUT ANY WARRANTY; without even the implied warranty of 22 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 23 // Lesser General Public License for more details. 24 // 25 // You should have received a copy of the GNU Lesser General Public 26 // License along with this library. If not, see http://www.gnu.org/licenses/. 27 // 28 // Questions? Contact Tammy Kolda (tgkolda@sandia.gov) 29 // or Todd Plantenga (tplante@sandia.gov) 30 // 31 // ************************************************************************ 32 //@HEADER 33 34 /*! 35 \file HOPSPACK_ParameterList.hpp 36 \brief Class declaration of HOPSPACK::ParameterList. 37 */ 38 39 #ifndef HOPSPACK_PARAMETER_LIST_HPP 40 #define HOPSPACK_PARAMETER_LIST_HPP 41 42 #include <map> 43 44 #include "HOPSPACK_common.hpp" 45 #include "HOPSPACK_ParameterEntry.hpp" 46 #include "HOPSPACK_Matrix.hpp" 47 48 #if defined(HAVE_MPI) 49 #include "HOPSPACK_GenProcComm.hpp" 50 #endif 51 52 53 namespace HOPSPACK { 54 55 //! Contains a set of user parameters. 56 /*! A ParameterList stores a set of parameters, optionally organized in 57 sublists. Each parameter has a name and a ParameterEntry. The name is a string, 58 case-sensitive. The ParameterEntry is itself a ParameterList (a sublist) 59 or a bool, int, double, string, Vector, or Matrix. 60 Each ParameterEntry keeps track of whether it was set to be the default value 61 or set by the input, and whether or not it has been used (i.e., accessed by 62 a get method). 63 */ 64 65 class ParameterList { 66 67 public: 68 69 70 //! Constructor 71 ParameterList(); 72 73 //! Copy constructor (deep copy) 74 ParameterList(const ParameterList& source); 75 76 //! Copy (deep copy) 77 ParameterList& operator=(const ParameterList& source); 78 79 //! Destructor 80 ~ParameterList(); 81 82 //------------------------- 83 /** @name Sublists 84 85 The entries in a parameter list can be organized into sublists. 86 87 */ 88 //@{ 89 90 //! Create a new sublist \b or return the sublist if it already exists. 91 /*! 92 Creates an empty sublist and returns a reference to the 93 sublist. If the list already exists, returns a reference to that 94 sublist. If the name exists but is not a sublist, throws an error. 95 */ 96 ParameterList& getOrSetSublist(const string& name); 97 98 //! Returns a const reference to the sublist, or throws an error. 99 /*! 100 If the name is not found, then an empty list is returned. 101 If the name exists but is not a sublist, throws an error. 102 */ 103 const ParameterList& sublist(const string& name) const; 104 //@} 105 106 107 //------------------------- 108 /** @name Setting Parameters 109 110 Methods to set parameters in a ParameterList. Each parameter has a name and 111 a value which is either bool, int, double, string, Vector, or Matrix. 112 Any previous value is overwritten. 113 114 If necessary, use static_cast<type>() to resolve the type when its 115 ambiguous. For example, 116 117 \code 118 ParameterList list; 119 list.setParameter("some name", static_cast<double>(0)) 120 \endcode 121 122 creates a double parameter named "some name" with a value of zero. 123 124 Both char* and string are stored as strings internally. 125 126 Sets "Default" to false. 127 */ 128 //@{ 129 130 //! Set a bool parameter 131 void setParameter(const string& name, bool value); 132 133 //! Set an int parameter 134 void setParameter(const string& name, int value); 135 136 //! Set a double parameter 137 void setParameter(const string& name, double value); 138 139 //! Set a string parameter 140 void setParameter(const string& name, const char* value); 141 142 //! Set a string parameter 143 void setParameter(const string& name, const string& value); 144 145 //! Set a character vector parameter 146 void setParameter(const string& name, const vector< char > value); 147 148 //! Set a Vector parameter 149 void setParameter(const string& name, const Vector& value); 150 151 //! Set a Matrix parameter 152 void setParameter(const string& name, const Matrix& value); 153 //@} 154 155 156 /** @name Getting Parameters 157 158 Get the value of a parameter from the list. Returns the nominal 159 value if the parameter is not already specified. 160 161 Caller should use static_cast<type>() when the type is ambiguous. 162 163 Both char* and string map return string values. 164 */ 165 //@{ 166 167 //! Get a bool parameter - no change to the list 168 bool getParameter(const string& name, bool nominal) const; 169 170 //! Get an int parameter - no change to the list 171 int getParameter(const string& name, int nominal) const; 172 173 //! Get a double parameter - no change to the list 174 double getParameter(const string& name, double nominal) const; 175 176 //! Get a string parameter - no change to the list 177 const string& getParameter(const string& name, const char* nominal) const; 178 179 //! Get a string parameter - no change to the list 180 const string& getParameter(const string& name, const string& nominal) const; 181 182 //! Get a Vector parameter - no change to the list 183 const Vector& getParameter(const string& name, const Vector& nominal) const; 184 185 //@} 186 187 /** @name GetOrSet Parameters 188 189 Get the value of a parameter from the list, or add the nominal value 190 to the list if the parameter is not already specified (also setting "Default" 191 to true). 192 193 Use static_cast<type>() when the type is ambiguous. 194 195 Both char* and string map return string values. 196 */ 197 //@{ 198 199 //! Get a bool parameter 200 bool getOrSetParameter(const string& name, bool nominal); 201 202 //! Get an int parameter 203 int getOrSetParameter(const string& name, int nominal); 204 205 //! Get a double parameter 206 double getOrSetParameter(const string& name, double nominal); 207 208 //! Get a string parameter 209 const string& getOrSetParameter(const string& name, const char* nominal); 210 211 //! Get a string parameter 212 const string& getOrSetParameter(const string& name, const string& nominal); 213 214 //@} 215 216 /** @name Getting Parameters Without Nominal Value 217 218 Get the value of a parameter from the list. Throws an error if the parameter 219 does not exist or is not the correct type. 220 */ 221 //@{ 222 223 //! Get a double parameter - no change to the list 224 double getDoubleParameter(const string& name) const; 225 226 //! Get a character vector parameter - no change to the list 227 const vector< char > & getCharVecParameter(const string& name) const; 228 229 //! Get a Vector parameter - no change to the list 230 const Vector& getVectorParameter(const string& name) const; 231 232 //! Get a Matrix parameter - no change to the list 233 const Matrix& getMatrixParameter(const string& name) const; 234 //@} 235 236 /** @name Checking parameter existence. 237 238 Returns true if the specified parameter exists AND is of the 239 specified type. 240 */ 241 //@{ 242 243 //! Return true if a parameter with this name exists. 244 bool isParameter(const string& name) const; 245 246 //! Return true if a bool parameter with this name exists 247 bool isParameterBool(const string& name) const; 248 249 //! Return true if an int parameter with this name exists 250 bool isParameterInt(const string& name) const; 251 252 //! Return true if a double parameter with this name exists 253 bool isParameterDouble(const string& name) const; 254 255 //! Return true if a string parameter with this name exists 256 bool isParameterString(const string& name) const; 257 258 //! Return true if a character vector parameter with this name exists 259 bool isParameterCharVec(const string& name) const; 260 261 //! Return true if a sublist with this name exists 262 bool isParameterSublist(const string& name) const; 263 264 //! Return true if a Value parameter with this name exists 265 bool isParameterValue(const string& name) const; 266 267 //! Return true if a Vector parameter with this name exists 268 bool isParameterVector(const string& name) const; 269 270 //! Return true if a Matrix parameter with this name exists 271 bool isParameterMatrix(const string& name) const; 272 //@} 273 274 //@{ \name Deleting Parameters 275 276 //! Delete the parameter if it exists. 277 void deleteParameter(const string& name); 278 279 //@} 280 281 //@{ \name Printing 282 283 //! Pretty-print a list. Indents sublists. 284 ostream& print(ostream& stream = cout, int indent = 0) const; 285 286 //@} 287 288 289 #if defined(HAVE_MPI) 290 /** @name Pack/Unpack for Inter-Process Communication 291 292 These methods work in conjunction with MPI or PVM objects. 293 */ 294 295 //@{ 296 297 //! Pack for MPI transmission 298 void pack (GenProcComm &) const; 299 300 //! Unpack from MPI transmission 301 void unpack (GenProcComm &); 302 303 //@} 304 #endif //-- HAVE_MPI 305 306 307 private: 308 309 //! Parameter container typedef 310 typedef map<string, ParameterEntry> Map; 311 312 //! Parameter container const iterator typedef 313 typedef Map::const_iterator ConstIterator; 314 315 //! Parameter container iterator typedef 316 typedef Map::iterator Iterator; 317 318 319 //! Access to name (i.e., returns i->first) 320 const string& name(ConstIterator i) const; 321 322 //! Access to ParameterEntry (i.e., returns i->second) 323 ParameterEntry& entry(Iterator i); 324 325 //! Access to ParameterEntry (i.e., returns i->second) 326 const ParameterEntry& entry(ConstIterator i) const; 327 328 329 //! Parameter list 330 Map params; 331 332 //! Used to create a string when the getParameter is called with a 333 //! char* nominal value. A new string is created for each such 334 //! argument. The whole group of strings is destroyed when this object 335 //! is destroyed. This is really annoying, but I don't know a better 336 //! way. 337 mutable vector<string> tmpstrings; 338 }; 339 340 } // namespace HOPSPACK 341 342 #endif 343 344 345