Measure.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_MEASURE_H_
#define SimTK_SimTKCOMMON_MEASURE_H_

/* -------------------------------------------------------------------------- *
 *                      SimTK Core: SimTKcommon                               *
 * -------------------------------------------------------------------------- *
 * This is part of the SimTK Core 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.               *
 *                                                                            *
 * Portions copyright (c) 2008-10 Stanford University and the Authors.        *
 * Authors: Michael Sherman                                                   *
 * Contributors:                                                              *
 *                                                                            *
 * Permission is hereby granted, free of charge, to any person obtaining a    *
 * copy of this software and associated documentation files (the "Software"), *
 * to deal in the Software without restriction, including without limitation  *
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,   *
 * and/or sell copies of the Software, and to permit persons to whom the      *
 * Software is furnished to do so, subject to the following conditions:       *
 *                                                                            *
 * The above copyright notice and this permission notice shall be included in *
 * all copies or substantial portions of the Software.                        *
 *                                                                            *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,   *
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL    *
 * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,    *
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR      *
 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE  *
 * USE OR OTHER DEALINGS IN THE SOFTWARE.                                     *
 * -------------------------------------------------------------------------- */

#include "SimTKcommon/basics.h"
#include "SimTKcommon/Simmatrix.h"

#include <cassert>

#define SimTK_MEASURE_HANDLE_PREAMBLE_BASE(MH,PH) \
    class Implementation;                                           \
    explicit MH(Implementation* imp) : PH(imp) {}                   \
    MH(Subsystem& sub, Implementation* imp, const SetHandle& sh)    \
    :   PH(sub,imp,sh) {}                                           \
    MH& operator=(const MH& src) {PH::operator=(src); return *this;}\
    MH& shallowAssign(const MH& src) {PH::shallowAssign(src); return *this;}\
    MH& deepAssign(const MH& src) {PH::deepAssign(src); return *this;}

// The default constructor for concrete classes should instantiate
// a default-constructed Implementation object if no Implementation
// is provided.
#define SimTK_MEASURE_HANDLE_PREAMBLE(MH,PH)    \
    SimTK_MEASURE_HANDLE_PREAMBLE_BASE(MH,PH)   \
    MH() : PH(new Implementation()) {}          \
    explicit MH(Subsystem& sub)                 \
    : PH(sub,new Implementation(), SetHandle()) {}

// The default constructor for a still-abstract derived class can't
// instantiate an Implementation.
#define SimTK_MEASURE_HANDLE_PREAMBLE_ABSTRACT(MH,PH)   \
    SimTK_MEASURE_HANDLE_PREAMBLE_BASE(MH,PH)           \
    MH() : PH() {}                                      \
    explicit MH(Subsystem& sub) : PH(sub) {}    

#define SimTK_MEASURE_HANDLE_POSTSCRIPT(MH,PH) \
    static bool isA(const AbstractMeasure& m)                               \
    {   return dynamic_cast<const Implementation*>(&m.getImpl()) != 0; }    \
    static const MH& getAs(const AbstractMeasure& m)                        \
    {   assert(isA(m)); return static_cast<const MH&>(m); }                 \
    static MH& updAs(AbstractMeasure& m)                                    \
    {   assert(isA(m)); return static_cast<MH&>(m); }                       \
    const Implementation& getImpl() const                                   \
    {   return dynamic_cast<const Implementation&>                          \
                    (AbstractMeasure::getImpl());}                          \
    Implementation& updImpl()                                               \
    {   return dynamic_cast<Implementation&>(AbstractMeasure::updImpl());} 

namespace SimTK {

class State;
class Subsystem;
class System;
class EventIndex;

SimTK_DEFINE_UNIQUE_INDEX_TYPE(MeasureIndex);

    // ABSTRACT MEASURE //

class SimTK_SimTKCOMMON_EXPORT AbstractMeasure {
protected:
    // An object of this type is used as a dummy argument to make sure the 
    // automatically-generated handle constructor's signature doesn't conflict 
    // with an explicitly-defined one.
    class SetHandle {};

public:
    class Implementation; // local; name is AbstractMeasure::Implementation

