Simbody  3.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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-12 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 
27 #include "SimTKcommon/basics.h"
28 #include "SimTKcommon/Simmatrix.h"
29 #include "SimTKcommon/internal/Event.h"
30 
31 #include <ostream>
32 #include <cassert>
33 #include <set>
34 
35 namespace SimTK {
36 
37 
40 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SubsystemIndex);
41 
48 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemYIndex);
49 
57 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemQIndex);
61 SimTK_DEFINE_UNIQUE_INDEX_TYPE(QIndex);
62 
69 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUIndex);
73 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UIndex);
74 
81 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemZIndex);
85 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ZIndex);
86 
91 SimTK_DEFINE_UNIQUE_INDEX_TYPE(DiscreteVariableIndex);
92 
97 SimTK_DEFINE_UNIQUE_INDEX_TYPE(CacheEntryIndex);
98 
104 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemYErrIndex);
105 
111 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemQErrIndex);
115 SimTK_DEFINE_UNIQUE_INDEX_TYPE(QErrIndex);
116 
122 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUErrIndex);
126 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UErrIndex);
127 
133 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUDotErrIndex);
137 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UDotErrIndex);
138 
144 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemMultiplierIndex);
148 SimTK_DEFINE_UNIQUE_INDEX_TYPE(MultiplierIndex);
149 
154 typedef int StageVersion;
155 
156 
264 class SimTK_SimTKCOMMON_EXPORT State {
265 public:
267 State();
268 ~State();
269 
271 void clear();
272 
276 void setNumSubsystems(int i);
277 
280 void initializeSubsystem(SubsystemIndex, const String& name,
281  const String& version);
282 
287 State(const State&);
288 
293 State& operator=(const State&);
294 
301 SubsystemIndex addSubsystem(const String& name, const String& version);
302 
303 int getNumSubsystems() const;
304 const String& getSubsystemName (SubsystemIndex) const;
305 const String& getSubsystemVersion(SubsystemIndex) const;
306 const Stage& getSubsystemStage (SubsystemIndex) const;
307 
309 const Stage& getSystemStage() const;
310 
317 void invalidateAll(Stage);
318 
326 void invalidateAllCacheAtOrAbove(Stage) const;
327 
334 void advanceSubsystemToStage(SubsystemIndex, Stage) const;
339 void advanceSystemToStage(Stage) const;
340 
345 StageVersion getSystemTopologyStageVersion() const;
346 
363 QIndex allocateQ(SubsystemIndex, const Vector& qInit);
371 UIndex allocateU(SubsystemIndex, const Vector& uInit);
377 ZIndex allocateZ(SubsystemIndex, const Vector& zInit);
394 QErrIndex allocateQErr (SubsystemIndex, int nqerr) const;
397 UErrIndex allocateUErr (SubsystemIndex, int nuerr) const;
402 UDotErrIndex allocateUDotErr(SubsystemIndex, int nudoterr) const;
421 EventTriggerByStageIndex
422 allocateEventTrigger(SubsystemIndex, Stage stage, int nevent) const;
448 DiscreteVariableIndex
449 allocateDiscreteVariable(SubsystemIndex, Stage invalidates, AbstractValue*);
450 
502 DiscreteVariableIndex
503 allocateAutoUpdateDiscreteVariable(SubsystemIndex, Stage invalidates,
504  AbstractValue*, Stage updateDependsOn);
507 CacheEntryIndex
508 getDiscreteVarUpdateIndex(SubsystemIndex, DiscreteVariableIndex) const;
510 Stage getDiscreteVarAllocationStage(SubsystemIndex, DiscreteVariableIndex) const;
515 Stage getDiscreteVarInvalidatesStage(SubsystemIndex, DiscreteVariableIndex) const;
516 
517 
520 const AbstractValue&
521 getDiscreteVariable(SubsystemIndex, DiscreteVariableIndex) const;
523 Real getDiscreteVarLastUpdateTime(SubsystemIndex, DiscreteVariableIndex) const;
528 const AbstractValue&
529 getDiscreteVarUpdateValue(SubsystemIndex, DiscreteVariableIndex) const;
535 AbstractValue&
536 updDiscreteVarUpdateValue(SubsystemIndex, DiscreteVariableIndex) const;
540 bool isDiscreteVarUpdateValueRealized(SubsystemIndex, DiscreteVariableIndex) const;
543 void markDiscreteVarUpdateValueRealized(SubsystemIndex, DiscreteVariableIndex) const;
544 
548 AbstractValue& updDiscreteVariable(SubsystemIndex, DiscreteVariableIndex);
550 void setDiscreteVariable(SubsystemIndex, DiscreteVariableIndex,
551  const AbstractValue&);
633 CacheEntryIndex allocateCacheEntry(SubsystemIndex, Stage earliest, Stage latest,
634  AbstractValue*) const;
635 
640 CacheEntryIndex allocateCacheEntry(SubsystemIndex sx, Stage g, AbstractValue* v) const
641 { return allocateCacheEntry(sx, g, g, v); }
642 
651 CacheEntryIndex allocateLazyCacheEntry(SubsystemIndex sx, Stage earliest, AbstractValue* v) const
652 { return allocateCacheEntry(sx, earliest, Stage::Infinity, v); }
653 
656 Stage getCacheEntryAllocationStage(SubsystemIndex, CacheEntryIndex) const;
657 
664 const AbstractValue& getCacheEntry(SubsystemIndex, CacheEntryIndex) const;
665 
672 AbstractValue& updCacheEntry(SubsystemIndex, CacheEntryIndex) const; // mutable
673 
682 bool isCacheValueRealized(SubsystemIndex, CacheEntryIndex) const;
683 
696 void markCacheValueRealized(SubsystemIndex, CacheEntryIndex) const;
697 
703 void markCacheValueNotRealized(SubsystemIndex, CacheEntryIndex) const;
706 
726 int getNY() const;
731 int getNQ() const;
733 SystemYIndex getQStart() const;
737 int getNU() const;
739 SystemYIndex getUStart() const;
743 int getNZ() const;
745 SystemYIndex getZStart() const;
749 int getNYErr() const;
752 int getNQErr() const;
754 SystemYErrIndex getQErrStart() const;
758 int getNUErr() const;
760 SystemYErrIndex getUErrStart() const;
765 int getNUDotErr() const;
770 int getNMultipliers() const; // =mp+mv+ma, necessarily the same as NUDotErr
773 int getNEventTriggers() const;
776 int getNEventTriggersByStage(Stage) const;
780 SystemEventTriggerIndex getEventTriggerStartByStage(Stage) const; // per-stage
781 
783 
797 
798 SystemQIndex getQStart(SubsystemIndex) const;
799 int getNQ(SubsystemIndex) const;
800 SystemUIndex getUStart(SubsystemIndex) const;
801 int getNU(SubsystemIndex) const;
802 SystemZIndex getZStart(SubsystemIndex) const;
803 int getNZ(SubsystemIndex) const;
804 
805 
806 SystemQErrIndex getQErrStart(SubsystemIndex) const;
807 int getNQErr(SubsystemIndex) const;
808 SystemUErrIndex getUErrStart(SubsystemIndex) const;
809 int getNUErr(SubsystemIndex) const;
810 SystemUDotErrIndex getUDotErrStart(SubsystemIndex) const;
811 int getNUDotErr(SubsystemIndex) const;
812 SystemMultiplierIndex getMultipliersStart(SubsystemIndex) const;
813 int getNMultipliers(SubsystemIndex) const;
814 
815 SystemEventTriggerByStageIndex
816  getEventTriggerStartByStage(SubsystemIndex, Stage) const;
817 int getNEventTriggersByStage(SubsystemIndex, Stage) const;
818 
820 
833 
836 void mapQToSubsystem(SystemQIndex, SubsystemIndex&, QIndex&) const;
839 void mapUToSubsystem(SystemUIndex, SubsystemIndex&, UIndex&) const;
842 void mapZToSubsystem(SystemZIndex, SubsystemIndex&, ZIndex&) const;
845 void mapQErrToSubsystem(SystemQErrIndex, SubsystemIndex&, QErrIndex&) const;
848 void mapUErrToSubsystem(SystemUErrIndex, SubsystemIndex&, UErrIndex&) const;
851 void mapUDotErrToSubsystem(SystemUDotErrIndex, SubsystemIndex&, UDotErrIndex&) const;
855 void mapMultiplierToSubsystem(SystemMultiplierIndex, SubsystemIndex&, MultiplierIndex&) const;
858 //void mapEventTriggerToSubsystem(SystemEventTriggerIndex, SubsystemIndex&, EventTriggerIndex&) const;
861 void mapEventTriggerToStage(SystemEventTriggerIndex, Stage&, SystemEventTriggerByStageIndex&) const;
864 //void mapSubsystemEventTriggerToStage(EventTriggerIndex, Stage&, EventTriggerByStageIndex&) const;
865 
867 
868 const Vector& getEventTriggers() const;
869 const Vector& getEventTriggersByStage(Stage) const;
870 const Vector& getEventTriggersByStage(SubsystemIndex, Stage) const;
871 
872 Vector& updEventTriggers() const; // mutable
873 Vector& updEventTriggersByStage(Stage) const;
874 Vector& updEventTriggersByStage(SubsystemIndex, Stage) const;
875 
877 const Vector& getQ(SubsystemIndex) const;
878 const Vector& getU(SubsystemIndex) const;
879 const Vector& getZ(SubsystemIndex) const;
880 
881 const Vector& getUWeights(SubsystemIndex) const;
882 const Vector& getZWeights(SubsystemIndex) const;
883 
884 Vector& updQ(SubsystemIndex);
885 Vector& updU(SubsystemIndex);
886 Vector& updZ(SubsystemIndex);
887 
888 Vector& updUWeights(SubsystemIndex);
889 Vector& updZWeights(SubsystemIndex);
890 
892 const Vector& getQDot(SubsystemIndex) const;
893 const Vector& getUDot(SubsystemIndex) const;
894 const Vector& getZDot(SubsystemIndex) const;
895 const Vector& getQDotDot(SubsystemIndex) const;
896 
897 Vector& updQDot(SubsystemIndex) const; // these are mutable
898 Vector& updUDot(SubsystemIndex) const;
899 Vector& updZDot(SubsystemIndex) const;
900 Vector& updQDotDot(SubsystemIndex) const;
901 
902 const Vector& getQErr(SubsystemIndex) const;
903 const Vector& getUErr(SubsystemIndex) const;
904 const Vector& getUDotErr(SubsystemIndex) const;
905 const Vector& getMultipliers(SubsystemIndex) const;
906 
907 const Vector& getQErrWeights(SubsystemIndex) const;
908 const Vector& getUErrWeights(SubsystemIndex) const;
909 
910 Vector& updQErr(SubsystemIndex) const; // these are mutable
911 Vector& updUErr(SubsystemIndex) const;
912 Vector& updUDotErr(SubsystemIndex) const;
913 Vector& updMultipliers(SubsystemIndex) const;
914 
915 Vector& updQErrWeights(SubsystemIndex);
916 Vector& updUErrWeights(SubsystemIndex);
917 
919 const Real& getTime() const;
920 const Vector& getY() const; // {Q,U,Z} packed and in that order
921 
923 const Vector& getQ() const;
924 const Vector& getU() const;
925 const Vector& getZ() const;
926 
927 
962 const Vector& getUWeights() const; // diag(Wu)
963 
970 const Vector& getZWeights() const;
971 
975 Vector& updUWeights();
976 
980 Vector& updZWeights();
981 
984 Real& updTime(); // Back up to Stage::Time-1
985 Vector& updY(); // Back up to Stage::Dynamics-1
986 
988 void setTime(Real t);
989 void setY(const Vector& y);
990 
992 Vector& updQ(); // Back up to Stage::Position-1
993 Vector& updU(); // Back up to Stage::Velocity-1
994 Vector& updZ(); // Back up to Stage::Dynamics-1
995 
997 void setQ(const Vector& q);
998 void setU(const Vector& u);
999 void setZ(const Vector& z);
1000 
1001 const Vector& getYDot() const; // Stage::Acceleration
1002 
1004 const Vector& getQDot() const; // Stage::Velocity
1005 const Vector& getZDot() const; // Stage::Dynamics
1006 const Vector& getUDot() const; // Stage::Acceleration
1007 
1009 const Vector& getQDotDot() const; // Stage::Acceleration
1010 
1012 Vector& updYDot() const; // Stage::Acceleration-1
1013 Vector& updQDot() const; // Stage::Velocity-1 (view into YDot)
1014 Vector& updZDot() const; // Stage::Dynamics-1 "
1015 Vector& updUDot() const; // Stage::Acceleration-1 "
1016 
1020 Vector& updQDotDot() const; // Stage::Acceleration-1
1021 
1024 const Vector& getYErr() const; // Stage::Velocity
1025 
1027 const Vector& getQErr() const; // Stage::Position (index 3 constraints)
1028 const Vector& getUErr() const; // Stage::Velocity (index 2 constraints)
1029 
1031 const Vector& getUDotErr() const; // Stage::Acceleration (index 1 constraints)
1032 const Vector& getMultipliers() const; // Stage::Acceleration
1033 
1036 const Vector& getQErrWeights() const;
1037 
1048 const Vector& getUErrWeights() const;
1049 
1054 Vector& updQErrWeights();
1055 
1060 Vector& updUErrWeights();
1061 
1063 Vector& updYErr() const; // Stage::Velocity-1
1064 Vector& updQErr() const; // Stage::Position-1 (view into YErr)
1065 Vector& updUErr() const; // Stage::Velocity-1 "
1066 
1067 Vector& updUDotErr() const; // Stage::Acceleration-1 (not a view)
1068 Vector& updMultipliers() const; // Stage::Acceleration-1 (not a view)
1069 
1077 void getSystemStageVersions(Array_<StageVersion>& versions) const;
1078 
1088 Stage getLowestSystemStageDifference
1089  (const Array_<StageVersion>& prevVersions) const;
1090 
1097 void setSystemTopologyStageVersion(StageVersion topoVersion);
1098 
1102 void autoUpdateDiscreteVariables();
1103 
1104 String toString() const;
1105 String cacheToString() const;
1106 
1107 //------------------------------------------------------------------------------
1108  private:
1109 class StateImpl* impl;
1110 const StateImpl& getImpl() const {assert(impl); return *impl;}
1111 StateImpl& updImpl() {assert(impl); return *impl;}
1112 };
1113 
1114 SimTK_SimTKCOMMON_EXPORT std::ostream&
1115 operator<<(std::ostream& o, const State& s);
1116 
1117 } // namespace SimTK
1118 
1119 #endif // SimTK_SimTKCOMMON_STATE_H_
SimTK_SimTKCOMMON_EXPORT
#define SimTK_SimTKCOMMON_EXPORT
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:202
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' 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::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:640
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
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 is the handle class for the hidden State implementation.
Definition: State.h:264
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::State::allocateLazyCacheEntry
CacheEntryIndex allocateLazyCacheEntry(SubsystemIndex sx, Stage earliest, AbstractValue *v) const
This is an abbreviation for allocation of a lazy cache entry.
Definition: State.h:651
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' 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'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...
SimTK::MultiplierIndex
Unique integer type for Subsystem-local multiplier indexing.
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:154