Simbody 3.7
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
34namespace SimTK {
35
40
48
58
63
76class Event {
77public:
78
126 class Cause {
127 public:
128 enum Num {
135 Invalid = -1
136 };
137
138 Cause() : value(Invalid) {}
139 Cause(Num n) : value(n) {} // implicit conversion
140 operator Num() const {return value;} // implicit conversion
141 Cause& operator=(Num n) {value=n; return *this;}
142
143 bool isValid() const {return Initialization<=value && value<=Termination;}
144
145 private:
146 Num value;
147 };
148
152
153
158 enum Trigger {
159 NoEventTrigger =0x0000, // must be 0
160
161 PositiveToNegative =0x0001, // 1
162 NegativeToPositive =0x0002, // 2
163
167 };
168
172
173
177 static Trigger classifyTransition(int before, int after) {
178 if (before==after)
179 return NoEventTrigger;
180 if (before==0)
181 return NoEventTrigger; // Do not report transitions away from zero.
182 if (before==1)
183 return PositiveToNegative;
184 // before==-1
185 return NegativeToPositive;
186 }
187
191 static Trigger maskTransition(Trigger transition, Trigger mask) {
192 // we're depending on NoEventTrigger==0
193 return Trigger(transition & mask);
194 }
195
196private:
197};
198
199
210public:
212 explicit EventTriggerInfo(EventId eventId);
216
217 EventId getEventId() const; // returns -1 if not set
218 bool shouldTriggerOnRisingSignTransition() const; // default=true
219 bool shouldTriggerOnFallingSignTransition() const; // default=true
221
222 // These return the modified 'this', like assignment operators.
227
229 unsigned mask = 0;
230 if (shouldTriggerOnRisingSignTransition()) {
232 }
233 if (shouldTriggerOnFallingSignTransition()) {
235 }
236 return Event::Trigger(mask);
237 }
238
240 (Event::Trigger transitionSeen) const
241 {
242 // report -1 to 1 or 1 to -1 as appropriate
243 if (transitionSeen & Event::Rising)
245 if (transitionSeen & Event::Falling)
247 assert(!"impossible event transition situation");
249 }
250
251private:
252 class EventTriggerInfoRep;
253
254 // opaque implementation for binary compatibility
255 EventTriggerInfoRep* rep;
256
257 const EventTriggerInfoRep& getRep() const {assert(rep); return *rep;}
258 EventTriggerInfoRep& updRep() {assert(rep); return *rep;}
259};
260
261
262
263
264//==============================================================================
265// HANDLE EVENTS OPTIONS and HANDLE EVENTS RESULTS
266//==============================================================================
270public:
271 enum Option {
273 None = 0x0000,
277 DontThrow = 0x0001,
280 UseInfinityNorm = 0x0002
281 };
282
283
285 explicit HandleEventsOptions(Real accuracy)
286 { clear(); setAccuracy(accuracy); }
288 { clear(); setOption(opt); }
289
294 { optionSet=0; setAccuracyDefaults(); return *this; }
295
300 assert(accuracy > 0);
301 requiredAccuracy = accuracy;
302 return *this;
303 }
304
308 { optionSet &= ~(unsigned)opt; return *this; }
312 { optionSet |= (unsigned)opt; return *this; }
313
315 Real getAccuracy() const {return requiredAccuracy;}
316
317 bool isOptionSet(Option opt) const {return (optionSet&(unsigned)opt) != 0;}
318
319 static Real getDefaultAccuracy() {return Real(1e-4);}
320
321 // Set operators: not, or, and, set difference
323 { optionSet |= opts.optionSet; return *this; }
325 { optionSet &= opts.optionSet; return *this; }
327 { optionSet &= ~opts.optionSet; return *this; }
328
329 HandleEventsOptions& operator|=(Option opt) {setOption(opt); return *this;}
331
332private:
333 Real requiredAccuracy;
334 unsigned optionSet;
335
336 void setAccuracyDefaults() {
337 requiredAccuracy = getDefaultAccuracy();
338 }
339};
340
346public:
347 HandleEventsResults() : m_lowestModifiedStage(Stage::Infinity) {clear();}
348
349 enum Status {
362 Failed = 2
363 };
364
368 m_exitStatus = Invalid;
369 m_anyChangeMade = false;
370 m_lowestModifiedStage = Stage::Infinity; // i.e., nothing modified
371 m_message.clear();
372 return *this;
373 }
374 bool isValid() const {return m_exitStatus != Invalid;}
375 Status getExitStatus() const {return m_exitStatus;}
376
377 bool getAnyChangeMade() const
378 { assert(isValid()); return m_anyChangeMade; }
380 { assert(isValid()); return m_lowestModifiedStage; }
381 const String& getMessage() const
382 { assert(isValid()); return m_message; }
383
385 { m_exitStatus=status; return *this; }
387 { m_anyChangeMade=changeMade; return *this; }
389 { m_lowestModifiedStage=stage; return *this; }
391 { m_message=message; return *this; }
392private:
393 Status m_exitStatus;
394 bool m_anyChangeMade;
395 Stage m_lowestModifiedStage;
396 String m_message;
397};
398
399} // namespace SimTK
400
401#endif // SimTK_SimTKCOMMON_EVENT_H_
#define SimTK_SimTKCOMMON_EXPORT
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:224
Includes internal headers providing declarations for the basic SimTK Core classes.
This is a class to represent unique IDs for events in a type-safe way.
Unique integer type for Subsystem-local, per-stage event indexing.
This class is used to communicate between the System and an Integrator regarding the properties of a ...
Definition: Event.h:209
Real getRequiredLocalizationTimeWindow() const
EventTriggerInfo(EventId eventId)
Event::Trigger calcTransitionMask() const
Definition: Event.h:228
EventId getEventId() const
EventTriggerInfo & operator=(const EventTriggerInfo &)
EventTriggerInfo(const EventTriggerInfo &)
EventTriggerInfo & setTriggerOnRisingSignTransition(bool)
EventTriggerInfo & setEventId(EventId)
EventTriggerInfo & setTriggerOnFallingSignTransition(bool)
Event::Trigger calcTransitionToReport(Event::Trigger transitionSeen) const
Definition: Event.h:240
bool shouldTriggerOnRisingSignTransition() const
EventTriggerInfo & setRequiredLocalizationTimeWindow(Real)
bool shouldTriggerOnFallingSignTransition() const
These are all the possible causes for events.
Definition: Event.h:126
Cause & operator=(Num n)
Definition: Event.h:141
Cause()
Definition: Event.h:138
Cause(Num n)
Definition: Event.h:139
Num
Definition: Event.h:128
@ Termination
Definition: Event.h:134
@ Triggered
Definition: Event.h:130
@ Scheduled
Definition: Event.h:131
@ Initialization
Definition: Event.h:129
@ TimeAdvanced
Definition: Event.h:132
@ Signaled
Definition: Event.h:133
@ Invalid
Definition: Event.h:135
bool isValid() const
Definition: Event.h:143
An Event is "something that happens" during a Study that is advancing through time.
Definition: Event.h:76
Trigger
Triggered Events respond to zero crossings of their associated trigger function.
Definition: Event.h:158
@ Falling
Definition: Event.h:164
@ PositiveToNegative
Definition: Event.h:161
@ NegativeToPositive
Definition: Event.h:162
@ AnySignChange
Definition: Event.h:166
@ NoEventTrigger
Definition: Event.h:159
@ Rising
Definition: Event.h:165
static Trigger maskTransition(Trigger transition, Trigger mask)
Given an observed transition, weed out ignorable ones using the supplied mask.
Definition: Event.h:191
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...
static Trigger classifyTransition(int before, int after)
Classify a before/after sign transition.
Definition: Event.h:177
static const char * getCauseName(Cause)
This is useful for debugging; it translates an Event::Cause into a readable string.
Options for the handleEvent() method.
Definition: Event.h:269
Real getAccuracy() const
Return the current value for the accuracy option.
Definition: Event.h:315
HandleEventsOptions(Real accuracy)
Definition: Event.h:285
static Real getDefaultAccuracy()
Definition: Event.h:319
HandleEventsOptions & clear()
Restore this object to its default-constructed state (no options selected, default accuracy).
Definition: Event.h:293
HandleEventsOptions & operator&=(const HandleEventsOptions &opts)
Definition: Event.h:324
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:299
HandleEventsOptions()
Definition: Event.h:284
bool isOptionSet(Option opt) const
Definition: Event.h:317
HandleEventsOptions & operator|=(Option opt)
Definition: Event.h:329
HandleEventsOptions(Option opt)
Definition: Event.h:287
HandleEventsOptions & operator-=(Option opt)
Definition: Event.h:330
HandleEventsOptions & operator-=(const HandleEventsOptions &opts)
Definition: Event.h:326
HandleEventsOptions & operator|=(const HandleEventsOptions &opts)
Definition: Event.h:322
HandleEventsOptions & clearOption(Option opt)
Remove a given option from the set.
Definition: Event.h:307
Option
Definition: Event.h:271
@ UseInfinityNorm
Use the stricter infinity (max absolute value) norm rather than the default RMS norm to determine whe...
Definition: Event.h:280
@ None
Take all defaults.
Definition: Event.h:273
@ DontThrow
Normally failure to meet the accuracy requirements throws an exception.
Definition: Event.h:277
HandleEventsOptions & setOption(Option opt)
Select a given option from the set.
Definition: Event.h:311
Results returned by the handleEvent() method.
Definition: Event.h:345
HandleEventsResults()
Definition: Event.h:347
bool isValid() const
Definition: Event.h:374
HandleEventsResults & setMessage(const String &message)
Definition: Event.h:390
bool getAnyChangeMade() const
Definition: Event.h:377
const String & getMessage() const
Definition: Event.h:381
HandleEventsResults & setLowestModifiedStage(Stage stage)
Definition: Event.h:388
Status
Definition: Event.h:349
@ Invalid
This object has not been filled in yet and holds no results.
Definition: Event.h:351
@ Succeeded
The handleEvent() operation was successful and time stepping may continue.
Definition: Event.h:354
@ Failed
The handleEvent() call was unable to successfully handle the event.
Definition: Event.h:362
@ ShouldTerminate
The handleEvent() call was successful but the event requires time stepping to terminate.
Definition: Event.h:358
HandleEventsResults & setAnyChangeMade(bool changeMade)
Definition: Event.h:386
HandleEventsResults & clear()
Restore this object to its default-constructed state, with the return status set to Invalid.
Definition: Event.h:367
HandleEventsResults & setExitStatus(Status status)
Definition: Event.h:384
Status getExitStatus() const
Definition: Event.h:375
Stage getLowestModifiedStage() const
Definition: Event.h:379
This class is basically a glorified enumerated type, type-safe and range checked but permitting conve...
Definition: Stage.h:66
@ Infinity
Higher than any legitimate Stage.
Definition: Stage.h:79
SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) inten...
Definition: String.h:62
This unique integer type is for identifying a triggered event within a particular Stage of the full S...
This unique integer type is for identifying a triggered event in the full System-level view of the St...
const Real Infinity
This is the IEEE positive infinity constant for this implementation of the default-precision Real typ...
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
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
SimTK_DEFINE_UNIQUE_INDEX_TYPE(AssemblyConditionIndex)