Simbody 3.7
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"
31
32namespace SimTK {
33
34class Subsystem;
35class 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.
77public:
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);
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.
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
174protected:
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
257private:
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 & clear()
Restore this object to its default-constructed state, with the return status set to Invalid.
Definition: System.h:1089
@ Succeeded
The project() was successful either because no projection was necessary or projection was able to ach...
Definition: System.h:1076
ProjectResults & setExitStatus(Status status)
Definition: System.h:1109
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:62
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 void multiplyByNPInvImpl(const State &state, const Vector &dq, Vector &u) const
virtual void multiplyByNTransposeImpl(const State &state, const Vector &fq, Vector &fu) const
Guts(const String &name="<NONAME>", const String &version="0.0.0")
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
const String & getVersion() const
virtual void multiplyByNPInvTransposeImpl(const State &state, const Vector &fu, Vector &fq) const
virtual int realizeInstanceImpl(const State &state) const
Definition: SystemGuts.h:192
Subsystem & updSubsystem(SubsystemIndex)
const State & realizeTopology() const
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
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
const Subsystem & getSubsystem(SubsystemIndex) 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
void realizeModel(State &) 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
virtual System::Guts * cloneImpl() const =0
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
System & updSystem()
const String & getName() 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
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
const GutsRep & getRep() const
Definition: SystemGuts.h:115
void realizeInstance(const State &s) const
System::Guts * clone() const
void realizeTime(const State &s) const
void reportEvents(const State &, Event::Cause, const Array_< EventId > &eventIds) const
bool prescribeQ(State &) const
State & updDefaultState()
void handleEvents(State &, Event::Cause, const Array_< EventId > &eventIds, const HandleEventsOptions &options, HandleEventsResults &results) const
void calcEventTriggerInfo(const State &, Array_< EventTriggerInfo > &) const
const State & getDefaultState() 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:606