Simbody  3.5
Stage.h
Go to the documentation of this file.
1 #ifndef SimTK_SimTKCOMMON_STAGE_H_
2 #define SimTK_SimTKCOMMON_STAGE_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) 2005-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 
30 
31 #include <cassert>
32 #include <iostream>
33 #include <iomanip>
34 #include <cstdarg>
35 
36 namespace SimTK {
37 
50 class Stage {
51 public:
52  enum Level {
53  Empty = 0,
54  Topology = 1,
55  Model = 2,
56  Instance = 3,
57  Time = 4,
58  Position = 5,
59  Velocity = 6,
60  Dynamics = 7,
62  Report = 9,
63  Infinity = 10,
64 
69  };
70 
71  enum {
74  };
75 
77  Stage() : level(Stage::Empty) {}
79  Stage(Level l) {
80  assert(LowestValid <= l && l <= HighestValid);
81  level = l;
82  }
84  explicit Stage(int l) {
85  assert(LowestValid <= l && l <= HighestValid);
86  level = Level(l);
87  }
89  operator int() const {return level;}
90 
91  bool operator==(Level other) const {return level==other;}
92  bool operator!=(Level other) const {return level!=other;}
93  bool operator<(Level other) const {return level<other;}
94  bool operator<=(Level other) const {return level<=other;}
95  bool operator>(Level other) const {return level>other;}
96  bool operator>=(Level other) const {return level>=other;}
97  bool operator==(Stage other) const {return level==other.level;}
98  bool operator!=(Stage other) const {return level!=other.level;}
99  bool operator<(Stage other) const {return level<other.level;}
100  bool operator<=(Stage other) const {return level<=other.level;}
101  bool operator>(Stage other) const {return level>other.level;}
102  bool operator>=(Stage other) const {return level>=other.level;}
103 
104  // Prefix operators
105  const Stage& operator++()
106  { assert(level<HighestValid); level=Level(level+1); return *this; }
107  const Stage& operator--()
108  { assert(level>LowestValid); level=Level(level-1); return *this;}
109  // Postfix operators
111  { assert(level<HighestValid); level=Level(level+1); return prev(); }
113  { assert(level>LowestValid); level=Level(level-1); return next(); }
114 
118  Stage next() const
119  { assert(level<HighestValid); return Stage(Level(level+1)); }
123  Stage prev() const
124  { assert(level>LowestValid); return Stage(Level(level-1)); }
125 
128  String getName() const {
129  switch (level) {
130  case Empty: return "Empty"; break;
131  case Topology: return "Topology"; break;
132  case Model: return "Model"; break;
133  case Instance: return "Instance"; break;
134  case Time: return "Time"; break;
135  case Position: return "Position"; break;
136  case Velocity: return "Velocity"; break;
137  case Dynamics: return "Dynamics"; break;
138  case Acceleration: return "Acceleration"; break;
139  case Report: return "Report"; break;
140  case Infinity: return "Infinity"; break;
141  default: assert(!"Stage::getName(): illegal level");
142  }
143  return String("INVALID STAGE LEVEL ") + String(level);
144  }
145 
147  void invalidate(Stage tooHigh) {
148  if (level >= tooHigh.level)
149  *this = tooHigh.prev();
150  }
151 
155  bool isInRuntimeRange() const
156  { return Stage::LowestRuntime <= level
157  && level <= Stage::HighestRuntime; }
158 
159 private:
160  Level level;
161 };
162 
163 
164 
165 
166 namespace Exception {
167 
169 public:
170  RealizeTopologyMustBeCalledFirst(const char* fn, int ln,
171  const char* objectType, // e.g., "System", "Subsystem"
172  const char* objectName, const char* methodName) : Base(fn,ln)
173  {
174  setMessage(String(methodName) + ": " + String(objectType) + " " + String(objectName)
175  + " topology has not been realized since the last topological change"
176  " -- you must call realizeTopology() first.");
177  }
178  virtual ~RealizeTopologyMustBeCalledFirst() throw() { }
179 };
180 
182 public:
184  const char* objectType, // e.g., "System", "Subsystem"
185  const char* objectName, const char* methodName,
186  int sysTopoVersion,
187  int stateTopoVersion) : Base(fn,ln)
188  {
189  setMessage(String(methodName)
190  + ": The given State's Topology stage version number ("
191  + String(stateTopoVersion)
192  + ") doesn't match the current topology cache version number ("
193  + String(sysTopoVersion)
194  + ") of " + String(objectType) + " " + String(objectName) + "."
195  + " That means there has been a topology change to this System since this"
196  " State was created so they are no longer compatible. You should create"
197  " a new State from the System's default State."
198  " (Loopholes exist for advanced users.)");
199  }
201 };
202 
203 
204 
205 class StageTooLow : public Base {
206 public:
207  StageTooLow(const char* fn, int ln,
208  Stage currentStage, Stage targetStage, const char* where) : Base(fn,ln)
209  {
210  setMessage("Expected stage to be at least " + targetStage.getName() + " in " + String(where)
211  + " but current stage was " + currentStage.getName());
212  }
213  virtual ~StageTooLow() throw() { }
214 };
215 
216 class StageIsWrong : public Base {
217 public:
218  StageIsWrong(const char* fn, int ln,
219  Stage currentStage, Stage targetStage, const char* where) : Base(fn,ln)
220  {
221  setMessage("Expected stage to be " + targetStage.getName() + " in " + String(where)
222  + " but current stage was " + currentStage.getName());
223  }
224  virtual ~StageIsWrong() throw() { }
225 };
226 
227 class StageTooHigh : public Base {
228 public:
229  StageTooHigh(const char* fn, int ln,
230  Stage currentStage, Stage targetStage, const char* where) : Base(fn,ln)
231  {
232  setMessage("Expected stage to be less than " + targetStage.getName() + " in " + String(where)
233  + " but current stage was " + currentStage.getName());
234  }
235  virtual ~StageTooHigh() throw() { }
236 };
237 
238 class StageOutOfRange : public Base {
239 public:
240  StageOutOfRange(const char* fn, int ln,
241  Stage lower, Stage currentStage, Stage upper, const char* where) : Base(fn,ln)
242  {
243  setMessage("Expected (" + lower.getName() + " <= stage <= " + upper.getName() + ") in " + String(where)
244  + " but stage was " + currentStage.getName());
245  }
246  virtual ~StageOutOfRange() throw() { }
247 };
248 
249 class CacheEntryOutOfDate : public Base {
250 public:
251  CacheEntryOutOfDate(const char* fn, int ln,
252  Stage currentStage, Stage dependsOn, int dependsOnVersion, int lastCalculatedVersion)
253  : Base(fn,ln)
254  {
255  setMessage("State Cache entry was out of date at Stage " + currentStage.getName()
256  + ". This entry depends on version " + String(dependsOnVersion)
257  + " of Stage " + dependsOn.getName()
258  + " but was last updated at version " + String(lastCalculatedVersion) + ".");
259  }
260  virtual ~CacheEntryOutOfDate() throw() { }
261 };
262 
263 // An attempt to realize a particular subsystem to a particular stage failed.
264 class RealizeCheckFailed : public Base {
265 public:
266  RealizeCheckFailed(const char* fn, int ln, Stage g,
267  int subsystemId, const char* subsystemName,
268  const char* fmt ...) : Base(fn,ln)
269  {
270  char buf[1024];
271  va_list args;
272  va_start(args, fmt);
273  vsprintf(buf, fmt, args);
274  setMessage("Couldn't realize subsystem " + String(subsystemId)
275  + "(" + String(subsystemName) + ") to Stage "
276  + g.getName() + ": " + String(buf) + ".");
277  va_end(args);
278  }
279  virtual ~RealizeCheckFailed() throw() { }
280 };
281 
282 
283 } // namespace Exception
284 
285 inline std::ostream& operator<<(std::ostream& o, Stage g)
286 { o << g.getName(); return o; }
287 
288 
289 } // namespace SimTK
290 
291  // REALIZECHECKs: these should be used to catch and report problems that
292  // occur when realizing a subsystem.
293 
294 #define SimTK_REALIZECHECK_ALWAYS(cond,stage,subsysIx,subsysName,msg) \
295  do{if(!(cond))SimTK_THROW4(SimTK::Exception::RealizeCheckFailed, \
296  (stage),(subsysIx),(subsysName),(msg)); \
297  }while(false)
298 #define SimTK_REALIZECHECK1_ALWAYS(cond,stage,subsysIx,subsysName,msg,a1) \
299  do{if(!(cond))SimTK_THROW5(SimTK::Exception::RealizeCheckFailed, \
300  (stage),(subsysIx),(subsysName),(msg),(a1)); \
301  }while(false)
302 #define SimTK_REALIZECHECK2_ALWAYS(cond,stage,subsysIx,subsysName,msg,a1,a2)\
303  do{if(!(cond))SimTK_THROW6(SimTK::Exception::RealizeCheckFailed, \
304  (stage),(subsysIx),(subsysName),(msg),(a1),(a2)); \
305  }while(false)
306 #define SimTK_REALIZECHECK3_ALWAYS(cond,stage,subsysIx,subsysName,msg,a1,a2,a3) \
307  do{if(!(cond))SimTK_THROW7(SimTK::Exception::RealizeCheckFailed, \
308  (stage),(subsysIx),(subsysName),(msg),(a1),(a2),(a3)); \
309  }while(false)
310 #define SimTK_REALIZECHECK4_ALWAYS(cond,stage,subsysIx,subsysName,msg,a1,a2,a3,a4) \
311  do{if(!(cond))SimTK_THROW8(SimTK::Exception::RealizeCheckFailed, \
312  (stage),(subsysIx),(subsysName),(msg),(a1),(a2),(a3),(a4)); \
313  }while(false)
314 #define SimTK_REALIZECHECK5_ALWAYS(cond,stage,subsysIx,subsysName,msg,a1,a2,a3,a4,a5) \
315  do{if(!(cond))SimTK_THROW9(SimTK::Exception::RealizeCheckFailed, \
316  (stage),(subsysIx),(subsysName),(msg),(a1),(a2),(a3),(a4),(a5)); \
317  }while(false)
318 
319 
320 #endif // SimTK_SimTKCOMMON_STAGE_H_
virtual ~RealizeCheckFailed()
Definition: Stage.h:279
Definition: Stage.h:72
Physical parameters set.
Definition: Stage.h:56
Definition: Stage.h:238
bool operator==(Level other) const
Definition: Stage.h:91
Modeling choices made.
Definition: Stage.h:55
Stage(Level l)
This is an implicit conversion from Stage::Level to Stage.
Definition: Stage.h:79
Level
Definition: Stage.h:52
RealizeTopologyMustBeCalledFirst(const char *fn, int ln, const char *objectType, const char *objectName, const char *methodName)
Definition: Stage.h:170
virtual ~CacheEntryOutOfDate()
Definition: Stage.h:260
bool operator==(Stage other) const
Definition: Stage.h:97
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
Stage prev() const
Return the Stage before this one, with Stage::Empty returned if this Stage is already at its lowest v...
Definition: Stage.h:123
Spatial velocities available.
Definition: Stage.h:59
Lower than any legitimate Stage.
Definition: Stage.h:53
Stage operator--(int)
Definition: Stage.h:112
virtual ~RealizeTopologyMustBeCalledFirst()
Definition: Stage.h:178
This class is basically a glorified enumerated type, type-safe and range checked but permitting conve...
Definition: Stage.h:50
String getName() const
Return a printable name corresponding to the stage level currently stored in this Stage...
Definition: Stage.h:128
Stage next() const
Return the Stage following this one, with Stage::Infinity returned if this Stage is already at its hi...
Definition: Stage.h:118
Definition: Stage.h:227
bool operator!=(Level other) const
Definition: Stage.h:92
bool operator<=(Stage other) const
Definition: Stage.h:100
bool operator>=(Level other) const
Definition: Stage.h:96
CacheEntryOutOfDate(const char *fn, int ln, Stage currentStage, Stage dependsOn, int dependsOnVersion, int lastCalculatedVersion)
Definition: Stage.h:251
StageIsWrong(const char *fn, int ln, Stage currentStage, Stage targetStage, const char *where)
Definition: Stage.h:218
RealizeCheckFailed(const char *fn, int ln, Stage g, int subsystemId, const char *subsystemName, const char *fmt...)
Definition: Stage.h:266
void invalidate(Stage tooHigh)
Set this Stage=min(stageNow, tooHigh-1).
Definition: Stage.h:147
virtual ~StageTooHigh()
Definition: Stage.h:235
virtual ~StageIsWrong()
Definition: Stage.h:224
Report-only quantities evaluated.
Definition: Stage.h:62
System topology realized.
Definition: Stage.h:54
Stage operator++(int)
Definition: Stage.h:110
Forces calculated.
Definition: Stage.h:60
bool operator>=(Stage other) const
Definition: Stage.h:102
bool operator!=(Stage other) const
Definition: Stage.h:98
Definition: Exception.h:45
bool operator>(Stage other) const
Definition: Stage.h:101
bool operator<(Level other) const
Definition: Stage.h:93
Spatial configuration available.
Definition: Stage.h:58
bool isInRuntimeRange() const
Return true if this Stage has one of the meaningful values between Stage::Topology and Stage::Report...
Definition: Stage.h:155
Definition: Stage.h:73
Higher than any legitimate Stage.
Definition: Stage.h:63
For iterating over all stage values.
Definition: Stage.h:65
std::ostream & operator<<(std::ostream &o, const ContactForce &f)
Definition: CompliantContactSubsystem.h:387
Stage()
Default construction gives Stage::Empty.
Definition: Stage.h:77
const Stage & operator++()
Definition: Stage.h:105
Definition: Stage.h:66
SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) inten...
Definition: String.h:62
StageOutOfRange(const char *fn, int ln, Stage lower, Stage currentStage, Stage upper, const char *where)
Definition: Stage.h:240
virtual ~StageTooLow()
Definition: Stage.h:213
Mandatory first inclusion for any Simbody source or header file.
bool operator<(Stage other) const
Definition: Stage.h:99
Stage(int l)
You can explicitly create a Stage from an int if it is in range.
Definition: Stage.h:84
const Stage & operator--()
Definition: Stage.h:107
bool operator<=(Level other) const
Definition: Stage.h:94
StateAndSystemTopologyVersionsMustMatch(const char *fn, int ln, const char *objectType, const char *objectName, const char *methodName, int sysTopoVersion, int stateTopoVersion)
Definition: Stage.h:183
StageTooLow(const char *fn, int ln, Stage currentStage, Stage targetStage, const char *where)
Definition: Stage.h:207
virtual ~StageOutOfRange()
Definition: Stage.h:246
For iterating over meaningful stage values.
Definition: Stage.h:67
StageTooHigh(const char *fn, int ln, Stage currentStage, Stage targetStage, const char *where)
Definition: Stage.h:229
bool operator>(Level other) const
Definition: Stage.h:95
A new time has been realized.
Definition: Stage.h:57
Definition: Stage.h:205
Accelerations and multipliers calculated.
Definition: Stage.h:61
Definition: Stage.h:216
virtual ~StateAndSystemTopologyVersionsMustMatch()
Definition: Stage.h:200