Simbody  3.5
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
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 #ifdef _WIN32
57  #ifdef _MSC_VER
58  #pragma warning(disable:4231) // need to use 'extern' template explicit instantiation
59  #endif
60  #if defined(SimTK_SIMBODY_BUILDING_SHARED_LIBRARY)
61  #define SimTK_SIMBODY_EXPORT __declspec(dllexport)
62  // Keep MS VC++ quiet when it tries to instantiate incomplete template classes in a DLL.
63  #ifdef _MSC_VER
64  #pragma warning(disable:4661)
65  #endif
66  #elif defined(SimTK_SIMBODY_BUILDING_STATIC_LIBRARY) || defined(SimTK_USE_STATIC_LIBRARIES)
67  #define SimTK_SIMBODY_EXPORT
68  #else
69  #define SimTK_SIMBODY_EXPORT __declspec(dllimport) // i.e., a client of a shared library
70  #endif
71 #else
72  #define SimTK_SIMBODY_EXPORT // Linux, Mac
73 #endif
74 
75 // Every SimTK library must provide these two routines, with the library
76 // name appearing after the "version_" and "about_".
77 extern "C" {
78  SimTK_SIMBODY_EXPORT void SimTK_version_simbody(int* major, int* minor, int* build);
79  SimTK_SIMBODY_EXPORT void SimTK_about_simbody(const char* key, int maxlen, char* value);
80 }
81 
82 namespace SimTK {
83 
84  // MATTER SUBSYSTEM-GLOBAL INDEX TYPES
85 
86 
95 SimTK_DEFINE_UNIQUE_INDEX_TYPE(MobilizedBodyIndex);
96 
101 
105 static const MobilizedBodyIndex GroundIndex(0);
106 
113 
114 // TODO: experimental
115 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UnilateralContactIndex);
116 SimTK_DEFINE_UNIQUE_INDEX_TYPE(UnilateralSpeedConstraintIndex);
117 SimTK_DEFINE_UNIQUE_INDEX_TYPE(BoundedSpeedConstraintIndex);
118 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ConstraintLimitedFrictionIndex);
119 SimTK_DEFINE_UNIQUE_INDEX_TYPE(StateLimitedFrictionIndex);
120 
121 // TODO: This is for arrays indexed by MatterSubsystem-global ParticleIndex,
122 // as yet to be defined.
123 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ParticleIndex);
124 
125 // Constrained Bodies in constraints where the Ancestor body is not Ground (we
126 // call these "Ancestor Constrained Bodies") require some additional cached
127 // data, such as their orientations and velocities in the Ancestor frame, so
128 // are each allocated a slot in pools of that data. Those pools are indexed by
129 // this type.
130 SimTK_DEFINE_UNIQUE_INDEX_TYPE(AncestorConstrainedBodyPoolIndex);
131 
132 // This is for "u-squared" arrays, that is, arrays which allocate space for an
133 // nuXnu block for each MobilizedBody.
134 SimTK_DEFINE_UNIQUE_INDEX_TYPE(USquaredIndex);
135 
136 // This is for "quaternion information" arrays, which have total dimension
137 // equal to the number of quaternions currently in use as generalized
138 // coordinates for modeling the Matter Subsystem's MobilizedBodies. Primarily
139 // this is for storing the norm of quaternions so we need calculate them only
140 // once.
141 SimTK_DEFINE_UNIQUE_INDEX_TYPE(QuaternionPoolIndex);
142 
143 // This is for miscellaneous Real-valued position cache data that individual
144 // mobilizers ask us to hold for generalized coordinate q precalculations
145 // (e.g. sines and cosines).
146 SimTK_DEFINE_UNIQUE_INDEX_TYPE(MobodQPoolIndex);
147 
148 // These are for indexing the pools of prescribed q's, u's, udots, and calculated forces
149 // needed to produce the udots. The arrays are allocated in order of MobilizedBodyIndex, and
150 // then in q and u order within the mobilizer. A mobilier with prescribed positions q gets
151 // slots in the u and udot pools also to hold derivatives, and similarly if it is the
152 // velocities u that are prescribed there will be slots in the udot pools. Note that
153 // the Q index can be used to index qdot and qdotdot arrays if needed. Note that a
154 // prescribed force is produced whenever there is a udot that is not force driven; that
155 // includes prescribed udots but also zero and discrete ones.
156 SimTK_DEFINE_UNIQUE_INDEX_TYPE(PresQPoolIndex);
157 SimTK_DEFINE_UNIQUE_INDEX_TYPE(PresUPoolIndex);
158 SimTK_DEFINE_UNIQUE_INDEX_TYPE(PresUDotPoolIndex);
159 SimTK_DEFINE_UNIQUE_INDEX_TYPE(PresForcePoolIndex);
160 
161  // PER-MOBILIZER INDEX TYPES
162 
177 
178  // PER-CONSTRAINT INDEX TYPES
179 
180 // This is the Constraint-specific index of the MobilizedBodies which are *directly* affected
181 // by a constraint, through body forces or body torques on these bodies.
182 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ConstrainedBodyIndex);
183 
184 // This is the Constraint-specific index of the MobilizedBodies whose mobilizers' mobilities
185 // can appear explicitly in constraint equations, and which are acted upon by the Constraint
186 // through generation of generalized (mobility) forces. Note that for a multi-dof mobilizer
187 // we don't select individual mobilities; it is all or nothing so we can use the MobilizedBody
188 // to stand for its mobilizer.
189 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ConstrainedMobilizerIndex);
190 
191 // This is the Constraint-specific index of a coordinate q which can be *directly* affected
192 // by this constraint through generation of a mobility force on a corresponding mobility. These
193 // are numbered in order of ConstrainedMobilizerIndex for the mobilizers for which these are the q's.
194 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ConstrainedQIndex);
195 
196 // This is the Constraint-specific index of a mobility u which can be *directly* affected
197 // by this constraint through generation of a mobility force. These are numbered in order
198 // of ConstrainedMobilizerIndex for the bodies for which these are the u's.
199 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ConstrainedUIndex);
200 
201 
202 // This is the Constraint-specific index of a coordinate q which can be involved in any
203 // constraint equation of this constraint, either directly through ConstrainedMobilizers
204 // or indirectly as a result of its effects on ConstrainedBodies (that is, this list
205 // includes all the ConstraintQIndex entries above, plus possibly many more). These are in sorted
206 // order by subsystem-wide QIndex, and each QIndex appears at most once.
207 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ParticipatingQIndex);
208 
209 // This is the Constraint-specific index of a coordinate u which can be involved in any
210 // constraint equation of this constraint, either directly through ConstrainedMobilizers
211 // or indirectly as a result of its effects on ConstrainedBodies (that is, this list
212 // includes all the ConstraintUIndex entries above, plus possibly many more). These are in sorted
213 // order by subsystem-wide UIndex, and each UIndex appears at most once.
214 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ParticipatingUIndex);
215 
216  // SUBTREE INDEX TYPES
217 
218 // And similarly for other unique Index types.
219 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SubtreeBodyIndex);
220 static const SubtreeBodyIndex SubtreeAncestorIndex(0);
221 
222 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SubtreeQIndex);
223 SimTK_DEFINE_UNIQUE_INDEX_TYPE(SubtreeUIndex);
224 
225  // INDEX TYPES FOR OTHER SUBSYSTEMS
226 
232 
233 SimTK_DEFINE_UNIQUE_INDEX_TYPE(ContactSetIndex);
234 
235 
236 namespace Exception {
237 
238 
239 class APIMethodFailed : public Base {
240 public:
241  APIMethodFailed(const char* fn, int ln, String method, String cause) : Base(fn,ln)
242  {
243  setMessage(method + " failed because:\n " + cause);
244  }
245 };
246 
247 
248 // This just reports rep-level bad things up to the API level with a helpful string.
249 class RepLevelException : public Base {
250 public:
251  RepLevelException(const char* fn, int ln, String message) : Base(fn,ln)
252  {
253  setMessage(message);
254  }
255 };
256 
258 public:
260  String method, MobilizedBodyIndex body, String quantity) : Base(fn,ln)
261  {
262  setMessage(method + "(): the mobilizer for body " + String((int)body)
263  + " can't represent the given " + quantity + " to machine precision");
264  }
265 private:
266 };
267 
268 class NewtonRaphsonFailure : public Base {
269 public:
270  NewtonRaphsonFailure(const char* fn, int ln, String msg) : Base(fn,ln)
271  {
272  setMessage("NewtonRaphson failure: " + msg);
273  }
274 private:
275 };
276 
278 public:
279  LoopConstraintConstructionFailure(const char* fn, int ln, String msg) : Base(fn,ln)
280  {
281  setMessage("Loop constraint construction failure: " + msg);
282  }
283 private:
284 };
285 
286 } // namespace SimTK::Exception
287 
288 
289 
290 } // namespace SimTK
291 
292 #endif // SimTK_SIMBODY_COMMON_H_
LoopConstraintConstructionFailure(const char *fn, int ln, String msg)
Definition: Simbody/include/simbody/internal/common.h:279
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:277
static const SubtreeBodyIndex SubtreeAncestorIndex(0)
Definition: Simbody/include/simbody/internal/common.h:239
void SimTK_version_simbody(int *major, int *minor, int *build)
void setMessage(const std::string &msgin)
Definition: Exception.h:56
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:241
Definition: Simbody/include/simbody/internal/common.h:249
Definition: Simbody/include/simbody/internal/common.h:268
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:270
Definition: Exception.h:45
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:100
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:259
#define SimTK_SIMBODY_EXPORT
Definition: Simbody/include/simbody/internal/common.h:72
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:251
Definition: Simbody/include/simbody/internal/common.h:257
The Mobilizer associated with each MobilizedBody, once modeled, has a specific number of generalized ...