Skip to content

Commit f9268b1

Browse files
jslee02jslee02
authored
docs: migrate PDFs to markdown with LaTeX math (#2467)
1 parent 61ef0c9 commit f9268b1

22 files changed

+2055
-704
lines changed

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ If this fails, see `docs/onboarding/ci-cd.md` for troubleshooting.
3535
| Contributing | @docs/onboarding/contributing.md @CONTRIBUTING.md |
3636
| Code style | @docs/onboarding/code-style.md |
3737
| Architecture | @docs/onboarding/architecture.md @docs/onboarding/README.md |
38+
| Theory (math) | @docs/background/dynamics/ @docs/background/lcp/ |
3839
| CI/CD issues | @docs/onboarding/ci-cd.md |
3940
| Python bindings | @docs/onboarding/python-bindings.md |
4041
| Model loading | @docs/onboarding/io-parsing.md |

‎docs/background/AGENTS.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Agent Guidelines for Background Documentation
2+
3+
Guidelines for AI agents working with `docs/background/` theoretical documentation.
4+
5+
## Purpose of This Directory
6+
7+
`docs/background/` contains **theoretical background** derived from academic PDFs written by
8+
DART's original authors. This is reference material explaining the mathematics behind the code.
9+
10+
| Directory | Content | Original Source |
11+
| ----------- | ----------------------------------------------- | ------------------- |
12+
| `dynamics/` | Lagrangian mechanics, articulated body dynamics | `docs/dynamics.pdf` |
13+
| `lcp/` | Linear Complementarity Problem solvers | `docs/lcp.pdf` |
14+
15+
## Key Rules
16+
17+
### 1. Attribution is Non-Negotiable
18+
19+
Every page derived from the original PDFs **MUST** include the attribution header:
20+
21+
```markdown
22+
> **Attribution**: This content is derived from "[Title]" by [Authors].
23+
> The original PDF is preserved at `docs/[file].pdf`.
24+
```
25+
26+
**Never remove or obscure original authorship.**
27+
28+
### 2. Original PDFs are Authoritative
29+
30+
When in doubt about mathematical correctness, **defer to the original PDF**.
31+
The markdown versions are for maintainability; the PDFs are the authoritative source.
32+
33+
```bash
34+
# To view original PDFs:
35+
# docs/dynamics.pdf - Multibody dynamics tutorial
36+
# docs/lcp.pdf - LCP contact handling
37+
```
38+
39+
### 3. Notation Consistency
40+
41+
Use the notation glossary to map between PDF symbols and DART code:
42+
43+
| PDF Notation | DART API | Notes |
44+
| ------------ | ----------------- | ---------------------- |
45+
| $q$ | `getPositions()` | Generalized positions |
46+
| $\dot{q}$ | `getVelocities()` | Generalized velocities |
47+
| $M(q)$ | `getMassMatrix()` | Mass matrix |
48+
| $\tau$ | `getForces()` | Generalized forces |
49+
50+
See [`dynamics/notation-glossary.md`](dynamics/notation-glossary.md) for the complete mapping.
51+
52+
### 4. LaTeX Math for Equations
53+
54+
These docs use **LaTeX math syntax** for equations (GitHub renders this natively):
55+
56+
```markdown
57+
✅ Correct: Inline math uses single dollars: $M(q)\ddot{q} + C(q,\dot{q}) = \tau$
58+
✅ Correct: Display equations use double dollars:
59+
$$M(q)\ddot{q} + C(q,\dot{q}) + g(q) = \tau$$
60+
61+
❌ Avoid: Unicode math like `M(q)q̈ + C(q,q̇) = τ` (harder to read/search)
62+
❌ Avoid: Code blocks for equations (no rendering)
63+
```
64+
65+
GitHub renders LaTeX math natively since 2022. This provides better readability for complex equations.
66+
67+
### 5. Cross-Reference to Code
68+
69+
When explaining concepts, link to the implementing code:
70+
71+
```markdown
72+
The mass matrix is computed by [`Skeleton::getMassMatrix()`][1].
73+
74+
[1]: ../../dart/dynamics/Skeleton.hpp
75+
```
76+
77+
Or use inline references:
78+
79+
```markdown
80+
See `dart/dynamics/Skeleton.hpp` for the implementation.
81+
```
82+
83+
## When to Edit These Docs
84+
85+
### DO Edit When:
86+
87+
- Fixing typos or formatting errors
88+
- Adding cross-references to DART code
89+
- Updating notation glossary for new APIs
90+
- Adding navigation links
91+
- Clarifying content (mark additions clearly)
92+
93+
### DO NOT Edit When:
94+
95+
- The math seems wrong → Check the original PDF first
96+
- You want to "improve" explanations → Add commentary separately
97+
- API names changed → Update the notation glossary, not the derivations
98+
99+
## File Organization
100+
101+
```
102+
docs/background/
103+
├── README.md # Index and attribution summary
104+
├── ATTRIBUTION.md # Attribution template
105+
├── AGENTS.md # This file
106+
├── dynamics/ # From dynamics.pdf
107+
│ ├── 01_introduction.md
108+
│ ├── 02_lagrangian-dynamics.md
109+
│ ├── ...
110+
│ └── notation-glossary.md
111+
└── lcp/ # From lcp.pdf (already migrated)
112+
├── 01_problem-statement.md
113+
├── 02_overview.md
114+
└── ...
115+
```
116+
117+
## Migration Status
118+
119+
| Source | Target | Status |
120+
| ------------------- | --------------------------- | ------------------------ |
121+
| `docs/lcp.pdf` | `docs/background/lcp/` | ✅ Complete (LaTeX math) |
122+
| `docs/dynamics.pdf` | `docs/background/dynamics/` | ✅ Complete (LaTeX math) |
123+
124+
## Related Documentation
125+
126+
- [`docs/onboarding/dynamics.md`](../onboarding/dynamics.md) — Code-level dynamics exploration
127+
- [`docs/onboarding/constraints.md`](../onboarding/constraints.md) — Constraint system internals
128+
129+
## Quick Reference: Adding New Content
130+
131+
1. **New page from PDF**: Copy structure, add attribution header, use LaTeX math syntax
132+
2. **New code reference**: Add to notation glossary, link to source file
133+
3. **Correction**: Note "Correction from original: [reason]" in a comment
134+
4. **Addition**: Mark clearly as "[Added for DART context]"

‎docs/background/ATTRIBUTION.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Attribution Template
2+
3+
Use this template when adding attribution headers to migrated documentation.
4+
5+
## Standard Header (for each migrated page)
6+
7+
```markdown
8+
> **Attribution**: This content is derived from "[Document Title]" by [Authors]
9+
> ([Affiliation]). The original PDF is preserved at `docs/[filename].pdf`.
10+
>
11+
> **Navigation**: [← Previous](previous.md) | [Index](../README.md) | [Next →](next.md)
12+
13+
---
14+
```
15+
16+
## Document-Specific Attribution
17+
18+
### For Dynamics Pages
19+
20+
```markdown
21+
> **Attribution**: This content is derived from "A Quick Tutorial on Multibody
22+
> Dynamics" by C. Karen Liu and Sumit Jain (Georgia Institute of Technology).
23+
> The original PDF is preserved at `docs/dynamics.pdf`.
24+
```
25+
26+
### For LCP Pages
27+
28+
```markdown
29+
> **Attribution**: This content is derived from "Contact Handling for Articulated
30+
> Rigid Bodies Using LCP" by Jie Tan, Kristin Siu, and C. Karen Liu.
31+
> The original PDF is preserved at `docs/lcp.pdf`.
32+
```
33+
34+
## Guidelines
35+
36+
### What to Preserve
37+
38+
- ✅ Original mathematical content and derivations
39+
- ✅ Author names and affiliations
40+
- ✅ Document structure (sections, ordering)
41+
- ✅ Original notation (with mapping to DART APIs)
42+
43+
### What to Add
44+
45+
- ✅ Navigation links between pages
46+
- ✅ Cross-references to DART code (`dart/dynamics/`, `dart/math/lcp/`)
47+
- ✅ Notation glossary entries mapping PDF symbols → DART APIs
48+
- ✅ Code examples showing DART usage
49+
50+
### What NOT to Do
51+
52+
- ❌ Remove or obscure original authorship
53+
- ❌ Claim migrated content as new original work
54+
- ❌ Delete original PDF files
55+
- ❌ Substantially rewrite original explanations (add commentary separately if needed)
56+
57+
## Provenance Tracking
58+
59+
Each background document should be traceable to its source:
60+
61+
| Markdown File | Source PDF | Section |
62+
| ------------------------------------ | -------------- | ----------- |
63+
| `dynamics/01_introduction.md` | `dynamics.pdf` | Chapter 1 |
64+
| `dynamics/02_lagrangian-dynamics.md` | `dynamics.pdf` | Chapter 2 |
65+
| `lcp/01_problem-statement.md` | `lcp.pdf` | Section 1-2 |
66+
| ... | ... | ... |
67+
68+
When making changes:
69+
70+
- **Corrections**: Note "Correction from original" in a comment
71+
- **Additions**: Clearly mark as "[Added for DART context]" or similar
72+
- **Clarifications**: Use blockquotes or callouts to distinguish from original

‎docs/background/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# DART Background Theory
2+
3+
Theoretical background materials derived from academic publications by DART's original authors.
4+
5+
> **Note**: These documents explain the mathematical foundations. For code-level exploration,
6+
> see [`docs/onboarding/`](../onboarding/README.md).
7+
8+
## Attribution
9+
10+
The materials in this section are derived from:
11+
12+
| Document | Authors | Original | Status |
13+
| --------------------------- | ---------------------------------- | -------------------------------------- | --------------------- |
14+
| Multibody Dynamics Tutorial | C. Karen Liu, Sumit Jain | [`docs/dynamics.pdf`](../dynamics.pdf) | Migration in progress |
15+
| LCP Contact Handling | Jie Tan, Kristin Siu, C. Karen Liu | [`docs/lcp.pdf`](../lcp.pdf) | ✅ Migrated |
16+
17+
These documents were reformatted from PDF to Markdown for maintainability while preserving
18+
the original authors' work. The original PDFs remain in the repository as authoritative references.
19+
20+
For the full attribution template, see [ATTRIBUTION.md](ATTRIBUTION.md).
21+
22+
## Contents
23+
24+
### [Dynamics](dynamics/)
25+
26+
Lagrangian dynamics for articulated rigid body systems:
27+
28+
1. [Introduction](dynamics/01_introduction.md) — Prerequisites and scope
29+
2. [Lagrangian Dynamics](dynamics/02_lagrangian-dynamics.md) — D'Alembert's principle, virtual work
30+
3. [Newton-Euler Review](dynamics/03_newton-euler-review.md) — Single rigid body dynamics
31+
4. [Rigid Body Lagrange](dynamics/04_rigid-body-lagrange.md) — Lagrange's equations for rigid bodies
32+
5. [Articulated Dynamics](dynamics/05_articulated-dynamics.md) — Equations of motion: `M(q)q̈ + C(q,q̇) = Q`
33+
6. [Coordinate Conversion](dynamics/06_coordinate-conversion.md) — Cartesian ↔ generalized coordinates
34+
7. [Recursive Inverse Dynamics](dynamics/07_recursive-inverse-dynamics.md) — Efficient O(n) algorithms
35+
36+
**Notation Glossary**: [dynamics/notation-glossary.md](dynamics/notation-glossary.md)
37+
38+
### [LCP Solvers](lcp/)
39+
40+
Contact handling via Linear Complementarity Problems:
41+
42+
1. [Problem Statement](lcp/01_problem-statement.md) — LCP definition, DART convention (`w = Ax - b`)
43+
2. [Overview](lcp/02_overview.md) — Solver taxonomy and comparison
44+
3. [Pivoting Methods](lcp/03_pivoting-methods.md) — Dantzig, Lemke algorithms
45+
4. [Projection Methods](lcp/04_projection-methods.md) — PGS, Jacobi, iterative solvers
46+
5. [Newton Methods](lcp/05_newton-methods.md) — Smooth reformulations
47+
6. [Other Methods](lcp/06_other-methods.md) — Interior point, QP-based
48+
7. [Selection Guide](lcp/07_selection-guide.md) — Which solver to use when
49+
50+
## Related Documentation
51+
52+
| Topic | Location | Description |
53+
| ------------------------- | -------------------------------------------------------------------------------------- | ---------------- |
54+
| Dynamics code exploration | [`docs/onboarding/dynamics.md`](../onboarding/dynamics.md) | API walkthrough |
55+
| Constraint system | [`docs/onboarding/constraints.md`](../onboarding/constraints.md) | Solver internals |
56+
| Control theory | [`docs/readthedocs/topics/control-theory.md`](../readthedocs/topics/control-theory.md) | Notation mapping |
57+
58+
## For AI Agents
59+
60+
See [AGENTS.md](AGENTS.md) for guidelines on working with these documents.

‎docs/background/dynamics/01_introduction.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Introduction
2+
3+
> **Attribution**: This content is derived from "A Quick Tutorial on Multibody
4+
> Dynamics" by C. Karen Liu and Sumit Jain (Georgia Institute of Technology).
5+
> The original PDF is preserved at [`docs/dynamics.pdf`](../../dynamics.pdf).
6+
7+
**Navigation**: [Index](../README.md) | [Lagrangian Dynamics →](02_lagrangian-dynamics.md)
8+
9+
---
10+
11+
## Prerequisites
12+
13+
If you have not read the excellent SIGGRAPH course notes on physics-based animation
14+
by Witkin and Baraff, you can stop reading further right now. Go look for those notes at
15+
http://www.cs.cmu.edu/~baraff/sigcourse/ and come back when you fully understand
16+
everything in those notes.
17+
18+
## Target Audience
19+
20+
If you are still reading this document, you probably fit the following profile:
21+
22+
- You are a computer scientist with no mechanical engineering background
23+
- You have minimal training in physics in high school
24+
- You are seriously interested in physics-based character animation
25+
- You have read Witkin and Baraff's SIGGRAPH course notes a few times
26+
- You don't know where to go from simulating rigid bodies to human figures
27+
- You have played with some commercial physics engines like ODE, PhysX, Havok, or Bullet
28+
- You wish to simulate human behaviors more interesting than ragdoll effects
29+
30+
## Scope
31+
32+
Physics-based character animation consists of two parts: **simulation** and **control**.
33+
This document focuses on the **simulation** part.
34+
35+
It's quite likely that you do not need to understand how the underlying simulation works
36+
if your control algorithm is simple enough. However, complex human behaviors often require
37+
sophisticated controllers that exploit the dynamics of a multibody system. A good
38+
understanding of multibody dynamics is paramount for designing effective controllers.
39+
40+
## Questions This Document Answers
41+
42+
1. **Equations of Motion**: "I know how to derive the equations of motion for one rigid
43+
body and I have seen people use the following equations for articulated rigid bodies,
44+
but I don't know how they are derived."
45+
46+
$$M(q)\ddot{q} + C(q,\dot{q}) = Q$$
47+
48+
2. **Euler-Lagrange Equation**: "I have seen the Euler-Lagrange equation in the following
49+
form before, but I don't know how it is related to the equations of motion above."
50+
51+
$$\frac{d}{dt}\left(\frac{\partial T}{\partial \dot{q}}\right) - \frac{\partial T}{\partial q} - Q = 0$$
52+
53+
3. **Coordinate Conversion**: "I use generalized coordinates to compute the control forces,
54+
how do I convert them to Cartesian forces such that I can use simulators like ODE, PhysX,
55+
or Bullet which represent rigid bodies in the maximal coordinates?"
56+
57+
4. **Recursive Inverse Dynamics**: "I heard that inverse dynamics can be computed efficiently
58+
using a recursive formulation. How does that work?"
59+
60+
## DART Implementation
61+
62+
In DART, the equations of motion are computed via the `Skeleton` class:
63+
64+
| Concept | DART API | Notes |
65+
| ----------------------- | ------------------------------------ | ------------------------------- |
66+
| Mass matrix $M(q)$ | `Skeleton::getMassMatrix()` | Returns `Eigen::MatrixXd` |
67+
| Coriolis $C(q,\dot{q})$ | `Skeleton::getCoriolisForces()` | Returns `Eigen::VectorXd` |
68+
| Gravity $g(q)$ | `Skeleton::getGravityForces()` | Returns `Eigen::VectorXd` |
69+
| Forward dynamics | `Skeleton::computeForwardDynamics()` | Computes $\ddot{q}$ from $\tau$ |
70+
| Inverse dynamics | `Skeleton::computeInverseDynamics()` | Computes $\tau$ from $\ddot{q}$ |
71+
72+
See `dart/dynamics/Skeleton.hpp` for the implementation.
73+
74+
---
75+
76+
**Navigation**: [Index](../README.md) | [Lagrangian Dynamics →](02_lagrangian-dynamics.md)

0 commit comments

Comments
 (0)