Simbody  3.5
SystemGuts.h
Go to the documentation of this file.
1 #ifndef SimTK_SimTKCOMMON_SYSTEM_GUTS_H_
2 #define SimTK_SimTKCOMMON_SYSTEM_GUTS_H_
3 
4 /* -------------------------------------------------------------------------- *
5  * Simbody(tm): SimTKcommon *
6  * -------------------------------------------------------------------------- *
7  * This is part of the SimTK biosimulation toolkit originating from *
8  * Simbios, the NIH National Center for Physics-Based Simulation of *
9  * Biological Structures at Stanford, funded under the NIH Roadmap for *
10  * Medical Research, grant U54 GM072970. See https://simtk.org/home/simbody. *
11  * *
12  * Portions copyright (c) 2006-12 Stanford University and the Authors. *
13  * Authors: Michael Sherman *
14  * Contributors: *
15  * *
16  * Licensed under the Apache License, Version 2.0 (the "License"); you may *
17  * not use this file except in compliance with the License. You may obtain a *
18  * copy of the License at http://www.apache.org/licenses/LICENSE-2.0. *
19  * *
20  * Unless required by applicable law or agreed to in writing, software *
21  * distributed under the License is distributed on an "AS IS" BASIS, *
22  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
23  * See the License for the specific language governing permissions and *
24  * limitations under the License. *
25  * -------------------------------------------------------------------------- */
26 
27 #include "SimTKcommon/basics.h"
28 #include "SimTKcommon/Simmatrix.h"
31 
32 namespace SimTK {
33 
34 class Subsystem;
35 class DecorativeGeometry;
36 
72  class GutsRep;
73  friend class GutsRep;
74 
75  // This is the only data member in this class.
76  GutsRep* rep; // opaque implementation of System::Guts base class.
77 public:
78  // Note that this serves as a default constructor since both arguments have defaults.
79  explicit Guts(const String& name="<NONAME>",
80  const String& version="0.0.0");
81  virtual ~Guts();
82 
83  const String& getName() const;
84  const String& getVersion() const;
85 
86  void setHasTimeAdvancedEvents(bool hasEm);
87  bool hasTimeAdvancedEvents() const;
88 
90  // EVALUATION (REALIZATION) //
92 
93  // These are the routines to which the System class forwards requests.
94 
95  const State& getDefaultState() const;
96  State& updDefaultState();
97 
98  void realize(const State& s, Stage g = Stage::HighestRuntime) const;
99 
100  SubsystemIndex adoptSubsystem(Subsystem& child);
101 
102  int getNumSubsystems() const;
103  const Subsystem& getSubsystem(SubsystemIndex) const;
104  Subsystem& updSubsystem(SubsystemIndex);
105 
106  // Obtain the owner handle for this System::Guts object.
107  const System& getSystem() const;
108  System& updSystem();
109 
110  void setOwnerHandle(System&);
111  bool hasOwnerHandle() const;
112 
113  explicit Guts(class GutsRep* r) : rep(r) { }
114  bool hasRep() const {return rep!=0;}
115  const GutsRep& getRep() const {assert(rep); return *rep;}
116  GutsRep& updRep() const {assert(rep); return *rep;}
117 
118  bool systemTopologyHasBeenRealized() const;
119  StageVersion getSystemTopologyCacheVersion() const;
120  void setSystemTopologyCacheVersion(StageVersion topoVersion) const;
121  void invalidateSystemTopologyCache() const;
122 
123  // Wrap the cloneImpl virtual method.
124  System::Guts* clone() const;
125 
126  // These routines wrap the virtual realize...Impl() methods to ensure
127  // good behavior such as checking that stage requirements are met and
128  // updating the stage at the end. Note that these will do nothing if
129  // the System stage is already at or greater than the indicated stage.
130 
131  const State& realizeTopology() const;
132  void realizeModel(State&) const;
133  void realizeInstance (const State& s) const;
134  void realizeTime (const State& s) const;
135  void realizePosition (const State& s) const;
136  void realizeVelocity (const State& s) const;
137  void realizeDynamics (const State& s) const;
138  void realizeAcceleration(const State& s) const;
139  void realizeReport (const State& s) const;
140 
141  // These wrap the other virtual methods.
142  void multiplyByN(const State& state, const Vector& u,
143  Vector& dq) const;
144  void multiplyByNTranspose(const State& state, const Vector& fq,
145  Vector& fu) const;
146  void multiplyByNPInv(const State& state, const Vector& dq,
147  Vector& u) const;
148  void multiplyByNPInvTranspose(const State& state, const Vector& fu,
149  Vector& fq) const;
150 
151  bool prescribeQ(State&) const;
152  bool prescribeU(State&) const;
153  void getFreeQIndex(const State&, Array_<SystemQIndex>& freeQs) const;
154  void getFreeUIndex(const State&, Array_<SystemUIndex>& freeUs) const;
155 
156  void projectQ(State&, Vector& qErrEst,
157  const ProjectOptions& options, ProjectResults& results) const;
158  void projectU(State&, Vector& uErrEst,
159  const ProjectOptions& options, ProjectResults& results) const;
160 
161  void handleEvents
162  (State&, Event::Cause, const Array_<EventId>& eventIds,
163  const HandleEventsOptions& options,
164  HandleEventsResults& results) const;
165  void reportEvents(const State&, Event::Cause, const Array_<EventId>& eventIds) const;
166  void calcEventTriggerInfo(const State&, Array_<EventTriggerInfo>&) const;
167  void calcTimeOfNextScheduledEvent(const State&, Real& tNextEvent, Array_<EventId>& eventIds, bool includeCurrentTime) const;
168  void calcTimeOfNextScheduledReport(const State&, Real& tNextEvent, Array_<EventId>& eventIds, bool includeCurrentTime) const;
169 
170  void calcDecorativeGeometryAndAppend(const State&, Stage,
172 
173 
174 protected:
175  Guts(const Guts&); // copies the base class; for use from derived class copy constructors
176 
177  // The destructor is already virtual; see above.
178 
179  virtual System::Guts* cloneImpl() const = 0;
180 
181  // Override these to change the evaluation order of the Subsystems.
182  // The default is to evaluate them in increasing order of SubsystemIndex.
183  // These methods should not be called directly; they are invoked by the
184  // above wrapper methods. Note: the wrappers *will not* call these
185  // routines if the system stage has already met the indicated stage level.
186  // If fact these routines will be called only when the system stage
187  // is at the level just prior to the one indicated here. For example,
188  // realizeVelocityImpl() will be called only if the passed-in State
189  // has been determined to have its system stage exactly Stage::Position.
190  virtual int realizeTopologyImpl(State& state) const {return 0;}
191  virtual int realizeModelImpl (State& state) const {return 0;}
192  virtual int realizeInstanceImpl(const State& state) const {return 0;}
193  virtual int realizeTimeImpl (const State& state) const {return 0;}
194  virtual int realizePositionImpl(const State& state) const {return 0;}
195  virtual int realizeVelocityImpl(const State& state) const {return 0;}
196  virtual int realizeDynamicsImpl(const State& state) const {return 0;}
197  virtual int realizeAccelerationImpl(const State& state) const {return 0;}
198  virtual int realizeReportImpl (const State& state) const {return 0;}
199 
200  virtual void multiplyByNImpl(const State& state, const Vector& u,
201  Vector& dq) const;
202  virtual void multiplyByNTransposeImpl(const State& state, const Vector& fq,
203  Vector& fu) const;
204  virtual void multiplyByNPInvImpl(const State& state, const Vector& dq,
205  Vector& u) const;
206  virtual void multiplyByNPInvTransposeImpl(const State& state, const Vector& fu,
207  Vector& fq) const;
208 
209  // Defaults assume no prescribed motion; hence, no change made.
210  virtual bool prescribeQImpl(State&) const {return false;}
211  virtual bool prescribeUImpl(State&) const {return false;}
212 
213 
214  // Defaults assume no constraints and return success meaning "all
215  // constraints satisfied".
216  virtual void projectQImpl(State& state, Vector& qErrEst,
217  const ProjectOptions& options, ProjectResults& results) const
218  { results.clear(); results.setExitStatus(ProjectResults::Succeeded); }
219  virtual void projectUImpl(State& state, Vector& uErrEst,
220  const ProjectOptions& options, ProjectResults& results) const
221  { results.clear(); results.setExitStatus(ProjectResults::Succeeded); }
222 
223  virtual void handleEventsImpl
224  (State& state, Event::Cause cause, const Array_<EventId>& eventIds,
225  const HandleEventsOptions& options, HandleEventsResults& results) const;
226 
227  virtual int reportEventsImpl(const State& state, Event::Cause cause,
228  const Array_<EventId>& eventIds) const;
229 
230  virtual int calcEventTriggerInfoImpl(const State& state,
231  Array_<EventTriggerInfo>& info) const;
232 
233  virtual int calcTimeOfNextScheduledEventImpl
234  (const State& state, Real& tNextEvent, Array_<EventId>& eventIds,
235  bool includeCurrentTime) const;
236  virtual int calcTimeOfNextScheduledReportImpl
237  (const State& state, Real& tNextEvent, Array_<EventId>& eventIds,
238  bool includeCurrentTime) const;
239 
240 
241  // Default is that all the state variables are free.
242  virtual void getFreeQIndexImpl
243  (const State& s, Array_<SystemQIndex>& freeQs) const {
244  const unsigned nq = (unsigned)s.getNQ();
245  freeQs.resize(nq);
246  for (unsigned i=0; i<nq; ++i)
247  freeQs[i] = SystemQIndex(i);
248  }
249  virtual void getFreeUIndexImpl
250  (const State& s, Array_<SystemUIndex>& freeUs) const {
251  const unsigned nu = (unsigned)s.getNU();
252  freeUs.resize(nu);
253  for (unsigned i=0; i<nu; ++i)
254  freeUs[i] = SystemUIndex(i);
255  }
256 
257 private:
258  Guts& operator=(const Guts&); // suppress default copy assignment operator
259 
260  class EventTriggerInfoRep;
261 
262 };
263 
264 
265 } // namespace SimTK
266 
267 #endif // SimTK_SimTKCOMMON_SYSTEM_GUTS_H_
A Subsystem is expected to be part of a larger System and to have interdependencies with other subsys...
Definition: Subsystem.h:55
virtual int realizeTimeImpl(const State &state) const
Definition: SystemGuts.h:193
#define SimTK_SimTKCOMMON_EXPORT
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:218
virtual int realizeTopologyImpl(State &state) const
Definition: SystemGuts.h:190
virtual void projectUImpl(State &state, Vector &uErrEst, const ProjectOptions &options, ProjectResults &results) const
Definition: SystemGuts.h:219
int getNU() const
Get total number of shared u&#39;s (generalized speeds; mobilities).
Definition: Stage.h:68
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
void resize(size_type n)
Change the size of this Array, preserving all the elements that will still fit, and default construct...
Definition: Array.h:2053
This class is basically a glorified enumerated type, type-safe and range checked but permitting conve...
Definition: Stage.h:50
virtual int realizeDynamicsImpl(const State &state) const
Definition: SystemGuts.h:196
virtual int realizeReportImpl(const State &state) const
Definition: SystemGuts.h:198
ProjectResults & clear()
Restore this object to its default-constructed state, with the return status set to Invalid...
Definition: System.h:1089
SimTK_Real Real
This is the default compiled-in floating point type for SimTK, either float or double.
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:593
This object is intended to contain all state information for a SimTK::System, except topological info...
Definition: State.h:276
int getNQ() const
Get total number of shared q&#39;s (generalized coordinates; second order state variables).
virtual int realizeAccelerationImpl(const State &state) const
Definition: SystemGuts.h:197
virtual bool prescribeQImpl(State &) const
Definition: SystemGuts.h:210
Results for advanced users of project() methods.
Definition: System.h:1067
These are all the possible causes for events.
Definition: Event.h:123
Options for the advanced project() methods.
Definition: System.h:950
virtual bool prescribeUImpl(State &) const
Definition: SystemGuts.h:211
virtual int realizeVelocityImpl(const State &state) const
Definition: SystemGuts.h:195
The project() was successful either because no projection was necessary or projection was able to ach...
Definition: System.h:1076
The SimTK::Array_<T> container class is a plug-compatible replacement for the C++ standard template l...
Definition: Array.h:50
This unique integer type is for indexing global "q-like" arrays, that is, arrays that inherently have...
virtual int realizePositionImpl(const State &state) const
Definition: SystemGuts.h:194
Guts(class GutsRep *r)
Definition: SystemGuts.h:113
GutsRep & updRep() const
Definition: SystemGuts.h:116
ProjectResults & setExitStatus(Status status)
Definition: System.h:1109
SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) inten...
Definition: String.h:62
Declares the user-visible part of a SimTK::State, the implementation is done in a separate internal c...
const GutsRep & getRep() const
Definition: SystemGuts.h:115
This is the declaration for the System::Guts class, the abstract object to which a System handle poin...
Definition: SystemGuts.h:71
bool hasRep() const
Definition: SystemGuts.h:114
This is the base class that serves as the parent of all SimTK System objects; most commonly Simbody&#39;s...
Definition: System.h:97
virtual int realizeInstanceImpl(const State &state) const
Definition: SystemGuts.h:192
Provide a unique integer type for identifying Subsystems.
Results returned by the handleEvent() method.
Definition: Event.h:342
This is the header which should be included in user programs that would like to make use of all the S...
This unique integer type is for indexing global "u-like" arrays, that is, arrays that inherently have...
Includes internal headers providing declarations for the basic SimTK Core classes.
virtual int realizeModelImpl(State &state) const
Definition: SystemGuts.h:191
virtual void projectQImpl(State &state, Vector &qErrEst, const ProjectOptions &options, ProjectResults &results) const
Definition: SystemGuts.h:216
int StageVersion
This is the type to use for Stage version numbers.
Definition: State.h:160
Options for the handleEvent() method.
Definition: Event.h:266