Inertial stuck mode for friction models

[m-kormann]

The current implementation of the friction models require the velocity to be selected as state. This is not the case for all model configurations (e. g. a MultiBody crankshaft connected to a translational bearing). The problem can be reduced to this exemplary model:

This can be solved by introducing an inertial stuck mode as described in the documentation of this PR:

If the velocity of the friction element is not selected as state (e. g. if connected to MultiBody elements like a crancshaft), the fix point iteration will not be able to solve the set of equations when leaving the stuck mode. In this case the acceleration is overdetermined by the external constrait a <> 0 and the stuck mode equation a = 0. Now that we already became comfortable with a non-zero but extremly small velocity in stuck mode, we can introduce another assumption: When locked, the block is fixed to a extremely huge mass. This means it can move in stuck mode, but then implies a huge friction force. These high values will not enter the integrator, because they only act during fix point iteration and directly lead to leaving the stuck mode. For better parametrization not the mass (or the moment of inertia in rotational case) but rather the inverse mass m_inv_fixed will be the input parameter. By default it is set to zero and implies exactly the same behaviour as the set of equations above. At fix point iteration problems it can be set to a small value (e. g. 1e-15) meaning a huge mass. This results in a slightly modified set of equations:

// part of mixed system of equations
startFor  = pre(mode) == Stuck and sa >  1;
startBack = pre(mode) == Stuck and sa < -1;
        a = der(v);
        a = if pre(mode) == Forward  or startFor  then  sa - 1    elseif
               pre(mode) == Backward or startBack then  sa + 1    else m_inv*f;
        f = if pre(mode) == Forward or startFor   then  f0 + f1*v elseif
               pre(mode) == Backward or startBack then -f0 + f1*v else f0*sa;

// state machine to determine configuration
mode = if (pre(mode) == Forward  or startFor)  and v>0 then Forward  elseif
          (pre(mode) == Backward or startBack) and v<0 then Backward else Stuck;

Summary by CodeRabbit

• New Features

  • Introduced advanced friction parameters that improve simulation fidelity by refining locked-state dynamics in both rotational and translational models.
  • Added new test models featuring enhanced inertial effects and updated oscillation phase configurations for more accurate dynamic behavior.

• Documentation

  • Expanded the user guide with a new section detailing the updated friction element behavior under fixed-state conditions and offering enhanced configuration guidance.

[m-kormann]

Well on default parameters this change does not change the behavior at all and all existing tests should have the same results.

If we set a value of m_inv_fixed = 1e-15 instead of zero, the behavior will be different, but at very low scale. So we cannot compare with the original behavior. Should we add a test if the results are similar?