    explicit AbstractMeasure(Implementation* g=0);

    AbstractMeasure(Subsystem&, Implementation* g, const SetHandle&);

    AbstractMeasure(const AbstractMeasure&);

    AbstractMeasure& operator=(const AbstractMeasure& source)
    {   return shallowAssign(source); }

    ~AbstractMeasure();

    AbstractMeasure& shallowAssign(const AbstractMeasure&);

    AbstractMeasure& deepAssign(const AbstractMeasure& source);

    int getNumTimeDerivatives() const;

    Stage getDependsOnStage(int derivOrder=0) const;


    bool isSameMeasure(const AbstractMeasure& other) const
    {   return impl && impl==other.impl;}

    bool isEmptyHandle() const {return !hasImpl();}

    bool isInSubsystem() const;
    const Subsystem& getSubsystem()  const;
    MeasureIndex getSubsystemMeasureIndex() const;

    // Internal use only

    // dynamic_cast the returned reference to a reference to your concrete
    // Implementation class.
    const Implementation& getImpl() const {assert(impl); return *impl;}
    Implementation&       updImpl()       {assert(impl); return *impl;}
    bool                  hasImpl() const {return impl!=0;}

    int getRefCount() const;
private:
    // This is the only data member in this class. Also, any class derived 
    // from AbstractMeasure must have *NO* data members at all (data goes 
    // in the Implementation class).
    Implementation* impl;

friend class Implementation;
};


    // MEASURE_<T> //

template <class T>
class Measure_ : public AbstractMeasure {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE_ABSTRACT(Measure_, AbstractMeasure);

    inline const T& getValue(const State& s, int derivOrder=0) const 
    {   return getImpl().getValue(s,derivOrder); }

    // These are built-in Measures with local class names. 

    // Templatized measures may have restrictions on the allowable template
    // type and may be specialized for particular types.
    class Zero;         // T is any numerical type
    class One;          // T is any numerical type
    class Constant;     // T is any assignable type
    class Time;         // T is any type for which T(t) makes sense.
    class Variable;     // T is any assignable type (state)
    class Result;       // T is any assignable type (cache)
    class SampleAndHold;//    "

    // This requires any numerical type.
    class Plus;
    class Minus;
    class Scale;
    class Differentiate;

    // These accept any type that supports operator<, elementwise for 
    // vectors and matrices. TODO
    class Minimum;
    class Maximum;

    // These accept floating point numerical template arguments only.
    class Integrate;
    class Sinusoid;

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Measure_, AbstractMeasure);
};

typedef Measure_<Real> Measure;


    // CONSTANT //

template <class T>
class Measure_<T>::Constant : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Constant, Measure_<T>);

    explicit Constant(const T& value)
    :   Measure_<T>(new Implementation(value)) {}

    Constant(Subsystem& sub, const T& value)
    :   Measure_<T>(sub, new Implementation(value), SetHandle()) {}

    Constant& setValue(const T& value) 
    {   updImpl().setValue(value); return *this; }

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Constant, Measure_<T>);
};

    // ZERO //

template <class T>
class Measure_<T>::Zero : public Measure_<T>::Constant {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Zero, Measure_<T>::Constant);

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Zero, Measure_<T>::Constant);
private:
    Zero& setValue(const T&) 
    {   return *reinterpret_cast<Zero*>(0);} // suppressed!
};

    // ONE //

template <class T>
class Measure_<T>::One : public Measure_<T>::Constant {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(One, Measure_<T>::Constant);

    SimTK_MEASURE_HANDLE_POSTSCRIPT(One, Measure_<T>::Constant);
private:
    One& setValue(const T&)     
    {   return *reinterpret_cast<One*>(0);} // suppressed!
};

    // TIME //

template <class T>
class Measure_<T>::Time : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Time, Measure_<T>);

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Time, Measure_<T>);
};

    // VARIABLE //

