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.116.2.2 $
40 //
41 // Revision Date : $Date: 2014/03/03 18:29:27 $
42 //
43 // Current Owner : $Author: tvrusso $
44 //-----------------------------------------------------------------------------
45 
46 
47 #ifndef Xyce_N_DEV_Device_h
48 #define Xyce_N_DEV_Device_h
49 
50 #include <iosfwd>
51 #include <map>
52 #include <string>
53 #include <vector>
54 
55 #include <N_DEV_fwd.h>
56 
57 class N_LAS_Matrix;
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 /// The Device class is an interface for device implementations.
81 ///
82 /// In general, DeviceMaster is the only class that actually inherits
83 /// from Device. Most devices either use the DeviceMaster class, but
84 /// some derive from DeviceMaster in what is known as a Master class.
85 ///
86 /// The interfaces are unfortunately used for but derived
87 /// implementation as well as usage. This should be changed at some
88 /// point, but this is the currently basic design of most interface
89 /// classes.
90 ///
91 /// @author Eric Keiter, SNL, Parallel Computational Sciences
92 /// @date 3/16/00
93 class Device
94 {
95 public:
97  {}
98 
99  virtual ~Device()
100  {}
101 
102 private:
103  Device(const Device &); ///< No copying
104  Device &operator=(const Device &); ///< No assignment
105 
106 public:
107  ///
108  /// Returns true if the device is linear
109  ///
110  /// @return true if the device is linear.
111  ///
112  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
113  /// @date Wed Jan 29 16:36:27 2014
114  virtual bool isLinearDevice() const = 0;
115 
116  ///
117  /// Returns true is the device is a PDE device
118  ///
119  /// @return true is the device is a PDE device.
120  ///
121  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
122  /// @date Wed Jan 29 16:37:02 2014
123  virtual bool isPDEDevice() const = 0;
124 
125  ///
126  /// Returns the name given to the device
127  ///
128  /// @return const reference to the device name.
129  ///
130  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
131  /// @date Wed Jan 29 16:37:34 2014
132  virtual const std::string &getName() const = 0;
133 
134  ///
135  /// Returns the name of the default model that would to used for this device
136  ///
137  /// @return const reference to the name of the default model
138  ///
139  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
140  /// @date Wed Jan 29 16:38:02 2014
141  virtual const std::string &getDefaultModelName() const = 0;
142 
143  ///
144  /// Returns the device entity with the specified name
145  ///
146  /// @param entity_name const reference to the name of the entity
147  ///
148  /// @return pointer to the device entity
149  ///
150  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
151  /// @date Wed Jan 29 16:39:23 2014
152  virtual DeviceEntity *findEntity(const std::string &entity_name) = 0;
153 
154  ///
155  /// Returns the device entity with the specified name
156  ///
157  /// @param entity_name const reference name of the entity
158  ///
159  /// @return const pointer to the device entity
160  ///
161  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
162  /// @date Wed Jan 29 16:39:23 2014
163  virtual const DeviceEntity *findEntity(const std::string &entity_name) const = 0;
164 
165  ///
166  /// Creates a device model and adds it to the device's list of models
167  ///
168  ///
169  /// @param model_block const reference to the model block describing the model to create
170  /// @param factory_block const reference to the factory data needed to create the model
171  ///
172  /// @return pointer to the newly created device model
173  ///
174  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
175  /// @date Wed Jan 29 16:40:30 2014
176  virtual DeviceModel *addModel(const ModelBlock &model_block, const FactoryBlock &factory_block) = 0;
177 
178  ///
179  /// Creates a device instance and adds to the device model's instance list
180  ///
181  ///
182  /// @param instance_block const reference to the model block describing the instance to create
183  /// @param factory_block const reference to the factory data needed to create the instance
184  ///
185  /// @return pointer to the newly creates device instance
186  ///
187  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
188  /// @date Wed Jan 29 16:43:08 2014
189  virtual DeviceInstance *addInstance(const InstanceBlock &instance_block, const FactoryBlock &factory_block) = 0;
190 
191  ///
192  /// Updates the devices source information
193  ///
194  /// This function is called by the analysis subsystem when it is time to update the device source information.
195  ///
196  /// @return true if the update was successful
197  ///
198  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
199  /// @date Wed Jan 29 16:44:34 2014
200  virtual bool updateSources()
201  {
202  return true;
203  }
204 
205  ///
206  /// Updates the devices state information
207  ///
208  /// This function is called by the analysis subsystem when it is time to update the device state information.
209  ///
210  /// @return true if the update was successful
211  ///
212  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
213  /// @date Wed Jan 29 16:44:34 2014
214  virtual bool updateState(double * solVec, double * staVec, double * stoVec)
215  {
216  return true;
217  }
218 
219  ///
220  /// Updates the devices secondary state information
221  ///
222  /// This function is called by the analysis subsystem when it is time to update the device secondary state information.
223  ///
224  /// @return true if the update was successful
225  ///
226  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
227  /// @date Wed Jan 29 16:44:34 2014
228  virtual bool updateSecondaryState(double * staDerivVec, double * stoVec)
229  {
230  return true;
231  }
232 
233  ///
234  /// Populates the device's ExternData object with these pointers
235  ///
236  /// THIS FUNCTION MUST BE CALLED PRIOR TO CALLING loadDAEMatrices.
237  ///
238  /// @param solVec pointer to the analysis solution vector for this device
239  /// @param fVec pointer to the analysis f vector for this device
240  /// @param qVec pointer to the analysis q vector for this device
241  /// @param storeLeadF pointer to the analysis lead store f vector for this device
242  /// @param storeLeadQ poitner to the analysis load store q vector for this device
243  ///
244  /// @return true if the update was successful
245  ///
246  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
247  /// @date Wed Jan 29 16:47:20 2014
248  virtual bool loadDAEVectors (double * solVec, double * fVec, double * qVec, double * storeLeadF, double * storeLeadQ)
249  {
250  return true;
251  }
252 
253  ///
254  /// Populates the device's Jacobian object with these pointers
255  ///
256  /// THIS FUNCTION MUST BE CALLED AFTER CALLING loadDAEVectors.
257  ///
258  /// @param dFdx pointer to the analysis dFdx matrix
259  /// @param dQdx pointer to the analysis dQdx matrix
260  ///
261  /// @return
262  ///
263  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
264  /// @date Wed Jan 29 17:06:52 2014
265  virtual bool loadDAEMatrices(N_LAS_Matrix & dFdx, N_LAS_Matrix & dQdx)
266  {
267  return true;
268  }
269 
270  // ///
271  // /// Delete the specified instance from the device
272  // ///
273  // /// TODO: Check this implementation in DeviceMaster...does it really work?
274  // ///
275  // /// @param instance_name const reference to the instance name of the device instance to be deleted
276  // ///
277  // /// @return true if the delete was successful
278  // ///
279  // /// @author David G. Baur Raytheon Sandia National Laboratories 1355
280  // /// @date Wed Jan 29 17:08:58 2014
281  // virtual bool deleteInstance(DeviceInstance *instance) = 0;
282 
283  ///
284  /// Executes op on each DeviceModel pointer of the device
285  ///
286  /// To use this function, create a class which derives from DeviceModelOp. Then implement the
287  /// operator()(DeviceModel/// ). Sample classes are defined in N_DEV_Algorithm.C.
288  ///
289  /// @param op reference to operator functor
290  ///
291  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
292  /// @date Mon Feb 3 10:36:04 2014
293  virtual void forEachModel(DeviceModelOp &op) const = 0;
294 
295  ///
296  /// Executes op on each DeviceInstance pointer of the device
297  ///
298  /// To use this function, create a class which derives from DeviceInstanceOp. Then implement the
299  /// operator()(DeviceInstance *). Sample classes are defined in N_DEV_Algorithm.C.
300  ///
301  /// @param op reference to operator functor
302  ///
303  /// @author David G. Baur Raytheon Sandia National Laboratories 1355
304  /// @date Mon Feb 3 10:36:04 2014
305  virtual void forEachInstance(DeviceInstanceOp &op) const = 0;
306 };
307 
308 } // namespace Device
309 } // namespace Xyce
310 
312 
313 #endif