Xyce  6.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
N_DEV_Pars.h
Go to the documentation of this file.
1 //-----------------------------------------------------------------------------
2 // Copyright Notice
3 //
4 // Copyright 2002 Sandia Corporation. Under the terms
5 // of Contract DE-AC04-94AL85000 with Sandia Corporation, the U.S.
6 // Government retains certain rights in this software.
7 //
8 // Xyce(TM) Parallel Electrical Simulator
9 // Copyright(C) 2002-2011 Sandia Corporation
10 //
11 // This program is free software: you can redistribute it and/or modify
12 // it under the terms of the GNU General Public License as published by
13 // the Free Software Foundation, either version 3 of the License, or
14 // (at your option) any later version.
15 //
16 // This program is distributed in the hope that it will be useful,
17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 // GNU General Public License for more details.
20 //
21 // You should have received a copy of the GNU General Public License
22 // along with this program. If not, see <http://www.gnu.org/licenses/>.
23 //-----------------------------------------------------------------------------
24 
25 //-------------------------------------------------------------------------
26 // Filename : $RCSfile: N_DEV_Pars.h,v $
27 //
28 // Purpose :
29 //
30 // Special Notes :
31 //
32 // Creator : Netlist device and model parameter management
33 //
34 // Creation Date : 2013/04/18 18:01:27
35 //
36 // Revision Information:
37 // ---------------------
38 //
39 // Revision Number: $Revision: 1.25.2.1 $
40 //
41 // Revision Date : $Date: 2014/08/13 20:36:35 $
42 //
43 // Current Owner : $Author: dgbaur $
44 //-------------------------------------------------------------------------
45 
46 #ifndef Xyce_N_DEV_Pars_h
47 #define Xyce_N_DEV_Pars_h
48 
49 #include <Sacado.hpp>
50 #include <algorithm>
51 #include <map>
52 #include <set>
53 #include <sstream>
54 #include <string>
55 #include <vector>
56 
57 #include <N_DEV_fwd.h>
58 #include <N_DEV_Units.h>
59 
60 ///
61 /// ParameterType::ExprAccess is enumeration of parameter usage types and masks
62 ///
63 namespace ParameterType {
65  {
66  NO_DEP = 0x0, ///< Parameter can only be set to a constant from netlist
67  TIME_DEP = 0x1, ///< Parameter may be specified as time dependent expression from netlist
68  SOLN_DEP = 0x2, ///< Parameter may be specified as a solution dependent expression from netlist
69  LOG_T_DEP = 0x8, ///< Parameter uses temperature interpolation based on log of value
70  MIN_RES = 0x10, ///< Parameter is subject to being set to minimum lead resistance
71  MIN_CAP = 0x20, ///< Parameter is subject to being set to minimum junction capacitance
72  NO_DOC = 0x40 ///< Parameter is not to be documented
73  };
74 };
75 
76 using namespace ParameterType;
77 
78 
79 namespace Xyce {
80 namespace Device {
81 
82 ///
83 /// @addtogroup xyce_device_parameters_detail
84 ///
85 /// @brief
86 ///
87 /// Device models, device instances and composite parameters are
88 /// collectively called an <b>entity</b>, which are all derived from
89 /// the ParameterBase tag class, and manage the mapping from a
90 /// parameter's string name to a member variable in each created
91 /// entity object. The mapping is refered to as parameter binding and
92 /// the object's bound member variable is refered to as the parameter
93 /// member variable. The object may have an additional member
94 /// variable for each binding that indicates if the value was
95 /// specified in the netlist device and is known as the given member
96 /// variable.
97 ///
98 /// Each class of entity has a ParametricData<T> class, where T is the
99 /// entity class, and a singleton object of that class. This
100 /// singleton manages the parameter binding. A parameter descriptor,
101 /// Descriptor, has the parameter member variable pointer for entity
102 /// object of type T that sets and retrieves the current value of an
103 /// entity's member variable using the parameters string name.
104 ///
105 /// The Descriptor maintains other information about the parameter.
106 /// It has a serial number for each parameter and a boolean member
107 /// variable pointer that determines if the parameter has been given
108 /// in the netlist. The given value map, GivenValueMap, is a mapping
109 /// from entity object pointer and serial number to a boolean given
110 /// member varaible indicating if the parameter was provided by the
111 /// netlist.
112 ///
113 /// Any entity may also wish to restore a parameter member variable
114 /// value to the value originally set during initialization. The
115 /// Descriptor maintains an index into an original value map to store
116 /// and retrieve the parameters original value. The original value
117 /// map, OriginalValueMap, is a mapping from entity object pointer and
118 /// original value index to the parameter's origin value. If the
119 /// original value index is -1, then no original value information is
120 /// maintained.
121 ///
122 /// A parameter may also be vectorized, allowing it to maintain a
123 /// vector values. The Descriptor maintains that vector length.
124 ///
125 /// A parameter has specific usages as described by the
126 /// ParameterType::ExprAccess enumeration.
127 ///
128 /// A parameter may also serves as an aggregation of parametric values
129 /// which is stored as a composite parameter, CompositeParam, entity.
130 ///
131 /// And a parameter has units, a documentation category and a
132 /// documentation description.
133 ///
134 /// Entity - DeviceModel, DeviceInstance or CompositeParam
135 ///
136 /// Given - flag and possibly and entity member variable that
137 /// indicates if a parameter was given in the netlist.
138 ///
139 /// OriginalValue - parameters value after initialization
140 ///
141 
142 typedef std::map<std::string, CompositeParam *> CompositeMap;
143 typedef std::map<int, double> OriginalValueMap;
144 typedef std::set<int> GivenValueSet;
145 
146 class Descriptor;
147 
148 typedef std::map<std::string, Descriptor *, LessNoCase> ParameterMap;
149 
150 class ParameterBase;
151 ///
152 /// Base sensitivity functor
153 ///
155 {
156 public:
158  virtual ~baseSensitivity() {}
159 
160  virtual void operator()(
161  const ParameterBase &entity,
162  const std::string &param,
163  std::vector<double> & dfdp,
164  std::vector<double> & dqdp,
165  std::vector<double> & dbdp,
166  std::vector<int> & Findices,
167  std::vector<int> & Qindices,
168  std::vector<int> & Bindices
169  ) const =0;
170 };
171 
172 ///
173 /// Base class for all parameters
174 ///
176 {
177 public:
179  : originalValueMap_(),
180  givenValueSet_()
181  {}
182 
183  virtual ~ParameterBase()
184  {}
185 
186 private:
187  ParameterBase(const ParameterBase &);
188  ParameterBase &operator=(const ParameterBase &);
189 
190 public:
191  double getOriginalValue(int serial_number)
192  {
193  return originalValueMap_[serial_number];
194  }
195 
196  void setOriginalValue(int serial_number, double value)
197  {
198  originalValueMap_[serial_number] = value;
199  }
200 
201  bool wasValueGiven(int serial_number) const
202  {
203  return givenValueSet_.find(serial_number) != givenValueSet_.end();
204  }
205 
206  void setValueGiven(int serial_number, bool value)
207  {
208  if (value)
209  givenValueSet_.insert(serial_number);
210  else
211  givenValueSet_.erase(serial_number);
212  }
213 
214 private:
215  OriginalValueMap originalValueMap_; ///< Map from device entity and original value index to original value
216  GivenValueSet givenValueSet_; ///< Map from device entity and serial number to value given flag
217 };
218 
219 template<class C>
221 
222 template<class T>
223 class Entry;
224 
225 template <class T>
226 inline std::ostream &printEntry(std::ostream &os, const Entry<T> &entry);
227 
228 template <class T>
229 inline std::ostream &printEntry(std::ostream &os, const Entry<std::vector<T> > &entry);
230 
231 template <>
232 inline std::ostream &printEntry(std::ostream &os, const Entry<std::string> &entry);
233 
234 template <>
235 inline std::ostream &printEntry(std::ostream &os, const Entry<bool> &entry);
236 
237 inline std::ostream &printEntry(std::ostream &os, const Entry<CompositeMap> &entry);
238 
239 void typeMismatch(const std::type_info &from_type, const std::type_info &to_type);
240 void nonexistentParameter(const std::string &name, const std::type_info &entity_type);
241 
242 ///
243 /// Class Entry<void> defines the parameter binding value entry interface.
244 ///
245 /// This defines the interface to check the data type of an Entry<T>
246 /// object and to print the value. Type specific Entry classes
247 /// inherit from this class. The entry_cast<T>() function is used to
248 /// cast an object of this type to the derived Entry<T> class safely.
249 ///
250 template<>
251 class Entry<void>
252 {
253 protected:
254  ///
255  /// Constructs the Entry base class
256  ///
257  /// @note The construct is protected so it may only be constructed by Entry<T> classes.
258  ///
259  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
260  /// @date Fri Aug 9 08:32:36 2013
261  ///
263  {}
264 
265 public:
266  ///
267  /// Destroys Entry
268  ///
269  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
270  /// @date Fri Aug 9 08:34:16 2013
271  virtual ~Entry()
272  {}
273 
274 private:
275  Entry(const Entry &);
276  Entry &operator=(const Entry &);
277 
278 public:
279  ///
280  /// Returns the type_info of the data type being stored in the entry.
281  ///
282  /// @return const reference to the type_info of the data type being stored in the entry.
283  ///
284  virtual const std::type_info &type() const = 0;
285 
286  ///
287  /// Prints the value of the entry to the output stream
288  ///
289  /// @param os output stream to write to
290  ///
291  /// @return reference to the output stream
292  ///
293  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
294  /// @date Wed Aug 7 11:28:02 2013
295  std::ostream &print(std::ostream &os) const
296  {
297  doPrint(os);
298 
299  return os;
300  }
301 
302 private:
303  ///
304  /// Prints the value of the entry to the output stream
305  ///
306  /// @param os output stream to write to
307  ///
308  /// @return reference to the output stream
309  ///
310  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
311  /// @date Wed Aug 7 11:29:29 2013
312  virtual std::ostream &doPrint(std::ostream &os) const = 0;
313 };
314 
315 ///
316 /// Class Entry<T> defines the parameter member variable access for
317 /// parameter member variable of type T
318 ///
319 /// The pointer to the parameter member variable and the default value
320 /// to set are contained in this class.
321 ///
322 template<class T>
323 class Entry : public Entry<void>
324 {
325 public:
326  ///
327  /// Constructs an Entry.
328  ///
329  /// Initializes the parameter member variable pointer of type T.
330  /// Note the member variable pointer are actually offsets into an
331  /// object where the data for the member exists. So, by storing
332  /// this pointer the value of any object of type can be retrieved.
333  ///
334  /// The default value ot type T is also contained here.
335  ///
336  /// @param member_value_ptr parameter member variable pointer
337  /// @param default_value Default value of parameter
338  ///
339  Entry(T ParameterBase::*member_value_ptr, const T &default_value = T())
340  : memberValuePtr_(member_value_ptr),
341  defaultValue_(default_value)
342  {}
343 
344  ///
345  /// Destroys the entry
346  ///
347  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
348  /// @date Wed Aug 7 11:30:29 2013
349  ///
350  virtual ~Entry()
351  {}
352 
353 private:
354  Entry(const Entry &); ///< No copying
355  Entry &operator=(const Entry &); ///< No assignment
356 
357 public:
358  ///
359  /// Returns type_info of this entry.
360  ///
361  /// @return const reference to type_info of this entry
362  ///
363  virtual const std::type_info &type() const
364  {
365  return typeid(T);
366  }
367 
368 private:
369  ///
370  /// Prints the value of the entry to the output stream
371  ///
372  /// @param os output stream to write to
373  ///
374  /// @return reference to the output stream
375  ///
376  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
377  /// @date Wed Aug 7 11:29:29 2013
378  ///
379  virtual std::ostream &doPrint(std::ostream &os) const
380  {
381  return printEntry(os, *this);
382  }
383 
384 public:
385  ///
386  /// Return the member pointer to the data member variable that holds
387  /// the value associated with this parameter
388  ///
389  /// @return member pointer to the data member variable
390  ///
391  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
392  /// @date Wed Aug 7 11:31:21 2013
393  ///
394  T ParameterBase::*getMemberPtr() const
395  {
396  return memberValuePtr_;
397  }
398 
399  ///
400  /// Return the value of the entity's parameter
401  ///
402  /// @param entity device class or device instance
403  ///
404  /// @return const reference to the value of the entity's parameter
405  ///
406  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
407  /// @date Wed Aug 7 11:32:58 2013
408  ///
409  const T &getValue(const ParameterBase &entity) const
410  {
411  return entity.*memberValuePtr_;
412  }
413 
414  ///
415  /// Return the value of the entity's parameter
416  ///
417  /// @param entity device class or device instance
418  ///
419  /// @return reference to the value of the entity's parameter
420  ///
421  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
422  /// @date Wed Aug 7 11:32:58 2013
423  ///
424  T &getValue(ParameterBase &entity) const
425  {
426  return entity.*memberValuePtr_;
427  }
428 
429  ///
430  /// Sets the value of the entity's parameter
431  ///
432  /// @param entity device class or device instance
433  /// @param value value to set the entity's parameter to
434  ///
435  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
436  /// @date Wed Aug 7 11:32:58 2013
437  ///
438  void setValue(ParameterBase &entity, const T &value) const
439  {
440  entity.*memberValuePtr_ = value;
441  }
442 
443  ///
444  /// Return the default value of the parameter
445  ///
446  /// All parameters provide a default value when created. The
447  /// parameter is set to this value and the given flag is cleared on
448  /// construction. If the value is provided by the net list, the
449  /// parameter's value is set accordingly and given flag is set to
450  /// true.
451  ///
452  /// @return const reference to the parameter's default value
453  ///
454  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
455  /// @date Wed Aug 7 11:35:18 2013
456  ///
457  const T &getDefaultValue() const
458  {
459  return defaultValue_;
460  }
461 
462  ///
463  /// Sets the parameter's default value
464  ///
465  /// All parameters provide a default value when created. The
466  /// parameter is set to this value and the given flag is cleared on
467  /// construction. If the value is provided by the net list, the
468  /// parameter's value is set accordingly and given flag is set to
469  /// true.
470  ///
471  /// @param value default value of the parameter
472  ///
473  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
474  /// @date Wed Aug 7 11:37:50 2013
475  ///
476  void setDefaultValue(const T &value)
477  {
478  defaultValue_ = value;
479  }
480 
481 private:
482  T defaultValue_; ///< Default value of parameter
483  T ParameterBase::* memberValuePtr_; ///< Member pointer containing value
484 };
485 
486 ///
487 /// Casts the entry to type T
488 ///
489 /// If the entry if not of the specified type, typeMismatch() is
490 /// called to emit a fatal error.
491 ///
492 /// @tparam T type to cast to
493 /// @param entry entry to cast
494 ///
495 /// @return const reference to Entry<T>
496 ///
497 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
498 /// @date Thu Jul 25 13:21:09 2013
499 ///
500 template<class T>
501 const Entry<T> &entry_cast(const Entry<void> &entry)
502 {
503  if (entry.type() != typeid(T))
504  typeMismatch(entry.type(), typeid(T));
505 
506  return static_cast<const Entry<T> &>(entry);
507 }
508 
509 ///
510 /// Casts the entry to type T
511 ///
512 /// If the entry if not of the specified type, typeMismatch() is called to emit a fatal error.
513 ///
514 /// @tparam T type to cast to
515 /// @param entry entry to cast
516 ///
517 /// @return reference to Entry<T>
518 ///
519 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
520 /// @date Thu Jul 25 13:21:09 2013
521 ///
522 template<class T>
524 {
525  if (entry.type() != typeid(T))
526  typeMismatch(entry.type(), typeid(T));
527 
528  return static_cast<Entry<T> &>(entry);
529 }
530 
531 ///
532 /// Class Descriptor describes the parameters stored in the
533 /// ParametricData parameter map.
534 ///
535 /// The descriptor contains the Entry for the parameter member
536 /// variable. Each parameter is assigned a serialNumber_ when it is
537 /// created and is used by manage the given value map. The parameter
538 /// may have a given member variable as well. The parameter can be
539 /// marked to store its original initialized value and the
540 /// serialNumber_ is used to store this value in the originalValueMap.
541 ///
542 /// If the parameter is vectorized, the index to this parameter is in
543 /// vec_.
544 ///
545 /// The expressionAccess_ is used to indicate the parameter's usage.
546 ///
547 /// The Descriptor also contains the units, catagory and description
548 /// for documentation generation. serial number, its original value
549 /// index if the initiazes value needs to be restored, its usage
550 /// (ExprAccess), units,
551 ///
553 {
554 public:
555  ///
556  /// Constructs Descriptor
557  ///
558  /// @param entry the parameter member variable pointer, type and default value
559  ///
560  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
561  /// @date Wed Aug 7 11:38:43 2013
562  ///
563  Descriptor(Entry<void> *const entry)
564  : serialNumber_(0),
565  originalValueFlag_(false),
566  vec_(0),
567  expressionAccess_(ParameterType::NO_DEP),
568  entry_(entry),
569  unit_(U_NONE),
570  category_(CAT_NONE),
571  description_(""),
572  compositeParametricData_(0),
573  given_(static_cast<bool ParameterBase::*>(0)),
574  sensitivityAvailable_(false),
575  sensPtr_(0)
576  {}
577 
578  ///
579  /// Destroy Descriptor
580  ///
581  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
582  /// @date Wed Aug 7 15:42:55 2013
583  ///
584  virtual ~Descriptor()
585  {
586  delete entry_;
587  }
588 
589 private:
590  Descriptor(const Descriptor &descriptor);
591  Descriptor &operator=(const Descriptor &descriptor);
592 
593 public:
594  ///
595  /// Tests entry data type
596  ///
597  /// @return true if entry is of type T
598  ///
599  /// @date Wed Aug 7 10:31:04 2013
600  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
601  ///
602  template <class T>
603  bool isType() const
604  {
605  if (entry_)
606  return entry_->type() == typeid(T);
607 
608  return typeid(T) == typeid(int);
609  }
610 
611  bool hasCompositeData() const
612  {
613  return compositeParametricData_ != 0;
614  }
615 
616  ///
617  /// Sets a boolean marking an original value having been stored.
618  ///
619  /// @param original_value_flag
620  ///
621  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
622  /// @date Fri Aug 9 14:37:03 2013
623  ///
624  Descriptor &setOriginalValueStored(bool original_value_flag)
625  {
626  originalValueFlag_ = original_value_flag;
627  return *this;
628  }
629 
630  ///
631  /// Returns whether an original value has been stored
632  ///
633  /// @return True if original value has been stored. False otherwise.
634  ///
635  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
636  /// @date Fri Aug 9 14:19:59 2013
637  ///
638  bool hasOriginalValueStored() const
639  {
640  return originalValueFlag_;
641  }
642 
643  ///
644  /// Sets the expression access which describe the usage of the parameter
645  ///
646  /// @param expression_access usage of the paraemeter
647  ///
648  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
649  /// @date Fri Aug 9 14:41:56 2013
650  ///
651  Descriptor &setExpressionAccess(ExprAccess expression_access)
652  {
653  expressionAccess_ = expression_access;
654  return *this;
655  }
656 
657  ///
658  /// Gets the expression access which describes the usage of the paramter
659  ///
660  /// @return usage of the parameter
661  ///
662  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
663  /// @date Fri Aug 9 14:41:26 2013
664  ///
665  ExprAccess getExpressionAccess() const
666  {
667  return expressionAccess_;
668  }
669 
670  ///
671  /// Sets the units of the parameter, only used to document the parameter
672  ///
673  /// @param unit units of the parameter
674  ///
675  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
676  /// @date Fri Aug 9 14:43:32 2013
677  ///
678  Descriptor &setUnit(ParameterUnit unit)
679  {
680  unit_ = unit;
681  return *this;
682  }
683 
684  ///
685  /// Gets the units of the parameter, only used to document the parameter
686  ///
687  /// @return units of the parameter
688  ///
689  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
690  /// @date Fri Aug 9 14:44:16 2013
691  ///
692  ParameterUnit getUnit() const
693  {
694  return unit_;
695  }
696 
697  ///
698  /// Sets the category of the parameter, only used to document the parameter
699  ///
700  /// @param category category of the parameter
701  ///
702  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
703  /// @date Fri Aug 9 14:45:09 2013
704  Descriptor &setCategory(ParameterCategory category)
705  {
706  category_ = category;
707  return *this;
708  }
709 
710  ///
711  /// Gets the category of the parameter, only used to document the parameter
712  ///
713  /// @return categort of the parameter
714  ///
715  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
716  /// @date Fri Aug 9 14:45:40 2013
717  ///
718  ParameterCategory getCategory() const
719  {
720  return category_;
721  }
722 
723  ///
724  /// Sets the description of the parameter, only used to document the parameter
725  ///
726  /// @param description description of the parameter
727  ///
728  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
729  /// @date Fri Aug 9 14:46:21 2013
730  ///
731  Descriptor &setDescription(const std::string &description)
732  {
733  description_ = description;
734  return *this;
735  }
736 
737  ///
738  /// Gets the description of the parameter, only used to document the parameter
739  ///
740  /// @return description of the parameter
741  ///
742  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
743  /// @date Fri Aug 9 14:46:46 2013
744  ///
745  const std::string &getDescription() const
746  {
747  return description_;
748  }
749 
750  ///
751  /// Sets the composite parametric
752  ///
753  /// A composite parameter is a named aggregation of parameters
754  ///
755  /// @param composite_parametric_data composite parameter
756  ///
757  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
758  /// @date Fri Aug 9 14:47:19 2013
759  ///
760  Descriptor &setCompositeParametricData(const ParametricData<void> *composite_parametric_data)
761  {
762  compositeParametricData_ = composite_parametric_data;
763  return *this;
764  }
765 
766  ///
767  /// Return the composite parameter
768  ///
769  /// A composite parameter is a named aggregation of parameters
770  ///
771  /// @return const pointer to the composite parameter
772  ///
773  /// @note I think the template parameter is really only ever CompositeParam, though sometimes its
774  /// currently void.
775  ///
776  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
777  /// @date Fri Aug 9 14:09:01 2013
778  ///
779  template <class U>
780  const ParametricData<U> *getCompositeParametricData() const
781  {
782  return static_cast<const ParametricData<U> *>(compositeParametricData_);
783  }
784 
785  ///
786  /// sets the vector length of an vectorized parameter
787  ///
788  /// @param index
789  ///
790  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
791  /// @date Fri Aug 9 14:50:05 2013
792  ///
793  Descriptor &setVec(int index)
794  {
795  vec_ = index;
796  return *this;
797  }
798 
799  ///
800  /// Gets the vector length of a vectorized parameter
801  ///
802  /// @return length of the vectorized parameter
803  ///
804  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
805  /// @date Fri Aug 9 14:51:10 2013
806  ///
807  int getVec() const
808  {
809  return vec_;
810  }
811 
812  ///
813  /// Gets the entry object of the parameter
814  ///
815  /// @return const reference to the Entry<void>
816  ///
817  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
818  /// @date Fri Aug 9 15:29:16 2013
819  ///
820  const Entry<void> &getEntry() const
821  {
822  return *entry_;
823  }
824 
825  ///
826  /// Gets the entry object of the parameter
827  ///
828  /// @return reference to the Entry<void>
829  ///
830  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
831  /// @date Fri Aug 9 15:29:16 2013
832  ///
833  Entry<void> &getEntry()
834  {
835  return *entry_;
836  }
837 
838  ///
839  /// Sets the serial number used to store and retrieve given boolean from the GivenValueMap
840  ///
841  /// @param serial_number serial number of the parameter in the GivenValueMap
842  ///
843  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
844  /// @date Fri Aug 9 14:38:18 2013
845  ///
846  Descriptor &setSerialNumber(int serial_number)
847  {
848  serialNumber_ = serial_number;
849  return *this;
850  }
851 
852  ///
853  /// Gets the serial number used to store and retireve given boolean fromt he GivenValueMap
854  ///
855  /// @return parameter serial number
856  ///
857  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
858  /// @date Fri Aug 9 14:40:30 2013
859  ///
860  int getSerialNumber() const
861  {
862  return serialNumber_;
863  }
864 
865 public:
866  ///
867  /// Returns the value of the parameter for the entity
868  ///
869  /// @param entity device class or device instance
870  ///
871  /// @return reference to the value of the parameter for the entity
872  ///
873  /// @date Wed Aug 7 10:36:10 2013
874  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
875  ///
876  template <class T>
877  const T &value(const ParameterBase &entity) const
878  {
879  const Entry<T> &entry = entry_cast<T>(*entry_);
880 
881  return entry.getValue(entity);
882  }
883 
884  ///
885  /// Returns the value of the parameter for the entity
886  ///
887  /// @param entity device class or device instance
888  ///
889  /// @return reference to the value of the parameter for the entity
890  ///
891  /// @date Wed Aug 7 10:36:10 2013
892  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
893  ///
894  template <class T>
895  T &value(ParameterBase &entity) const
896  {
897  const Entry<T> &entry = entry_cast<T>(*entry_);
898 
899  return entry.getValue(entity);
900  }
901 
902  ///
903  /// Returns the parameter member variable pointer of the enrtry
904  ///
905  /// @return parameter member pointer of type T
906  ///
907  /// @date Wed Aug 7 10:54:58 2013
908  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
909  ///
910  template <class T>
911  T ParameterBase::*getMemberPtr() const
912  {
913  const Entry<T> &entry = entry_cast<T>(*entry_);
914 
915  return entry.getMemberPtr();
916  }
917 
918  ///
919  /// Tests if parameter has a given data member
920  ///
921  /// Parameters may provide a boolean member variable that is set true if the netlist provides
922  /// the value.
923  ///
924  /// @return true if the parameter has a boolean member variable to set if it is provided by the netlist
925  ///
926  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
927  /// @date Wed Aug 7 11:03:55 2013
928  ///
929  bool hasGivenMember() const
930  {
931  return given_ != static_cast<bool ParameterBase::*>(0);
932  }
933 
934  ///
935  /// Sets the boolean member variable to set if the netlist provides the value.
936  ///
937  /// Parameters may provide a boolean member variable that is set true if the netlist provides
938  /// the value.
939  ///
940  /// @param given boolean member variable to be set
941  ///
942  /// @date Wed Aug 7 11:02:38 2013
943  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
944  ///
945  template<class U>
946  Descriptor &setGivenMember(bool U::*given)
947  {
948  given_ = static_cast<bool ParameterBase::*>(given);
949  return *this;
950  }
951 
952  ///
953  /// Tests if the parameter has been given by the netlist.
954  ///
955  /// @return true if the parameter was given by the netline
956  ///
957  /// @date Wed Aug 7 11:01:42 2013
958  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
959  ///
960  bool getGiven(ParameterBase &entity) const
961  {
962  if (hasGivenMember())
963  {
964  return entity.*given_;
965  }
966 
967  return false;
968  }
969 
970  ///
971  /// Sets the given state of the parameter to value
972  ///
973  /// The parameter's boolean member variable that is set true if exists and the netlist provides
974  /// the value.
975  ///
976  /// @param entity device class or device instance
977  /// @param value true if provided by netlist
978  ///
979  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
980  /// @date Wed Aug 7 11:09:00 2013
981  ///
982  void setGiven(ParameterBase &entity, bool value) const
983  {
984  if (hasGivenMember())
985  {
986  entity.*given_ = value;
987  }
988  }
989 
990  ///
991  /// Sets a boolean to indicate if analytic sensitivities are available w.r.t. this parameter.
992  //
993  /// @param entity device class or device instance
994  /// @param value true if provided by netlist
995  ///
996  /// @author Eric R. Keiter, Sandia National Laboratories 1355
997  /// @date Wed Aug 7 11:09:00 2013
998  ///
999  Descriptor &setAnalyticSensitivityAvailable(bool value)
1000  {
1001  sensitivityAvailable_ = value;
1002  return *this;
1003  }
1004 
1005  Descriptor &setSensitivityFunctor(const baseSensitivity * sensPtr)
1006  {
1007  sensPtr_ = sensPtr;
1008  return *this;
1009  }
1010 
1011  ///
1012  /// returns a boolean to indicate if analytic sensitivities are available w.r.t. this parameter.
1013  //
1014  /// @param entity device class or device instance
1015  /// @param value true if provided by netlist
1016  ///
1017  /// @author Eric R. Keiter, Sandia National Laboratories 1355
1018  /// @date Wed Aug 7 11:09:00 2013
1019  ///
1020  bool getAnalyticSensitivityAvailable() const
1021  {
1022  return sensitivityAvailable_;
1023  }
1024 
1025  ///
1026  /// returns analytic sensitivity, evaluated at the most recent solve point.
1027  //
1028  /// @param entity device class or device instance
1029  /// @param value true if provided by netlist
1030  ///
1031  /// @author Eric R. Keiter, Sandia National Laboratories 1355
1032  /// @date Wed Aug 7 11:09:00 2013
1033  ///
1034  bool getAnalyticSensitivity(
1035  const ParameterBase &entity1,
1036  const std::string & name,
1037  std::vector<double> & dfdp, std::vector<double> & dqdp, std::vector<double> & dbdp,
1038  std::vector<int> & Findices, std::vector<int> & Qindices, std::vector<int> & Bindices) const
1039  {
1040  if (sensPtr_)
1041  {
1042  sensPtr_->operator()(entity1, name, dfdp, dqdp, dbdp, Findices, Qindices, Bindices);
1043  return true;
1044  }
1045  else
1046  {
1047  return false;
1048  }
1049  }
1050 
1051 private:
1052  int serialNumber_; ///< Unique identifier of descriptor
1053  bool originalValueFlag_; ///< Flag indicating original value was stored
1054  int vec_; ///< If > 0 specifies a vector of params.(eg: if = 3 then IC becomes IC1, IC2, IC3)
1055  ExprAccess expressionAccess_; ///< Flags for parameter attributes, such as whether can be input by user, may depend on time, etc.
1056  Entry<void> * const entry_; ///< Pointer to entry which contains the value
1057  ParameterUnit unit_; ///< Unit designator for documentation
1058  ParameterCategory category_; ///< Category designator for documentation
1059  std::string description_; ///< Description of parameter for documentation
1060  const ParametricData<void> * compositeParametricData_; ///< If a composite, then this points to the ParameterData of the composite
1061  bool ParameterBase::* given_; ///< Pointer to given bool, usually 0
1062  bool sensitivityAvailable_; ///< Flag indicating that analytic sensitivity is available for this param.
1063  const baseSensitivity * sensPtr_; ///< pointer to the sensitivity functor
1064 };
1065 
1066 
1067 ///
1068 /// Prints the entry default value to the output stream
1069 ///
1070 /// @param os output stream
1071 /// @param entry entry to print
1072 ///
1073 /// @return reference to the output stream
1074 ///
1075 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1076 /// @date Fri Aug 9 15:32:26 2013
1077 ///
1078 template <class T>
1079 inline std::ostream &printEntry(std::ostream &os, const Entry<T> &entry)
1080 {
1081  os << entry.getDefaultValue();
1082 
1083  return os;
1084 }
1085 
1086 ///
1087 /// Prints the entry default values of a vectorized parameter
1088 ///
1089 /// @param os output stream
1090 /// @param entry entry to print
1091 ///
1092 /// @return reference to the output stream
1093 ///
1094 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1095 /// @date Fri Aug 9 15:33:24 2013
1096 ///
1097 template <class T>
1098 inline std::ostream &printEntry(std::ostream &os, const Entry<std::vector<T> > &entry)
1099 {
1100  for (typename std::vector<T>::const_iterator it = entry.getDefaultValue().begin(); it != entry.getDefaultValue().end(); ++it)
1101  os << (*it) << std::endl;
1102 
1103  return os;
1104 }
1105 
1106 ///
1107 /// Prints the entry default values of a map parameter
1108 ///
1109 /// @param os output stream
1110 /// @param entry entry to print
1111 ///
1112 /// @return reference to the output stream
1113 ///
1114 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1115 /// @date Thu Feb 6 16:37:16 2014
1116 ///
1117 template <class T>
1118 inline std::ostream &printEntry(std::ostream &os, const Entry<std::map<std::string, T> > &entry)
1119 {
1120  for (typename std::map<std::string, T>::const_iterator it = entry.getDefaultValue().begin(); it != entry.getDefaultValue().end(); ++it)
1121  os << (*it).first << std::endl;
1122 
1123  return os;
1124 }
1125 
1126 ///
1127 /// Prints the entry default string value, within single quotes
1128 ///
1129 /// @param os output stream
1130 /// @param entry entry to print
1131 ///
1132 /// @return reference to the output stream
1133 ///
1134 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1135 /// @date Fri Aug 9 15:34:18 2013
1136 ///
1137 template <>
1138 inline std::ostream &printEntry(std::ostream &os, const Entry<std::string> &entry)
1139 {
1140  os << "'" << entry.getDefaultValue() << "'";
1141 
1142  return os;
1143 }
1144 
1145 ///
1146 /// Prints the entry default boolean value, printed as true or false
1147 ///
1148 /// @param os output stream
1149 /// @param entry entry to print
1150 ///
1151 /// @return reference to the output stream
1152 ///
1153 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1154 /// @date Fri Aug 9 15:34:18 2013
1155 ///
1156 template <>
1157 inline std::ostream &printEntry(std::ostream &os, const Entry<bool> &entry)
1158 {
1159  os << (entry.getDefaultValue() ? "true" : "false");
1160 
1161  return os;
1162 }
1163 
1164 ///
1165 /// Prints the entry composite value as newline terminated list of colon separated name, value pairs
1166 ///
1167 /// @param os output stream
1168 /// @param entry entry to print
1169 ///
1170 /// @return reference to the output stream
1171 ///
1172 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1173 /// @date Fri Aug 9 15:34:18 2013
1174 ///
1175 inline std::ostream &printEntry(std::ostream &os, const Entry<CompositeMap> &entry)
1176 {
1177  for (CompositeMap::const_iterator it = entry.getDefaultValue().begin(); it != entry.getDefaultValue().end(); ++it)
1178  os << (*it).first << ": " << (*it).second << std::endl;
1179 
1180  return os;
1181 }
1182 
1183 ///
1184 /// Gets the default value of the parameter
1185 ///
1186 /// @param descriptor descriptor of the parameter
1187 ///
1188 /// @return const reference to the default value of the entry of the descriptor
1189 ///
1190 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1191 /// @date Fri Aug 9 15:37:33 2013
1192 ///
1193 template <class T>
1194 inline const T &getDefaultValue(const Descriptor &descriptor)
1195 {
1196  const Entry<T> &entry = entry_cast<T>(descriptor.getEntry());
1197 
1198  return entry.getDefaultValue();
1199 }
1200 
1201 ///
1202 /// Sets the default value of the parameter
1203 ///
1204 /// @param descriptor descriptor of the parameter
1205 /// @param t default value
1206 ///
1207 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1208 /// @date Fri Aug 9 15:38:49 2013
1209 ///
1210 template <class T>
1211 inline void setDefaultValue(Descriptor &descriptor, const T &t)
1212 {
1213  Entry<T> &entry = entry_cast<T>(descriptor.getEntry());
1214 
1215  entry.setDefaultValue(t);
1216 }
1217 
1218 ///
1219 /// Returns the value of the parameter for the entity
1220 ///
1221 /// @param entity device class or device instance
1222 /// @param descriptor descriptor of the parameter
1223 ///
1224 /// @return const reference to the value of the entry of the descriptor
1225 ///
1226 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1227 /// @date Fri Aug 9 15:39:40 2013
1228 ///
1229 template <class T>
1230 inline const T &value(const ParameterBase &entity, const Descriptor &descriptor)
1231 {
1232  const Entry<T> &entry = entry_cast<T>(descriptor.getEntry());
1233 
1234  return entry.getValue(entity);
1235 }
1236 
1237 ///
1238 /// Returns the value of the parameter for the entity
1239 ///
1240 /// @param entity device class or device instance
1241 /// @param descriptor descriptor of the parameter
1242 ///
1243 /// @return reference to the value of the entry of the descriptor
1244 ///
1245 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1246 /// @date Fri Aug 9 15:39:40 2013
1247 ///
1248 template <class T>
1249 inline T &value(ParameterBase &entity, const Descriptor &descriptor)
1250 {
1251  const Entry<T> &entry = entry_cast<T>(descriptor.getEntry());
1252 
1253  return entry.getValue(entity);
1254 }
1255 
1256 
1257 ///
1258 /// Gets the value of the parameter for the entity
1259 ///
1260 /// @param entity device class or device instance
1261 /// @param descriptor descriptor of the parameter
1262 ///
1263 /// @return const reference to the value of the entry of the descriptor
1264 ///
1265 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1266 /// @date Fri Aug 9 15:39:40 2013
1267 ///
1268 template <class T, class U>
1269 inline const T &getValue(const ParameterBase &entity, const Descriptor &descriptor)
1270 {
1271  const Entry<T> &entry = entry_cast<T>(descriptor.getEntry());
1272 
1273  return entry.getValue(entity);
1274 }
1275 
1276 ///
1277 /// Sets the value of the parameter
1278 ///
1279 /// @param entity device class or device instance
1280 /// @param descriptor descriptor of the parameter
1281 /// @param value value
1282 ///
1283 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1284 /// @date Fri Aug 9 15:42:13 2013
1285 ///
1286 template <class T, class U>
1287 inline void setValue(ParameterBase &entity, const Descriptor &descriptor, const T &value)
1288 {
1289  const Entry<T> &entry = entry_cast<T>(descriptor.getEntry());
1290 
1291  entry.setValue(entity, value);
1292 }
1293 
1294 ///
1295 /// Class ParametricData<void> manages the configuration information and the parameter binding map
1296 ///
1297 /// Parametric data associated with a device instance, device model or composite parameter
1298 ///
1299 /// The Parametric data class manages the mapping of parameter string names to descriptors and the
1300 /// general configuration information associated with a device model.
1301 ///
1302 /// To restore original values during perturbation, the originalValueCount_ and serialNumber_ members
1303 /// maintain counts of original values to be stored and of parameters declared.
1304 ///
1305 /// @date Tue Aug 6 13:10:21 2013
1306 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1307 ///
1308 template<>
1309 class ParametricData<void>
1310 {
1311 public:
1312  ///
1313  /// Constructs a ParametricData object
1314  ///
1315  /// @date Tue Aug 6 13:10:21 2013
1316  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1317  ///
1319  : map_()
1320  {}
1321 
1322  ///
1323  /// Destroys a ParametricData object
1324  ///
1325  /// @date Tue Aug 6 13:13:47 2013
1326  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1327  ///
1328  virtual ~ParametricData()
1329  {
1330  for (ParameterMap::iterator it = map_.begin(); it != map_.end(); ++it)
1331  delete (*it).second;
1332  }
1333 
1334 private:
1335  ParametricData(const ParametricData &parametric_data); ///< No copying
1336  ParametricData &operator=(const ParametricData &parametric_data); ///< No assignment
1337 
1338 public:
1339  ///
1340  /// Gets the parameter binding map map
1341  ///
1342  /// @return reference to the parameter binding map
1343  ///
1344  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1345  /// @date Fri Aug 9 15:50:06 2013
1346  ///
1347  ParameterMap &getMap()
1348  {
1349  return map_;
1350  }
1351 
1352  ///
1353  /// Returns the parameter binding map
1354  ///
1355  /// @return const reference to the parameter binding map
1356  ///
1357  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1358  /// @date Fri Aug 9 15:50:06 2013
1359  ///
1360  const ParameterMap &getMap() const
1361  {
1362  return map_;
1363  }
1364 
1365 protected:
1366  ///
1367  /// Adds the parameter to the parameter binding map
1368  ///
1369  /// @param name parameter name
1370  /// @param descriptor descriptor created for the parameter
1371  /// @param parameter_data_class typeinfo to get the class name for diagnostics
1372  ///
1373  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1374  /// @date Fri Aug 9 16:23:45 2013
1375  ///
1376  void addDescriptor(const std::string &name, Descriptor *descriptor, const std::type_info &parameter_data_class);
1377 
1378 protected:
1379  ParameterMap map_; ///< Mapping from parameter name to descriptor
1380 };
1381 
1382 void checkExprAccess(const std::string &name, ParameterType::ExprAccess &expr_access, const std::type_info &parameter_data_class);
1383 
1384 ///
1385 /// Manages parameter binding for class C.
1386 ///
1387 ///
1388 template<class C>
1389 class ParametricData : public ParametricData<void>
1390 {
1391 public:
1392  ///
1393  /// Constructs the parameter data map
1394  ///
1395  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1396  /// @date Thu Feb 6 16:39:06 2014
1397  ///
1399  : ParametricData<void>()
1400  {}
1401 
1402  ///
1403  /// Destroys the parameter data map
1404  ///
1405  ///
1406  ///
1407  /// @return
1408  ///
1409  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1410  /// @date Thu Feb 6 16:39:34 2014
1411  ///
1412  virtual ~ParametricData()
1413  {}
1414 
1415 private:
1416  ParametricData(const ParametricData &parametric_data); ///< No copying
1417  ParametricData &operator=(const ParametricData &parametric_data); ///< No assignment
1418 
1419 public:
1420  ///
1421  /// Adds the parameter description to the parameter map
1422  ///
1423  /// @tparam T data type of the parameter
1424  /// @tparam U class containing the member data storing the parameter's value
1425  /// @param parName const pointer to the parameter name
1426  /// @param default_value default value
1427  /// @param varPtr member pointer to the parameter's value
1428  ///
1429  /// @return
1430  ///
1431  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1432  /// @date Thu Feb 6 16:33:48 2014
1433  ///
1434  template<class T, class U>
1435  Descriptor &addPar(const char *parName, T default_value, T U::*varPtr)
1436  {
1437  Descriptor *descriptor = new Descriptor(new Entry<T>(static_cast<T ParameterBase::*>(varPtr), default_value));
1438 
1439  addDescriptor(parName, descriptor, typeid(C));
1440 
1441  return *descriptor;
1442  }
1443 
1444  ///
1445  /// Adds the parameter description to the parameter map
1446  ///
1447  /// This is specialization to allow const char * (quoted strings) to create a std::string type parameter.
1448  ///
1449  /// @tparam U class containing the member data storing the parameter's value
1450  /// @param parName const pointer to the parameter name
1451  /// @param default_value default value
1452  /// @param varPtr member pointer to the parameter's value
1453  ///
1454  /// @return
1455  ///
1456  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1457  /// @date Thu Feb 6 16:33:48 2014
1458  ///
1459  template<class U>
1460  Descriptor &addPar(const char *parName, const char *default_value, std::string U::*varPtr)
1461  {
1462  Descriptor *descriptor = new Descriptor(new Entry<std::string>(static_cast<std::string ParameterBase::*>(varPtr), default_value));
1463 
1464  addDescriptor(parName, descriptor, typeid(C));
1465 
1466  return *descriptor;
1467  }
1468 
1469 
1470  ///
1471  /// Adds the parameter description to the parameter map
1472  ///
1473  /// TODO: [DGB] This function should be eliminated and the addPar(const char *parName, T default_value, T U::*varPtr) used exclusively
1474  ///
1475  /// @tparam T data type of the parameter
1476  /// @tparam U class containing the member data storing the parameter's value
1477  /// @param parName const pointer to the parameter name
1478  /// @param def default value
1479  /// @param orig true if the original value is no be stored
1480  /// @param depend the dependency type of this parameter
1481  /// @param varPtr member pointer to the parameter's value
1482  /// @param givenPtr member pointer to the parameter's given boolean
1483  /// @param unit parameter's measurement units
1484  /// @param category parameter documentation category
1485  /// @param description documentation description
1486  ///
1487  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1488  /// @date Thu Feb 6 16:43:30 2014
1489  ///
1490  template<class T, class U>
1491  void addPar(const char *parName, T def, bool orig, ParameterType::ExprAccess depend, T U::*varPtr, bool U::*givenPtr, ParameterUnit unit, ParameterCategory category, const char *description)
1492  {
1493  Descriptor *descriptor = new Descriptor(new Entry<T>(static_cast<T ParameterBase::*>(varPtr), def));
1494 
1495  checkExprAccess(parName, depend, typeid(C));
1496 
1497  descriptor->setExpressionAccess(depend);
1498  descriptor->setOriginalValueStored(orig);
1499  descriptor->setGivenMember(givenPtr);
1500  descriptor->setUnit(unit);
1501  descriptor->setCategory(category);
1502  descriptor->setDescription(description);
1503 
1504  addDescriptor(parName, descriptor, typeid(C));
1505  }
1506 
1507  ///
1508  /// Adds the parameter description to the parameter map
1509  ///
1510  /// This is specialization to allow const char * (quoted strings) to create a std::string type parameter.
1511  ///
1512  /// TODO: [DGB] This function should be eliminated and the addPar(const char *parName, T default_value, T U::*varPtr) used exclusively
1513  ///
1514  /// @tparam T data type of the parameter
1515  /// @tparam U class containing the member data storing the parameter's value
1516  /// @param parName const pointer to the parameter name
1517  /// @param def default value
1518  /// @param orig true if the original value is no be stored
1519  /// @param depend the dependency type of this parameter
1520  /// @param varPtr member pointer to the parameter's value
1521  /// @param givenPtr member pointer to the parameter's given boolean
1522  /// @param unit parameter's measurement units
1523  /// @param category parameter documentation category
1524  /// @param description documentation description
1525  ///
1526  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1527  /// @date Thu Feb 6 16:43:30 2014
1528  ///
1529  template<class U>
1530  void addPar(const char *parName, const char *def, bool orig, ParameterType::ExprAccess depend, std::string U::*varPtr, bool U::*givenPtr, ParameterUnit unit, ParameterCategory category, const char *description)
1531  {
1532  Descriptor *descriptor = new Descriptor(new Entry<std::string>(static_cast<std::string ParameterBase::*>(varPtr), def));
1533 
1534  checkExprAccess(parName, depend, typeid(C));
1535 
1536  descriptor->setExpressionAccess(depend);
1537  descriptor->setOriginalValueStored(orig);
1538  descriptor->setGivenMember(givenPtr);
1539  descriptor->setUnit(unit);
1540  descriptor->setCategory(category);
1541  descriptor->setDescription(description);
1542 
1543  addDescriptor(parName, descriptor, typeid(C));
1544  }
1545 
1546  ///
1547  /// Adds the parameter description to the parameter map
1548  ///
1549  /// This is specialization to allow 0 to be passed as given member pointer
1550  ///
1551  /// TODO: [DGB] This function should be eliminated and the addPar(const char *parName, T default_value, T U::*varPtr) used exclusively
1552  ///
1553  /// @tparam T data type of the parameter
1554  /// @tparam U class containing the member data storing the parameter's value
1555  /// @param parName const pointer to the parameter name
1556  /// @param def default value
1557  /// @param orig true if the original value is no be stored
1558  /// @param depend the dependency type of this parameter
1559  /// @param varPtr member pointer to the parameter's value
1560  /// @param noGivenPtr always 0
1561  /// @param unit parameter's measurement units
1562  /// @param category parameter documentation category
1563  /// @param description documentation description
1564  ///
1565  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1566  /// @date Thu Feb 6 16:43:30 2014
1567  ///
1568  template<class T, class U>
1569  void addPar(const char *parName, T def, bool orig, ParameterType::ExprAccess depend, T U::*varPtr, void *noGivenPtr, ParameterUnit unit, ParameterCategory category, const char *description)
1570  {
1571  Descriptor *descriptor = new Descriptor(new Entry<T>(static_cast<T ParameterBase::*>(varPtr), def));
1572 
1573  checkExprAccess(parName, depend, typeid(C));
1574 
1575  descriptor->setExpressionAccess(depend);
1576  descriptor->setOriginalValueStored(orig);
1577  descriptor->setUnit(unit);
1578  descriptor->setCategory(category);
1579  descriptor->setDescription(description);
1580 
1581  addDescriptor(parName, descriptor, typeid(C));
1582  }
1583 
1584  ///
1585  /// Adds a composite parameter to the parameter map
1586  ///
1587  /// THIS IS SUPER DANGEROUS U * MAY NOT ACTUALLY POINT TO CompositeParam *. IT COULD BE SLICED
1588  ///
1589  /// @param comp_name
1590  /// @param composite_pars
1591  /// @param composite_map
1592  ///
1593  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1594  /// @date Thu Feb 6 16:47:59 2014
1595  ///
1596  template<class U, class V>
1597  void addComposite(const char *comp_name, const ParametricData<U> &composite_pars, std::map<std::string, U *> V::*composite_map)
1598  {
1599  Descriptor *descriptor = new Descriptor(new Entry<CompositeMap>(reinterpret_cast<CompositeMap ParameterBase::*>(composite_map)));
1600 
1601  descriptor->setUnit(U_INVALID);
1602  descriptor->setCategory(CAT_INVALID);
1603  descriptor->setCompositeParametricData(&composite_pars);
1604 
1605  addDescriptor(comp_name, descriptor, typeid(C));
1606  }
1607 
1608  ///
1609  /// Adds a composite vector parameter to the parameter map
1610  ///
1611  /// THIS IS SUPER DANGEROUS U * MAY NOT ACTUALLY POINT TO CompositeParam *. IT COULD BE SLICED
1612  ///
1613  /// @param comp_name
1614  /// @param composite_pars
1615  /// @param composite_vector
1616  ///
1617  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1618  /// @date Thu Feb 6 16:47:59 2014
1619  ///
1620  template<class U, class V>
1621  void addComposite(const char *comp_name, const ParametricData<U> &composite_pars, std::vector<U *> V::*composite_vector)
1622  {
1623  Descriptor *descriptor = new Descriptor(new Entry<CompositeVector>(reinterpret_cast<CompositeVector ParameterBase::*>(composite_vector)));
1624 
1625  descriptor->setUnit(U_INVALID);
1626  descriptor->setCategory(CAT_INVALID);
1627  descriptor->setCompositeParametricData(&composite_pars);
1628  addDescriptor(comp_name, descriptor, typeid(C));
1629  }
1630 
1631  ///
1632  /// Allows the parameter to be specified as a vector
1633  ///
1634  ///
1635  /// @param cname
1636  /// @param len
1637  ///
1638  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1639  /// @date Thu Feb 6 16:50:29 2014
1640  ///
1641  void makeVector(const std::string &cname, int len)
1642  {
1643  for (int i = 1; i <= len; ++i)
1644  {
1645  std::ostringstream oss;
1646  oss << cname << i;
1647  std::string param = oss.str();
1648 
1649  ParameterMap::iterator it = map_.find(param);
1650  if (it == map_.end())
1651  nonexistentParameter(param, typeid(C));
1652 
1653  Descriptor &descriptor = *(*it).second;
1654  descriptor.setVec(i);
1655  }
1656  }
1657 };
1658 
1659 ///
1660 /// Set the default values for the parameter.
1661 ///
1662 /// Note that any values provided in the objects constructor that are defined as parameters have their initialized value
1663 /// replaced with the default value given in the addPar() call
1664 ///
1665 /// @param parameter_base
1666 /// @param begin
1667 /// @param end
1668 /// @param device_options
1669 ///
1670 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1671 /// @date Thu Feb 6 16:51:00 2014
1672 ///
1673 void setDefaultParameters(ParameterBase &parameter_base, ParameterMap::const_iterator begin, ParameterMap::const_iterator end, const DeviceOptions &device_options);
1674 
1675 ///
1676 /// Retrieve a parameter's original value
1677 ///
1678 /// @param parameter_base device entity holding parameter
1679 /// @param serial_number entity's serial number
1680 ///
1681 /// @return original value of the parameter
1682 ///
1683 /// @date Tue Aug 6 13:51:16 2013
1684 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1685 ///
1686 inline double getOriginalValue(ParameterBase &parameter_base, int serial_number)
1687 {
1688  return parameter_base.getOriginalValue(serial_number);
1689 }
1690 
1691 ///
1692 /// Set a parameter's original value
1693 ///
1694 /// @param parameter_base device entity or composite holding parameter
1695 /// @param serial_number entity's serial number
1696 /// @param value value to be stored
1697 ///
1698 /// @date Tue Aug 6 13:53:29 2013
1699 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1700 ///
1701 inline void setOriginalValue(ParameterBase &parameter_base, int serial_number, double value)
1702 {
1703  parameter_base.setOriginalValue(serial_number, value);
1704 }
1705 
1706 
1707 ///
1708 /// Return true if a value was provided for the device
1709 ///
1710 /// @param parameter_base device entity or composite holding parameter
1711 /// @param serial_number serial number of parameter
1712 ///
1713 /// @return true if a value was provided for the device
1714 ///
1715 /// @date Tue Aug 6 13:54:25 2013
1716 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1717 ///
1718 inline bool wasValueGiven(const ParameterBase &parameter_base, int serial_number)
1719 {
1720  return parameter_base.wasValueGiven(serial_number);
1721 }
1722 
1723 
1724 ///
1725 /// Set the given value state of a parameter
1726 ///
1727 /// @param parameter_base device entity or composite holding parameter
1728 /// @param serial_number serial number of parameter
1729 /// @param value true if the value was given
1730 ///
1731 /// @date Tue Aug 6 13:55:34 2013
1732 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1733 ///
1734 inline void setValueGiven(ParameterBase &parameter_base, int serial_number, bool value)
1735 {
1736  parameter_base.setValueGiven(serial_number, value);
1737 }
1738 
1739 ///
1740 /// Returns true if the name is TNOM or TEMP
1741 ///
1742 /// @param name parameter name
1743 ///
1744 /// @return true if the name is TNOM or TEMP
1745 ///
1746 /// @author David G. Baur Raytheon Sandia National Laboratories 1355
1747 /// @date Thu Feb 6 16:52:26 2014
1748 ///
1749 inline bool isTempParam(const std::string &name)
1750 {
1751  return equal_nocase(name, "TNOM") || equal_nocase(name, "TEMP");
1752 }
1753 
1754 } // namespace Device
1755 } // namespace Xyce
1756 
1757 #endif // Xyce_N_DEV_Pars_h