Xyce  6.1
N_DEV_Device.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_Device.h,v $
27 //
28 // Purpose :
29 //
30 // Special Notes :
31 //
32 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
33 //
34 // Creation Date : 02/28/00
35 //
36 // Revision Information:
37 // ---------------------
38 //
39 // Revision Number: $Revision: 1.127.2.1 $
40 //
41 // Revision Date : $Date: 2015/04/02 18:20:09 $
42 //
43 // Current Owner : $Author: tvrusso $
44 //-----------------------------------------------------------------------------
45 
46 #ifndef Xyce_N_DEV_Device_h
47 #define Xyce_N_DEV_Device_h
48 
49 #include <iosfwd>
50 #include <map>
51 #include <string>
52 #include <vector>
53 #include <functional>
54 
55 #include <N_DEV_fwd.h>
56 #include <N_LAS_fwd.h>
57 #include <N_DEV_InstanceName.h>
58 
59 namespace Xyce {
60 namespace Device {
61 
62 struct DeviceModelOp: public std::unary_function<DeviceModel *, bool>
63 {
64  virtual ~DeviceModelOp()
65  {}
66 
67  virtual bool operator()(DeviceModel *model) = 0;
68 };
69 
70 struct DeviceInstanceOp: public std::unary_function<DeviceInstance *, bool>
71 {
72 
74  {}
75 
76  virtual bool operator()(DeviceInstance *instance) = 0;
77 };
78 
79 //-----------------------------------------------------------------------------
80 // Class : Device
81 // Purpose :
82 // Special Notes :
83 // Scope : public
84 // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
85 // Creation Date : Tue Apr 22 12:47:22 2014
86 //-----------------------------------------------------------------------------
87 ///
88 /// The Device class is an interface for device implementations.
89 ///
90 /// In general, DeviceMaster is the only class that actually inherits
91 /// from Device. Most devices either use the DeviceMaster class, but
92 /// some derive from DeviceMaster in what is known as a Master class.
93 ///
94 /// The interfaces are unfortunately used for but derived
95 /// implementation as well as usage. This should be changed at some
96 /// point, but this is the currently basic design of most interface
97 /// classes.
98 ///
99 /// @author Eric Keiter, SNL, Parallel Computational Sciences
100 /// @date 3/16/00
101 class Device
102 {
103 public:
105  {}
106 
107  virtual ~Device()
108  {}
109 
110 private:
111  Device(const Device &); ///< No copying
112  Device &operator=(const Device &); ///< No assignment
113 
114 public:
115  //-----------------------------------------------------------------------------
116  // Function : isLinearDevice
117  // Purpose :
118  // Special Notes :
119  // Scope : public
120  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
121  // Creation Date : Wed Jan 29 16:36:27 2014
122  //-----------------------------------------------------------------------------
123  ///
124  /// Returns true if the device is linear
125  ///
126  /// @return true if the device is linear.
127  ///
128  virtual bool isLinearDevice() const = 0;
129 
130  //-----------------------------------------------------------------------------
131  // Function : isPDEDevice
132  // Purpose :
133  // Special Notes :
134  // Scope : public
135  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
136  // Creation Date : Wed Jan 29 16:37:02 2014
137  //-----------------------------------------------------------------------------
138  ///
139  /// Returns true is the device is a PDE device
140  ///
141  /// @return true is the device is a PDE device.
142  ///
143  virtual bool isPDEDevice() const = 0;
144 
145  //-----------------------------------------------------------------------------
146  // Function : getName
147  // Purpose :
148  // Special Notes :
149  // Scope : public
150  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
151  // Creation Date : Wed Jan 29 16:37:34 2014
152  //-----------------------------------------------------------------------------
153  ///
154  /// Returns the name given to the device
155  ///
156  /// @return const reference to the device name.
157  ///
158  virtual const std::string &getName() const = 0;
159 
160  //-----------------------------------------------------------------------------
161  // Function : getDefaultModelName
162  // Purpose :
163  // Special Notes :
164  // Scope : public
165  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
166  // Creation Date : Wed Jan 29 16:38:02 2014
167  //-----------------------------------------------------------------------------
168  ///
169  /// Returns the name of the default model that would to used for this device
170  ///
171  /// @return const reference to the name of the default model
172  ///
173  virtual const std::string &getDefaultModelName() const = 0;
174 
175  //-----------------------------------------------------------------------------
176  // Function : findModel
177  // Purpose :
178  // Special Notes :
179  // Scope : public
180  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
181  // Creation Date : Wed Jan 29 16:39:23 2014
182  //-----------------------------------------------------------------------------
183  ///
184  /// Returns the device entity with the specified name
185  ///
186  /// @param model_name const reference to the name of the entity
187  ///
188  /// @return pointer to the device entity
189  ///
190  virtual DeviceModel *findModel(const ModelName &model_name) = 0;
191 
192  //-----------------------------------------------------------------------------
193  // Function : findModel
194  // Purpose :
195  // Special Notes :
196  // Scope : public
197  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
198  // Creation Date : Wed Jan 29 16:39:23 2014
199  //-----------------------------------------------------------------------------
200  ///
201  /// Returns the device entity with the specified name
202  ///
203  /// @param model_name const reference name of the entity
204  ///
205  /// @return const pointer to the device entity
206  ///
207  virtual const DeviceModel *findModel(const ModelName &model_name) const = 0;
208 
209  //-----------------------------------------------------------------------------
210  // Function : findInstance
211  // Purpose :
212  // Special Notes :
213  // Scope : public
214  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
215  // Creation Date : Wed Jan 29 16:39:23 2014
216  //-----------------------------------------------------------------------------
217  ///
218  /// Returns the device entity with the specified name
219  ///
220  /// @param instance_name const reference to the name of the entity
221  ///
222  /// @return pointer to the device entity
223  ///
224  virtual DeviceEntity *findInstance(const InstanceName &instance_name) = 0;
225 
226  //-----------------------------------------------------------------------------
227  // Function : findInstance
228  // Purpose :
229  // Special Notes :
230  // Scope : public
231  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
232  // Creation Date : Wed Jan 29 16:39:23 2014
233  //-----------------------------------------------------------------------------
234  ///
235  /// Returns the device entity with the specified name
236  ///
237  /// @param instance_name const reference name of the entity
238  ///
239  /// @return const pointer to the device entity
240  ///
241  virtual const DeviceEntity *findInstance(const InstanceName &instance_name) const = 0;
242 
243  //-----------------------------------------------------------------------------
244  // Function : addModel
245  // Purpose :
246  // Special Notes :
247  // Scope : public
248  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
249  // Creation Date : Wed Jan 29 16:40:30 2014
250  //-----------------------------------------------------------------------------
251  ///
252  /// Creates a device model and adds it to the device's list of models
253  ///
254  /// @param model_block const reference to the model block describing the model to create
255  /// @param factory_block const reference to the factory data needed to create the model
256  ///
257  /// @return pointer to the newly created device model
258  ///
259  virtual DeviceModel *addModel(const ModelBlock &model_block, const FactoryBlock &factory_block) = 0;
260 
261  //-----------------------------------------------------------------------------
262  // Function : addInstance
263  // Purpose :
264  // Special Notes :
265  // Scope : public
266  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
267  // Creation Date : Wed Jan 29 16:43:08 2014
268  //-----------------------------------------------------------------------------
269  ///
270  /// Creates a device instance and adds to the device model's instance list
271  ///
272  /// @param instance_block const reference to the model block describing the instance to create
273  /// @param factory_block const reference to the factory data needed to create the instance
274  ///
275  /// @return pointer to the newly creates device instance
276  ///
277  virtual DeviceInstance *addInstance(const InstanceBlock &instance_block, const FactoryBlock &factory_block) = 0;
278 
279  //-----------------------------------------------------------------------------
280  // Function : updateSources
281  // Purpose :
282  // Special Notes :
283  // Scope : public
284  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
285  // Creation Date : Wed Jan 29 16:44:34 2014
286  //-----------------------------------------------------------------------------
287  ///
288  /// Updates the devices source information
289  ///
290  /// This function is called by the analysis subsystem when it is time to update the device source information.
291  ///
292  /// @return true if the update was successful
293  ///
294  virtual bool updateSources()
295  {
296  return true;
297  }
298 
299  //-----------------------------------------------------------------------------
300  // Function : updateState
301  // Purpose :
302  // Special Notes :
303  // Scope : public
304  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
305  // Creation Date : Wed Jan 29 16:44:34 2014
306  //-----------------------------------------------------------------------------
307  ///
308  /// Updates the devices state information
309  ///
310  /// This function is called by the analysis subsystem when it is time to update the device state information.
311  ///
312  /// @return true if the update was successful
313  ///
314  virtual bool updateState(double * solVec, double * staVec, double * stoVec)
315  {
316  return true;
317  }
318 
319  //-----------------------------------------------------------------------------
320  // Function : updateSecondaryState
321  // Purpose :
322  // Special Notes :
323  // Scope : public
324  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
325  // Creation Date : Wed Jan 29 16:44:34 2014
326  //-----------------------------------------------------------------------------
327  ///
328  /// Updates the devices secondary state information
329  ///
330  /// This function is called by the analysis subsystem when it is time to update the device secondary state information.
331  ///
332  /// @return true if the update was successful
333  ///
334  virtual bool updateSecondaryState(double * staDerivVec, double * stoVec)
335  {
336  return true;
337  }
338 
339  //-----------------------------------------------------------------------------
340  // Function : loadDAEVectors
341  // Purpose :
342  // Special Notes :
343  // Scope : public
344  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
345  // Creation Date : Wed Jan 29 16:47:20 2014
346  //-----------------------------------------------------------------------------
347  ///
348  /// Populates the device's ExternData object with these pointers
349  ///
350  /// THIS FUNCTION MUST BE CALLED PRIOR TO CALLING loadDAEMatrices.
351  ///
352  /// @param solVec pointer to the analysis solution vector for this device
353  /// @param fVec pointer to the analysis f vector for this device
354  /// @param qVec pointer to the analysis q vector for this device
355  /// @param storeLeadF pointer to the analysis lead store f vector for this device
356  /// @param storeLeadQ poitner to the analysis load store q vector for this device
357  ///
358  /// @return true if the update was successful
359  ///
360  virtual bool loadDAEVectors (double * solVec, double * fVec, double * qVec, double *bVec, double * storeLeadF, double * storeLeadQ, double * leadF, double * leadQ, double * junctionV)
361  {
362  return true;
363  }
364 
365  //-----------------------------------------------------------------------------
366  // Function : loadDAEMatrices
367  // Purpose :
368  // Special Notes :
369  // Scope : public
370  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
371  // Creation Date : Wed Jan 29 17:06:52 2014
372  //-----------------------------------------------------------------------------
373  ///
374  /// Populates the device's Jacobian object with these pointers
375  ///
376  /// THIS FUNCTION MUST BE CALLED AFTER CALLING loadDAEVectors.
377  ///
378  /// @param dFdx pointer to the analysis dFdx matrix
379  /// @param dQdx pointer to the analysis dQdx matrix
380  ///
381  /// @return
382  ///
383  virtual bool loadDAEMatrices(Linear::Matrix & dFdx, Linear::Matrix & dQdx)
384  {
385  return true;
386  }
387 
388  //-----------------------------------------------------------------------------
389  // Function : deleteInstance
390  // Purpose :
391  // Special Notes :
392  // Scope : public
393  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
394  // Creation Date : Wed Jan 29 17:08:58 2014
395  //-----------------------------------------------------------------------------
396  // ///
397  // /// Delete the specified instance from the device
398  // ///
399  // /// TODO: Check this implementation in DeviceMaster...does it really work?
400  // ///
401  // /// @param instance_name const reference to the instance name of the device instance to be deleted
402  // ///
403  // /// @return true if the delete was successful
404  // ///
405  // virtual bool deleteInstance(DeviceInstance *instance) = 0;
406 
407  //-----------------------------------------------------------------------------
408  // Function : forEachModel
409  // Purpose :
410  // Special Notes :
411  // Scope : public
412  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
413  // Creation Date : Mon Feb 3 10:36:04 2014
414  //-----------------------------------------------------------------------------
415  ///
416  /// Executes op on each DeviceModel pointer of the device
417  ///
418  /// To use this function, create a class which derives from DeviceModelOp. Then implement the
419  /// operator()(DeviceModel/// ). Sample classes are defined in N_DEV_Algorithm.C.
420  ///
421  /// @param op reference to operator functor
422  ///
423  virtual void forEachModel(DeviceModelOp &op) const = 0;
424 
425  //-----------------------------------------------------------------------------
426  // Function : forEachInstance
427  // Purpose :
428  // Special Notes :
429  // Scope : public
430  // Creator : David G. Baur Raytheon Sandia National Laboratories 1355
431  // Creation Date : Mon Feb 3 10:36:04 2014
432  //-----------------------------------------------------------------------------
433  ///
434  /// Executes op on each DeviceInstance pointer of the device
435  ///
436  /// To use this function, create a class which derives from DeviceInstanceOp. Then implement the
437  /// operator()(DeviceInstance *). Sample classes are defined in N_DEV_Algorithm.C.
438  ///
439  /// @param op reference to operator functor
440  ///
441  virtual void forEachInstance(DeviceInstanceOp &op) const = 0;
442 };
443 
444 } // namespace Device
445 } // namespace Xyce
446 
447 #endif
virtual const std::string & getName() const =0
Returns the name given to the device.
virtual bool updateSources()
Updates the devices source information.
Definition: N_DEV_Device.h:294
virtual const std::string & getDefaultModelName() const =0
Returns the name of the default model that would to used for this device.
virtual bool isPDEDevice() const =0
Returns true is the device is a PDE device.
Pure virtual class to augment a linear system.
Devices and models are each named.
virtual bool updateState(double *solVec, double *staVec, double *stoVec)
Updates the devices state information.
Definition: N_DEV_Device.h:314
virtual bool updateSecondaryState(double *staDerivVec, double *stoVec)
Updates the devices secondary state information.
Definition: N_DEV_Device.h:334
virtual DeviceModel * findModel(const ModelName &model_name)=0
Returns the device entity with the specified name.
The FactoryBlock contains parameters needed by the device, instance and model creation functions...
virtual void forEachModel(DeviceModelOp &op) const =0
Executes op on each DeviceModel pointer of the device.
virtual DeviceInstance * addInstance(const InstanceBlock &instance_block, const FactoryBlock &factory_block)=0
Creates a device instance and adds to the device model's instance list.
virtual bool operator()(DeviceInstance *instance)=0
virtual bool loadDAEMatrices(Linear::Matrix &dFdx, Linear::Matrix &dQdx)
Populates the device's Jacobian object with these pointers.
Definition: N_DEV_Device.h:383
virtual void forEachInstance(DeviceInstanceOp &op) const =0
Executes op on each DeviceInstance pointer of the device.
The Device class is an interface for device implementations.
Definition: N_DEV_Device.h:101
virtual bool loadDAEVectors(double *solVec, double *fVec, double *qVec, double *bVec, double *storeLeadF, double *storeLeadQ, double *leadF, double *leadQ, double *junctionV)
Populates the device's ExternData object with these pointers.
Definition: N_DEV_Device.h:360
virtual DeviceEntity * findInstance(const InstanceName &instance_name)=0
Returns the device entity with the specified name.
virtual DeviceModel * addModel(const ModelBlock &model_block, const FactoryBlock &factory_block)=0
Creates a device model and adds it to the device's list of models.
Device & operator=(const Device &)
No assignment.
ModelBlock represents a .MODEL line from the netlist.
std::string ModelName
Definition: N_DEV_fwd.h:157
InstanceBlock represent a device instance line from the netlist.
virtual bool operator()(DeviceModel *model)=0
virtual bool isLinearDevice() const =0
Returns true if the device is linear.