State.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_STATE_H_
#define SimTK_SimTKCOMMON_STATE_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.               *
 *                                                                            *
 * Portions copyright (c) 2005-15 Stanford University and the Authors.        *
 * Authors: Michael Sherman                                                   *
 * Contributors: Peter Eastman                                                *
 *                                                                            *
 * 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.                                             *
 * -------------------------------------------------------------------------- */
 
// Note: the StateImpl.h header is included at the end of this file to 
// complete the inline part of the State definition.
#include "SimTKcommon/basics.h"
#include "SimTKcommon/Simmatrix.h"
#include "SimTKcommon/internal/Event.h"
 
#include <ostream>
#include <cassert>
#include <algorithm>
#include <mutex>
#include <array>
 
namespace SimTK {
 
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(SubsystemIndex);
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemYIndex);
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemQIndex);
SimTK_DEFINE_UNIQUE_INDEX_TYPE(QIndex);
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUIndex);
SimTK_DEFINE_UNIQUE_INDEX_TYPE(UIndex);
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemZIndex);
SimTK_DEFINE_UNIQUE_INDEX_TYPE(ZIndex);
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(DiscreteVariableIndex);
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(CacheEntryIndex);
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemYErrIndex);
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemQErrIndex);
SimTK_DEFINE_UNIQUE_INDEX_TYPE(QErrIndex);
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUErrIndex);
SimTK_DEFINE_UNIQUE_INDEX_TYPE(UErrIndex);
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUDotErrIndex);
SimTK_DEFINE_UNIQUE_INDEX_TYPE(UDotErrIndex);
 
SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemMultiplierIndex);
SimTK_DEFINE_UNIQUE_INDEX_TYPE(MultiplierIndex);
 
class StateImpl;
class PerSubsystemInfo;
class DiscreteVarInfo;
class CacheEntryInfo;
class ListOfDependents;
 
using CacheEntryKey = std::pair<SubsystemIndex,CacheEntryIndex>;
using DiscreteVarKey = std::pair<SubsystemIndex,DiscreteVariableIndex>;
 
