Simbody  3.7
State.h
Go to the documentation of this file.
1 #ifndef SimTK_SimTKCOMMON_STATE_H_
2 #define SimTK_SimTKCOMMON_STATE_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. *
11  * *
12  * Portions copyright (c) 2005-15 Stanford University and the Authors. *
13  * Authors: Michael Sherman *
14  * Contributors: Peter Eastman *
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 
31 // Note: the StateImpl.h header is included at the end of this file to
32 // complete the inline part of the State definition.
33 #include "SimTKcommon/basics.h"
34 #include "SimTKcommon/Simmatrix.h"
35 #include "SimTKcommon/internal/Event.h"
36 
37 #include <ostream>
38 #include <cassert>
39 #include <algorithm>
40 #include <mutex>
41 #include <array>
42 
43 namespace SimTK {
44 
45 
48 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SubsystemIndex);
49 
56 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemYIndex);
57 
65 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemQIndex);
69 SimTK_DEFINE_UNIQUE_INDEX_TYPE(QIndex);
70 
77 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUIndex);
81 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UIndex);
82 
89 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemZIndex);
93 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ZIndex);
94 
99 SimTK_DEFINE_UNIQUE_INDEX_TYPE(DiscreteVariableIndex);
100 
105 SimTK_DEFINE_UNIQUE_INDEX_TYPE(CacheEntryIndex);
106 
112 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemYErrIndex);
113 
119 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemQErrIndex);
123 SimTK_DEFINE_UNIQUE_INDEX_TYPE(QErrIndex);
124 
130 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUErrIndex);
134 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UErrIndex);
135 
141 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUDotErrIndex);
145 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UDotErrIndex);
146 
152 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemMultiplierIndex);
156 SimTK_DEFINE_UNIQUE_INDEX_TYPE(MultiplierIndex);
157 
158 class StateImpl;
159 class PerSubsystemInfo;
160 class DiscreteVarInfo;
161 class CacheEntryInfo;
162 class ListOfDependents;
163 
164 using CacheEntryKey = std::pair<SubsystemIndex,CacheEntryIndex>;
165 using DiscreteVarKey = std::pair<SubsystemIndex,DiscreteVariableIndex>;
166 
280 class SimTK_SimTKCOMMON_EXPORT State {
281 public:
283 State();
284 
291 State(const State&);
292 
294 State(State&& source);
295 
302 State& operator=(const State&);
303 
306 State& operator=(State&& source);
307 
309 ~State();
310 
312 void clear();
313 
337 bool isConsistent(const SimTK::State& otherState) const;
338 
342 inline void setNumSubsystems(int i);
343 
346 inline void initializeSubsystem(SubsystemIndex, const String& name,
347  const String& version);
348 
355 inline SubsystemIndex addSubsystem(const String& name, const String& version);
356 
358 inline int getNumSubsystems() const;
359 inline const String& getSubsystemName (SubsystemIndex) const;
360 inline const String& getSubsystemVersion(SubsystemIndex) const;
361 inline const Stage& getSubsystemStage (SubsystemIndex) const;
362 
364 inline const Stage& getSystemStage() const;
365 
372 inline void invalidateAll(Stage);
373 
381 inline void invalidateAllCacheAtOrAbove(Stage) const;
382 
389 inline void advanceSubsystemToStage(SubsystemIndex, Stage) const;
394 inline void advanceSystemToStage(Stage) const;
395 
400 inline StageVersion getSystemTopologyStageVersion() const;
401 
418 inline QIndex allocateQ(SubsystemIndex, const Vector& qInit);
426 inline UIndex allocateU(SubsystemIndex, const Vector& uInit);
432 inline ZIndex allocateZ(SubsystemIndex, const Vector& zInit);
449 inline QErrIndex allocateQErr (SubsystemIndex, int nqerr) const;
452 inline UErrIndex allocateUErr (SubsystemIndex, int nuerr) const;
457 inline UDotErrIndex allocateUDotErr(SubsystemIndex, int nudoterr) const;
476 inline EventTriggerByStageIndex
477 allocateEventTrigger(SubsystemIndex, Stage stage, int nevent) const;
504 inline DiscreteVariableIndex
505 allocateDiscreteVariable(SubsystemIndex, Stage invalidates, AbstractValue*);
506 
557 inline DiscreteVariableIndex
558 allocateAutoUpdateDiscreteVariable(SubsystemIndex, Stage invalidates,
559  AbstractValue*, Stage updateDependsOn);
562 inline CacheEntryIndex
563 getDiscreteVarUpdateIndex(SubsystemIndex, DiscreteVariableIndex) const;
566 inline Stage
567 getDiscreteVarAllocationStage(SubsystemIndex, DiscreteVariableIndex) const;
572 inline Stage
573 getDiscreteVarInvalidatesStage(SubsystemIndex, DiscreteVariableIndex) const;
574 
575 
578 inline const AbstractValue&
579 getDiscreteVariable(SubsystemIndex, DiscreteVariableIndex) const;
581 inline Real
582 getDiscreteVarLastUpdateTime(SubsystemIndex, DiscreteVariableIndex) const;
587 inline const AbstractValue&
588 getDiscreteVarUpdateValue(SubsystemIndex, DiscreteVariableIndex) const;
594 inline AbstractValue&
595 updDiscreteVarUpdateValue(SubsystemIndex, DiscreteVariableIndex) const;
599 inline bool
600 isDiscreteVarUpdateValueRealized(SubsystemIndex, DiscreteVariableIndex) const;
603 inline void
604 markDiscreteVarUpdateValueRealized(SubsystemIndex, DiscreteVariableIndex) const;
605 
609 inline AbstractValue&
610 updDiscreteVariable(SubsystemIndex, DiscreteVariableIndex);
612 inline void
613 setDiscreteVariable
614  (SubsystemIndex, DiscreteVariableIndex, const AbstractValue&);
696 inline CacheEntryIndex
697 allocateCacheEntry(SubsystemIndex, Stage earliest, Stage latest,
698  AbstractValue* value) const;
699 
704 inline CacheEntryIndex
705 allocateCacheEntry(SubsystemIndex sx, Stage stage,
706  AbstractValue* value) const
707 { return allocateCacheEntry(sx, stage, stage, value); }
708 
717 inline CacheEntryIndex
718 allocateLazyCacheEntry(SubsystemIndex sx, Stage earliest,
719  AbstractValue* value) const {
720  return allocateCacheEntry(sx, earliest, Stage::Infinity, value);
721 }
722 
727 inline CacheEntryIndex
728 allocateCacheEntryWithPrerequisites
729  (SubsystemIndex, Stage earliest, Stage latest,
730  bool q, bool u, bool z,
731  const Array_<DiscreteVarKey>& discreteVars,
732  const Array_<CacheEntryKey>& cacheEntries,
733  AbstractValue* value);
734 
737 inline Stage
738 getCacheEntryAllocationStage(SubsystemIndex, CacheEntryIndex) const;
739 
746 inline const AbstractValue&
747 getCacheEntry(SubsystemIndex, CacheEntryIndex) const;
748 
755 inline AbstractValue&
756 updCacheEntry(SubsystemIndex, CacheEntryIndex) const; // mutable
757 
766 inline bool isCacheValueRealized(SubsystemIndex, CacheEntryIndex) const;
767 
780 inline void markCacheValueRealized(SubsystemIndex, CacheEntryIndex) const;
781 
787 inline void markCacheValueNotRealized(SubsystemIndex, CacheEntryIndex) const;
790 
810 inline int getNY() const;
815 inline int getNQ() const;
817 inline SystemYIndex getQStart() const;
821 inline int getNU() const;
823 inline SystemYIndex getUStart() const;
827 inline int getNZ() const;
829 inline SystemYIndex getZStart() const;
833 inline int getNYErr() const;
836 inline int getNQErr() const;
838 inline SystemYErrIndex getQErrStart() const;
842 inline int getNUErr() const;
844 inline SystemYErrIndex getUErrStart() const;
849 inline int getNUDotErr() const;
854 inline int getNMultipliers() const; // =mp+mv+ma, necessarily the same as NUDotErr
857 inline int getNEventTriggers() const;
860 inline int getNEventTriggersByStage(Stage) const;
864 inline SystemEventTriggerIndex getEventTriggerStartByStage(Stage) const;
870 inline std::mutex& getStateLock() const;
871 
873 
887 
888 inline SystemQIndex getQStart(SubsystemIndex) const;
889 inline int getNQ(SubsystemIndex) const;
890 inline SystemUIndex getUStart(SubsystemIndex) const;
891 inline int getNU(SubsystemIndex) const;
892 inline SystemZIndex getZStart(SubsystemIndex) const;
893 inline int getNZ(SubsystemIndex) const;
894 
895 inline SystemQErrIndex getQErrStart(SubsystemIndex) const;
896 inline int getNQErr(SubsystemIndex) const;
897 inline SystemUErrIndex getUErrStart(SubsystemIndex) const;
898 inline int getNUErr(SubsystemIndex) const;
899 inline SystemUDotErrIndex getUDotErrStart(SubsystemIndex) const;
900 inline int getNUDotErr(SubsystemIndex) const;
901 inline SystemMultiplierIndex getMultipliersStart(SubsystemIndex) const;
902 inline int getNMultipliers(SubsystemIndex) const;
903 
904 inline SystemEventTriggerByStageIndex
905  getEventTriggerStartByStage(SubsystemIndex, Stage) const;
906 inline int getNEventTriggersByStage(SubsystemIndex, Stage) const;
907 
909 
910 inline const Vector& getEventTriggers() const;
911 inline const Vector& getEventTriggersByStage(Stage) const;
912 inline const Vector& getEventTriggersByStage(SubsystemIndex, Stage) const;
913 
914 inline Vector& updEventTriggers() const; // mutable
915 inline Vector& updEventTriggersByStage(Stage) const;
916 inline Vector& updEventTriggersByStage(SubsystemIndex, Stage) const;
917 
919 inline const Vector& getQ(SubsystemIndex) const;
920 inline const Vector& getU(SubsystemIndex) const;
921 inline const Vector& getZ(SubsystemIndex) const;
922 
923 inline const Vector& getUWeights(SubsystemIndex) const;
924 inline const Vector& getZWeights(SubsystemIndex) const;
925 
926 inline Vector& updQ(SubsystemIndex);
927 inline Vector& updU(SubsystemIndex);
928 inline Vector& updZ(SubsystemIndex);
929 
930 inline Vector& updUWeights(SubsystemIndex);
931 inline Vector& updZWeights(SubsystemIndex);
932 
934 inline const Vector& getQDot(SubsystemIndex) const;
935 inline const Vector& getUDot(SubsystemIndex) const;
936 inline const Vector& getZDot(SubsystemIndex) const;
937 inline const Vector& getQDotDot(SubsystemIndex) const;
938 
939 inline Vector& updQDot(SubsystemIndex) const; // these are mutable
940 inline Vector& updUDot(SubsystemIndex) const;
941 inline Vector& updZDot(SubsystemIndex) const;
942 inline Vector& updQDotDot(SubsystemIndex) const;
943 
944 inline const Vector& getQErr(SubsystemIndex) const;
945 inline const Vector& getUErr(SubsystemIndex) const;
946 inline const Vector& getUDotErr(SubsystemIndex) const;
947 inline const Vector& getMultipliers(SubsystemIndex) const;
948 
949 inline const Vector& getQErrWeights(SubsystemIndex) const;
950 inline const Vector& getUErrWeights(SubsystemIndex) const;
951 
952 inline Vector& updQErr(SubsystemIndex) const; // these are mutable
953 inline Vector& updUErr(SubsystemIndex) const;
954 inline Vector& updUDotErr(SubsystemIndex) const;
955 inline Vector& updMultipliers(SubsystemIndex) const;
956 
957 inline Vector& updQErrWeights(SubsystemIndex);
958 inline Vector& updUErrWeights(SubsystemIndex);
959 
961 inline const Real& getTime() const;
962 inline const Vector& getY() const; // {Q,U,Z} packed and in that order
963 
965 inline const Vector& getQ() const;
966 inline const Vector& getU() const;
967 inline const Vector& getZ() const;
968 
969 
1004 inline const Vector& getUWeights() const; // diag(Wu)
1005 
1012 inline const Vector& getZWeights() const;
1013 
1017 inline Vector& updUWeights();
1018 
1022 inline Vector& updZWeights();
1023 
1026 inline Real& updTime(); // Back up to Stage::Time-1
1027 inline Vector& updY(); // Back up to Stage::Dynamics-1
1028 
1030 inline void setTime(Real t);
1031 inline void setY(const Vector& y);
1032 
1034 inline Vector& updQ(); // Back up to Stage::Position-1
1035 inline Vector& updU(); // Back up to Stage::Velocity-1
1036 inline Vector& updZ(); // Back up to Stage::Dynamics-1
1037 
1039 inline void setQ(const Vector& q);
1040 inline void setU(const Vector& u);
1041 inline void setZ(const Vector& z);
1042 
1043 inline const Vector& getYDot() const; // Stage::Acceleration
1044 
1046 inline const Vector& getQDot() const; // Stage::Velocity
1047 inline const Vector& getZDot() const; // Stage::Dynamics
1048 inline const Vector& getUDot() const; // Stage::Acceleration
1049 
1051 inline const Vector& getQDotDot() const; // Stage::Acceleration
1052 
1054 inline Vector& updYDot() const; // Stage::Acceleration-1
1055 inline Vector& updQDot() const; // Stage::Velocity-1 (view into YDot)
1056 inline Vector& updZDot() const; // Stage::Dynamics-1 "
1057 inline Vector& updUDot() const; // Stage::Acceleration-1 "
1058 
1062 inline Vector& updQDotDot() const; // Stage::Acceleration-1
1063 
1066 inline const Vector& getYErr() const; // Stage::Velocity
1067 
1069 inline const Vector& getQErr() const; // Stage::Position (index 3 constraints)
1070 inline const Vector& getUErr() const; // Stage::Velocity (index 2 constraints)
1071 
1073 inline const Vector& getUDotErr() const; // Stage::Acceleration (index 1 constraints)
1074 inline const Vector& getMultipliers() const; // Stage::Acceleration
1075 
1078 inline const Vector& getQErrWeights() const;
1079 
1090 inline const Vector& getUErrWeights() const;
1091 
1096 inline Vector& updQErrWeights();
1097 
1102 inline Vector& updUErrWeights();
1103 
1105 inline Vector& updYErr() const; // Stage::Velocity-1
1106 inline Vector& updQErr() const; // Stage::Position-1 (view into YErr)
1107 inline Vector& updUErr() const; // Stage::Velocity-1 "
1108 
1109 inline Vector& updUDotErr() const; // Stage::Acceleration-1 (not a view)
1110 inline Vector& updMultipliers() const; // Stage::Acceleration-1 (not a view)
1111 
1123 inline void getSystemStageVersions(Array_<StageVersion>& versions) const;
1124 
1134 inline Stage getLowestSystemStageDifference
1135  (const Array_<StageVersion>& prevVersions) const;
1136 
1143 inline void setSystemTopologyStageVersion(StageVersion topoVersion);
1144 
1149 inline ValueVersion getQValueVersion() const;
1154 inline ValueVersion getUValueVersion() const;
1159 inline ValueVersion getZValueVersion() const;
1160 
1164 inline const ListOfDependents& getQDependents() const;
1168 inline const ListOfDependents& getUDependents() const;
1172 inline const ListOfDependents& getZDependents() const;
1173 
1175 inline bool hasCacheEntry(const CacheEntryKey& cacheEntry) const;
1176 
1179 SimTK_FORCE_INLINE const CacheEntryInfo&
1180 getCacheEntryInfo(const CacheEntryKey& cacheEntry) const;
1181 
1184 SimTK_FORCE_INLINE CacheEntryInfo&
1185 updCacheEntryInfo(const CacheEntryKey& cacheEntry);
1186 
1189 inline bool hasDiscreteVar(const DiscreteVarKey& discreteVar) const;
1190 
1193 SimTK_FORCE_INLINE const DiscreteVarInfo&
1194 getDiscreteVarInfo(const DiscreteVarKey& discreteVar) const;
1195 
1198 SimTK_FORCE_INLINE const PerSubsystemInfo&
1199 getPerSubsystemInfo(SubsystemIndex) const;
1200 
1204 inline void autoUpdateDiscreteVariables();
1205 
1207 inline String toString() const;
1209 inline String cacheToString() const;
1212 //------------------------------------------------------------------------------
1213 // The implementation class and associated inline methods are defined in a
1214 // separate header file included below.
1215  private:
1216 StateImpl* impl;
1217 
1218 const StateImpl& getImpl() const {assert(impl); return *impl;}
1219 StateImpl& updImpl() {assert(impl); return *impl;}
1220 };
1221 
1222 // Dump state and cache to a stream for debugging; this is not serialization.
1223 SimTK_SimTKCOMMON_EXPORT std::ostream&
1224 operator<<(std::ostream& o, const State& s);
1225 
1226 } // namespace SimTK
1227 
1228 // This completes the inline definition of State.
1229 #include "SimTKcommon/internal/StateImpl.h"
1230 
1231 #endif // SimTK_SimTKCOMMON_STATE_H_
SimTK_SimTKCOMMON_EXPORT
#define SimTK_SimTKCOMMON_EXPORT
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:224
SimTK::SimTK_DEFINE_UNIQUE_INDEX_TYPE
SimTK_DEFINE_UNIQUE_INDEX_TYPE(AssemblyConditionIndex)
SimTK::UDotErrIndex
Unique integer type for Subsystem-local uDotErr indexing.
SimTK::SystemEventTriggerIndex
This unique integer type is for identifying a triggered event in the full System-level view of the St...
SimTK::State::allocateCacheEntry
CacheEntryIndex allocateCacheEntry(SubsystemIndex sx, Stage stage, AbstractValue *value) const
This is an abbreviation for allocation of a cache entry whose earliest and latest Stages are the same...
Definition: State.h:705
SimTK::SystemYIndex
This unique integer type is for indexing the global, System-level "y-like" arrays, that is, the arrays in which all of the various Subsystems&#39; continuous state variables q, u, and z have been collected into contiguous memory.
SimTK::Vector_< Real >
SimTK::UIndex
Unique integer type for Subsystem-local u indexing.
SimTK
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
SimTK::UErrIndex
Unique integer type for Subsystem-local uErr indexing.
SimTK::QErrIndex
Unique integer type for Subsystem-local qErr indexing.
SimTK::Stage
This class is basically a glorified enumerated type, type-safe and range checked but permitting conve...
Definition: Stage.h:66
StateImpl.h
This is part of the internal implementation of SimTK::State and does not contain any user-visible obj...
SimTK::Real
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::StageVersion
long long StageVersion
This is the type to use for Stage version numbers that get incremented whenever a state variable chan...
Definition: Stage.h:44
SimTK::SystemMultiplierIndex
This unique integer type is for indexing global "multiplier-like" arrays, that is, arrays that inherently have the same dimension as the total number of Lagrange multipliers in the full System-level view of the State.
SimTK::State
This object is intended to contain all state information for a SimTK::System, except topological info...
Definition: State.h:280
SimTK::ValueVersion
long long ValueVersion
This is the type to use for state variable version numbers that get incremented whenever a state valu...
Definition: Stage.h:52
SimTK::Array_
The Array_<T> container class is a plug-compatible replacement for the C++ standard template library ...
Definition: Array.h:53
SimTK::State::allocateLazyCacheEntry
CacheEntryIndex allocateLazyCacheEntry(SubsystemIndex sx, Stage earliest, AbstractValue *value) const
This is an abbreviation for allocation of a lazy cache entry.
Definition: State.h:718
SimTK::SystemQIndex
This unique integer type is for indexing global "q-like" arrays, that is, arrays that inherently have...
SimTK::SystemQErrIndex
This unique integer type is for indexing global "qErr-like" arrays, that is, arrays that inherently h...
SimTK::ZIndex
Unique integer type for Subsystem-local z indexing.
SimTK::SystemYErrIndex
This unique integer type is for indexing the global, System-level "yErr-like" arrays, that is, the arrays in which all of the various Subsystems&#39; qErr and uErr constraint equation slots have been collected together.
SimTK::SystemUErrIndex
This unique integer type is for indexing global "uErr-like" arrays, that is, arrays that inherently h...
SimTK::QIndex
Unique integer type for Subsystem-local q indexing.
SimTK::DiscreteVarKey
std::pair< SubsystemIndex, DiscreteVariableIndex > DiscreteVarKey
Definition: State.h:165
SimTK::Stage::Infinity
Higher than any legitimate Stage.
Definition: Stage.h:79
SimTK_FORCE_INLINE
#define SimTK_FORCE_INLINE
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:269
SimTK::operator<<
std::ostream & operator<<(std::ostream &o, const ContactForce &f)
Definition: CompliantContactSubsystem.h:387
SimTK::SystemEventTriggerByStageIndex
This unique integer type is for identifying a triggered event within a particular Stage of the full S...
SimTK::String
SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) inten...
Definition: String.h:62
SimTK::AbstractValue
Abstract base class representing an arbitrary value of unknown type.
Definition: Value.h:49
SimTK::SystemUDotErrIndex
This unique integer type is for indexing global "uDotErr-like" arrays, that is, arrays that inherentl...
Event.h
This file declares the types needed for Simbody&#39;s support for Events.
SimTK::DiscreteVariableIndex
This unique integer type is for selecting discrete variables.
SimTK::SystemZIndex
This unique integer type is for indexing global "z-like" arrays, that is, arrays that inherently have...
SimTK::SubsystemIndex
Provide a unique integer type for identifying Subsystems.
SimTK::CacheEntryKey
std::pair< SubsystemIndex, CacheEntryIndex > CacheEntryKey
Definition: State.h:164
SimTK::CacheEntryIndex
This unique integer type is for selecting non-shared cache entries.
Simmatrix.h
This is the header which should be included in user programs that would like to make use of all the S...
SimTK::EventTriggerByStageIndex
Unique integer type for Subsystem-local, per-stage event indexing.
SimTK::SystemUIndex
This unique integer type is for indexing global "u-like" arrays, that is, arrays that inherently have...
basics.h
Includes internal headers providing declarations for the basic SimTK Core classes.