Simbody  3.8
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;
97 
98  void realize(const State& s, Stage g = Stage::HighestRuntime) const;
99 
101 
102  int getNumSubsystems() const;
105 
106  // Obtain the owner handle for this System::Guts object.
107  const System& getSystem() const;
109 
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 
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 
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;
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 
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 
234  (const State& state, Real& tNextEvent, Array_<EventId>& eventIds,
235  bool includeCurrentTime) const;
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_
#define SimTK_SimTKCOMMON_EXPORT
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:224
This is the header which should be included in user programs that would like to make use of all the S...
Declares the user-visible part of a SimTK::State, the implementation is done in a separate internal c...
Includes internal headers providing declarations for the basic SimTK Core classes.
The Array_<T> container class is a plug-compatible replacement for the C++ standard template library ...
Definition: Array.h:1520
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:2091
These are all the possible causes for events.
Definition: Event.h:126
Options for the handleEvent() method.
Definition: Event.h:269
Results returned by the handleEvent() method.
Definition: Event.h:345
Options for the advanced project() methods.
Definition: System.h:950
Results for advanced users of project() methods.
Definition: System.h:1067
ProjectResults & setExitStatus(Status status)
Definition: System.h:1109
@ Succeeded
The project() was successful either because no projection was necessary or projection was able to ach...
Definition: System.h:1076
ProjectResults & clear()
Restore this object to its default-constructed state, with the return status set to Invalid.
Definition: System.h:1089
This class is basically a glorified enumerated type, type-safe and range checked but permitting conve...
Definition: Stage.h:66
@ HighestRuntime
Definition: Stage.h:84
This object is intended to contain all state information for a SimTK::System, except topological info...
Definition: State.h:280
int getNQ() const
Get total number of shared q's (generalized coordinates; second order state variables).
int getNU() const
Get total number of shared u's (generalized speeds; mobilities).
SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) inten...
Definition: String.h:65
Provide a unique integer type for identifying Subsystems.
A Subsystem is expected to be part of a larger System and to have interdependencies with other subsys...
Definition: Subsystem.h:55
This unique integer type is for indexing global "q-like" arrays, that is, arrays that inherently have...
This unique integer type is for indexing global "u-like" arrays, that is, arrays that inherently have...
This is the declaration for the System::Guts class, the abstract object to which a System handle poin...
Definition: SystemGuts.h:71
virtual int calcEventTriggerInfoImpl(const State &state, Array_< EventTriggerInfo > &info) const
virtual bool prescribeQImpl(State &) const
Definition: SystemGuts.h:210
virtual System::Guts * cloneImpl() const =0
virtual void multiplyByNPInvImpl(const State &state, const Vector &dq, Vector &u) const
virtual void multiplyByNTransposeImpl(const State &state, const Vector &fq, Vector &fu) const
const Subsystem & getSubsystem(SubsystemIndex) const
Guts(const String &name="<NONAME>", const String &version="0.0.0")
const State & getDefaultState() const
const String & getVersion() const
Guts(class GutsRep *r)
Definition: SystemGuts.h:113
void multiplyByNPInvTranspose(const State &state, const Vector &fu, Vector &fq) const
void calcDecorativeGeometryAndAppend(const State &, Stage, Array_< DecorativeGeometry > &) const
void projectU(State &, Vector &uErrEst, const ProjectOptions &options, ProjectResults &results) const
void realizeVelocity(const State &s) const
virtual void multiplyByNPInvTransposeImpl(const State &state, const Vector &fu, Vector &fq) const
virtual int realizeInstanceImpl(const State &state) const
Definition: SystemGuts.h:192
const GutsRep & getRep() const
Definition: SystemGuts.h:115
void realizePosition(const State &s) const
GutsRep & updRep() const
Definition: SystemGuts.h:116
virtual void multiplyByNImpl(const State &state, const Vector &u, Vector &dq) const
void realizeDynamics(const State &s) const
virtual void getFreeQIndexImpl(const State &s, Array_< SystemQIndex > &freeQs) const
Definition: SystemGuts.h:243
Subsystem & updSubsystem(SubsystemIndex)
void multiplyByNPInv(const State &state, const Vector &dq, Vector &u) const
Guts(const Guts &)
bool hasTimeAdvancedEvents() const
void projectQ(State &, Vector &qErrEst, const ProjectOptions &options, ProjectResults &results) const
void realizeAcceleration(const State &s) const
void calcTimeOfNextScheduledReport(const State &, Real &tNextEvent, Array_< EventId > &eventIds, bool includeCurrentTime) const
void multiplyByN(const State &state, const Vector &u, Vector &dq) const
virtual int realizeModelImpl(State &state) const
Definition: SystemGuts.h:191
const String & getName() const
void realizeModel(State &) const
System::Guts * clone() const
virtual int realizeAccelerationImpl(const State &state) const
Definition: SystemGuts.h:197
virtual int realizeTimeImpl(const State &state) const
Definition: SystemGuts.h:193
void multiplyByNTranspose(const State &state, const Vector &fq, Vector &fu) const
void calcTimeOfNextScheduledEvent(const State &, Real &tNextEvent, Array_< EventId > &eventIds, bool includeCurrentTime) const
void getFreeUIndex(const State &, Array_< SystemUIndex > &freeUs) const
virtual int realizeDynamicsImpl(const State &state) const
Definition: SystemGuts.h:196
virtual void projectUImpl(State &state, Vector &uErrEst, const ProjectOptions &options, ProjectResults &results) const
Definition: SystemGuts.h:219
State & updDefaultState()
void invalidateSystemTopologyCache() const
virtual int realizePositionImpl(const State &state) const
Definition: SystemGuts.h:194
virtual bool prescribeUImpl(State &) const
Definition: SystemGuts.h:211
bool systemTopologyHasBeenRealized() const
void setHasTimeAdvancedEvents(bool hasEm)
int getNumSubsystems() const
const State & realizeTopology() const
virtual void getFreeUIndexImpl(const State &s, Array_< SystemUIndex > &freeUs) const
Definition: SystemGuts.h:250
virtual void projectQImpl(State &state, Vector &qErrEst, const ProjectOptions &options, ProjectResults &results) const
Definition: SystemGuts.h:216
System & updSystem()
bool hasRep() const
Definition: SystemGuts.h:114
bool prescribeU(State &) const
virtual int calcTimeOfNextScheduledReportImpl(const State &state, Real &tNextEvent, Array_< EventId > &eventIds, bool includeCurrentTime) const
void getFreeQIndex(const State &, Array_< SystemQIndex > &freeQs) const
virtual int realizeVelocityImpl(const State &state) const
Definition: SystemGuts.h:195
SubsystemIndex adoptSubsystem(Subsystem &child)
void realizeReport(const State &s) const
virtual void handleEventsImpl(State &state, Event::Cause cause, const Array_< EventId > &eventIds, const HandleEventsOptions &options, HandleEventsResults &results) const
virtual int realizeReportImpl(const State &state) const
Definition: SystemGuts.h:198
void setOwnerHandle(System &)
StageVersion getSystemTopologyCacheVersion() const
virtual int realizeTopologyImpl(State &state) const
Definition: SystemGuts.h:190
virtual int reportEventsImpl(const State &state, Event::Cause cause, const Array_< EventId > &eventIds) const
bool hasOwnerHandle() const
void realizeInstance(const State &s) const
void realizeTime(const State &s) const
void reportEvents(const State &, Event::Cause, const Array_< EventId > &eventIds) const
bool prescribeQ(State &) const
void handleEvents(State &, Event::Cause, const Array_< EventId > &eventIds, const HandleEventsOptions &options, HandleEventsResults &results) const
void calcEventTriggerInfo(const State &, Array_< EventTriggerInfo > &) const
void setSystemTopologyCacheVersion(StageVersion topoVersion) const
const System & getSystem() const
void realize(const State &s, Stage g=Stage::HighestRuntime) const
virtual int calcTimeOfNextScheduledEventImpl(const State &state, Real &tNextEvent, Array_< EventId > &eventIds, bool includeCurrentTime) const
This is the base class that serves as the parent of all SimTK System objects; most commonly Simbody's...
Definition: System.h:97
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
long long StageVersion
This is the type to use for Stage version numbers that get incremented whenever a state variable chan...
Definition: Stage.h:44
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:607