Simbody  3.5
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-14 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 
41 namespace SimTK {
42 
43 
46 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SubsystemIndex);
47 
54 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemYIndex);
55 
63 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemQIndex);
67 SimTK_DEFINE_UNIQUE_INDEX_TYPE(QIndex);
68 
75 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUIndex);
79 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UIndex);
80 
87 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemZIndex);
91 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ZIndex);
92 
97 SimTK_DEFINE_UNIQUE_INDEX_TYPE(DiscreteVariableIndex);
98 
103 SimTK_DEFINE_UNIQUE_INDEX_TYPE(CacheEntryIndex);
104 
110 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemYErrIndex);
111 
117 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemQErrIndex);
121 SimTK_DEFINE_UNIQUE_INDEX_TYPE(QErrIndex);
122 
128 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUErrIndex);
132 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UErrIndex);
133 
139 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUDotErrIndex);
143 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UDotErrIndex);
144 
150 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemMultiplierIndex);
154 SimTK_DEFINE_UNIQUE_INDEX_TYPE(MultiplierIndex);
155 
160 typedef int StageVersion;
161 
162 
276 class SimTK_SimTKCOMMON_EXPORT State {
277 public:
279 State();
280 
287 State(const State&);
288 
295 State& operator=(const State&);
296 
298 ~State();
299 
301 void clear();
302 
306 inline void setNumSubsystems(int i);
307 
310 inline void initializeSubsystem(SubsystemIndex, const String& name,
311  const String& version);
312 
319 inline SubsystemIndex addSubsystem(const String& name, const String& version);
320 
322 inline int getNumSubsystems() const;
323 inline const String& getSubsystemName (SubsystemIndex) const;
324 inline const String& getSubsystemVersion(SubsystemIndex) const;
325 inline const Stage& getSubsystemStage (SubsystemIndex) const;
326 
328 inline const Stage& getSystemStage() const;
329 
336 inline void invalidateAll(Stage);
337 
345 inline void invalidateAllCacheAtOrAbove(Stage) const;
346 
353 inline void advanceSubsystemToStage(SubsystemIndex, Stage) const;
358 inline void advanceSystemToStage(Stage) const;
359 
364 inline StageVersion getSystemTopologyStageVersion() const;
365 
382 inline QIndex allocateQ(SubsystemIndex, const Vector& qInit);
390 inline UIndex allocateU(SubsystemIndex, const Vector& uInit);
396 inline ZIndex allocateZ(SubsystemIndex, const Vector& zInit);
413 inline QErrIndex allocateQErr (SubsystemIndex, int nqerr) const;
416 inline UErrIndex allocateUErr (SubsystemIndex, int nuerr) const;
421 inline UDotErrIndex allocateUDotErr(SubsystemIndex, int nudoterr) const;
440 inline EventTriggerByStageIndex
441 allocateEventTrigger(SubsystemIndex, Stage stage, int nevent) const;
468 inline DiscreteVariableIndex
469 allocateDiscreteVariable(SubsystemIndex, Stage invalidates, AbstractValue*);
470 
521 inline DiscreteVariableIndex
522 allocateAutoUpdateDiscreteVariable(SubsystemIndex, Stage invalidates,
523  AbstractValue*, Stage updateDependsOn);
526 inline CacheEntryIndex
527 getDiscreteVarUpdateIndex(SubsystemIndex, DiscreteVariableIndex) const;
530 inline Stage
531 getDiscreteVarAllocationStage(SubsystemIndex, DiscreteVariableIndex) const;
536 inline Stage
537 getDiscreteVarInvalidatesStage(SubsystemIndex, DiscreteVariableIndex) const;
538 
539 
542 inline const AbstractValue&
543 getDiscreteVariable(SubsystemIndex, DiscreteVariableIndex) const;
545 inline Real
546 getDiscreteVarLastUpdateTime(SubsystemIndex, DiscreteVariableIndex) const;
551 inline const AbstractValue&
552 getDiscreteVarUpdateValue(SubsystemIndex, DiscreteVariableIndex) const;
558 inline AbstractValue&
559 updDiscreteVarUpdateValue(SubsystemIndex, DiscreteVariableIndex) const;
563 inline bool
564 isDiscreteVarUpdateValueRealized(SubsystemIndex, DiscreteVariableIndex) const;
567 inline void
568 markDiscreteVarUpdateValueRealized(SubsystemIndex, DiscreteVariableIndex) const;
569 
573 inline AbstractValue&
574 updDiscreteVariable(SubsystemIndex, DiscreteVariableIndex);
576 inline void
577 setDiscreteVariable
578  (SubsystemIndex, DiscreteVariableIndex, const AbstractValue&);
660 inline CacheEntryIndex
661 allocateCacheEntry(SubsystemIndex, Stage earliest, Stage latest,
662  AbstractValue*) const;
663 
668 inline CacheEntryIndex
669 allocateCacheEntry(SubsystemIndex sx, Stage g, AbstractValue* v) const
670 { return allocateCacheEntry(sx, g, g, v); }
671 
680 inline CacheEntryIndex
681 allocateLazyCacheEntry
682  (SubsystemIndex sx, Stage earliest, AbstractValue* v) const
683 { return allocateCacheEntry(sx, earliest, Stage::Infinity, v); }
684 
687 inline Stage
688 getCacheEntryAllocationStage(SubsystemIndex, CacheEntryIndex) const;
689 
696 inline const AbstractValue&
697 getCacheEntry(SubsystemIndex, CacheEntryIndex) const;
698 
705 inline AbstractValue&
706 updCacheEntry(SubsystemIndex, CacheEntryIndex) const; // mutable
707 
716 inline bool isCacheValueRealized(SubsystemIndex, CacheEntryIndex) const;
717 
730 inline void markCacheValueRealized(SubsystemIndex, CacheEntryIndex) const;
731 
737 inline void markCacheValueNotRealized(SubsystemIndex, CacheEntryIndex) const;
740 
760 inline int getNY() const;
765 inline int getNQ() const;
767 inline SystemYIndex getQStart() const;
771 inline int getNU() const;
773 inline SystemYIndex getUStart() const;
777 inline int getNZ() const;
779 inline SystemYIndex getZStart() const;
783 inline int getNYErr() const;
786 inline int getNQErr() const;
788 inline SystemYErrIndex getQErrStart() const;
792 inline int getNUErr() const;
794 inline SystemYErrIndex getUErrStart() const;
799 inline int getNUDotErr() const;
804 inline int getNMultipliers() const; // =mp+mv+ma, necessarily the same as NUDotErr
807 inline int getNEventTriggers() const;
810 inline int getNEventTriggersByStage(Stage) const;
814 inline SystemEventTriggerIndex getEventTriggerStartByStage(Stage) const;
815 
817 
831 
832 inline SystemQIndex getQStart(SubsystemIndex) const;
833 inline int getNQ(SubsystemIndex) const;
834 inline SystemUIndex getUStart(SubsystemIndex) const;
835 inline int getNU(SubsystemIndex) const;
836 inline SystemZIndex getZStart(SubsystemIndex) const;
837 inline int getNZ(SubsystemIndex) const;
838 
839 inline SystemQErrIndex getQErrStart(SubsystemIndex) const;
840 inline int getNQErr(SubsystemIndex) const;
841 inline SystemUErrIndex getUErrStart(SubsystemIndex) const;
842 inline int getNUErr(SubsystemIndex) const;
843 inline SystemUDotErrIndex getUDotErrStart(SubsystemIndex) const;
844 inline int getNUDotErr(SubsystemIndex) const;
845 inline SystemMultiplierIndex getMultipliersStart(SubsystemIndex) const;
846 inline int getNMultipliers(SubsystemIndex) const;
847 
848 inline SystemEventTriggerByStageIndex
849  getEventTriggerStartByStage(SubsystemIndex, Stage) const;
850 inline int getNEventTriggersByStage(SubsystemIndex, Stage) const;
851 
853 
854 inline const Vector& getEventTriggers() const;
855 inline const Vector& getEventTriggersByStage(Stage) const;
856 inline const Vector& getEventTriggersByStage(SubsystemIndex, Stage) const;
857 
858 inline Vector& updEventTriggers() const; // mutable
859 inline Vector& updEventTriggersByStage(Stage) const;
860 inline Vector& updEventTriggersByStage(SubsystemIndex, Stage) const;
861 
863 inline const Vector& getQ(SubsystemIndex) const;
864 inline const Vector& getU(SubsystemIndex) const;
865 inline const Vector& getZ(SubsystemIndex) const;
866 
867 inline const Vector& getUWeights(SubsystemIndex) const;
868 inline const Vector& getZWeights(SubsystemIndex) const;
869 
870 inline Vector& updQ(SubsystemIndex);
871 inline Vector& updU(SubsystemIndex);
872 inline Vector& updZ(SubsystemIndex);
873 
874 inline Vector& updUWeights(SubsystemIndex);
875 inline Vector& updZWeights(SubsystemIndex);
876 
878 inline const Vector& getQDot(SubsystemIndex) const;
879 inline const Vector& getUDot(SubsystemIndex) const;
880 inline const Vector& getZDot(SubsystemIndex) const;
881 inline const Vector& getQDotDot(SubsystemIndex) const;
882 
883 inline Vector& updQDot(SubsystemIndex) const; // these are mutable
884 inline Vector& updUDot(SubsystemIndex) const;
885 inline Vector& updZDot(SubsystemIndex) const;
886 inline Vector& updQDotDot(SubsystemIndex) const;
887 
888 inline const Vector& getQErr(SubsystemIndex) const;
889 inline const Vector& getUErr(SubsystemIndex) const;
890 inline const Vector& getUDotErr(SubsystemIndex) const;
891 inline const Vector& getMultipliers(SubsystemIndex) const;
892 
893 inline const Vector& getQErrWeights(SubsystemIndex) const;
894 inline const Vector& getUErrWeights(SubsystemIndex) const;
895 
896 inline Vector& updQErr(SubsystemIndex) const; // these are mutable
897 inline Vector& updUErr(SubsystemIndex) const;
898 inline Vector& updUDotErr(SubsystemIndex) const;
899 inline Vector& updMultipliers(SubsystemIndex) const;
900 
901 inline Vector& updQErrWeights(SubsystemIndex);
902 inline Vector& updUErrWeights(SubsystemIndex);
903 
905 inline const Real& getTime() const;
906 inline const Vector& getY() const; // {Q,U,Z} packed and in that order
907 
909 inline const Vector& getQ() const;
910 inline const Vector& getU() const;
911 inline const Vector& getZ() const;
912 
913 
948 inline const Vector& getUWeights() const; // diag(Wu)
949 
956 inline const Vector& getZWeights() const;
957 
961 inline Vector& updUWeights();
962 
966 inline Vector& updZWeights();
967 
970 inline Real& updTime(); // Back up to Stage::Time-1
971 inline Vector& updY(); // Back up to Stage::Dynamics-1
972 
974 inline void setTime(Real t);
975 inline void setY(const Vector& y);
976 
978 inline Vector& updQ(); // Back up to Stage::Position-1
979 inline Vector& updU(); // Back up to Stage::Velocity-1
980 inline Vector& updZ(); // Back up to Stage::Dynamics-1
981 
983 inline void setQ(const Vector& q);
984 inline void setU(const Vector& u);
985 inline void setZ(const Vector& z);
986 
987 inline const Vector& getYDot() const; // Stage::Acceleration
988 
990 inline const Vector& getQDot() const; // Stage::Velocity
991 inline const Vector& getZDot() const; // Stage::Dynamics
992 inline const Vector& getUDot() const; // Stage::Acceleration
993 
995 inline const Vector& getQDotDot() const; // Stage::Acceleration
996 
998 inline Vector& updYDot() const; // Stage::Acceleration-1
999 inline Vector& updQDot() const; // Stage::Velocity-1 (view into YDot)
1000 inline Vector& updZDot() const; // Stage::Dynamics-1 "
1001 inline Vector& updUDot() const; // Stage::Acceleration-1 "
1002 
1006 inline Vector& updQDotDot() const; // Stage::Acceleration-1
1007 
1010 inline const Vector& getYErr() const; // Stage::Velocity
1011 
1013 inline const Vector& getQErr() const; // Stage::Position (index 3 constraints)
1014 inline const Vector& getUErr() const; // Stage::Velocity (index 2 constraints)
1015 
1017 inline const Vector& getUDotErr() const; // Stage::Acceleration (index 1 constraints)
1018 inline const Vector& getMultipliers() const; // Stage::Acceleration
1019 
1022 inline const Vector& getQErrWeights() const;
1023 
1034 inline const Vector& getUErrWeights() const;
1035 
1040 inline Vector& updQErrWeights();
1041 
1046 inline Vector& updUErrWeights();
1047 
1049 inline Vector& updYErr() const; // Stage::Velocity-1
1050 inline Vector& updQErr() const; // Stage::Position-1 (view into YErr)
1051 inline Vector& updUErr() const; // Stage::Velocity-1 "
1052 
1053 inline Vector& updUDotErr() const; // Stage::Acceleration-1 (not a view)
1054 inline Vector& updMultipliers() const; // Stage::Acceleration-1 (not a view)
1055 
1063 inline void getSystemStageVersions(Array_<StageVersion>& versions) const;
1064 
1074 inline Stage getLowestSystemStageDifference
1075  (const Array_<StageVersion>& prevVersions) const;
1076 
1083 inline void setSystemTopologyStageVersion(StageVersion topoVersion);
1084 
1088 inline void autoUpdateDiscreteVariables();
1089 
1090 inline String toString() const;
1091 inline String cacheToString() const;
1092 
1093 //------------------------------------------------------------------------------
1094 // The implementation class and associated inline methods are defined in a
1095 // separate header file included below.
1096  private:
1097 class StateImpl* impl;
1098 const StateImpl& getImpl() const {assert(impl); return *impl;}
1099 StateImpl& updImpl() {assert(impl); return *impl;}
1100 };
1101 
1102 // Dump state and cache to a stream for debugging; this is not serialization.
1103 SimTK_SimTKCOMMON_EXPORT std::ostream&
1104 operator<<(std::ostream& o, const State& s);
1105 
1106 } // namespace SimTK
1107 
1108 // This completes the inline definition of State.
1109 #include "SimTKcommon/internal/StateImpl.h"
1110 
1111 #endif // SimTK_SimTKCOMMON_STATE_H_
SimTK_SimTKCOMMON_EXPORT
#define SimTK_SimTKCOMMON_EXPORT
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:218
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::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::State::allocateCacheEntry
CacheEntryIndex allocateCacheEntry(SubsystemIndex sx, Stage g, AbstractValue *v) const
This is an abbreviation for allocation of a cache entry whose earliest and latest Stages are the same...
Definition: State.h:669
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:50
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:593
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:276
SimTK::Array_
The SimTK::Array_<T> container class is a plug-compatible replacement for the C++ standard template l...
Definition: Array.h:50
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::Stage::Infinity
Higher than any legitimate Stage.
Definition: Stage.h:63
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 self-describing type.
Definition: Value.h:41
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::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.
SimTK::StageVersion
int StageVersion
This is the type to use for Stage version numbers.
Definition: State.h:160