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