Simbody  3.7
Simbody/include/simbody/internal/common.h
Go to the documentation of this file.
1 #ifndef SimTK_SIMBODY_COMMON_H_
2 #define SimTK_SIMBODY_COMMON_H_
3 
4 /* -------------------------------------------------------------------------- *
5  * Simbody(tm) *
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/home/simbody. *
11  * *
12  * Portions copyright (c) 2005-12 Stanford University and the Authors. *
13  * Authors: Michael Sherman *
14  * Contributors: *
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 #include "SimTKcommon.h"
32 
33 #include <cassert>
34 #include <vector>
35 #include <limits>
36 
37 
38 // Shared libraries are messy in Visual Studio. We have to distinguish three
39 // cases:
40 // (1) this header is being used to build the simbody shared library (dllexport)
41 // (2) this header is being used by a *client* of the simbody shared
42 // library (dllimport)
43 // (3) we are building the simbody static library, or the client is
44 // being compiled with the expectation of linking with the
45 // simbody static library (nothing special needed)
46 // In the CMake script for building this library, we define one of the symbols
47 // SimTK_SIMBODY_BUILDING_{SHARED|STATIC}_LIBRARY
48 // Client code normally has no special symbol defined, in which case we'll
49 // assume it wants to use the shared library. However, if the client defines
50 // the symbol SimTK_USE_STATIC_LIBRARIES we'll suppress the dllimport so
51 // that the client code can be linked with static libraries. Note that
52 // the client symbol is not library dependent, while the library symbols
53 // affect only the simbody library, meaning that other libraries can
54 // be clients of this one. However, we are assuming all-static or all-shared.
55 
56 #if defined(_WIN32) && defined(_MSC_VER)
57  #pragma warning(disable:4231) // need to use 'extern' template explicit instantiation
58  #if defined(SimTK_SIMBODY_BUILDING_SHARED_LIBRARY)
59  #define SimTK_SIMBODY_EXPORT __declspec(dllexport)
60  // Keep MS VC++ quiet when it tries to instantiate incomplete template classes in a DLL.
61  #pragma warning(disable:4661)
62  #elif defined(SimTK_SIMBODY_BUILDING_STATIC_LIBRARY) || defined(SimTK_USE_STATIC_LIBRARIES)
63  #define SimTK_SIMBODY_EXPORT
64  #else
65  #define SimTK_SIMBODY_EXPORT __declspec(dllimport) // i.e., a client of a shared library
66  #endif
67 #else
68  #define SimTK_SIMBODY_EXPORT // Linux, Mac, MinGW
69 #endif
70 
71 // Every SimTK library must provide these two routines, with the library
72 // name appearing after the "version_" and "about_".
73 extern "C" {
74  SimTK_SIMBODY_EXPORT void SimTK_version_simbody(int* major, int* minor, int* build);
75  SimTK_SIMBODY_EXPORT void SimTK_about_simbody(const char* key, int maxlen, char* value);
76 }
77 
78 namespace SimTK {
79 
80  // MATTER SUBSYSTEM-GLOBAL INDEX TYPES
81 
82 
91 SimTK_DEFINE_UNIQUE_INDEX_TYPE(MobilizedBodyIndex);
92 
97 
101 static const MobilizedBodyIndex GroundIndex(0);
102 
109 
110 // TODO: experimental
111 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UnilateralContactIndex);
112 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UnilateralSpeedConstraintIndex);
113 SimTK_DEFINE_UNIQUE_INDEX_TYPE(BoundedSpeedConstraintIndex);
114 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ConstraintLimitedFrictionIndex);
115 SimTK_DEFINE_UNIQUE_INDEX_TYPE(StateLimitedFrictionIndex);
116 
117 // TODO: This is for arrays indexed by MatterSubsystem-global ParticleIndex,
118 // as yet to be defined.
119 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ParticleIndex);
120 
121 // Constrained Bodies in constraints where the Ancestor body is not Ground (we
122 // call these "Ancestor Constrained Bodies") require some additional cached
123 // data, such as their orientations and velocities in the Ancestor frame, so
124 // are each allocated a slot in pools of that data. Those pools are indexed by
125 // this type.
126 SimTK_DEFINE_UNIQUE_INDEX_TYPE(AncestorConstrainedBodyPoolIndex);
127 
128 // This is for "u-squared" arrays, that is, arrays which allocate space for an
129 // nuXnu block for each MobilizedBody.
130 SimTK_DEFINE_UNIQUE_INDEX_TYPE(USquaredIndex);
131 
132 // This is for "quaternion information" arrays, which have total dimension
133 // equal to the number of quaternions currently in use as generalized
134 // coordinates for modeling the Matter Subsystem's MobilizedBodies. Primarily
135 // this is for storing the norm of quaternions so we need calculate them only
136 // once.
137 SimTK_DEFINE_UNIQUE_INDEX_TYPE(QuaternionPoolIndex);
138 
139 // This is for miscellaneous Real-valued position cache data that individual
140 // mobilizers ask us to hold for generalized coordinate q precalculations
141 // (e.g. sines and cosines).
142 SimTK_DEFINE_UNIQUE_INDEX_TYPE(MobodQPoolIndex);
143 
144 // These are for indexing the pools of prescribed q's, u's, udots, and calculated forces
145 // needed to produce the udots. The arrays are allocated in order of MobilizedBodyIndex, and
146 // then in q and u order within the mobilizer. A mobilier with prescribed positions q gets
147 // slots in the u and udot pools also to hold derivatives, and similarly if it is the
148 // velocities u that are prescribed there will be slots in the udot pools. Note that
149 // the Q index can be used to index qdot and qdotdot arrays if needed. Note that a
150 // prescribed force is produced whenever there is a udot that is not force driven; that
151 // includes prescribed udots but also zero and discrete ones.
152 SimTK_DEFINE_UNIQUE_INDEX_TYPE(PresQPoolIndex);
153 SimTK_DEFINE_UNIQUE_INDEX_TYPE(PresUPoolIndex);
154 SimTK_DEFINE_UNIQUE_INDEX_TYPE(PresUDotPoolIndex);
155 SimTK_DEFINE_UNIQUE_INDEX_TYPE(PresForcePoolIndex);
156 
157  // PER-MOBILIZER INDEX TYPES
158 
173 
174  // PER-CONSTRAINT INDEX TYPES
175 
176 // This is the Constraint-specific index of the MobilizedBodies which are *directly* affected
177 // by a constraint, through body forces or body torques on these bodies.
178 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ConstrainedBodyIndex);
179 
180 // This is the Constraint-specific index of the MobilizedBodies whose mobilizers' mobilities
181 // can appear explicitly in constraint equations, and which are acted upon by the Constraint
182 // through generation of generalized (mobility) forces. Note that for a multi-dof mobilizer
183 // we don't select individual mobilities; it is all or nothing so we can use the MobilizedBody
184 // to stand for its mobilizer.
185 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ConstrainedMobilizerIndex);
186 
187 // This is the Constraint-specific index of a coordinate q which can be *directly* affected
188 // by this constraint through generation of a mobility force on a corresponding mobility. These
189 // are numbered in order of ConstrainedMobilizerIndex for the mobilizers for which these are the q's.
190 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ConstrainedQIndex);
191 
192 // This is the Constraint-specific index of a mobility u which can be *directly* affected
193 // by this constraint through generation of a mobility force. These are numbered in order
194 // of ConstrainedMobilizerIndex for the bodies for which these are the u's.
195 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ConstrainedUIndex);
196 
197 
198 // This is the Constraint-specific index of a coordinate q which can be involved in any
199 // constraint equation of this constraint, either directly through ConstrainedMobilizers
200 // or indirectly as a result of its effects on ConstrainedBodies (that is, this list
201 // includes all the ConstraintQIndex entries above, plus possibly many more). These are in sorted
202 // order by subsystem-wide QIndex, and each QIndex appears at most once.
203 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ParticipatingQIndex);
204 
205 // This is the Constraint-specific index of a coordinate u which can be involved in any
206 // constraint equation of this constraint, either directly through ConstrainedMobilizers
207 // or indirectly as a result of its effects on ConstrainedBodies (that is, this list
208 // includes all the ConstraintUIndex entries above, plus possibly many more). These are in sorted
209 // order by subsystem-wide UIndex, and each UIndex appears at most once.
210 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ParticipatingUIndex);
211 
212  // SUBTREE INDEX TYPES
213 
214 // And similarly for other unique Index types.
215 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SubtreeBodyIndex);
216 static const SubtreeBodyIndex SubtreeAncestorIndex(0);
217 
218 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SubtreeQIndex);
219 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SubtreeUIndex);
220 
221  // INDEX TYPES FOR OTHER SUBSYSTEMS
222 
228 
229 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ContactSetIndex);
230 
231 
232 namespace Exception {
233 
234 
235 class APIMethodFailed : public Base {
236 public:
237  APIMethodFailed(const char* fn, int ln, String method, String cause) : Base(fn,ln)
238  {
239  setMessage(method + " failed because:\n " + cause);
240  }
241 };
242 
243 
244 // This just reports rep-level bad things up to the API level with a helpful string.
245 class RepLevelException : public Base {
246 public:
247  RepLevelException(const char* fn, int ln, String message) : Base(fn,ln)
248  {
249  setMessage(message);
250  }
251 };
252 
254 public:
256  String method, MobilizedBodyIndex body, String quantity) : Base(fn,ln)
257  {
258  setMessage(method + "(): the mobilizer for body " + String((int)body)
259  + " can't represent the given " + quantity + " to machine precision");
260  }
261 private:
262 };
263 
264 class NewtonRaphsonFailure : public Base {
265 public:
266  NewtonRaphsonFailure(const char* fn, int ln, String msg) : Base(fn,ln)
267  {
268  setMessage("NewtonRaphson failure: " + msg);
269  }
270 private:
271 };
272 
274 public:
275  LoopConstraintConstructionFailure(const char* fn, int ln, String msg) : Base(fn,ln)
276  {
277  setMessage("Loop constraint construction failure: " + msg);
278  }
279 private:
280 };
281 
282 } // namespace SimTK::Exception
283 
284 
285 
286 } // namespace SimTK
287 
288 #endif // SimTK_SIMBODY_COMMON_H_
LoopConstraintConstructionFailure(const char *fn, int ln, String msg)
Definition: Simbody/include/simbody/internal/common.h:275
This is for arrays indexed by mobilized body number within a subsystem (typically the SimbodyMatterSu...
SimTK_DEFINE_UNIQUE_INDEX_TYPE(AssemblyConditionIndex)
Definition: Simbody/include/simbody/internal/common.h:273
static const SubtreeBodyIndex SubtreeAncestorIndex(0)
Definition: Simbody/include/simbody/internal/common.h:235
void SimTK_version_simbody(int *major, int *minor, int *build)
void setMessage(const std::string &msgin)
Definition: Exception.h:57
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
static const MobilizedBodyIndex GroundIndex(0)
This is the MobilizedBodyIndex corresponding to the unique Ground body; its index is always zero...
APIMethodFailed(const char *fn, int ln, String method, String cause)
Definition: Simbody/include/simbody/internal/common.h:237
Definition: Simbody/include/simbody/internal/common.h:245
Definition: Simbody/include/simbody/internal/common.h:264
This is for arrays indexed by constraint number within a subsystem (typically the SimbodyMatterSubsys...
Includes internal headers providing declarations for the basic SimTK Core classes, including Simmatrix.
This type represents the index of a Force element within its subsystem.
NewtonRaphsonFailure(const char *fn, int ln, String msg)
Definition: Simbody/include/simbody/internal/common.h:266
Definition: Exception.h:46
MobilizedBodyIndex MobodIndex
This is the approved abbeviation for MobilizedBodyIndex. Feel free to use it if you get tired of typi...
Definition: Simbody/include/simbody/internal/common.h:96
void SimTK_about_simbody(const char *key, int maxlen, char *value)
SimTK::String is a plug-compatible std::string replacement (plus some additional functionality) inten...
Definition: String.h:62
MobilizerCantExactlyRepresentRequestedQuantity(const char *fn, int ln, String method, MobilizedBodyIndex body, String quantity)
Definition: Simbody/include/simbody/internal/common.h:255
#define SimTK_SIMBODY_EXPORT
Definition: Simbody/include/simbody/internal/common.h:68
The Mobilizer associated with each MobilizedBody, once modeled, has a specific number of generalized ...
RepLevelException(const char *fn, int ln, String message)
Definition: Simbody/include/simbody/internal/common.h:247
Definition: Simbody/include/simbody/internal/common.h:253
The Mobilizer associated with each MobilizedBody, once modeled, has a specific number of generalized ...