template <class T>
class Measure_<T>::Variable : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Variable, Measure_<T>);

    // TODO: should not require invalidated Stage here. Instead, 
    // should have a unique "generation" counter for this variable
    // and allow subsequent users to check it.
    Variable(Subsystem& sub, Stage invalidates, const T& defaultValue)
    :   Measure_<T>(sub, new Implementation(invalidates, defaultValue), 
                    SetHandle()) {}

    Variable& setDefaultValue(const T& defaultValue) 
    {   updImpl().setDefaultValue(defaultValue); return *this; }

    const T& getDefaultValue() const
    {   return getImpl().getDefaultValue(); }

    void setValue(State& state, const T& value) const
    {   getImpl().setValue(state, value); }

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Variable, Measure_<T>);
};

    // RESULT //

template <class T>
class Measure_<T>::Result : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Result, Measure_<T>);

    // TODO: should not require invalidated Stage here. Instead, 
    // should have a unique "generation" counter for this cache entry
    // and allow subsequent users of the value to check it.

    Result(Subsystem& sub, Stage dependsOn, Stage invalidated)
    :   Measure_<T>(sub, new Implementation(dependsOn, invalidated), 
                    SetHandle()) {}

    Stage getDependsOnStage() const {return getImpl().getDependsOnStage();}
    Stage getInvalidatedStage() const {return getImpl().getInvalidatedStage();}
    Result& setDependsOnStage(Stage dependsOn) 
    {   updImpl().setDependsOnStage(dependsOn); return *this; }
    Result& setInvalidatedStage(Stage invalidated) 
    {   updImpl().setInvalidatedStage(invalidated); return *this; }

    Result& setIsPresumedValidAtDependsOnStage(bool presume)
    {   updImpl().setIsPresumedValidAtDependsOnStage(presume); return *this; }

    bool getIsPresumedValidAtDependsOnStage() const
    {   return getImpl().getIsPresumedValidAtDependsOnStage(); }


    T& updValue(const State& state) const
    {   return getImpl().updValue(state); }

    void markAsValid(const State& state) const {getImpl().markAsValid(state);}

    bool isValid(const State& state) const {return getImpl().isValid(state);}

    void markAsNotValid(const State& state) const 
    {   getImpl().markAsNotValid(state); }

    void setValue(const State& state, const T& value) const
    {   updValue(state) = value; markAsValid(state); }

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Result, Measure_<T>);
};

    // SINUSOID //

template <class T>
class Measure_<T>::Sinusoid : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Sinusoid, Measure_<T>);

    Sinusoid(Subsystem& sub,
             const T& amplitude, 
             const T& frequency,
             const T& phase=T(0))
    :   Measure_<T>(sub, new Implementation(amplitude,frequency,phase), SetHandle()) {}

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Sinusoid, Measure_<T>);
};

    // PLUS //

template <class T>
class Measure_<T>::Plus : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Plus, Measure_<T>);

    Plus(Subsystem& sub, const Measure_<T>& left, const Measure_<T>& right)
    :   Measure_<T>(sub,
                    new Implementation(left, right), SetHandle())
    {   SimTK_ERRCHK_ALWAYS
           (   this->getSubsystem().isSameSubsystem(left.getSubsystem())
            && this->getSubsystem().isSameSubsystem(right.getSubsystem()),
            "Measure_<T>::Plus::ctor()",
            "Arguments must be in the same Subsystem as this Measure.");
    }

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Plus, Measure_<T>);
};

    // MINUS //

template <class T>
class Measure_<T>::Minus : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Minus, Measure_<T>);

    Minus(Subsystem& sub, const Measure_<T>& left, const Measure_<T>& right)
    :   Measure_<T>(sub,
                    new Implementation(left, right), SetHandle())
    {   SimTK_ERRCHK_ALWAYS
           (   this->getSubsystem().isSameSubsystem(left.getSubsystem())
            && this->getSubsystem().isSameSubsystem(right.getSubsystem()),
            "Measure_<T>::Minus::ctor()",
            "Arguments must be in the same Subsystem as this Measure.");
    }

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Minus, Measure_<T>);
};

    // SCALE //

