Simbody  3.7
Go to the documentation of this file.
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 *
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 *
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  * -------------------------------------------------------------------------- */
27 #include "SimTKcommon/basics.h"
28 #include "SimTKcommon/Simmatrix.h"
32 namespace SimTK {
34 class Subsystem;
35 class DecorativeGeometry;
72  class GutsRep;
73  friend class GutsRep;
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();
83  const String& getName() const;
84  const String& getVersion() const;
86  void setHasTimeAdvancedEvents(bool hasEm);
87  bool hasTimeAdvancedEvents() const;
93  // These are the routines to which the System class forwards requests.
95  const State& getDefaultState() const;
96  State& updDefaultState();
98  void realize(const State& s, Stage g = Stage::HighestRuntime) const;
100  SubsystemIndex adoptSubsystem(Subsystem& child);
102  int getNumSubsystems() const;
103  const Subsystem& getSubsystem(SubsystemIndex) const;
104  Subsystem& updSubsystem(SubsystemIndex);
106  // Obtain the owner handle for this System::Guts object.
107  const System& getSystem() const;
108  System& updSystem();
110  void setOwnerHandle(System&);
111  bool hasOwnerHandle() const;
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;}
118  bool systemTopologyHasBeenRealized() const;
119  StageVersion getSystemTopologyCacheVersion() const;
120  void setSystemTopologyCacheVersion(StageVersion topoVersion) const;
121  void invalidateSystemTopologyCache() const;
123  // Wrap the cloneImpl virtual method.
124  System::Guts* clone() const;
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.
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;
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;
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;
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;
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;
170  void calcDecorativeGeometryAndAppend(const State&, Stage,
174 protected:
175  Guts(const Guts&); // copies the base class; for use from derived class copy constructors
177  // The destructor is already virtual; see above.
179  virtual System::Guts* cloneImpl() const = 0;
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;}
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;
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;}
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); }
223  virtual void handleEventsImpl
224  (State& state, Event::Cause cause, const Array_<EventId>& eventIds,
225  const HandleEventsOptions& options, HandleEventsResults& results) const;
227  virtual int reportEventsImpl(const State& state, Event::Cause cause,
228  const Array_<EventId>& eventIds) const;
230  virtual int calcEventTriggerInfoImpl(const State& state,
231  Array_<EventTriggerInfo>& info) const;
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;
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  }
257 private:
258  Guts& operator=(const Guts&); // suppress default copy assignment operator
260  class EventTriggerInfoRep;
262 };
265 } // namespace SimTK
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
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:224
virtual int realizeInstanceImpl(const State &state) const
Definition: SystemGuts.h:192
Definition: Stage.h:84
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:2091
const GutsRep & getRep() const
Definition: SystemGuts.h:115
This class is basically a glorified enumerated type, type-safe and range checked but permitting conve...
Definition: Stage.h:66
virtual void projectUImpl(State &state, Vector &uErrEst, const ProjectOptions &options, ProjectResults &results) const
Definition: SystemGuts.h:219
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:606
bool hasRep() const
Definition: SystemGuts.h:114
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
virtual bool prescribeUImpl(State &) const
Definition: SystemGuts.h:211
This object is intended to contain all state information for a SimTK::System, except topological info...
Definition: State.h:280
Results for advanced users of project() methods.
Definition: System.h:1067
These are all the possible causes for events.
Definition: Event.h:126
virtual bool prescribeQImpl(State &) const
Definition: SystemGuts.h:210
Options for the advanced project() methods.
Definition: System.h:950
virtual int realizePositionImpl(const State &state) const
Definition: SystemGuts.h:194
The project() was successful either because no projection was necessary or projection was able to ach...
Definition: System.h:1076
The Array_<T> container class is a plug-compatible replacement for the C++ standard template library ...
Definition: Array.h:53
This unique integer type is for indexing global "q-like" arrays, that is, arrays that inherently have...
virtual int realizeAccelerationImpl(const State &state) const
Definition: SystemGuts.h:197
Guts(class GutsRep *r)
Definition: SystemGuts.h:113
GutsRep & updRep() const
Definition: SystemGuts.h:116
virtual void projectQImpl(State &state, Vector &qErrEst, const ProjectOptions &options, ProjectResults &results) const
Definition: SystemGuts.h:216
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...
This is the declaration for the System::Guts class, the abstract object to which a System handle poin...
Definition: SystemGuts.h:71
int getNQ() const
Get total number of shared q&#39;s (generalized coordinates; second order state variables).
virtual int realizeReportImpl(const State &state) const
Definition: SystemGuts.h:198
This is the base class that serves as the parent of all SimTK System objects; most commonly Simbody&#39;s...
Definition: System.h:97
Provide a unique integer type for identifying Subsystems.
int getNU() const
Get total number of shared u&#39;s (generalized speeds; mobilities).
Results returned by the handleEvent() method.
Definition: Event.h:345
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 realizeDynamicsImpl(const State &state) const
Definition: SystemGuts.h:196
virtual int realizeTopologyImpl(State &state) const
Definition: SystemGuts.h:190
virtual int realizeModelImpl(State &state) const
Definition: SystemGuts.h:191
virtual int realizeTimeImpl(const State &state) const
Definition: SystemGuts.h:193
Options for the handleEvent() method.
Definition: Event.h:269
virtual int realizeVelocityImpl(const State &state) const
Definition: SystemGuts.h:195