Simbody  3.5
Event.h
Go to the documentation of this file.
1 #ifndef SimTK_SimTKCOMMON_EVENT_H_
2 #define SimTK_SimTKCOMMON_EVENT_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) 2008-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 
32 #include "SimTKcommon/basics.h"
33 
34 namespace SimTK {
35 
40 
47 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemEventTriggerIndex);
48 
57 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemEventTriggerByStageIndex);
58 
62 SimTK_DEFINE_UNIQUE_INDEX_TYPE(EventTriggerByStageIndex);
63 
76 class Event {
77 public:
78 
123  class Cause {
124  public:
125  enum Num {
130  Signaled = 5,
132  Invalid = -1
133  };
134 
135  Cause() : value(Invalid) {}
136  Cause(Num n) : value(n) {} // implicit conversion
137  operator Num() const {return value;} // implicit conversion
138  Cause& operator=(Num n) {value=n; return *this;}
139 
140  bool isValid() const {return Initialization<=value && value<=Termination;}
141 
142  private:
143  Num value;
144  };
145 
148  SimTK_SimTKCOMMON_EXPORT static const char* getCauseName(Cause);
149 
150 
155  enum Trigger {
156  NoEventTrigger =0x0000, // must be 0
157 
158  PositiveToNegative =0x0001, // 1
159  NegativeToPositive =0x0002, // 2
160 
164  };
165 
169 
170 
174  static Trigger classifyTransition(int before, int after) {
175  if (before==after)
176  return NoEventTrigger;
177  if (before==0)
178  return NoEventTrigger; // Do not report transitions away from zero.
179  if (before==1)
180  return PositiveToNegative;
181  // before==-1
182  return NegativeToPositive;
183  }
184 
188  static Trigger maskTransition(Trigger transition, Trigger mask) {
189  // we're depending on NoEventTrigger==0
190  return Trigger(transition & mask);
191  }
192 
193 private:
194 };
195 
196 
207 public:
209  explicit EventTriggerInfo(EventId eventId);
210  ~EventTriggerInfo();
213 
214  EventId getEventId() const; // returns -1 if not set
215  bool shouldTriggerOnRisingSignTransition() const; // default=true
216  bool shouldTriggerOnFallingSignTransition() const; // default=true
217  Real getRequiredLocalizationTimeWindow() const; // default=0.1
218 
219  // These return the modified 'this', like assignment operators.
220  EventTriggerInfo& setEventId(EventId);
221  EventTriggerInfo& setTriggerOnRisingSignTransition(bool);
222  EventTriggerInfo& setTriggerOnFallingSignTransition(bool);
223  EventTriggerInfo& setRequiredLocalizationTimeWindow(Real);
224 
226  unsigned mask = 0;
227  if (shouldTriggerOnRisingSignTransition()) {
229  }
230  if (shouldTriggerOnFallingSignTransition()) {
232  }
233  return Event::Trigger(mask);
234  }
235 
236  Event::Trigger calcTransitionToReport
237  (Event::Trigger transitionSeen) const
238  {
239  // report -1 to 1 or 1 to -1 as appropriate
240  if (transitionSeen & Event::Rising)
242  if (transitionSeen & Event::Falling)
244  assert(!"impossible event transition situation");
245  return Event::NoEventTrigger;
246  }
247 
248 private:
249  class EventTriggerInfoRep;
250 
251  // opaque implementation for binary compatibility
252  EventTriggerInfoRep* rep;
253 
254  const EventTriggerInfoRep& getRep() const {assert(rep); return *rep;}
255  EventTriggerInfoRep& updRep() {assert(rep); return *rep;}
256 };
257 
258 
259 
260 
261 //==============================================================================
262 // HANDLE EVENTS OPTIONS and HANDLE EVENTS RESULTS
263 //==============================================================================
267 public:
268  enum Option {
270  None = 0x0000,
274  DontThrow = 0x0001,
277  UseInfinityNorm = 0x0002
278  };
279 
280 
281  HandleEventsOptions() {clear();}
282  explicit HandleEventsOptions(Real accuracy)
283  { clear(); setAccuracy(accuracy); }
285  { clear(); setOption(opt); }
286 
291  { optionSet=0; setAccuracyDefaults(); return *this; }
292 
297  assert(accuracy > 0);
298  requiredAccuracy = accuracy;
299  return *this;
300  }
301 
305  { optionSet &= ~(unsigned)opt; return *this; }
309  { optionSet |= (unsigned)opt; return *this; }
310 
312  Real getAccuracy() const {return requiredAccuracy;}
313 
314  bool isOptionSet(Option opt) const {return (optionSet&(unsigned)opt) != 0;}
315 
316  static Real getDefaultAccuracy() {return Real(1e-4);}
317 
318  // Set operators: not, or, and, set difference
320  { optionSet |= opts.optionSet; return *this; }
322  { optionSet &= opts.optionSet; return *this; }
324  { optionSet &= ~opts.optionSet; return *this; }
325 
326  HandleEventsOptions& operator|=(Option opt) {setOption(opt); return *this;}
327  HandleEventsOptions& operator-=(Option opt) {clearOption(opt); return *this;}
328 
329 private:
330  Real requiredAccuracy;
331  unsigned optionSet;
332 
333  void setAccuracyDefaults() {
334  requiredAccuracy = getDefaultAccuracy();
335  }
336 };
337 
343 public:
344  HandleEventsResults() : m_lowestModifiedStage(Stage::Infinity) {clear();}
345 
346  enum Status {
348  Invalid = -1,
351  Succeeded = 0,
355  ShouldTerminate = 1,
359  Failed = 2
360  };
361 
365  m_exitStatus = Invalid;
366  m_anyChangeMade = false;
367  m_lowestModifiedStage = Stage::Infinity; // i.e., nothing modified
368  m_message.clear();
369  return *this;
370  }
371  bool isValid() const {return m_exitStatus != Invalid;}
372  Status getExitStatus() const {return m_exitStatus;}
373 
374  bool getAnyChangeMade() const
375  { assert(isValid()); return m_anyChangeMade; }
377  { assert(isValid()); return m_lowestModifiedStage; }
378  const String& getMessage() const
379  { assert(isValid()); return m_message; }
380 
382  { m_exitStatus=status; return *this; }
384  { m_anyChangeMade=changeMade; return *this; }
386  { m_lowestModifiedStage=stage; return *this; }
388  { m_message=message; return *this; }
389 private:
390  Status m_exitStatus;
391  bool m_anyChangeMade;
392  Stage m_lowestModifiedStage;
393  String m_message;
394 };
395 
396 } // namespace SimTK
397 
398 #endif // SimTK_SimTKCOMMON_EVENT_H_
#define SimTK_SimTKCOMMON_EXPORT
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:218
Trigger
Triggered Events respond to zero crossings of their associated trigger function.
Definition: Event.h:155
SimTK_DEFINE_UNIQUE_INDEX_TYPE(AssemblyConditionIndex)
HandleEventsOptions & operator-=(const HandleEventsOptions &opts)
Definition: Event.h:323
Definition: Event.h:162
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
static std::string eventTriggerString(Trigger)
This is useful for debugging; it translates an Event::Trigger or a mask formed by a union of Event::T...
Definition: Event.h:128
Definition: Event.h:156
Definition: Event.h:161
static Trigger classifyTransition(int before, int after)
Classify a before/after sign transition.
Definition: Event.h:174
This class is basically a glorified enumerated type, type-safe and range checked but permitting conve...
Definition: Stage.h:50
Definition: Event.h:132
HandleEventsOptions & setAccuracy(Real accuracy)
The norm of the constraint errors must be driven to below this value for a project() to be considered...
Definition: Event.h:296
Definition: Event.h:163
Status getExitStatus() const
Definition: Event.h:372
bool isValid() const
Definition: Event.h:140
HandleEventsResults & setExitStatus(Status status)
Definition: Event.h:381
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
HandleEventsOptions & clearOption(Option opt)
Remove a given option from the set.
Definition: Event.h:304
bool isOptionSet(Option opt) const
Definition: Event.h:314
HandleEventsResults & setMessage(const String &message)
Definition: Event.h:387
HandleEventsOptions & setOption(Option opt)
Select a given option from the set.
Definition: Event.h:308
Definition: Event.h:130
An Event is "something that happens" during a Study that is advancing through time.
Definition: Event.h:76
Num
Definition: Event.h:125
Definition: Event.h:131
HandleEventsResults & setAnyChangeMade(bool changeMade)
Definition: Event.h:383
These are all the possible causes for events.
Definition: Event.h:123
HandleEventsOptions & operator-=(Option opt)
Definition: Event.h:327
Option
Definition: Event.h:268
HandleEventsOptions & clear()
Restore this object to its default-constructed state (no options selected, default accuracy)...
Definition: Event.h:290
HandleEventsOptions & operator|=(Option opt)
Definition: Event.h:326
HandleEventsOptions & operator|=(const HandleEventsOptions &opts)
Definition: Event.h:319
Cause()
Definition: Event.h:135
HandleEventsOptions()
Definition: Event.h:281
Stage getLowestModifiedStage() const
Definition: Event.h:376
Definition: Event.h:127
static const char * getCauseName(Cause)
This is useful for debugging; it translates an Event::Cause into a readable string.
Higher than any legitimate Stage.
Definition: Stage.h:63
Real getAccuracy() const
Return the current value for the accuracy option.
Definition: Event.h:312
HandleEventsOptions & operator&=(const HandleEventsOptions &opts)
Definition: Event.h:321
const Real Infinity
This is the IEEE positive infinity constant for this implementation of the default-precision Real typ...
HandleEventsResults & clear()
Restore this object to its default-constructed state, with the return status set to Invalid...
Definition: Event.h:364
HandleEventsResults()
Definition: Event.h:344
SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) inten...
Definition: String.h:62
Event::Trigger calcTransitionMask() const
Definition: Event.h:225
static Trigger maskTransition(Trigger transition, Trigger mask)
Given an observed transition, weed out ignorable ones using the supplied mask.
Definition: Event.h:188
Cause(Num n)
Definition: Event.h:136
Definition: Event.h:159
Status
Definition: Event.h:346
This class is used to communicate between the System and an Integrator regarding the properties of a ...
Definition: Event.h:206
bool getAnyChangeMade() const
Definition: Event.h:374
Definition: Event.h:129
Results returned by the handleEvent() method.
Definition: Event.h:342
HandleEventsOptions(Option opt)
Definition: Event.h:284
bool isValid() const
Definition: Event.h:371
Includes internal headers providing declarations for the basic SimTK Core classes.
Definition: Event.h:158
HandleEventsOptions(Real accuracy)
Definition: Event.h:282
Cause & operator=(Num n)
Definition: Event.h:138
HandleEventsResults & setLowestModifiedStage(Stage stage)
Definition: Event.h:385
const String & getMessage() const
Definition: Event.h:378
static Real getDefaultAccuracy()
Definition: Event.h:316
Options for the handleEvent() method.
Definition: Event.h:266
This is a class to represent unique IDs for events in a type-safe way.