Drake
Terminology and Notation
Collaboration diagram for Terminology and Notation:

Modules

 Notation Basics
 We are interested in representing physical quantities like position, orientation, inertia, and spatial velocity.
 
 Frames and Bodies
 The most fundamental object in multibody mechanics is the coordinate frame, or just frame.
 
 Multibody Quantities
 Quantities of interest in multibody dynamics have distinct types.
 
 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.
 

Detailed Description

Drake uses consistent terminology and notation for multibody mechanics.

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.

Next topic: Notation Basics