MassSpringDamperModel

MassSpringDamperModel simulates a point mass on a spring and damper, coupled to a neighbouring model. Its purpose is chains: connect several instances and you have a flexible structure, a series-elastic joint, or a multi-body compliance model built from copies of one block.

It does both compliance directions in one block. By default it behaves like an admittance — force in, motion out. Set enableImpedance and it behaves like an impedance — motion in, force out — and adds an inertia term to its output force.

flowchart LR
    i1(["inputForce — external force on the mass"]) --> B["MassSpringDamperModel"]
    i2(["inputState — external state, impedance mode only"]) --> B
    i3(["connectedForce — force from the next model"]) --> B
    i4(["connectedState — state of the previous model"]) --> B
    B --> o1(["outputState — this mass's motion"])
    B --> o2(["outputForce — coupling force"])
    B --> o3(["mass — effective mass"])
    B --> o4(["damping — effective damping"])
    B --> o5(["stiffness — effective stiffness"])
    B --> o6(["relativePosition — spring extension"])
    B --> o7(["relativeVelocity"])

The mass obeys $M\ddot{x} =$ inputForce $+$ connectedForce $-$ outputForce, and the coupling force is $K,\Delta x + D,\Delta\dot{x}$, plus $M,\Delta\ddot{x}$ in impedance mode. Aim at $\omega_n = \sqrt{K/M}$ [rad/s] and $\zeta = D/(2\sqrt{KM})$ — target $\zeta$ near 1. Keep the task period below $2/\omega_n$ or the simulation grows without bound; nothing checks this.

To build a chain: connect this model’s outputForce to the previous model’s connectedForce, and the previous model’s outputState to this one’s connectedState. The spring anchors on connectedState.

This block has no enable and no disable. disableDynamics pins the motion to connectedState but still publishes a coupling force, so a chain keeps transmitting while it is set.

Signals

Inputs

Outputs

Parameters

All six are persistent and survive a restart.

The three coefficients live below this block, as lookup tables: massLookup driven by this mass’s own position, dampingLookup by the relative velocity, and stiffnessLookup by the relative position. Each ships as a single point at 1.0. The two integrators — velocityIntegrator and positionIntegrator — carry the motion limits. See lookup.md and integrator.md.

Never let massLookup return zero. The mass divides the net force, and a zero mass makes the simulation non-numeric. A table that is not strictly increasing in x also returns zero, so check monotonicity as well as values.

Setup

1. Configure massLookup with the mass you want this point to have. A single point is enough if it does not vary with position. Confirm it never returns zero.

2. Configure dampingLookup and stiffnessLookup. Start with a low stiffness and generous damping — a soft, well-damped model is safe to experiment with.

3. Compute $\omega_n = \sqrt{K/M}$ and check the task period is below $2/\omega_n$, comfortably. A stiff spring on a slow task will not simulate; it will diverge.

   Step 3 is the check nothing does for you. There is no warning and no clamp. Too stiff a spring for the task rate makes outputState grow without bound, and the only way out is a restart.

4. Set the integrators' output limits to the travel and speed this mass may have.

5. Leave enableImpedance false for a first pass. Link inputForce and watch outputState respond.

6. Read mass, damping and stiffness back and confirm they are the values you intended. They are the gain times the table output.

7. To chain: link this model’s outputForce to the previous model’s connectedForce, and that model’s outputState to this one’s connectedState. Build the chain one link at a time and check each is stable before adding the next.

Tuning

1. Set the mass first, from the physical mass this point represents.
2. Set the stiffness from the compliance you are modelling. For a series-elastic joint that is the spring’s real rate.
3. Set the damping for stability: compute $\zeta = D/(2\sqrt{KM})$ and aim near
   1. Below about 0.5 the model rings, and in a chain that ringing couples between links.
4. Re-check step 3 of Setup after every stiffness or mass change. The stability bound moves with both.
5. Use the tables rather than the gains for anything non-linear — a progressive spring, or a damper that softens at speed.
6. Choose the mode deliberately, and not mid-run. Switching enableImpedance changes which inputs matter: admittance mode ignores inputState, and impedance mode stops using this block’s own position for the coupling force.
7. In a chain, tune from one end. Each link’s connectedState is the previous link’s output, so an unstable link destabilises everything after it.

Read the damping ratio off the overshoot on any curve.

A starting point for a soft, well-damped single mass on a 1 ms task — $\omega_n$ = 4.5 rad/s, $\zeta$ = 1.1, comfortably inside the stability bound:

enableImpedance    = false
massGain           = 1.0
stiffnessGain      = 1.0
dampingGain        = 1.0
disableDynamics    = false
inputForceDeadZone = 0.1
massLookup:      numPoints = 1, x = 0, y = 1.0
stiffnessLookup: numPoints = 1, x = 0, y = 20.0
dampingLookup:   numPoints = 1, x = 0, y = 10.0

This is a starting point, not a final tuning.

Limits and errors

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).