Xyce  6.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
N_DEV_DeviceInstance.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-2014 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_DeviceInstance.h,v $
27 //
28 // Purpose : This file contains the device instance base class.
29 //
30 // Special Notes :
31 //
32 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
33 //
34 // Creation Date : 03/30/00
35 //
36 // Revision Information:
37 // ---------------------
38 //
39 // Revision Number: $Revision: 1.184 $
40 //
41 // Revision Date : $Date: 2014/05/16 15:06:08 $
42 //
43 // Current Owner : $Author: dgbaur $
44 //-----------------------------------------------------------------------------
45 
46 #ifndef Xyce_N_DEV_DeviceInstance_h
47 #define Xyce_N_DEV_DeviceInstance_h
48 
49 #include <list>
50 #include <map>
51 #include <string>
52 #include <vector>
53 
54 #include <N_DEV_fwd.h>
55 
56 #include <N_DEV_DeviceEntity.h>
57 #include <N_DEV_DeviceSupport.h>
58 #include <N_UTL_Misc.h>
59 
60 class N_LAS_Matrix;
61 class N_LAS_MultiVector;
62 class N_LAS_Vector;
63 class N_LAS_Solver;
64 
65 namespace Xyce {
66 namespace Device {
67 
68 //-----------------------------------------------------------------------------
69 // Class : DeviceInstance
70 // Purpose :
71 // Special Notes :
72 // Creator : Eric Keiter, SNL, Parallel Computational Sciences
73 // Creation Date : 3/16/00
74 //-----------------------------------------------------------------------------
76 {
77 private:
79 
80 public:
82  const InstanceBlock & instance_block,
83  ParametricData<void> & parametric_data,
84  const FactoryBlock & factory_block);
85 
86  virtual ~DeviceInstance();
87 
88 private:
91 
92 public:
93  virtual std::ostream &printName(std::ostream &os) const;
94 
95  // This function configures the device to request space in the store
96  // vector for lead current calculations. It must be called soon
97  // after the constructor call before the store vector is allocated.
98  virtual void enableLeadCurrentCalc();
99 
100  virtual void registerGIDs(
101  const std::list<index_pair> & intGIDListRef,
102  const std::list<index_pair> & extGIDListRef ) {}
103 
104  virtual void registerStateGIDs(const std::list<index_pair> & staGIDListRef) {}
105 
106  virtual void registerStoreGIDs(const std::list<index_pair> & stoGIDListRef) {}
107 
108  virtual void registerLIDs( const std::vector<int> & intLIDVecRef,
109  const std::vector<int> & extLIDVecRef ) {}
110  virtual void registerStateLIDs( const std::vector<int> & staLIDVecRef ) {}
111 
112  virtual void registerStoreLIDs( const std::vector<int> & stoLIDVecRef ) {}
113 
114  virtual const std::vector<std::string> & getDepSolnVars();
115  virtual void registerDepSolnGIDs( const std::vector< std::vector<int> > & varList );
116  virtual const std::vector<std::string> & getDepStateVars();
117  virtual void registerDepStateGIDs( const std::vector< std::vector<int> > & varList );
118  virtual const std::vector<std::string> & getDepStoreVars();
119  virtual void registerDepStoreGIDs( const std::vector< std::vector<int> > & varList );
120 
121  virtual void registerDepSolnLIDs( const std::vector< std::vector<int> > & depSolnLIDVecRef );
122  virtual void registerDepStateLIDs( const std::vector< std::vector<int> > & depStaLIDVecRef ) {}
123  virtual void registerDepStoreLIDs( const std::vector< std::vector<int> > & depStoLIDVecRef ) {}
124 
125  virtual const std::vector< std::vector<int> > & jacobianStamp() const
126  {
127  static std::vector< std::vector<int> > dummy;
128  return dummy;
129  }
130 
131  virtual void registerJacLIDs( const std::vector< std::vector<int> > & jacLIDVec );
132 
133  virtual void registerGIDData(
134  const std::vector<int> & counts,
135  const std::vector<int> & GIDs,
136  const std::vector< std::vector<int> > & jacGIDs );
137 
138  virtual void setupPointers()
139  {}
140 
141  virtual void getDepSolnGIDVec( std::vector<int> & depGIDVec );
142 
143  virtual bool getIndexPairList(std::list<index_pair> & iplRef);
144 
145  virtual bool getInstanceBreakPoints (std::vector<Util::BreakPoint> &breakPointTimes);
146 
147  virtual bool updateSource ();
148 
149  virtual bool processParams ();
150 
151  virtual bool processInstanceParams ()
152  {
153  return true;
154  }
155 
156  virtual bool updateTemperature(const double & temp_tmp);
157 
158  virtual bool isConverged();
159 
160  virtual bool testDAEMatrices (std::vector<std::string> & nameVec);
161 
162  virtual bool loadTrivialDAE_FMatrixStamp ();
163  bool trivialStampLoader (N_LAS_Matrix * matPtr);
164  bool zeroMatrixDiagonal (N_LAS_Matrix * matPtr);
165 
166  virtual bool updateIntermediateVars() = 0;
167  virtual bool updatePrimaryState() = 0;
168  virtual bool updateSecondaryState ();
169  virtual bool setIC ();
170 
171  // This indicates if the device has functions that can output plot files for
172  // internal variables.
173  virtual bool plotfileFlag () {return false;}
174 
175  // load zeros into mask for equations that should not be used
176  // to compute error estimates. Return true if any zeros set.
177  // Default implementation just does nothing (leaves everything 1.0)
178  virtual bool loadDeviceMask() {return false;}
179 
180  // tell device instance that current solution has been accepted at
181  // current time. Most devices don't care, but the transmission line
182  // does.
183  virtual void acceptStep() {}
184 
185  // new DAE functions:
186  virtual bool loadDAEQVector ()=0;
187  virtual bool loadDAEFVector ()=0;
188  virtual bool loadDAEBVector (){return true;}
189 
190  virtual bool loadDAEdQdx ()=0;
191  virtual bool loadDAEdFdx ()=0;
192 
193  const InstanceName &getName() const
194  {
195  return name_;
196  }
197 
198  int getNumIntVars() const
199  {
200  return numIntVars;
201  }
202 
203  int getNumExtVars() const
204  {
205  return numExtVars;
206  }
207 
208  int getNumStateVars() const
209  {
210  return numStateVars;
211  }
212 
213  int getNumStoreVars() const
214  {
215  return numStoreVars;
216  }
217 
218  void setNumStoreVars(int num_store_vars)
219  {
220  numStoreVars = num_store_vars;
221  }
222 
223  virtual void getDevConMap(std::vector<int> &);
224 
225  virtual DeviceState * getInternalState();
226  virtual bool setInternalState( const DeviceState & state );
227 
228  virtual bool loadDFDV(int iElectrode, N_LAS_Vector * dfdvPtr);
229  virtual bool calcConductance (int iElectrode, const N_LAS_Vector * dxdvPtr);
230 
231  // internal name map stuff:
232  virtual std::map<int, std::string> & getIntNameMap ();
233  virtual std::map<int, std::string> & getStateNameMap ();
234  virtual std::map<int, std::string> & getStoreNameMap ();
235 
236  virtual bool outputPlotFiles () {return true;}
237 
238  // two level newton and PDE-continuation
239  virtual bool enablePDEContinuation();
240  virtual bool disablePDEContinuation();
241  virtual void setPDEContinuationAlpha (double alpha);
242  virtual void setPDEContinuationBeta (double beta );
243 
244  virtual bool setInitialGuess ();
245  virtual double getMaxTimeStepSize ();
246 
247  virtual void varTypes( std::vector<char> & varTypeVec ) {}
248 
249 protected:
250  void jacStampMap(
251  std::vector< std::vector<int> > & stamp_parent,
252  std::vector<int> & map_parent,
253  std::vector< std::vector<int> > & map2_parent,
254  std::vector< std::vector<int> > & stamp,
255  std::vector<int> & map,
256  std::vector< std::vector<int> > & map2,
257  int from, int to, int original_size);
258 
260  std::vector< std::vector<int> > & stamp_parent,
261  std::vector< std::vector<int> > & map2_parent,
262  std::vector< std::vector<int> > & stamp,
263  std::vector< std::vector<int> > & map2);
264 
265  void outputJacStamp(const std::vector<std::vector<int> > & jac);
266  void outputJacMaps(const std::vector<int> & jacMap, const std::vector<std::vector<int> > & jacMap2);
267 
268 public:
269  bool getOrigFlag() const
270  {
271  return origFlag;
272  }
273 
274  void setOrigFlag(bool origFlag_local)
275  {
276  origFlag = origFlag_local;
277  }
278 
279  const std::vector<int> &getDevLIDs() const
280  {
281  return devLIDs;
282  }
283 
284  const std::vector<std::vector<int> > &getDevJacLIDs() const
285  {
286  return devJacLIDs;
287  }
288 
289  const std::vector<int> &getStaLIDVec() const
290  {
291  return staLIDVec;
292  }
293 
294  bool getMergeRowColChecked() const
295  {
296  return mergeRowColChecked;
297  }
298  void setMergeRowColChecked(bool mergeRowColChecked_local)
299  {
300  mergeRowColChecked = mergeRowColChecked_local;
301  }
302 
304  {
305  return mlData;
306  }
307 
309  {
310  return mlData;
311  }
312 
313  const ExternData &getExternData() const {
314  return extData;
315  }
316 
317 private:
320 
321 protected:
323  std::list<index_pair> intGIDList;
324  std::list<index_pair> extGIDList;
325  std::list<index_pair> indexPairList;
326 
327  std::list<index_pair> staGIDList;
328 
329  std::vector<int> intLIDVec;
330  std::vector<int> extLIDVec;
331 
332  std::vector<int> staLIDVec;
333  std::vector<int> stoLIDVec;
334 
335  // devLIDs is a combined LID vector, containing int, ext, and expVar ID's.
336  std::vector<int> devLIDs;
337  std::vector< std::vector<int> > devJacLIDs;
338 
339  std::map<int,std::string> intNameMap;
340  std::map<int,std::string> stateNameMap;
341  std::map<int,std::string> storeNameMap;
342 
343  // device support class: (limiter functions, etc.)
345 
346 private:
347  bool configuredForLeadCurrent; // flag which indicates that numStoreVars already includes numLeadCurrentStoreVars
348 
349 public:
350  std::vector<int> & cols;
351  std::vector<double> & vals;
352 
354 
355  bool psLoaded;
356  bool ssLoaded;
357  bool rhsLoaded;
358 
359  bool origFlag;
360 
365 
367  bool loadLeadCurrent; // flag indicating that we want to load lead current data during F & Q load
368 
369  std::vector<int> devConMap;
370 
372 };
373 
374 //-----------------------------------------------------------------------------
375 // Function : DeviceInstance::updateSecondaryState
376 // Purpose :
377 // Special Notes :
378 // Scope : public
379 // Creator : Eric Keiter, SNL, Parallel Computational Sciences
380 // Creation Date : 11/30/00
381 //-----------------------------------------------------------------------------
383 {
384  return true;
385 }
386 
387 //-----------------------------------------------------------------------------
388 // Function : DeviceInstance::setIC
389 // Purpose :
390 // Special Notes :
391 // Scope : public
392 // Creator : Eric Keiter, SNL, Parallel Computational Sciences
393 // Creation Date : 07/22/03
394 //-----------------------------------------------------------------------------
395 inline bool DeviceInstance::setIC ()
396 {
397  return true;
398 }
399 
400 //-----------------------------------------------------------------------------
401 // Function : DeviceInstance::getInternalState
402 // Purpose :
403 // Special Notes :
404 // Scope : public
405 // Creator : Robert J Hoekstra, SNL, Parallel Computational Sciences
406 // Creation Date : 09/02/01
407 //-----------------------------------------------------------------------------
409 {
410  return NULL;
411 }
412 
413 //-----------------------------------------------------------------------------
414 // Function : DeviceInstance::getIntNameMap
415 // Purpose :
416 // Special Notes :
417 // Scope : public
418 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
419 // Creation Date : 09/07/01
420 //-----------------------------------------------------------------------------
421 inline std::map<int, std::string> & DeviceInstance::getIntNameMap ()
422 {
423  return intNameMap;
424 }
425 
426 //-----------------------------------------------------------------------------
427 // Function : DeviceInstance::getStateNameMap
428 // Purpose :
429 // Special Notes :
430 // Scope : public
431 // Creator : Richard Schiek, Electrical Systems Modeling
432 // Creation Date : 07/31/2012
433 //-----------------------------------------------------------------------------
434 inline std::map<int, std::string> & DeviceInstance::getStateNameMap ()
435 {
436  return stateNameMap;
437 }
438 
439 //-----------------------------------------------------------------------------
440 // Function : DeviceInstance::getStoreNameMap
441 // Purpose :
442 // Special Notes :
443 // Scope : public
444 // Creator : Richard Schiek, Electrical Systems Modeling
445 // Creation Date : 07/31/2012
446 //-----------------------------------------------------------------------------
447 inline std::map<int, std::string> & DeviceInstance::getStoreNameMap ()
448 {
449  return storeNameMap;
450 }
451 
452 //-----------------------------------------------------------------------------
453 // Function : DeviceInstance::getDevConMap
454 // Purpose : Get connectivity map for leads. Zero means a lead is
455 // connected to ground. Other values indicate subsets of
456 // leads that have sonnection to each other. Example would
457 // be a mosfet which would have 1 for gate and 2 for drain
458 // and source and zero for bulk, assuming bulk is grounded
459 // Special Notes :
460 // Scope : public
461 // Creator : Dave Shirley, PSSI
462 // Creation Date : 06/20/05
463 //-----------------------------------------------------------------------------
464 inline void DeviceInstance::getDevConMap(std::vector<int> & conMap)
465 {
466  conMap = devConMap;
467 }
468 
469 //-----------------------------------------------------------------------------
470 // Function : DeviceInstance::loadDFDV
471 // Purpose :
472 // Special Notes :
473 // Scope : public
474 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
475 // Creation Date : 12/03/02
476 //-----------------------------------------------------------------------------
477 inline bool DeviceInstance::loadDFDV(int iElectrode, N_LAS_Vector * dfdvPtr)
478 {
479  return true;
480 }
481 
482 //-----------------------------------------------------------------------------
483 // Function : DeviceInstance::calcConductance
484 // Purpose :
485 // Special Notes :
486 // Scope : public
487 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
488 // Creation Date : 12/03/02
489 //-----------------------------------------------------------------------------
490 inline bool DeviceInstance::calcConductance (int iElectrode, const N_LAS_Vector * dxdvPtr)
491 {
492  return true;
493 }
494 
495 //-----------------------------------------------------------------------------
496 // Function : DeviceInstance:isConverged ()
497 // Purpose : Return whether a device has done something that should
498 // be interpreted as invalidating other convergence tests
499 // (i.e. that means this step should not be considered
500 // converged even if norms are good)
501 // Since origFlag is set to true by the DeviceInstance
502 // constructor, this is a suitable base class method for
503 // almost all devices. Devices with more complex convergence
504 // issues can override.
505 // Special Notes :
506 // Scope : public
507 // Creator : Tom Russo, SNL, Component Information and Models
508 // Creation Date : 03/22/05
509 //-----------------------------------------------------------------------------
511 {
512  return origFlag;
513 }
514 
515 //-----------------------------------------------------------------------------
516 // Function : DeviceInstance::getInstanceBreakPoints
517 // Purpose : virtual function for obtaining breakpoints from a device.
518 //
519 // Special Notes : No-op for the base class version.
520 //
521 // Scope : public
522 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
523 // Creation Date : 2/05/06
524 //-----------------------------------------------------------------------------
525 inline bool DeviceInstance::getInstanceBreakPoints(std::vector<Util::BreakPoint> &breakPointTimes)
526 {
527  return false;
528 }
529 
530 //-----------------------------------------------------------------------------
531 // Function : DeviceInstance::updateSource
532 // Purpose : virtual function for obtaining breakpoints from a device.
533 //
534 // Special Notes : No-op for the base class version.
535 //
536 // Scope : public
537 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
538 // Creation Date : 2/05/06
539 //-----------------------------------------------------------------------------
541 {
542  return true;
543 }
544 
545 } // namespace Device
546 } // namespace Xyce
547 
549 
550 #endif
551