class SimTK_SimTKCOMMON_EXPORT State {
public:
State();
 
State(const State&);
 
State(State&& source);
 
State& operator=(const State&);
 
State& operator=(State&& source);
 
~State();
 
void clear();
 
bool isConsistent(const SimTK::State& otherState) const;
 
inline void setNumSubsystems(int i);
 
inline void initializeSubsystem(SubsystemIndex, const String& name, 
                                const String& version);
 
inline SubsystemIndex addSubsystem(const String& name, const String& version);
 
inline int getNumSubsystems() const;
inline const String& getSubsystemName   (SubsystemIndex) const;
inline const String& getSubsystemVersion(SubsystemIndex) const;
inline const Stage&  getSubsystemStage  (SubsystemIndex) const;
 
inline const Stage& getSystemStage() const;
 
inline void invalidateAll(Stage);
 
inline void invalidateAllCacheAtOrAbove(Stage) const;
 
inline void advanceSubsystemToStage(SubsystemIndex, Stage) const;
inline void advanceSystemToStage(Stage) const;
 
inline StageVersion getSystemTopologyStageVersion() const;
 
inline QIndex allocateQ(SubsystemIndex, const Vector& qInit);
inline UIndex allocateU(SubsystemIndex, const Vector& uInit); 
inline ZIndex allocateZ(SubsystemIndex, const Vector& zInit);
inline QErrIndex    allocateQErr   (SubsystemIndex, int nqerr) const;   
inline UErrIndex    allocateUErr   (SubsystemIndex, int nuerr) const;
inline UDotErrIndex allocateUDotErr(SubsystemIndex, int nudoterr) const;
inline EventTriggerByStageIndex 
allocateEventTrigger(SubsystemIndex, Stage stage, int nevent) const;
inline DiscreteVariableIndex 
allocateDiscreteVariable(SubsystemIndex, Stage invalidates, AbstractValue*);
 
inline DiscreteVariableIndex
allocateAutoUpdateDiscreteVariable(SubsystemIndex, Stage invalidates, 
                                   AbstractValue*, Stage updateDependsOn); 
inline CacheEntryIndex 
getDiscreteVarUpdateIndex(SubsystemIndex, DiscreteVariableIndex) const;
inline Stage 
getDiscreteVarAllocationStage(SubsystemIndex, DiscreteVariableIndex) const;
inline Stage 
getDiscreteVarInvalidatesStage(SubsystemIndex, DiscreteVariableIndex) const;
 
 
inline const AbstractValue& 
getDiscreteVariable(SubsystemIndex, DiscreteVariableIndex) const;
inline Real 
getDiscreteVarLastUpdateTime(SubsystemIndex, DiscreteVariableIndex) const;
inline const AbstractValue& 
getDiscreteVarUpdateValue(SubsystemIndex, DiscreteVariableIndex) const;
inline AbstractValue& 
updDiscreteVarUpdateValue(SubsystemIndex, DiscreteVariableIndex) const;
inline bool 
isDiscreteVarUpdateValueRealized(SubsystemIndex, DiscreteVariableIndex) const;
inline void 
markDiscreteVarUpdateValueRealized(SubsystemIndex, DiscreteVariableIndex) const;
 
inline AbstractValue& 
updDiscreteVariable(SubsystemIndex, DiscreteVariableIndex);
inline void 
setDiscreteVariable
   (SubsystemIndex, DiscreteVariableIndex, const AbstractValue&);
inline CacheEntryIndex 
allocateCacheEntry(SubsystemIndex, Stage earliest, Stage latest,
                   AbstractValue* value) const;
 
inline CacheEntryIndex 
allocateCacheEntry(SubsystemIndex sx, Stage stage, 
                   AbstractValue* value) const
{   return allocateCacheEntry(sx, stage, stage, value); }
 
inline CacheEntryIndex 
allocateLazyCacheEntry(SubsystemIndex sx, Stage earliest, 
                       AbstractValue* value) const {
    return allocateCacheEntry(sx, earliest, Stage::Infinity, value);
}
 
inline CacheEntryIndex
allocateCacheEntryWithPrerequisites
   (SubsystemIndex, Stage earliest, Stage latest,
    bool q, bool u, bool z,
    const Array_<DiscreteVarKey>& discreteVars,
    const Array_<CacheEntryKey>& cacheEntries,
    AbstractValue* value);
 
inline Stage 
getCacheEntryAllocationStage(SubsystemIndex, CacheEntryIndex) const;
 
inline const AbstractValue& 
getCacheEntry(SubsystemIndex, CacheEntryIndex) const;
 
inline AbstractValue& 
updCacheEntry(SubsystemIndex, CacheEntryIndex) const; // mutable 
 
inline bool isCacheValueRealized(SubsystemIndex, CacheEntryIndex) const;
 
inline void markCacheValueRealized(SubsystemIndex, CacheEntryIndex) const;
 
inline void markCacheValueNotRealized(SubsystemIndex, CacheEntryIndex) const;
 
inline int getNY() const;
inline int getNQ() const;
inline SystemYIndex getQStart() const;
inline int getNU() const;
inline SystemYIndex getUStart() const;
inline int getNZ() const;
inline SystemYIndex getZStart() const;
inline int getNYErr() const;
inline int getNQErr() const;
inline SystemYErrIndex getQErrStart() const; 
inline int getNUErr() const;
inline SystemYErrIndex getUErrStart() const; 
inline int getNUDotErr() const;
inline int getNMultipliers() const; // =mp+mv+ma, necessarily the same as NUDotErr
inline int getNEventTriggers() const;
inline int getNEventTriggersByStage(Stage) const;
inline SystemEventTriggerIndex getEventTriggerStartByStage(Stage) const;
inline std::mutex& getStateLock() const;
 
 
 
inline SystemQIndex getQStart(SubsystemIndex) const; 
inline int getNQ(SubsystemIndex) const;
inline SystemUIndex getUStart(SubsystemIndex) const; 
inline int getNU(SubsystemIndex) const;
inline SystemZIndex getZStart(SubsystemIndex) const; 
inline int getNZ(SubsystemIndex) const;
 
inline SystemQErrIndex getQErrStart(SubsystemIndex) const; 
inline int getNQErr(SubsystemIndex) const;
inline SystemUErrIndex getUErrStart(SubsystemIndex) const; 
inline int getNUErr(SubsystemIndex) const;
inline SystemUDotErrIndex getUDotErrStart(SubsystemIndex) const; 
inline int getNUDotErr(SubsystemIndex) const;
inline SystemMultiplierIndex getMultipliersStart(SubsystemIndex) const;
inline int getNMultipliers(SubsystemIndex) const;
 
inline SystemEventTriggerByStageIndex 
    getEventTriggerStartByStage(SubsystemIndex, Stage) const;
inline int getNEventTriggersByStage(SubsystemIndex, Stage) const;
 
 
inline const Vector& getEventTriggers() const;
inline const Vector& getEventTriggersByStage(Stage) const;
inline const Vector& getEventTriggersByStage(SubsystemIndex, Stage) const;
 
inline Vector& updEventTriggers() const; // mutable
inline Vector& updEventTriggersByStage(Stage) const;
inline Vector& updEventTriggersByStage(SubsystemIndex, Stage) const;
 
inline const Vector& getQ(SubsystemIndex) const;
inline const Vector& getU(SubsystemIndex) const;
inline const Vector& getZ(SubsystemIndex) const;
 
inline const Vector& getUWeights(SubsystemIndex) const;
inline const Vector& getZWeights(SubsystemIndex) const;
 
inline Vector& updQ(SubsystemIndex);
inline Vector& updU(SubsystemIndex);
inline Vector& updZ(SubsystemIndex);
 
inline Vector& updUWeights(SubsystemIndex);
inline Vector& updZWeights(SubsystemIndex);
 
inline const Vector& getQDot(SubsystemIndex) const;
inline const Vector& getUDot(SubsystemIndex) const;
inline const Vector& getZDot(SubsystemIndex) const;
inline const Vector& getQDotDot(SubsystemIndex) const;
 
inline Vector& updQDot(SubsystemIndex) const;    // these are mutable
inline Vector& updUDot(SubsystemIndex) const;
inline Vector& updZDot(SubsystemIndex) const;
inline Vector& updQDotDot(SubsystemIndex) const;
 
inline const Vector& getQErr(SubsystemIndex) const;
inline const Vector& getUErr(SubsystemIndex) const;
inline const Vector& getUDotErr(SubsystemIndex) const;
inline const Vector& getMultipliers(SubsystemIndex) const;
 
inline const Vector& getQErrWeights(SubsystemIndex) const;
inline const Vector& getUErrWeights(SubsystemIndex) const;
 
inline Vector& updQErr(SubsystemIndex) const;    // these are mutable
inline Vector& updUErr(SubsystemIndex) const;
inline Vector& updUDotErr(SubsystemIndex) const;
inline Vector& updMultipliers(SubsystemIndex) const;
 
inline Vector& updQErrWeights(SubsystemIndex);
inline Vector& updUErrWeights(SubsystemIndex);
 
inline const Real&   getTime() const;
inline const Vector& getY() const; // {Q,U,Z} packed and in that order
 
inline const Vector& getQ() const;
inline const Vector& getU() const;
inline const Vector& getZ() const;
 
 
inline const Vector& getUWeights() const;    // diag(Wu)
 
inline const Vector& getZWeights() const;
 
inline Vector& updUWeights();
 
inline Vector& updZWeights();
 
inline Real&   updTime();  // Back up to Stage::Time-1
inline Vector& updY();     // Back up to Stage::Dynamics-1
 
inline void setTime(Real t);
inline void setY(const Vector& y);
 
inline Vector& updQ();     // Back up to Stage::Position-1
inline Vector& updU();     // Back up to Stage::Velocity-1
inline Vector& updZ();     // Back up to Stage::Dynamics-1
 
inline void setQ(const Vector& q);
inline void setU(const Vector& u);
inline void setZ(const Vector& z);
 
inline const Vector& getYDot()    const; // Stage::Acceleration
 
inline const Vector& getQDot()    const; // Stage::Velocity
inline const Vector& getZDot()    const; // Stage::Dynamics
inline const Vector& getUDot()    const; // Stage::Acceleration
 
inline const Vector& getQDotDot() const; // Stage::Acceleration
 
inline Vector& updYDot() const;    // Stage::Acceleration-1
inline Vector& updQDot() const;    // Stage::Velocity-1     (view into YDot)
inline Vector& updZDot() const;    // Stage::Dynamics-1            "
inline Vector& updUDot() const;    // Stage::Acceleration-1        "
 
inline Vector& updQDotDot() const; // Stage::Acceleration-1
 
inline const Vector& getYErr() const;  // Stage::Velocity
 
inline const Vector& getQErr() const;  // Stage::Position (index 3 constraints)
inline const Vector& getUErr() const;  // Stage::Velocity (index 2 constraints)
 
inline const Vector& getUDotErr()     const; // Stage::Acceleration (index 1 constraints)
inline const Vector& getMultipliers() const; // Stage::Acceleration
 
inline const Vector& getQErrWeights() const;
 
inline const Vector& getUErrWeights() const;
 
inline Vector& updQErrWeights();
 
inline Vector& updUErrWeights();
 
inline Vector& updYErr() const; // Stage::Velocity-1
inline Vector& updQErr() const; // Stage::Position-1 (view into YErr)
inline Vector& updUErr() const; // Stage::Velocity-1        "
 
inline Vector& updUDotErr()     const; // Stage::Acceleration-1 (not a view)
inline Vector& updMultipliers() const; // Stage::Acceleration-1 (not a view)
 
inline void getSystemStageVersions(Array_<StageVersion>& versions) const;
 
inline Stage getLowestSystemStageDifference
   (const Array_<StageVersion>& prevVersions) const;
 
inline void setSystemTopologyStageVersion(StageVersion topoVersion);
 
inline ValueVersion getQValueVersion() const;
inline ValueVersion getUValueVersion() const;
inline ValueVersion getZValueVersion() const;
 
inline const ListOfDependents& getQDependents() const;
inline const ListOfDependents& getUDependents() const;
inline const ListOfDependents& getZDependents() const;
 
inline bool hasCacheEntry(const CacheEntryKey& cacheEntry) const;
 
SimTK_FORCE_INLINE const CacheEntryInfo& 
getCacheEntryInfo(const CacheEntryKey& cacheEntry) const;
 
SimTK_FORCE_INLINE CacheEntryInfo& 
updCacheEntryInfo(const CacheEntryKey& cacheEntry);
 
inline bool hasDiscreteVar(const DiscreteVarKey& discreteVar) const;
 
SimTK_FORCE_INLINE const DiscreteVarInfo& 
getDiscreteVarInfo(const DiscreteVarKey& discreteVar) const;
 
SimTK_FORCE_INLINE const PerSubsystemInfo& 
getPerSubsystemInfo(SubsystemIndex) const;
 
inline void autoUpdateDiscreteVariables();
 
inline String toString() const;
inline String cacheToString() const;
//------------------------------------------------------------------------------
// The implementation class and associated inline methods are defined in a
// separate header file included below.
                                private:
StateImpl* impl;
 
const StateImpl& getImpl() const {assert(impl); return *impl;}
StateImpl&       updImpl()       {assert(impl); return *impl;}
};
 
// Dump state and cache to a stream for debugging; this is not serialization.
SimTK_SimTKCOMMON_EXPORT std::ostream& 
operator<<(std::ostream& o, const State& s);
 
} // namespace SimTK
 
// This completes the inline definition of State.
#include "SimTKcommon/internal/StateImpl.h"
 
#endif // SimTK_SimTKCOMMON_STATE_H_