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