Xyce  6.1
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-2015 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.203 $
40 //
41 // Revision Date : $Date: 2015/04/24 20:25:43 $
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_ANP_fwd.h>
55 #include <N_DEV_fwd.h>
56 #include <N_LAS_fwd.h>
57 
58 #include <N_DEV_DeviceEntity.h>
59 #include <N_DEV_DeviceSupport.h>
60 #include <N_UTL_Diagnostic.h>
61 #include <N_UTL_IndexPair.h>
62 #include <N_UTL_NodeSymbols.h>
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  // Is the instance of this device linear.
93  // NOTE: Only linear devices need to override this virtual function.
94  virtual bool isLinearDevice() const { return false; }
95 
96  virtual std::ostream &printName(std::ostream &os) const;
97 
98  // This function configures the device to request space in the store
99  // vector for lead current calculations. It must be called soon
100  // after the constructor call before the store vector is allocated.
101  virtual void enableLeadCurrentCalc();
102 
103  virtual void registerGIDs(const IndexPairVector & intGIDListRef, const IndexPairVector &extGIDListRef)
104  {}
105 
106  virtual void registerStateGIDs(const IndexPairVector & staGIDListRef)
107  {}
108 
109  virtual void registerStoreGIDs(const IndexPairVector & stoGIDListRef)
110  {}
111 
112  virtual void registerLIDs( const LocalIdVector & intLIDVecRef, const LocalIdVector & extLIDVecRef )
113  {}
114 
115  virtual void registerStateLIDs( const LocalIdVector & staLIDVecRef )
116  {}
117 
118  virtual void registerStoreLIDs( const LocalIdVector & stoLIDVecRef )
119  {}
120 
121  virtual void registerBranchDataLIDs( const LocalIdVector & branchDataLIDVecRef )
122  {}
123 
124  virtual const std::vector<std::string> & getDepSolnVars();
125  virtual void registerDepSolnGIDs( const std::vector< IdVector > & varList );
126 
127  virtual const std::vector<std::string> & getDepStateVars();
128  virtual void registerDepStateGIDs( const std::vector< IdVector > & varList );
129 
130  virtual const std::vector<std::string> & getDepStoreVars();
131  virtual void registerDepStoreGIDs( const std::vector< IdVector > & varList );
132 
133  virtual const std::vector<std::string> & getDepLeadCurrentVars();
134  virtual void registerDepLeadCurrentGIDs( const std::vector< IdVector > & varList );
135 
136 
137  virtual void registerDepSolnLIDs(const std::vector< IdVector > & depSolnLIDVecRef);
138 
139  virtual void registerDepStateLIDs(const std::vector< IdVector > & depStaLIDVecRef )
140  {}
141 
142  virtual void registerDepStoreLIDs( const std::vector< IdVector > & depStoLIDVecRef )
143  {}
144 
145  virtual const JacobianStamp & jacobianStamp() const
146  {
147  static JacobianStamp dummy;
148  return dummy;
149  }
150 
151  virtual void registerJacLIDs( const JacobianStamp & jacLIDVec );
152 
153  virtual void registerGIDData(
154  const std::vector<int> & counts,
155  const IdVector & GIDs,
156  const JacobianStamp & jacGIDs );
157 
158  virtual void setupPointers()
159  {}
160 
161  virtual const IdVector & getDepSolnGIDVec()
162  {
163  return expVarGIDs;
164  }
165 
166  virtual const IndexPairVector & getIndexPairList()
167  {
168  return indexPairList;
169  }
170 
171  virtual bool getInstanceBreakPoints (std::vector<Util::BreakPoint> &breakPointTimes);
172 
173  virtual bool updateSource ();
174 
175  virtual bool processParams ();
176 
177  virtual bool processInstanceParams ()
178  {
179  return true;
180  }
181 
182  virtual bool updateTemperature(const double & temp_tmp);
183 
184  virtual bool isConverged();
185 
186  virtual bool testDAEMatrices(const std::vector<const std::string *> &nameVec);
187 
188  virtual bool loadTrivialDAE_FMatrixStamp ();
189  bool trivialStampLoader (Linear::Matrix * matPtr);
190  bool zeroMatrixDiagonal (Linear::Matrix * matPtr);
191 
192  virtual bool updateIntermediateVars() = 0;
193  virtual bool updatePrimaryState() = 0;
194  virtual bool updateSecondaryState ();
195  virtual bool setIC ();
196 
197  // This indicates if the device has functions that can output plot files for
198  // internal variables.
199  virtual bool plotfileFlag () {return false;}
200 
201  // load zeros into mask for equations that should not be used
202  // to compute error estimates. Return true if any zeros set.
203  // Default implementation just does nothing (leaves everything 1.0)
204  virtual void loadErrorWeightMask() {}
205 
206  // tell device instance that current solution has been accepted at
207  // current time. Most devices don't care, but the transmission line
208  // does.
209  virtual void acceptStep() {}
210 
211  // new DAE functions:
212  virtual bool loadDAEQVector ()=0;
213  virtual bool loadDAEFVector ()=0;
214  virtual bool loadDAEBVector (){return true;}
215 
216  virtual bool loadDAEdQdx ()=0;
217  virtual bool loadDAEdFdx ()=0;
218 
219  virtual int getNumNoiseSources () const
220  {
221  return 0;
222  }
223 
224  virtual void setupNoiseSources (Xyce::Analysis::NoiseData & noiseDataVec)
225  {
226  return;
227  }
228 
229  virtual void getNoiseSources (Xyce::Analysis::NoiseData & noiseDataVec)
230  {
231  return;
232  }
233 
234  const InstanceName &getName() const
235  {
236  return name_;
237  }
238 
239  int getNumIntVars() const
240  {
241  return numIntVars;
242  }
243 
244  int getNumExtVars() const
245  {
246  return numExtVars;
247  }
248 
249  int getNumStateVars() const
250  {
251  return numStateVars;
252  }
253 
254  int getNumStoreVars() const
255  {
256  return numStoreVars;
257  }
258 
260  {
261  return numBranchDataVars;
262  }
263 
264  void setNumStoreVars(int num_store_vars)
265  {
266  numStoreVars = num_store_vars;
267  }
268 
269  void setNumBranchDataVars(int num_branch_data_vars)
270  {
271  numBranchDataVars = num_branch_data_vars;
272  }
273 
274 
275  virtual const std::vector<int> & getDevConMap();
276 
277  virtual DeviceState * getInternalState();
278  virtual bool setInternalState( const DeviceState & state );
279 
280  virtual bool loadDFDV(int iElectrode, Linear::Vector * dfdvPtr);
281  virtual bool calcConductance (int iElectrode, const Linear::Vector * dxdvPtr);
282 
283  /// Populates and returns the store name map.
284  virtual void loadNodeSymbols(Util::SymbolTable &symbol_table) const = 0;
285 
286  virtual bool outputPlotFiles(bool force_final_output) {return true;}
287 
288  // two level newton and PDE-continuation
289  virtual bool enablePDEContinuation(int &max_PDE_continuation_steps);
290  virtual bool disablePDEContinuation();
291  virtual void setPDEContinuationAlpha (double alpha);
292  virtual void setPDEContinuationBeta (double beta );
293 
294  virtual bool setInitialGuess ();
295  virtual double getMaxTimeStepSize ();
296 
297  virtual void varTypes( std::vector<char> & varTypeVec ) {}
298 
299 protected:
300  void jacStampMap(
301  const JacobianStamp & stamp_parent,
302  IdVector & map_parent,
303  JacobianStamp & map2_parent,
304  JacobianStamp & stamp,
305  IdVector & map,
306  JacobianStamp & map2,
307  int from,
308  int to,
309  int original_size);
310 
312  const JacobianStamp & stamp_parent,
313  JacobianStamp & map2_parent,
314  JacobianStamp & stamp,
315  JacobianStamp & map2);
316 
317  void outputJacStamp(const JacobianStamp & jac);
318  void outputJacMaps(const std::vector<int> & jacMap, const JacobianStamp & jacMap2);
319 
320 public:
321  bool getOrigFlag() const
322  {
323  return origFlag;
324  }
325 
326  void setOrigFlag(bool origFlag_local)
327  {
328  origFlag = origFlag_local;
329  }
330 
331  const IdVector &getDevLIDs() const
332  {
333  return devLIDs;
334  }
335 
336  const std::vector<IdVector > &getDevJacLIDs() const
337  {
338  return devJacLIDs;
339  }
340 
341  const IdVector &getStaLIDVec() const
342  {
343  return staLIDVec;
344  }
345 
346  bool getMergeRowColChecked() const
347  {
348  return mergeRowColChecked;
349  }
350  void setMergeRowColChecked(bool mergeRowColChecked_local)
351  {
352  mergeRowColChecked = mergeRowColChecked_local;
353  }
354 
356  {
357  return mlData;
358  }
359 
361  {
362  return mlData;
363  }
364 
365  const ExternData &getExternData() const {
366  return extData;
367  }
368 
369 private:
372 
373 protected:
375 
376  IndexPairVector indexPairList;
377  IndexPairVector intGIDList;
378  IndexPairVector extGIDList;
379  IndexPairVector staGIDList;
380 
385  IdVector devLIDs; ///< devLIDs is a combined LID vector, containing int, ext, and expVar ID's.
387 
388  // device support class: (limiter functions, etc.)
390 
391 private:
392  bool configuredForLeadCurrent; // flag which indicates that numStoreVars already includes numLeadCurrentStoreVars
393 
394 public:
395  std::vector<int> & cols;
396  std::vector<double> & vals;
397 
399 
400  bool psLoaded;
401  bool ssLoaded;
402  bool rhsLoaded;
403 
404  bool origFlag;
405 
411 
413  bool loadLeadCurrent; // flag indicating that we want to load lead current data during F & Q load
414 
415  int numBranchDataVars; // number of spaces to allocate in lead current and junction voltage arrays for lead current and power calculations
416  // this is initially set to zero but the next variable is added to this if the parser find a lead current or power
417  // calculation called for by the simulation.
418  int numBranchDataVarsIfAllocated; // number of spaces to allocate in lead current and junction voltage arrays for lead current and power calculations
419 
420  std::vector<int> devConMap;
421 
423 };
424 
425 //-----------------------------------------------------------------------------
426 // Function : DeviceInstance::updateSecondaryState
427 // Purpose :
428 // Special Notes :
429 // Scope : public
430 // Creator : Eric Keiter, SNL, Parallel Computational Sciences
431 // Creation Date : 11/30/00
432 //-----------------------------------------------------------------------------
434 {
435  return true;
436 }
437 
438 //-----------------------------------------------------------------------------
439 // Function : DeviceInstance::setIC
440 // Purpose :
441 // Special Notes :
442 // Scope : public
443 // Creator : Eric Keiter, SNL, Parallel Computational Sciences
444 // Creation Date : 07/22/03
445 //-----------------------------------------------------------------------------
446 inline bool DeviceInstance::setIC ()
447 {
448  return true;
449 }
450 
451 //-----------------------------------------------------------------------------
452 // Function : DeviceInstance::getInternalState
453 // Purpose :
454 // Special Notes :
455 // Scope : public
456 // Creator : Robert J Hoekstra, SNL, Parallel Computational Sciences
457 // Creation Date : 09/02/01
458 //-----------------------------------------------------------------------------
460 {
461  return NULL;
462 }
463 
464 //-----------------------------------------------------------------------------
465 // Function : DeviceInstance::getDevConMap
466 // Purpose : Get connectivity map for leads. Zero means a lead is
467 // connected to ground. Other values indicate subsets of
468 // leads that have connection to each other. Example would
469 // be a mosfet which would have 1 for gate and 2 for drain
470 // and source and zero for bulk, assuming bulk is grounded
471 // Special Notes :
472 // Scope : public
473 // Creator : Dave Shirley, PSSI
474 // Creation Date : 06/20/05
475 //-----------------------------------------------------------------------------
476 inline const std::vector<int> & DeviceInstance::getDevConMap()
477 {
478  return devConMap;
479 }
480 
481 //-----------------------------------------------------------------------------
482 // Function : DeviceInstance::loadDFDV
483 // Purpose :
484 // Special Notes :
485 // Scope : public
486 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
487 // Creation Date : 12/03/02
488 //-----------------------------------------------------------------------------
489 inline bool DeviceInstance::loadDFDV(int iElectrode, Linear::Vector * dfdvPtr)
490 {
491  return true;
492 }
493 
494 //-----------------------------------------------------------------------------
495 // Function : DeviceInstance::calcConductance
496 // Purpose :
497 // Special Notes :
498 // Scope : public
499 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
500 // Creation Date : 12/03/02
501 //-----------------------------------------------------------------------------
502 inline bool DeviceInstance::calcConductance (int iElectrode, const Linear::Vector * dxdvPtr)
503 {
504  return true;
505 }
506 
507 //-----------------------------------------------------------------------------
508 // Function : DeviceInstance:isConverged ()
509 // Purpose : Return whether a device has done something that should
510 // be interpreted as invalidating other convergence tests
511 // (i.e. that means this step should not be considered
512 // converged even if norms are good)
513 // Since origFlag is set to true by the DeviceInstance
514 // constructor, this is a suitable base class method for
515 // almost all devices. Devices with more complex convergence
516 // issues can override.
517 // Special Notes :
518 // Scope : public
519 // Creator : Tom Russo, SNL, Component Information and Models
520 // Creation Date : 03/22/05
521 //-----------------------------------------------------------------------------
523 {
524  return origFlag;
525 }
526 
527 //-----------------------------------------------------------------------------
528 // Function : DeviceInstance::getInstanceBreakPoints
529 // Purpose : virtual function for obtaining breakpoints from a device.
530 //
531 // Special Notes : No-op for the base class version.
532 //
533 // Scope : public
534 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
535 // Creation Date : 2/05/06
536 //-----------------------------------------------------------------------------
537 inline bool DeviceInstance::getInstanceBreakPoints(std::vector<Util::BreakPoint> &breakPointTimes)
538 {
539  return false;
540 }
541 
542 //-----------------------------------------------------------------------------
543 // Function : DeviceInstance::updateSource
544 // Purpose : virtual function for obtaining breakpoints from a device.
545 //
546 // Special Notes : No-op for the base class version.
547 //
548 // Scope : public
549 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
550 // Creation Date : 2/05/06
551 //-----------------------------------------------------------------------------
553 {
554  return true;
555 }
556 
557 inline void addInternalNode(Util::SymbolTable &symbol_table, int index, const InstanceName &instance_name, const std::string &lead_name) {
558  Util::addSymbol(symbol_table, Util::SOLUTION_SYMBOL, index, spiceInternalName(instance_name, lead_name));
559 }
560 
561 inline void addInternalNode(Util::SymbolTable &symbol_table, int index, const std::string &lead_name) {
562  Util::addSymbol(symbol_table, Util::SOLUTION_SYMBOL, index, lead_name);
563 }
564 
565 inline void addStoreNode(Util::SymbolTable &symbol_table, int index, const InstanceName &instance_name, const std::string &lead_name) {
566  Util::addSymbol(symbol_table, Util::STORE_SYMBOL, index, spiceStoreName(instance_name, lead_name));
567 }
568 
569 inline void addStoreNode(Util::SymbolTable &symbol_table, int index, const std::string &lead_name) {
570  Util::addSymbol(symbol_table, Util::STORE_SYMBOL, index, lead_name);
571 }
572 
573 inline void addStateNode(Util::SymbolTable &symbol_table, int index, const InstanceName &instance_name, const std::string &lead_name) {
574  Util::addSymbol(symbol_table, Util::STATE_SYMBOL, index, spiceInternalName(instance_name, lead_name));
575 }
576 
577 inline void addBranchDataNode(Util::SymbolTable &symbol_table, int index, const InstanceName &instance_name, const std::string &lead_name) {
578  Util::addSymbol(symbol_table, Util::BRANCH_SYMBOL, index, spiceStoreName(instance_name, lead_name));
579 }
580 
581 inline void addBranchDataNode(Util::SymbolTable &symbol_table, int index, const std::string &lead_name) {
582  Util::addSymbol(symbol_table, Util::BRANCH_SYMBOL, index, lead_name);
583 }
584 
585 } // namespace Device
586 } // namespace Xyce
587 
588 #endif
589 
const InstanceName & getName() const
virtual void registerGIDData(const std::vector< int > &counts, const IdVector &GIDs, const JacobianStamp &jacGIDs)
virtual const IndexPairVector & getIndexPairList()
virtual void setupNoiseSources(Xyce::Analysis::NoiseData &noiseDataVec)
virtual void loadNodeSymbols(Util::SymbolTable &symbol_table) const =0
Populates and returns the store name map.
virtual void registerStoreLIDs(const LocalIdVector &stoLIDVecRef)
void addStateNode(Util::SymbolTable &symbol_table, int index, const InstanceName &instance_name, const std::string &lead_name)
virtual void registerStateGIDs(const IndexPairVector &staGIDListRef)
std::vector< double > & vals
const std::vector< IdVector > & getDevJacLIDs() const
virtual DeviceState * getInternalState()
Pure virtual class to augment a linear system.
Devices and models are each named.
virtual void getNoiseSources(Xyce::Analysis::NoiseData &noiseDataVec)
virtual void registerGIDs(const IndexPairVector &intGIDListRef, const IndexPairVector &extGIDListRef)
void addInternalNode(Util::SymbolTable &symbol_table, int index, const InstanceName &instance_name, const std::string &lead_name)
void outputJacMaps(const std::vector< int > &jacMap, const JacobianStamp &jacMap2)
virtual bool loadDAEFVector()=0
void setNumStoreVars(int num_store_vars)
virtual bool loadDAEQVector()=0
void addBranchDataNode(Util::SymbolTable &symbol_table, int index, const InstanceName &instance_name, const std::string &lead_name)
virtual bool enablePDEContinuation(int &max_PDE_continuation_steps)
virtual void registerDepSolnGIDs(const std::vector< IdVector > &varList)
virtual bool loadDAEdFdx()=0
void jacStampMap_fixOrder(const JacobianStamp &stamp_parent, JacobianStamp &map2_parent, JacobianStamp &stamp, JacobianStamp &map2)
virtual void registerDepStateLIDs(const std::vector< IdVector > &depStaLIDVecRef)
virtual void registerJacLIDs(const JacobianStamp &jacLIDVec)
virtual bool getInstanceBreakPoints(std::vector< Util::BreakPoint > &breakPointTimes)
void setOrigFlag(bool origFlag_local)
virtual bool setInternalState(const DeviceState &state)
const IdVector & getStaLIDVec() const
virtual bool testDAEMatrices(const std::vector< const std::string * > &nameVec)
const MatrixLoadData & getMatrixLoadData() const
virtual bool loadDFDV(int iElectrode, Linear::Vector *dfdvPtr)
virtual const std::vector< int > & getDevConMap()
virtual const std::vector< std::string > & getDepStoreVars()
virtual void registerStateLIDs(const LocalIdVector &staLIDVecRef)
virtual void registerDepStateGIDs(const std::vector< IdVector > &varList)
std::vector< int > IdVector
Definition: N_DEV_fwd.h:197
virtual void registerLIDs(const LocalIdVector &intLIDVecRef, const LocalIdVector &extLIDVecRef)
virtual bool calcConductance(int iElectrode, const Linear::Vector *dxdvPtr)
const IdVector & getDevLIDs() const
The FactoryBlock contains parameters needed by the device, instance and model creation functions...
virtual void registerBranchDataLIDs(const LocalIdVector &branchDataLIDVecRef)
virtual void registerDepSolnLIDs(const std::vector< IdVector > &depSolnLIDVecRef)
virtual const std::vector< std::string > & getDepLeadCurrentVars()
virtual void registerDepLeadCurrentGIDs(const std::vector< IdVector > &varList)
std::vector< std::vector< int > > JacobianStamp
Definition: N_DEV_fwd.h:196
virtual bool updateTemperature(const double &temp_tmp)
Class ParametricData manages the configuration information and the parameter binding map...
Definition: N_DEV_Pars.h:1303
bool trivialStampLoader(Linear::Matrix *matPtr)
void setMergeRowColChecked(bool mergeRowColChecked_local)
virtual bool isLinearDevice() const
virtual void registerStoreGIDs(const IndexPairVector &stoGIDListRef)
DeviceInstance & operator=(const DeviceInstance &)
virtual bool loadDAEdQdx()=0
virtual bool updatePrimaryState()=0
IdVector LocalIdVector
Definition: N_DEV_fwd.h:198
void addStoreNode(Util::SymbolTable &symbol_table, int index, const InstanceName &instance_name, const std::string &lead_name)
virtual void registerDepStoreLIDs(const std::vector< IdVector > &depStoLIDVecRef)
virtual void varTypes(std::vector< char > &varTypeVec)
void outputJacStamp(const JacobianStamp &jac)
virtual int getNumNoiseSources() const
virtual void setPDEContinuationBeta(double beta)
virtual const std::vector< std::string > & getDepStateVars()
IdVector devLIDs
devLIDs is a combined LID vector, containing int, ext, and expVar ID's.
void jacStampMap(const JacobianStamp &stamp_parent, IdVector &map_parent, JacobianStamp &map2_parent, JacobianStamp &stamp, IdVector &map, JacobianStamp &map2, int from, int to, int original_size)
virtual void registerDepStoreGIDs(const std::vector< IdVector > &varList)
virtual void setPDEContinuationAlpha(double alpha)
std::string spiceStoreName(const InstanceName &instance_name, const std::string &lead)
virtual const JacobianStamp & jacobianStamp() const
void setNumBranchDataVars(int num_branch_data_vars)
const ExternData & getExternData() const
std::string spiceInternalName(const InstanceName &instance_name, const std::string &lead)
bool zeroMatrixDiagonal(Linear::Matrix *matPtr)
virtual std::ostream & printName(std::ostream &os) const
virtual const IdVector & getDepSolnGIDVec()
InstanceBlock represent a device instance line from the netlist.
virtual bool updateIntermediateVars()=0
virtual bool outputPlotFiles(bool force_final_output)
virtual const std::vector< std::string > & getDepSolnVars()