What does linearDamping mean in Box2D?

Question

If I set linearDamping on a body, it's velocity will be decreased slowly, until it stops. The documentation says, that the units are 1/time, which is unclear for me.

If the velocity of a body is 10 m/s, and the linearDamping is 0.5, then how can I calculate that when will the velocity be decreased to 1 m/s ?

Answer 1

I worked out a closed formula to calculate the velocity v' after some elapsed time t with a given linearDamping D and original velocity v:

v' = v*exp(-D*t)

To calculate how much time is needed to reach a given velocity v':

t = ln(v' / v) / (-D)

Using the parameters from the question:

t = ln(1 / 10) / (-0.5) = 4.605

The object needs 4,6 seconds to decelerate from 10 m/s to 1 m/s

Note:

The original source code to calculate new velocity inside the step function:

v *= b2Clamp(1.0f - h * b->m_linearDamping, 0.0f, 1.0f);

To calculate the distance the object should move over this interval, assuming continuous physics decoupled from any timestep, we can take the integral of the speed over that interval.

$$\begin{align} v(T) &= v_0 e^{-D T}\\ \Delta p(T) &= \int_0^T v_0 e^{-D t} dt\\ \Delta p(T) &= \left[ \frac {v_0} {-D} e^{-Dt} \right] \bigg\rvert_0^T\\ \Delta p(T) &= \frac {v_0} {-D} \left(e^{-DT} - e^0\right)\\ \Delta p(T) &= \frac {v_0} {D} \left( 1 - e^{-DT}\right)\\ \end{align}$$

So we can see the object asymptotically approaches a distance of \$\frac {v_0} {D}\$ from its initial position.

Answer 2

I looked at the Box2D source code, where it applies damping:

v *= b2Clamp(1.0f - h * b->m_linearDamping, 0.0f, 1.0f);

So the loss of velocity is certainly not a fixed number of units per second, despite what the manual says.

Your example of 10m/s to 1m/s would also slightly depend on timestep. Let's assume 120Hz simulation step...

#!/usr/bin/python

v = 10
step = 0
h = 1/120.0
time = 0.0

while v > 1 :
    v *= ( 1 - h * 0.5 )
    step += 1
    time += h
    print( "step %d, time %f, v %f" % ( step, time, v ) )

Then it would take 4.6 seconds to slow down by that much.

...
step 551, time 4.591667, v 1.001957
step 552, time 4.600000, v 0.997783

I checked with 1/60 timestep as well, and the result is almost the same, btw.

I am not sure if you can determine this time delay in a single expression, though, without stepping through it.