Subsystem.h

Go to the documentation of this file.
00001 #ifndef SimTK_SimTKCOMMON_SUBSYSTEM_H_
00002 #define SimTK_SimTKCOMMON_SUBSYSTEM_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) 2006-7 Stanford University and the Authors.         *
00013  * Authors: Michael Sherman                                                   *
00014  * Contributors:                                                              *
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/State.h"
00038 #include "SimTKcommon/internal/Measure.h"
00039 #include "SimTKcommon/internal/System.h"
00040 
00041 #include <cassert>
00042 
00043 namespace SimTK {
00044 
00045 class System;
00046 class DecorativeGeometry;
00047 class DefaultSystemSubsystemGuts;
00048 class ScheduledEventHandler;
00049 class ScheduledEventReporter;
00050 class TriggeredEventHandler;
00051 class TriggeredEventReporter;
00052 
00075 class SimTK_SimTKCOMMON_EXPORT Subsystem {
00076 public:
00077     class Guts; // local; name is Subsystem::Guts
00078     friend class Guts;
00079 private:
00080     // This is the only data member in this class. Also, any class derived from
00081     // Subsystem must have *NO* data members at all (data goes in the Guts class).
00082     Guts* guts;
00083 public:
00084     Subsystem() : guts(0) { } // an empty handle
00085     Subsystem(const Subsystem&);
00086     Subsystem& operator=(const Subsystem&);
00087     ~Subsystem();
00088 
00089     const String& getName()    const;
00090     const String& getVersion() const;
00091 
00092     // These call the corresponding State method, supplying this Subsystem's
00093     // SubsystemIndex. The returned indices are local to this Subsystem.
00094     QIndex allocateQ(State&, const Vector& qInit) const;
00095     UIndex allocateU(State&, const Vector& uInit) const;
00096     ZIndex allocateZ(State&, const Vector& zInit) const;
00097     DiscreteVariableIndex allocateDiscreteVariable(State&, Stage, AbstractValue* v) const;
00098 
00099     CacheEntryIndex allocateCacheEntry   (const State&, Stage dependsOn, Stage computedBy, AbstractValue* v) const;
00100     CacheEntryIndex allocateCacheEntry   (const State& state, Stage g, AbstractValue* v) const 
00101     {   return allocateCacheEntry(state, g, g, v); }
00102     QErrIndex allocateQErr         (const State&, int nqerr) const;
00103     UErrIndex allocateUErr         (const State&, int nuerr) const;
00104     UDotErrIndex allocateUDotErr      (const State&, int nudoterr) const;
00105     EventTriggerByStageIndex allocateEventTriggersByStage(const State&, Stage, int ntriggers) const;
00106 
00107     // These return views on State shared global resources. The views
00108     // are private to this subsystem, but the global resources themselves
00109     // are not allocated until the *System* advances to stage Model.
00110     // Note that there is no subsystem equivalent of the State's "y"
00111     // vector because in general a subsystem's state variables will
00112     // not be contiguous. However, a subsystem's q's, u's, and z's
00113     // will all be contiguous within those arrays.
00114     const Vector& getQ(const State&) const;
00115     const Vector& getU(const State&) const;
00116     const Vector& getZ(const State&) const;
00117     const Vector& getQDot(const State&) const;
00118     const Vector& getUDot(const State&) const;
00119     const Vector& getZDot(const State&) const;
00120     const Vector& getQDotDot(const State&) const;
00121     const Vector& getQErr(const State&) const;
00122     const Vector& getUErr(const State&) const;
00123     const Vector& getUDotErr(const State&) const;
00124     const Vector& getMultipliers(const State&) const;
00125     const Vector& getEventTriggersByStage(const State&, Stage) const;
00126 
00127     // These return writable access to this subsystem's partition in the
00128     // State pool of continuous variables. These can be called at Stage::Model
00129     // or higher, and if necesary they invalidate the Position (q), Velocity (u),
00130     // or Dynamics (z) stage respectively.
00131     Vector& updQ(State&) const; // invalidates Stage::Position
00132     Vector& updU(State&) const; // invalidates Stage::Velocity
00133     Vector& updZ(State&) const; // invalidates Stage::Dynamics
00134 
00135     // For convenience.
00136     void setQ(State& s, const Vector& q) const {
00137         assert(q.size() == getNQ(s));
00138         updQ(s) = q;
00139     }
00140     void setU(State& s, const Vector& u) const {
00141         assert(u.size() == getNU(s));
00142         updU(s) = u;
00143     }
00144     void setZ(State& s, const Vector& z) const {
00145         assert(z.size() == getNZ(s));
00146         updZ(s) = z;
00147     }
00148 
00149     // These update the State cache which is mutable; hence, const State. They
00150     // can be called only if the previous stage has already been realized, e.g.,
00151     // updQDot() is allowed only while realizing the Velocity stage, requiring
00152     // that Position stage has already been realized.
00153     Vector& updQDot(const State&) const;
00154     Vector& updUDot(const State&) const;
00155     Vector& updZDot(const State&) const;
00156     Vector& updQDotDot(const State&) const;
00157     Vector& updQErr(const State&) const;
00158     Vector& updUErr(const State&) const;
00159     Vector& updUDotErr(const State&) const;
00160     Vector& updMultipliers(const State&) const;
00161     Vector& updEventTriggersByStage(const State&, Stage) const;
00162 
00163     // These pull out the State entries which belong exclusively to
00164     // this Subsystem. These variables and cache entries are available
00165     // as soon as this subsystem is at stage Model.
00166     Stage getStage(const State&) const;
00167     const AbstractValue& getDiscreteVariable(const State&, DiscreteVariableIndex) const;
00168     // State is *not* mutable here -- must have write access to change state variables.
00169     AbstractValue& updDiscreteVariable(State&, DiscreteVariableIndex) const;
00170     const AbstractValue& getCacheEntry(const State&, CacheEntryIndex) const;
00171     // State is mutable here.
00172     AbstractValue& updCacheEntry(const State&, CacheEntryIndex) const;
00173 
00174     bool isCacheValueCurrent(const State&, CacheEntryIndex) const;
00175     void markCacheValueRealized(const State&, CacheEntryIndex) const;
00176 
00177     // Dimensions. These are valid at System Stage::Model while access to the various
00178     // arrays may have stricter requirements. Hence it is better to use these
00179     // routines than to get a reference to a Vector above and ask for its size().
00180 
00181     SystemQIndex getQStart      (const State&) const;
00182     int getNQ          (const State&) const;
00183     SystemUIndex getUStart      (const State&) const;
00184     int getNU          (const State&) const;
00185     SystemZIndex getZStart      (const State&) const;
00186     int getNZ          (const State&) const;
00187     SystemQErrIndex getQErrStart   (const State&) const;
00188     int getNQErr       (const State&) const;
00189     SystemUErrIndex getUErrStart   (const State&) const;
00190     int getNUErr       (const State&) const;
00191     SystemUDotErrIndex getUDotErrStart(const State&) const;
00192     int getNUDotErr    (const State&) const;
00193     SystemMultiplierIndex getMultipliersStart (const State&) const;
00194     int getNMultipliers     (const State&) const;
00195     SystemEventTriggerByStageIndex getEventTriggerStartByStage(const State&, Stage) const;
00196     int getNEventTriggersByStage   (const State&, Stage) const;
00197 
00198     bool isInSystem() const;
00199     bool isInSameSystem(const Subsystem& otherSubsystem) const;
00200 
00201     const System& getSystem() const;
00202     System&       updSystem();
00203 
00204     SubsystemIndex getMySubsystemIndex() const;
00205 
00206     // Is this handle the owner of this rep? This is true if the
00207     // handle is empty or if its rep points back here.
00208     bool isOwnerHandle() const;
00209     bool isEmptyHandle() const;
00210 
00211     // There can be multiple handles on the same Subsystem.
00212     bool isSameSubsystem(const Subsystem& otherSubsystem) const;
00213 
00214     bool subsystemTopologyHasBeenRealized() const;
00215     void invalidateSubsystemTopologyCache() const;
00216 
00217     // Add a new Measure to this Subsystem. This method is generally used by Measure
00218     // constructors to install a newly-constructed Measure into its Subsystem.
00219     MeasureIndex adoptMeasure(Measure&);
00220 
00221     Measure getMeasure(MeasureIndex) const;
00222     template <class T> Measure_<T> getMeasure_(MeasureIndex mx) const
00223     {   return Measure_<T>::getAs(getMeasure(mx));}
00224 
00225     // dynamic_cast the returned reference to a reference to your concrete Guts
00226     // class.
00227     const Subsystem::Guts& getSubsystemGuts() const {assert(guts); return *guts;}
00228     Subsystem::Guts&       updSubsystemGuts()       {assert(guts); return *guts;}
00229 
00230     // Put new Guts into this *empty* handle and take over ownership.
00231     // If this handle is already in use, this routine will throw
00232     // an exception.
00233     void adoptSubsystemGuts(Subsystem::Guts* g);
00234     void setSystem(System&, SubsystemIndex);
00235 
00236     explicit Subsystem(Subsystem::Guts* g) : guts(g) { }
00237     bool hasGuts() const {return guts!=0;}
00238 };
00239 
00240 
00247 class SimTK_SimTKCOMMON_EXPORT DefaultSystemSubsystem : public Subsystem {
00248 public:
00249     DefaultSystemSubsystem(System& sys);
00250     void addEventHandler(ScheduledEventHandler* handler);
00251     void addEventHandler(TriggeredEventHandler* handler);
00252     void addEventReporter(ScheduledEventReporter* handler) const;
00253     void addEventReporter(TriggeredEventReporter* handler) const;
00254     EventId createEventId(SubsystemIndex subsys, const State& state) const;
00255     void findSubsystemEventIds(SubsystemIndex subsys, const State& state, const std::vector<EventId>& allEvents, std::vector<EventId>& eventsForSubsystem) const;
00256 private:
00257     const DefaultSystemSubsystemGuts& getGuts() const;
00258     DefaultSystemSubsystemGuts& updGuts();
00259 };
00260 
00261 
00262 } // namespace SimTK
00263 
00264 #endif // SimTK_SimTKCOMMON_SUBSYSTEM_H_

Generated by  doxygen 1.6.2