Event.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_EVENT_H_
#define SimTK_SimTKCOMMON_EVENT_H_

/* -------------------------------------------------------------------------- *
 *                       Simbody(tm): SimTKcommon                             *
 * -------------------------------------------------------------------------- *
 * This is part of the SimTK biosimulation toolkit originating from           *
 * Simbios, the NIH National Center for Physics-Based Simulation of           *
 * Biological Structures at Stanford, funded under the NIH Roadmap for        *
 * Medical Research, grant U54 GM072970. See https://simtk.org/home/simbody.  *
 *                                                                            *
 * Portions copyright (c) 2008-12 Stanford University and the Authors.        *
 * Authors: Michael Sherman                                                   *
 * Contributors:                                                              *
 *                                                                            *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may    *
 * not use this file except in compliance with the License. You may obtain a  *
 * copy of the License at http://www.apache.org/licenses/LICENSE-2.0.         *
 *                                                                            *
 * Unless required by applicable law or agreed to in writing, software        *
 * distributed under the License is distributed on an "AS IS" BASIS,          *
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   *
 * See the License for the specific language governing permissions and        *
 * limitations under the License.                                             *
 * -------------------------------------------------------------------------- */

#include "SimTKcommon/basics.h"

namespace SimTK {
    
SimTK_DEFINE_UNIQUE_INDEX_TYPE(EventId);

SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemEventTriggerIndex);

SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemEventTriggerByStageIndex);

SimTK_DEFINE_UNIQUE_INDEX_TYPE(EventTriggerByStageIndex);

class Event {
public:

    class Cause {
    public:
        enum Num {
            Initialization  = 1,
            Triggered       = 2,
            Scheduled       = 3,
            TimeAdvanced    = 4,
            Signaled        = 5,
            Termination     = 6,
            Invalid         = -1
        };

        Cause() : value(Invalid) {}
        Cause(Num n) : value(n) {}           // implicit conversion
        operator Num() const {return value;} // implicit conversion
        Cause& operator=(Num n) {value=n; return *this;}

        bool isValid() const {return Initialization<=value && value<=Termination;}

    private:
        Num value;
    };

    SimTK_SimTKCOMMON_EXPORT static const char* getCauseName(Cause);


    enum Trigger {
        NoEventTrigger          =0x0000,    // must be 0

        PositiveToNegative      =0x0001,    // 1
        NegativeToPositive      =0x0002,    // 2

        Falling                 =(PositiveToNegative), // 1
        Rising                  =(NegativeToPositive), // 2
        AnySignChange           =(PositiveToNegative|NegativeToPositive)    // 3
    };

    SimTK_SimTKCOMMON_EXPORT static std::string eventTriggerString(Trigger);


    static Trigger classifyTransition(int before, int after) {
        if (before==after)
            return NoEventTrigger;
        if (before==0)
            return NoEventTrigger; // Do not report transitions away from zero.
        if (before==1)
            return PositiveToNegative;
        // before==-1
        return NegativeToPositive;
    }

    static Trigger maskTransition(Trigger transition, Trigger mask) {
        // we're depending on NoEventTrigger==0
        return Trigger(transition & mask); 
    }

private:
};


class SimTK_SimTKCOMMON_EXPORT EventTriggerInfo {
public:
    EventTriggerInfo();
    explicit EventTriggerInfo(EventId eventId);
    ~EventTriggerInfo();
    EventTriggerInfo(const EventTriggerInfo&);
    EventTriggerInfo& operator=(const EventTriggerInfo&);

    EventId getEventId() const; // returns -1 if not set
    bool shouldTriggerOnRisingSignTransition()  const; // default=true
    bool shouldTriggerOnFallingSignTransition() const; // default=true
    Real getRequiredLocalizationTimeWindow()    const; // default=0.1

    // These return the modified 'this', like assignment operators.
    EventTriggerInfo& setEventId(EventId);
    EventTriggerInfo& setTriggerOnRisingSignTransition(bool);
    EventTriggerInfo& setTriggerOnFallingSignTransition(bool);
    EventTriggerInfo& setRequiredLocalizationTimeWindow(Real);

    Event::Trigger calcTransitionMask() const {
        unsigned mask = 0;
        if (shouldTriggerOnRisingSignTransition()) {
            mask |= Event::NegativeToPositive;
        }
        if (shouldTriggerOnFallingSignTransition()) {
            mask |= Event::PositiveToNegative;
        }
        return Event::Trigger(mask);
    }

