You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/src/contact_models.md
+1-4Lines changed: 1 addition & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,6 @@
1
1
# Overview
2
2
3
-
### Models
4
-
Impact and friction behaviors are modeled, along with the system’s dynamics, as an NCP. This model simulates hard contact without requiring system-specific solver tuning. Additionally, contacts between a system and the environment are treated as a single graph node connected to a rigid body (see below). As a result, the simulator retains efficient linear-time complexity for open-chain mechanical systems.
3
+
Impact and friction behaviors are modeled, along with the system’s dynamics, as a nonlinear complementarity problem (NCP). This model simulates hard contact without requiring system-specific solver tuning. Additionally, contacts between a system and the environment are treated as a single graph node connected to a rigid body (see below). As a result, the simulator retains efficient linear-time complexity for open-chain mechanical systems.
5
4
6
5
7
6
@@ -14,7 +13,6 @@ Three contact models are implemented in Dojo:
14
13
15
14
All 3 of these contact models implement hard contact i.e. no interpenetration. This means that for both the nonlinear and linearized cones, we concatenate the constraints resulting from friction with the impact constraints.
16
15
17
-
18
16
### Implementation
19
17
Dojo currently supports contact constraints occurring between a sphere and the ground i.e. a horizontal half-space of altitude 0.0. Each spherical contact is attached to a single [`Body`](@ref).
20
18
@@ -23,7 +21,6 @@ To create a new point of contact, we need to define:
23
21
- radius of the sphere defining the spherical contact
24
22
- coefficient of friction (except for [`ImpactContact`](@ref))
25
23
26
-
27
24
### Example
28
25
For the Quadruped model shown in the picture below, we defined 12 contacts spheres show in red:
Copy file name to clipboardExpand all lines: docs/src/impact.md
+14-10Lines changed: 14 additions & 10 deletions
Original file line number
Diff line number
Diff line change
@@ -3,22 +3,26 @@
3
3
### Mathematical Model
4
4
We model hard contact via constraints on the system’s configuration and the applied contact forces. For a system with $P$ contact points, we define a signed-distance function,
5
5
6
-
$$\phi : \mathbf{Z} \rightarrow \mathbf{R}^P$$
6
+
```math
7
+
\phi : \mathbf{Z} \rightarrow \mathbf{R}^P
8
+
```
7
9
8
10
subject to the following element-wise constraint:
9
11
10
-
$$ϕ(z) > 0,$$
12
+
```math
13
+
ϕ(z) > 0,
14
+
```
11
15
12
-
Impact forces with magnitude $\gamma \in \mathbf{R}^P$ are applied to the bodies’ contact points in the direction of their surface normals in order to enforce (5) and prevent interpenetration. A non-negative constraint,
16
+
Impact forces with magnitude ``\gamma \in \mathbf{R}^P`` are applied to the bodies’ contact points in the direction of their surface normals in order to enforce (5) and prevent interpenetration. A non-negative constraint,
13
17
14
-
$$\gamma \geq 0,$$
18
+
```math
19
+
\gamma \geq 0,
20
+
```
15
21
16
22
enforces physical behavior that impulses are repulsive (e.g., the floor does not attract bodies), and the complementarity condition,
17
23
18
-
$$\gamma \circ \phi(z) = 0,$$
24
+
```math
25
+
\gamma \circ \phi(z) = 0,
26
+
```
19
27
20
-
where $\circ$ is an element-wise product operator, enforces zero force if the body is not in contact and allows non-zero force during contact.
21
-
22
-
23
-
### Constructor
24
-
[`ImpactContact`](@ref)
28
+
where ``\circ`` is an element-wise product operator, enforces zero force if the body is not in contact and allows non-zero force during contact.
Copy file name to clipboardExpand all lines: docs/src/index.md
+13-7Lines changed: 13 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,11 @@
1
-
# [Dojo](https://github.com/dojo-sim/Dojo.jl)
2
-
A differentiable simulator for robotics
1
+
# Get Started
2
+
3
+
__[Dojo](https://github.com/dojo-sim/Dojo.jl) is a differentiable simulator for robotics__, prioritizing accurate physics and useful gradients. The simulator is written in pure Julia in order to be both performant and easy to use.
3
4
4
5
## Features
5
-
*__Maximal-Coordinates Representation__
6
-
*__Smooth Gradients__
7
-
*__Open Source__: Our code is available on [GitHub](https://github.com/dojo-sim/Dojo.jl) and distributed under the MIT Licence.
6
+
*__Maximal-Coordinates Representation__: Fast and efficient conversion between [maximal](maximal_representation.md) and [minimal](minimal_representation.md) representations
7
+
*__Smooth Gradients__: Simulation with [hard contact](impact.md) and useful [gradients](gradients.md) through contact events
8
+
*__Open Source__: Code is available on [GitHub](https://github.com/dojo-sim/Dojo.jl) and distributed under the MIT Licence.
& \quad y^{(i)}, z^{(i)} \in \mathcal{K}, && \quad i = 1,\dots, n,
17
+
\end{align*}
18
+
```
15
19
16
-
with decision variables $x \in \mathbf{R}^k$ and $y, z \in \mathbf{R}^m$, equality-constraint set $c : \mathbf{R}^k \times \mathbf{R}^m \times \mathbf{R}^m \times \mathbf{R}^l \rightarrow \mathbf{R}^h$, problem data $\theta \in \mathbf{R}^l$; and where $\mathcal{K}$ is the Cartesian product of $n$ total positive-orthant and second-order cones. The variables are partitioned: $x = (x^{(1)}, \dots, x^{(p)})$, where $i = 1$ are Euclidean variables and $i = 2, \dots, p$ are each quaternion variables; and $y = (y^{(1)}, \dots, y^{(n)})$, $z = (z^{(1)}, \dots, z^{(n)})$, where $j = 1$ is the positive-orthant and the remaining $j = 2, \dots, n$ are second-order cones. For convenience, we denote $w = (x, y, z)$.
20
+
with decision variables ``x \in \mathbf{R}^k`` and ``y, z \in \mathbf{R}^m``, equality-constraint set ``c : \mathbf{R}^k \times \mathbf{R}^m \times \mathbf{R}^m \times \mathbf{R}^l \rightarrow \mathbf{R}^h``, problem data ``\theta \in \mathbf{R}^l``; and where ``\mathcal{K}`` is the Cartesian product of ``n`` total positive-orthant and second-order cones. The variables are partitioned: ``x = (x^{(1)}, \dots, x^{(p)})``, where ``i = 1`` are Euclidean variables and ``i = 2, \dots, p`` are each quaternion variables; and ``y = (y^{(1)}, \dots, y^{(n)})``, ``z = (z^{(1)}, \dots, z^{(n)})``, where ``j = 1`` is the positive-orthant and the remaining ``j = 2, \dots, n`` are second-order cones. For convenience, we denote ``w = (x, y, z)``.
17
21
18
-
The algorithm aims to satisfy a sequence of relaxed problems with $\kappa > 0$ and $\kappa \rightarrow 0$ in order to reliably converge to a solution of the original problem (i.e., $\kappa = 0$). This continuation approach helps avoid premature ill-conditioning and is the basis for numerous convex and non-convex general-purpose interior-point solvers.
22
+
The algorithm aims to satisfy a sequence of relaxed problems with ``\kappa > 0`` and ``\kappa \rightarrow 0`` in order to reliably converge to a solution of the original problem (i.e., ``\kappa = 0``). This continuation approach helps avoid premature ill-conditioning and is the basis for numerous convex and non-convex general-purpose interior-point solvers.
The NCP is considered solved when $r_{\text{vio}} < r_{\text{tol}}$ and $b_{\text{vio}} < b_{\text{tol}}$.
38
+
The NCP is considered solved when ``r_{\text{vio}} < r_{\text{tol}}`` and ``b_{\text{vio}} < b_{\text{tol}}``.
31
39
!!! info "solver options"
32
40
Both `r_tol` and `b_tol` are options that can easily be accessed and modified via [`SolverOptions`](@ref).
33
41
34
42
### Newton Steps
35
-
The main loop of the solver performs Newton's method on the equality-constraint set $c$ and the bilinear constraints. The solver typically converges in about 10 iterations.
43
+
The main loop of the solver performs Newton's method on the equality-constraint set ``c`` and the bilinear constraints. The solver typically converges in about 10 iterations.
36
44
!!! info "solver options"
37
45
The maximal number of Newton's iterations `max_iter` can be set via [`SolverOptions`](@ref).
38
46
39
47
### Line Search
40
-
Newton's method provides a search direction, then we perform a line search along this search direction to detemine the step length $\alpha$. We use a backtracking line search that accepts the step whenever it decreases $c_{\text{vio}}$ or $b_{\text{vio}}$.
41
-
The line search starts with a step $\alpha=1$, if the step acceptance conditions are not met the step is decreased geometrically:
42
-
$$\alpha \leftarrow \alpha \times s $$. The line search takes at most `max_ls` backtracking steps.
48
+
Newton's method provides a search direction, then we perform a line search along this direction to detemine the step length ``\alpha``. We use a backtracking line search that accepts the step whenever it decreases ``c_{\text{vio}}`` or ``b_{\text{vio}}``.
49
+
The line search starts with a step ``\alpha=1``, if the step acceptance conditions are not met the step is decreased geometrically:
50
+
``\alpha \leftarrow s \cdot \alpha``. The line search takes at most `max_ls` backtracking steps.
43
51
44
52
!!! info "solver options"
45
-
The scaling parameter $s$ is called `ls_scale` and the maximum number of line search iteration `max_ls` can be set via [`SolverOptions`](@ref).
53
+
The scaling parameter ``s`` is called `ls_scale` and the maximum number of line search iteration `max_ls` can be set via [`SolverOptions`](@ref).
Coulomb friction instantaneously maximizes the dissipation of kinetic energy between two objects in contact. For a single contact point, this physical phenomenon can be modeled by the following optimization problem,
Coulomb friction instantaneously maximizes the dissipation of kinetic energy between two objects in contact.
8
4
9
-
where $v \in \mathbf{R}^{2}$ is the tangential velocity at the contact point, $b \in \mathbf{R}^2$ is the friction force, and $\mu \in \mathbf{R}_{+}$ is the coefficient of friction between the two objects.
5
+
### Mathematical Model
6
+
For a single contact point, this physical phenomenon can be modeled by the following optimization problem,
where ``v \in \mathbf{R}^{2}`` is the tangential velocity at the contact point, ``b \in \mathbf{R}^2`` is the friction force, and ``\mu \in \mathbf{R}_{+}`` is the coefficient of friction between the two objects.
12
16
13
-
This problem is naturally a convex second-order cone program, and can be efficiently and reliably solved. However, classically, an approximate version of the above problem:
17
+
### Linearized Model
18
+
This above problem is naturally a convex second-order cone program, and can be efficiently and reliably solved. However, classically, an approximate version:
which satisfies the LCP formulation, is instead solved. Here, the friction cone is linearized and the friction vector, $\beta \in \mathbf{R}^{4}$, is correspondingly overparameterized and subject to additional non-negative constraints.
28
+
which satisfies the LCP formulation, is instead solved. Here, the friction cone is linearized and the friction vector, ``\beta \in \mathbf{R}^{4}``, is correspondingly overparameterized and subject to additional non-negative constraints.
20
29
21
30
The optimality conditions of the above problem and constraints used in the LCP are:
where $\psi \in \mathbf{R}$ and $\eta \in \mathbf{R}^{4}$ are the dual variables associated with the friction cone and positivity constraints, respectively, and $\textbf{1}$ is a vector of ones.
where ``\psi \in \mathbf{R}`` and ``\eta \in \mathbf{R}^{4}`` are the dual variables associated with the friction cone and positivity constraints, respectively, and ``\textbf{1}`` is a vector of ones.
y = (y^{(1)}, \dots, y^{(M)}) \leftarrow z = (z^{(1)}, \dots, z^{(N)}),
9
+
```
8
10
9
11
where ``y^{(j)}`` depends on the degree and type of joint. **Note**: this minimal representation does not stack coordinates followed by velocities, which is a common convention; instead, **coordinates and velocities are grouped by joint**.
0 commit comments