|
Drake
|
|
Drake
|
Translating from the mathematics of multibody mechanics to correct code is a difficult process and requires careful discipline to ensure that the resulting code is correct.
In Drake we use terminology, notation, and abstractions that have been designed specifically to reduce the possibility of errors, based on these observations:
In this section we provide general documentation about our terminology, notation, and abstraction choices in a form that can be referenced from code documentation. Much of the information here is most useful for programmers who are writing or reading Drake multibody code. Some comments are specifically targeted to those developers, and formatting compromises have been made so that the information in this section is (mostly) readable from the source code used to generate it (for example, ASCII drawings instead of image files, simple Markdown tables rather than fancy-but-unreadable html ones). However, much of this can be useful to users of the Drake API also so it is included in the external documentation.
Where possible, we refer to published literature to supplement our code documentation. That literature can provide clear, concise, and unambiguous documentation of the equations and algorithms we are using, but employs typeset mathematics to do so. We need to translate that mathematics into code, where there is much less typographical flexibility. The Drake notation is designed to facilitate comparison between the typeset and coded math in order to verify correct implementation.
In addition, we need developers to provide good local documentation for our mathematical algorithms in the form of Doxygen comments. That documentation will be best viewed after formatting by Doxygen, which employs other tools like LaTeX and Markdown for beautification. However, for effective development we need that documentation to be understandable and easily modified by developers who are working directly in the source code. Maximizing the post-Doxygen elegance of the formatted documentation can come at a steep cost in source code readability and writability. And difficult-to-write documentation often doesn't get written at all.
Perhaps not surprisingly, some notational compromises are necessary to achieve these goals! When we do choose to use typeset mathematical notation, we avoid typical typographical flourishes that would impede translation from math notation to code. For example, we avoid script typefaces and putting arrows over vectors. Also, since almost all interesting quantities in multibody dynamics are vectors or matrices, we do not follow the common convention of using bold for those quantities since (a) almost everything would be bold adding little clarity, and (b) we can't do that in source code or comments. We do use a limited set of super- and subscripts but define a rote mapping from them to their code equivalents, as described below. We use Greek symbols where conventional, such as ω for angular velocity, but define English equivalents for use in variable names (w in this case). Where possible, we prefer use of Unicode UTF-8 encoding in comments rather than LaTeX since UTF-8 is equally readable in the source and in the formatted output. At times we will forego font purity where there is no chance of confusion. For example, we may decide to format a complicated equation in LaTeX, where it will appear in a typeset font like \(A\) (which appears in the source as @f$A@f$), but then refer in the text to A (source: just A) using the default font that is much easier to write and to read in the source.
Developers: you can link directly to specific discussion topics here from your Doxygen comments; instructions are at the top of the source file used to generate them.
Next topic: Notation Basics
Modules | |
| Notation Basics | |
| We are interested in representing physical quantities like position, orientation, inertia, and spatial velocity. | |
| Frames and Bodies | |
| The frame and body are fundamental to multibody mechanics. | |
| Multibody Quantities | |
| Quantities of interest in multibody dynamics have distinct types. | |
| Units of Multibody Quantities | |
| Drake uses SI units (also known as MKS – meters, kilograms, and seconds). | |
| Time Derivatives of Multibody Quantities | |
| Scalar quantities: The ordinary first time-derivative of the scalar x is denoted xdot or xDt whereas the ordinary second time-derivative of x is denoted xddot or xDDt. | |
| Spatial Algebra | |
| Multibody dynamics involves both rotational and translational quantities, for motion, forces, and mass properties. | |