    Event::Trigger calcTransitionToReport
       (Event::Trigger transitionSeen) const
    {
        // report -1 to 1 or 1 to -1 as appropriate
        if (transitionSeen & Event::Rising)
            return Event::NegativeToPositive;
        if (transitionSeen & Event::Falling)
            return Event::PositiveToNegative;
        assert(!"impossible event transition situation");
        return Event::NoEventTrigger;
    }

private:
    class EventTriggerInfoRep;

    // opaque implementation for binary compatibility
    EventTriggerInfoRep* rep;

    const EventTriggerInfoRep& getRep() const {assert(rep); return *rep;}
    EventTriggerInfoRep&       updRep()       {assert(rep); return *rep;}
};




//==============================================================================
//              HANDLE EVENTS OPTIONS and HANDLE EVENTS RESULTS
//==============================================================================
class HandleEventsOptions {
public:
    enum Option {
        None            = 0x0000,
        DontThrow       = 0x0001,
        UseInfinityNorm = 0x0002
    };


    HandleEventsOptions() {clear();}
    explicit HandleEventsOptions(Real accuracy) 
    {   clear(); setAccuracy(accuracy); }
    explicit HandleEventsOptions(Option opt)
    {   clear(); setOption(opt); }

    HandleEventsOptions& clear() 
    {   optionSet=0; setAccuracyDefaults(); return *this; }

    HandleEventsOptions& setAccuracy(Real accuracy) {
        assert(accuracy > 0);
        requiredAccuracy = accuracy;
        return *this;
    }

    HandleEventsOptions& clearOption(Option opt) 
    {   optionSet &= ~(unsigned)opt; return *this; }
    HandleEventsOptions& setOption  (Option opt) 
    {   optionSet |= (unsigned)opt; return *this; }

    Real getAccuracy()       const {return requiredAccuracy;}

    bool isOptionSet(Option opt) const {return (optionSet&(unsigned)opt) != 0;}

    static Real getDefaultAccuracy() {return Real(1e-4);}

    // Set operators: not, or, and, set difference
    HandleEventsOptions& operator|=(const HandleEventsOptions& opts) 
    {   optionSet |= opts.optionSet; return *this; }
    HandleEventsOptions& operator&=(const HandleEventsOptions& opts) 
    {   optionSet &= opts.optionSet; return *this; }
    HandleEventsOptions& operator-=(const HandleEventsOptions& opts) 
    {   optionSet &= ~opts.optionSet; return *this; }

    HandleEventsOptions& operator|=(Option opt) {setOption(opt); return *this;}
    HandleEventsOptions& operator-=(Option opt) {clearOption(opt); return *this;}

private:
    Real     requiredAccuracy;
    unsigned optionSet;

    void setAccuracyDefaults() {
        requiredAccuracy = getDefaultAccuracy();
    }
};

class HandleEventsResults {
public:
    HandleEventsResults() : m_lowestModifiedStage(Stage::Infinity) {clear();}

    enum Status {
        Invalid                 = -1,
        Succeeded               = 0,
        ShouldTerminate         = 1,
        Failed                  = 2    
    };

    HandleEventsResults& clear() {
        m_exitStatus = Invalid;
        m_anyChangeMade = false;
        m_lowestModifiedStage = Stage::Infinity; // i.e., nothing modified
        m_message.clear();
        return *this;
    }
    bool    isValid()           const {return m_exitStatus != Invalid;}
    Status  getExitStatus()     const {return m_exitStatus;}

    bool getAnyChangeMade()     const 
    {   assert(isValid()); return m_anyChangeMade; }
    Stage getLowestModifiedStage() const 
    {   assert(isValid()); return m_lowestModifiedStage; }
    const String& getMessage() const
    {   assert(isValid()); return m_message; }

    HandleEventsResults& setExitStatus(Status status) 
    {   m_exitStatus=status; return *this; }
    HandleEventsResults& setAnyChangeMade(bool changeMade) 
    {   m_anyChangeMade=changeMade; return *this; }
    HandleEventsResults& setLowestModifiedStage(Stage stage) 
    {   m_lowestModifiedStage=stage; return *this; }
    HandleEventsResults& setMessage(const String& message) 
    {   m_message=message; return *this; }
private:
    Status  m_exitStatus;
    bool    m_anyChangeMade;
    Stage   m_lowestModifiedStage;
    String  m_message;
};

} // namespace SimTK

#endif // SimTK_SimTKCOMMON_EVENT_H_