template <class T>
class Measure_<T>::Scale : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Scale, Measure_<T>);

    Scale(Subsystem& sub, Real factor, const Measure_<T>& operand)
    :   Measure_<T>(sub,
                    new Implementation(factor, operand), SetHandle())
    {   SimTK_ERRCHK_ALWAYS
           (this->getSubsystem().isSameSubsystem(operand.getSubsystem()),
            "Measure_<T>::Scale::ctor()",
            "Argument must be in the same Subsystem as this Measure.");
    }

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Scale, Measure_<T>);
};

    // INTEGRATE //

template <class T>
class Measure_<T>::Integrate : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Integrate, Measure_<T>);

    Integrate(Subsystem& sub, const Measure_<T>& deriv, const Measure_<T>& ic)
    :   Measure_<T>(sub, new Implementation(deriv,ic), SetHandle()) {}

    void setValue(State& s, const T& value) const 
    {   return getImpl().setValue(s, value); }
    const Measure_<T>& getDerivativeMeasure() const 
    {   return getImpl().getDerivativeMeasure(); }
    const Measure_<T>& getInitialConditionMeasure() const 
    {   return getImpl().getInitialConditionMeasure(); }

    Integrate& setDerivativeMeasure(const Measure_<T>& d)
    {   updImpl().setDerivativeMeasure(d); return *this; }
    Integrate& setInitialConditionMeasure(const Measure_<T>& ic)
    {   updImpl().setInitialConditionMeasure(ic); return *this; }

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Integrate, Measure_<T>);
};

    // DIFFERENTIATE //

template <class T>
class Measure_<T>::Differentiate : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Differentiate, Measure_<T>);

    Differentiate(Subsystem& subsystem, const Measure_<T>& operand)
    :   Measure_<T>(subsystem, new Implementation(operand), SetHandle()) {}

    bool isUsingApproximation() const 
    {   return getImpl().isUsingApproximation(); }

    const Measure_<T>& getOperandMeasure() const 
    {   return getImpl().getOperandMeasure(); }

    Differentiate& setOperandMeasure(const Measure_<T>& operand)
    {   updImpl().setOperandMeasure(operand); return *this; }

    void setForceUseApproximation(bool mustApproximate)
    {   updImpl().setForceUseApproximation(mustApproximate); }

    bool getForceUseApproximation() const 
    {   return getImpl().getForceUseApproximation(); }

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Differentiate, Measure_<T>);
};

    // MINIMUM //

template <class T>
class Measure_<T>::Minimum : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(Minimum, Measure_<T>);

    Minimum(Subsystem& sub, const Measure_<T>& source, const Measure_<T>& sourceDot)
    :   Measure_<T>(sub, new Implementation(source, sourceDot), SetHandle()) {}

    void setValue(State& s, const T& value) const 
    {   return getImpl().setValue(s, value); }
    const Measure_<T>& getSourceMeasure() const 
    {   return getImpl().getSourceMeasure(); }
    const Measure_<T>& getSourceDerivativeMeasure() const 
    {   return getImpl().getSourceDerivativeMeasure(); }

    Minimum& setSourceMeasure(const Measure_<T>& s)
    {   updImpl().setSourceMeasure(s); return *this; }
    Minimum& setSourceDerivativeMeasure(const Measure_<T>& sdot)
    {   updImpl().setSourceDerivativeMeasure(sdot); return *this; }

    SimTK_MEASURE_HANDLE_POSTSCRIPT(Minimum, Measure_<T>);
};

template <class T>
class Measure_<T>::SampleAndHold : public Measure_<T> {
public:
    SimTK_MEASURE_HANDLE_PREAMBLE(SampleAndHold, Measure_<T>);

    SampleAndHold(Subsystem& sub, const Measure_<T>& source, EventIndex e);

    void setValue(State& s, const T& value) const;

    void sample(State& s) const;

    const Measure_<T>& getSource() const;
    EventIndex         getEvent() const;

    SampleAndHold& setSource(const Measure_<T>& s);
    SampleAndHold& setEvent(EventIndex);

    SimTK_MEASURE_HANDLE_POSTSCRIPT(SampleAndHold, Measure_<T>);
};

} // namespace SimTK

#endif // SimTK_SimTKCOMMON_MEASURE_H_