State.h

Go to the documentation of this file.
00001 #ifndef SimTK_SimTKCOMMON_STATE_H_
00002 #define SimTK_SimTKCOMMON_STATE_H_
00003 
00004 /* -------------------------------------------------------------------------- *
00005  *                      SimTK Core: SimTKcommon                               *
00006  * -------------------------------------------------------------------------- *
00007  * This is part of the SimTK Core biosimulation toolkit originating from      *
00008  * Simbios, the NIH National Center for Physics-Based Simulation of           *
00009  * Biological Structures at Stanford, funded under the NIH Roadmap for        *
00010  * Medical Research, grant U54 GM072970. See https://simtk.org.               *
00011  *                                                                            *
00012  * Portions copyright (c) 2005-10 Stanford University and the Authors.        *
00013  * Authors: Michael Sherman                                                   *
00014  * Contributors: Peter Eastman                                                *
00015  *                                                                            *
00016  * Permission is hereby granted, free of charge, to any person obtaining a    *
00017  * copy of this software and associated documentation files (the "Software"), *
00018  * to deal in the Software without restriction, including without limitation  *
00019  * the rights to use, copy, modify, merge, publish, distribute, sublicense,   *
00020  * and/or sell copies of the Software, and to permit persons to whom the      *
00021  * Software is furnished to do so, subject to the following conditions:       *
00022  *                                                                            *
00023  * The above copyright notice and this permission notice shall be included in *
00024  * all copies or substantial portions of the Software.                        *
00025  *                                                                            *
00026  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
00027  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,   *
00028  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL    *
00029  * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,    *
00030  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR      *
00031  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE  *
00032  * USE OR OTHER DEALINGS IN THE SOFTWARE.                                     *
00033  * -------------------------------------------------------------------------- */
00034 
00035 #include "SimTKcommon/basics.h"
00036 #include "SimTKcommon/Simmatrix.h"
00037 #include "SimTKcommon/internal/Event.h"
00038 
00039 #include <ostream>
00040 #include <cassert>
00041 #include <set>
00042 
00043 namespace SimTK {
00044 
00045 
00047 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SubsystemIndex);
00048 
00054 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemYIndex);
00055 
00062 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemQIndex);
00065 SimTK_DEFINE_UNIQUE_INDEX_TYPE(QIndex);
00066 
00072 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUIndex);
00075 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UIndex);
00076 
00082 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemZIndex);
00085 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ZIndex);
00086 
00090 SimTK_DEFINE_UNIQUE_INDEX_TYPE(DiscreteVariableIndex);
00091 
00095 SimTK_DEFINE_UNIQUE_INDEX_TYPE(CacheEntryIndex);
00096 
00101 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemYErrIndex);
00102 
00107 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemQErrIndex);
00110 SimTK_DEFINE_UNIQUE_INDEX_TYPE(QErrIndex);
00111 
00116 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUErrIndex);
00119 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UErrIndex);
00120 
00125 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemUDotErrIndex);
00128 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UDotErrIndex);
00129 
00134 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemMultiplierIndex);
00137 SimTK_DEFINE_UNIQUE_INDEX_TYPE(MultiplierIndex);
00138 
00143 typedef int StageVersion;
00144 
00145 
00259 class SimTK_SimTKCOMMON_EXPORT State {
00260 public:
00262     State();
00263     ~State();
00264 
00266     void clear();
00267 
00271     void setNSubsystems(int i);
00272 
00275     void initializeSubsystem(SubsystemIndex, const String& name, const String& version);
00276 
00281     State(const State&);
00282 
00287     State& operator=(const State&);
00288 
00295     SubsystemIndex addSubsystem(const String& name, const String& version);
00296 
00297     int getNSubsystems() const;
00298     const String& getSubsystemName   (SubsystemIndex) const;
00299     const String& getSubsystemVersion(SubsystemIndex) const;
00300     const Stage&  getSubsystemStage  (SubsystemIndex) const;
00301 
00303     const Stage& getSystemStage() const;
00304 
00308     void invalidateAll(Stage) const;  // cache is mutable
00309 
00316     void advanceSubsystemToStage(SubsystemIndex, Stage) const;
00321     void advanceSystemToStage(Stage) const;
00322 
00331 
00332     QIndex allocateQ(SubsystemIndex, const Vector& qInit); // qdot, qdotdot also allocated in cache
00333     UIndex allocateU(SubsystemIndex, const Vector& uInit); // udot                    "
00334     ZIndex allocateZ(SubsystemIndex, const Vector& zInit); // zdot                    "
00335 
00346 
00347     QErrIndex    allocateQErr   (SubsystemIndex, int nqerr) const;    // these are cache entries
00348     UErrIndex    allocateUErr   (SubsystemIndex, int nuerr) const;
00349     UDotErrIndex allocateUDotErr(SubsystemIndex, int nudoterr) const;
00350 
00360     EventIndex allocateEventIndex(SubsystemIndex, int nevent=1) const;
00361 
00373     EventTriggerByStageIndex allocateEventTrigger(SubsystemIndex, Stage, EventIndex, int nevent=1) const;
00374 
00375     //OBSOLETE
00376     EventTriggerByStageIndex allocateEventTrigger(SubsystemIndex, Stage, int nevent) const;
00377 
00397     DiscreteVariableIndex allocateDiscreteVariable(SubsystemIndex, Stage invalidates, AbstractValue*);
00398 
00399 
00432     std::pair<DiscreteVariableIndex, CacheEntryIndex>
00433         allocateUpdatingDiscreteVariable(SubsystemIndex, Stage invalidates, AbstractValue*,
00434                                          Stage earliestUpdate); 
00435 
00437     const AbstractValue& getDiscreteVariable         (SubsystemIndex, DiscreteVariableIndex) const;
00438     Real                 getDiscreteVarLastUpdateTime(SubsystemIndex, DiscreteVariableIndex) const;
00439     CacheEntryIndex      getDiscreteVarUpdateEntry   (SubsystemIndex, DiscreteVariableIndex) const;
00440     const AbstractValue& getDiscreteVarPrevValue     (SubsystemIndex, DiscreteVariableIndex) const;
00441 
00443     AbstractValue&       updDiscreteVariable(SubsystemIndex, DiscreteVariableIndex);
00444 
00446     void setDiscreteVariable(SubsystemIndex, DiscreteVariableIndex, const AbstractValue&);
00447 
00525     CacheEntryIndex allocateCacheEntry(SubsystemIndex, Stage earliest, Stage latest,
00526                                        AbstractValue*) const;
00527 
00532     CacheEntryIndex allocateCacheEntry(SubsystemIndex sx, Stage g, AbstractValue* v) const
00533     {   return allocateCacheEntry(sx, g, g, v); }
00534 
00535 
00542     const AbstractValue& getCacheEntry(SubsystemIndex, CacheEntryIndex) const;
00543 
00550     AbstractValue& updCacheEntry(SubsystemIndex, CacheEntryIndex) const; // mutable
00551 
00560     bool isCacheValueRealized(SubsystemIndex sx, CacheEntryIndex cx) const
00561     {   return isCacheValueCurrent(sx,cx); } // the old "Current" name is obsolete; don't use it
00562 
00575     void markCacheValueRealized(SubsystemIndex, CacheEntryIndex) const;
00576     
00593 
00597     int getNY() const;
00602     int getNQ() const;
00604     SystemYIndex getQStart() const;
00608     int getNU() const;
00610     SystemYIndex getUStart() const;
00614     int getNZ() const;
00616     SystemYIndex getZStart() const;
00620     int getNYErr() const;
00623     int getNQErr() const;
00625     SystemYErrIndex getQErrStart() const; 
00629     int getNUErr() const;
00631     SystemYErrIndex getUErrStart() const; 
00636     int getNUDotErr() const;
00641     int getNMultipliers() const; // =mp+mv+ma, necessarily the same as NUDotErr
00644     int getNEventTriggers() const;
00647     int getNEventTriggersByStage(Stage) const;
00651     SystemEventTriggerIndex getEventTriggerStartByStage(Stage) const; // per-stage
00652 
00654 
00668 
00669     SystemQIndex getQStart(SubsystemIndex)       const; int getNQ(SubsystemIndex)       const;
00670     SystemUIndex getUStart(SubsystemIndex)       const; int getNU(SubsystemIndex)       const;
00671     SystemZIndex getZStart(SubsystemIndex)       const; int getNZ(SubsystemIndex)       const;
00672 
00673     SystemQErrIndex       getQErrStart(SubsystemIndex)    const; int getNQErr(SubsystemIndex)    const;
00674     SystemUErrIndex       getUErrStart(SubsystemIndex)    const; int getNUErr(SubsystemIndex)    const;
00675     SystemUDotErrIndex    getUDotErrStart(SubsystemIndex) const; int getNUDotErr(SubsystemIndex) const;
00676     SystemMultiplierIndex getMultipliersStart(SubsystemIndex) const;
00677     int getNMultipliers(SubsystemIndex)     const;
00678 
00679     SystemEventTriggerByStageIndex getEventTriggerStartByStage(SubsystemIndex, Stage) const;
00680     int getNEventTriggersByStage(SubsystemIndex, Stage) const;
00681 
00683 
00694 
00697     void mapQToSubsystem(SystemQIndex, SubsystemIndex&, QIndex&) const;
00700     void mapUToSubsystem(SystemUIndex, SubsystemIndex&, UIndex&) const;
00703     void mapZToSubsystem(SystemZIndex, SubsystemIndex&, ZIndex&) const;
00706     void mapQErrToSubsystem(SystemQErrIndex, SubsystemIndex&, QErrIndex&) const;
00709     void mapUErrToSubsystem(SystemUErrIndex, SubsystemIndex&, UErrIndex&) const;
00712     void mapUDotErrToSubsystem(SystemUDotErrIndex, SubsystemIndex&, UDotErrIndex&) const;
00716     void mapMultiplierToSubsystem(SystemMultiplierIndex, SubsystemIndex&, MultiplierIndex&) const;
00719     void mapEventTriggerToSubsystem(SystemEventTriggerIndex, SubsystemIndex&, EventTriggerIndex&) const;
00722     void mapEventTriggerToStage(SystemEventTriggerIndex, Stage&, SystemEventTriggerByStageIndex&) const;
00725     void mapSubsystemEventTriggerToStage(EventTriggerIndex, Stage&, EventTriggerByStageIndex&) const;
00726 
00728 
00729     const Vector& getEventTriggers() const;
00730     const Vector& getEventTriggersByStage(Stage) const;
00731     const Vector& getEventTriggersByStage(SubsystemIndex, Stage) const;
00732 
00733     Vector& updEventTriggers() const; // mutable
00734     Vector& updEventTriggersByStage(Stage) const;
00735     Vector& updEventTriggersByStage(SubsystemIndex, Stage) const;
00736 
00738     const Vector& getQ(SubsystemIndex) const;
00739     const Vector& getU(SubsystemIndex) const;
00740     const Vector& getZ(SubsystemIndex) const;
00741 
00742     Vector& updQ(SubsystemIndex);
00743     Vector& updU(SubsystemIndex);
00744     Vector& updZ(SubsystemIndex);
00745 
00747     const Vector& getQDot(SubsystemIndex) const;
00748     const Vector& getUDot(SubsystemIndex) const;
00749     const Vector& getZDot(SubsystemIndex) const;
00750     const Vector& getQDotDot(SubsystemIndex) const;
00751 
00752     Vector& updQDot(SubsystemIndex) const;    // these are mutable
00753     Vector& updUDot(SubsystemIndex) const;
00754     Vector& updZDot(SubsystemIndex) const;
00755     Vector& updQDotDot(SubsystemIndex) const;
00756 
00757     const Vector& getQErr(SubsystemIndex) const;
00758     const Vector& getUErr(SubsystemIndex) const;
00759     const Vector& getUDotErr(SubsystemIndex) const;
00760     const Vector& getMultipliers(SubsystemIndex) const;
00761     Vector& updQErr(SubsystemIndex) const;    // these are mutable
00762     Vector& updUErr(SubsystemIndex) const;
00763     Vector& updUDotErr(SubsystemIndex) const;
00764     Vector& updMultipliers(SubsystemIndex) const;
00765 
00767     const Real&   getTime() const;
00768     const Vector& getY() const; // {Q,U,Z} packed and in that order
00769 
00771     const Vector& getQ() const;
00772     const Vector& getU() const;
00773     const Vector& getZ() const;
00774 
00777     Real&   updTime();  // Back up to Stage::Time-1
00778     Vector& updY();     // Back up to Stage::Congfigured-1
00779 
00781     void setTime(Real t);
00782     void setY(const Vector& y);
00783 
00785     Vector& updQ();     // Back up to Stage::Position-1
00786     Vector& updU();     // Back up to Stage::Velocity-1
00787     Vector& updZ();     // Back up to Stage::Dynamics-1
00788 
00790     void setQ(const Vector& q);
00791     void setU(const Vector& u);
00792     void setZ(const Vector& z);
00793 
00794     const Vector& getYDot()    const; // Stage::Acceleration
00795 
00797     const Vector& getQDot()    const; // Stage::Velocity
00798     const Vector& getZDot()    const; // Stage::Dynamics
00799     const Vector& getUDot()    const; // Stage::Acceleration
00800 
00802     const Vector& getQDotDot() const; // Stage::Acceleration
00803 
00805     Vector& updYDot() const;    // Stage::Acceleration-1
00806     Vector& updQDot() const;    // Stage::Velocity-1     (view into YDot)
00807     Vector& updZDot() const;    // Stage::Dynamics-1            "
00808     Vector& updUDot() const;    // Stage::Acceleration-1        "
00809 
00813     Vector& updQDotDot() const; // Stage::Acceleration-1
00814 
00816     const Vector& getYErr() const; // {QErr,UErr} packed and in that order
00817 
00819     const Vector& getQErr() const;  // Stage::Position (index 3 constraints)
00820     const Vector& getUErr() const;  // Stage::Velocity (index 2 constraints)
00821 
00823     const Vector& getUDotErr()     const; // Stage::Acceleration (index 1 constraints)
00824     const Vector& getMultipliers() const; // Stage::Acceleration
00825 
00827     Vector& updYErr() const; // Stage::Dynamics-1
00828     Vector& updQErr() const; // Stage::Position-1 (view into YErr)
00829     Vector& updUErr() const; // Stage::Velocity-1        "
00830 
00831     Vector& updUDotErr()     const; // Stage::Acceleration-1 (not a view)
00832     Vector& updMultipliers() const; // Stage::Acceleration-1 (not a view)
00833 
00837     const Stage& getLowestStageModified() const;
00838 
00841     void resetLowestStageModified() const;
00842     
00853     void createRestrictedState(State&                       restrictedState, 
00854                                EnumerationSet<Stage>        restrictedStages,
00855                                std::set<SubsystemIndex>     restrictedSubsystems);
00856 
00859     const EnumerationSet<Stage>& getRestrictedStages() const;
00860 
00863     const std::set<SubsystemIndex>& getRestrictedSubsystems() const;
00864 
00865     String toString() const;
00866     String cacheToString() const;
00867 
00868     // OBSOLETE NAME. Don't use this, use isCacheValueRealized() -- you'll
00869     // have to in the next release.
00870     bool isCacheValueCurrent(SubsystemIndex, CacheEntryIndex) const;
00871 
00872 private:
00873     class StateRep* rep;
00874     const StateRep& getRep() const {assert(rep); return *rep;}
00875     StateRep&       updRep()       {assert(rep); return *rep;}
00876 };
00877 
00878 SimTK_SimTKCOMMON_EXPORT std::ostream& 
00879 operator<<(std::ostream& o, const State& s);
00880 
00881 } // namespace SimTK
00882 
00883 #endif // SimTK_SimTKCOMMON_STATE_H_

Generated by  doxygen 1.6.2