# Documentation

## Applying Motions and Forces

The SimMechanics™ Actuators & Sensors library provides a set of Actuator blocks that enable you to apply time-dependent forces and motions to bodies, joints, and drivers. You can also vary a body's mass and inertia tensor.

 Caution   Do not connect an Actuator to a Ground. An error results if you attempt to simulate or update a model containing such a connection. This is because ground is immobile and cannot be actuated.

You can use Actuator blocks to perform the following tasks:

• Apply a time-varying force or torque to a body or joint.

• Specify the position, velocity, and acceleration of a joint or driver as a function of time.

• Specify the initial position and velocity of a joint primitive.

• Specify the mass and/or inertia tensor of a body as a function of time.

In general, actuators can apply any combination of forces and motions to a machine provided that

• The applied forces and motions are consistent with each other and with the machine's geometry, constraints, and assembly restrictions.

• The actuation signals representing these forces and motions remain consistent when differentiated or integrated. See Stabilizing Numerical Derivatives in Actuation Signals.

• It is possible to find a unique solution for the motion of each actuated degree of freedom (DoF).

#### Stabilizing Numerical Derivatives in Actuation Signals

To actuate a physical system modeled by blocks, you often need to differentiate an incoming Simulink® signal.

Simulink provides a Derivative block for numerical differentiation of a signal. However, this block's output is sometimes not stable or accurate enough for physical modeling purposes. Recommended alternatives to the Derivative block include the following.

Integrating Higher Derivative Signals.  Start by specifying the highest derivative signal (such as an acceleration), then integrate this signal to obtain lower derivative signals (such as a velocity) using the Integrator block.

Transforming Signals with Transfer Functions.  To differentiate a signal, use a transfer function block (Transfer Fcn). This block actually performs a Laplace transform convolution to smooth the output, which is not exactly the derivative.

You can eliminate this drawback by filtering the original signal f, then defining exact derivatives dF/dt, etc., of the filtered signal F by adding higher orders to the transfer function numerator. The order of the denominator should be equal to or greater than the number of output signals. Use the filtered signal F (instead of f), as well as the filtered derivatives.

In this example, the constant τ represents a smoothing time. The transfer functions define a filtered signal and its first derivative, two signals in all. Therefore, the transfer function denominator should be second order or higher.

#### Examples of Numerical Derivatives of Actuator Signals

A SimMechanics example requiring numerical derivatives is motion actuation of a joint, which requires position, velocity, and acceleration of each joint primitive as a function of time. You specify this information as a set of Simulink signals, which you can stabilize with one of the previous methods.

The transfer function method is illustrated by the `mech_stewart_control` model. For an example of the derivative-integration method, see the `mech_body_driver` model.

### Actuating a Body

You can use the Body Actuator to apply forces and/or torques, but not motions, to bodies. (You can apply motions to a body indirectly, using Joint Actuators. See Applying Motions to Bodies.)

To actuate a body,

1. If there is not already an unused connector port available for the Actuator create a Body CS port on the Body for the Actuator. See the Body block reference if you need to learn how.

2. Drag a Body Actuator block from the Sensors & Actuators library into your model and connect its output port to a Body CS port on the Body.

3. Open the Actuator's dialog box.

4. Choose to apply a force or torque to the body:

• Select the Applied force check box if you want to apply a force to the body, and select the units of force from the adjacent list.

• Select the Applied torque check box if you want to apply a torque to the body, and select the units of torque from the adjacent list.

5. Select the coordinate system used to specify the applied torque from the With respect to CS list.

The list allows you to choose either the World CS or the Body CS of the port to which you attached the Actuator.

6. Create vector signals that specify the value of the applied torque and force at each time step.

You can use any Simulink source block (for example, an Input port block or a Sine Wave block) or combination of Simulink blocks to create the Body Actuator signal. You can also use the output of a Sensor block connected to the Body as input to the Actuator, thereby creating a feedback loop. Such loops are useful for modeling springs and dampers (see Validating Mechanical Models).

7. Connect the force and/or torque signal to the input port of the Actuator.

If you are applying both a force and a torque to the body, connect the force and torque signals to the inputs of a two-input Mux block. Then connect the output of the Mux block to the input of the Actuator.

#### Body Actuator Example: Pure Kinetic Friction

The `mech_ballistic_kin_fric` provides an example of how to implement pure kinetic friction. This type of friction is a continuous force that depends on a body's motion relative to a medium (such as air), as well as on physical characteristics of the body. Kinetic friction, unlike "stiction," involves no "sticking" or locking of motion, and the friction is not discontinuous. While you could use the Joint Stiction Actuator, this is not necessary. This model applies air friction or drag to a projectile with a Body Actuator.

Open the Air Drag subsystem. If you double-click the block, a mask dialog box opens asking for the drag coefficient `Cd`. If you right-click the block and select Look under mask, the subsystem itself appears:

The Air Drag subsystem computes the air friction according to a standard air friction model. (See the Aerospace Blockset documentation for more information.) The drag always opposes the projectile's motion and is proportional to the product of the air density, the projectile's cross-sectional area, and the square of its speed.

Run the model with the default drag coefficient (zero). The XY Graph window opens to plot the parabolic path of the projectile. Now open the Air Drag dialog again and experiment with different drag coefficients Cd. Start with small values such as Cd = 0.05. For a rigid sphere, Cd is two. The effect of the drag is dramatic in that case.

#### Applying Motions to Bodies

The Body Actuator block cannot actuate a Body with motion signals. But you can construct such body motion actuators with a combination of other blocks. See Joint Actuator Example: Body Driver.

### Varying a Body's Mass and Inertia Tensor

The Variable Mass & Inertia Actuator block gives you a way to vary a body's mass and/or inertia tensor as external functions of time. You specify these functions with incoming Simulink signals.

 Caution   The Variable Mass & Inertia Actuator block does not apply any thrust forces or torques to the Body so actuated. Mass loss or gain in a particular direction results in thrust forces and torques on the body. You must apply these forces/torques to the Body separately with Body Actuator blocks.The variable mass/inertia actuator affects a body's motion only when you apply forces/torques on the body. When a body's motion is determined only by initial conditions, changing the mass or inertia tensor of a body does not affect its motion, because the variable mass/inertia actuator does not apply forces/torques to the body.

The Variable Mass & Inertia Actuator block changes the actuated Body's mass and rotational inertia by attaching an invisible body to the actuated body at a particular Body coordinate system (CS). This invisible body has a mass and an inertia tensor that vary in time as specified by the Actuator's external Simulink signal. The simulation treats the actuated body and the invisible body as a single composite body. The composite body has a new mass, new center of gravity (CG), and new inertia tensor compounded from its two constituent bodies.

You can add multiple Variable Mass & Inertia Actuator blocks to one Body. In that case, the simulation treats the actuated body and all attached invisible bodies as a single composite body. This composite body's mass, CG, and inertia tensor are compounded from its constituent bodies.

Attaching Variable Mass and Inertia Bodies to a Visible Body

To vary the mass and/or inertia tensor of a Body with this Actuator:

1. From the Sensors & Actuators library, drag a Variable Mass & Inertia Actuator block into your model.

2. Attach the Actuator's connector port to the Body CS on the Body where you want the invisible variable mass to be. If a suitable Body CS port does not exist on the Body, open its dialog and create one.

3. Create an external Simulink signal to model the time-varying mass and/or inertia tensor for this invisible body. Connect it to the Variable Mass & Inertia Actuator block's Simulink input port.

This Simulink signal can have one, nine, or ten components, depending on whether you are varying the mass only, the inertia tensor only, or both.

#### Example: Simple Rocket

The following model simulates a simple rocket. It treats the rocket as a point mass moving upward (+y direction) with an exhaust pointing downward (-y direction). The rocket loses mass at a constant rate.

The Rocket block is the point mass. The Thrust Velocity block represents the downward exhaust and, multiplied by the mass loss represented by the Fuel Loss block, actuates the Rocket body with a thrust force pointing upward. The Thrust block (a body actuator) applies this force at the local Body CS, which, for a point rocket, is identical to the Rocket's CG CS.

The same mass loss from the Fuel Loss block that produces the thrust force also must vary the rocket's mass directly. The Variable Mass Actuator block accomplishes this by feeding the same mass loss signal to the Rocket block.

### Actuating a Joint

You individually actuate each of the prismatic and revolute primitives of an assembled joint with a Joint Actuator. You can apply

• Forces or translational motions (but not both) to prismatic primitives

• Torques or rotational motions (but not both) to revolute primitives

 Caution   You cannot actuate spherical or weld primitives, disassembled joints, or massless connectors.Do not connect multiple Actuators to the same joint primitive. An error results if you attempt to update or simulate a model containing such a connection.Exception: You can apply a Joint Initial Condition Actuator and force or torque actuation (including stiction) to the same primitive. You cannot apply a Joint Initial Condition Actuator and motion actuation to the same primitive. See Specifying Initial Positions and Velocities.

#### Actuating a Joint Primitive

 Tip   If you have multiple forces/torques or motions you want to apply to a joint primitive, sum their values as Simulink signals first, then apply the net result as the input to the Joint Actuator.

To actuate a prismatic or revolute joint primitive of an assembled joint:

1. Create an Actuator port on the Joint block for the primitive (see Creating Actuator and Sensor Ports on a Joint).

2. Drag a Joint Actuator or Joint Stiction Actuator from the Sensors & Actuators library into your model and connect its output port to the Actuator port on the Joint.

The remaining steps in this procedure apply to the creation of a standard Joint Actuator. For information on creating a stiction actuator, which applies classical Coulombic friction to a prismatic or revolute joint, see the Joint Stiction Actuator block reference page.

3. Open the Joint Actuator's dialog box.

4. Select the primitive you want to actuate from the Connected to primitive list on the dialog box.

5. Select the type of actuation you want to apply from the Actuate with pull-down menu, either `Generalized Forces` or `Motion`.

6. If you are actuating a prismatic primitive:

• If you selected `Generalized Forces` as the actuation type, select the units of force from the Applied force units list.

• If you selected `Motion` as the actuation type, select the units for each motion to be actuated (position, velocity, acceleration).

7. If you are actuating a revolute primitive:

• If you selected `Generalized Forces` as the actuation type, select the units of torque from the Applied torque units list.

• If you selected `Motion` as the actuation type, select the units for each motion to be actuated (angle, angular velocity, angular acceleration).

8. Click OK to apply your choices and dismiss the dialog box.

Each joint primitive that you motion-actuate is lost as a true degree of freedom in your machine. That is because the DoF can no longer respond freely to externally applied forces or torques. See Counting Model Degrees of Freedom.

9. Create a signal that specifies the applied force, torque, or motions at each time step.

You can use any Simulink source block or any combination of blocks to create the actuator signal. You can also connect the output of a Sensor block attached to the Joint to the Actuator input, thereby creating a feedback loop. You can use such loops to model springs and dampers attached to the joint.

A force or torque signal must be a scalar signal. A motion signal must be a 1-D array signal comprising three components: position, velocity, and acceleration. The directionality of the joint determines the response of the follower to the sign of the actuator signal (see Joint Directionality).

10. Connect the Actuator signal to the Actuator port on the Joint.

#### Joint Actuator Example: Body Driver

The `mech_body_driver` model illustrates the use of Joint Actuators to create a custom driver.

The Body Driver subsystem accepts an 18-component signal that feeds the coordinates, velocities, and accelerations for all six relative DoFs between Body and Body1. The subsystem uses a Bushing block that contains three translational and three rotational primitives to represent the relative DoFs:

You can modify the body driver to move only one of the bodies, thereby creating a motion actuator. To move Body1 relative to World, for example, remove the blocks Body and Weld and connect the subsystem Body Driver directly to Ground.

#### Joint Stiction Actuator Example: Mixed Static and Kinetic Friction

 Tip   You should use the Joint Stiction Actuator block only if you need static (locking) friction that removes one or more degrees of freedom from your machine.You can model pure kinetic friction (damping) with other Actuator and Sensor blocks. See Actuating a Body and Adding Internal Forces.

The `mech_dpen_sticky` model illustrates a driven double pendulum, with "sticky" friction or stiction applied to both revolute joints with the Joint Stiction Actuator block.

Open the unmasked Joint1 or Joint2 Stiction Model blocks (marked in yellow) to view the subsystems:

Each Stiction subsystem contains a Joint Stiction Actuator block (marked in orange) that requires static and kinetic friction coefficients via their respective blocks. For either revolute, an angular velocity threshold, specified through the block dialog, determines if a joint locks. Once locked, the joint cannot move until a combination of forces reaches a threshold specified by the `Forward Stiction Limit` or ```Reverse Stiction Limit```.

Run the model with different kinetic and static friction coefficients and different velocity thresholds. View the results in the Scope blocks and through a visualization window. You can find more details on how SimMechanics stiction works by consulting the Joint Stiction Actuator block reference page.

### Actuating a Driver

Actuating a Driver with a Driver Actuator allows you to specify the time dependence of the rheonomic constraint applied by the Driver.

To actuate a Driver:

1. Create an additional connector port on the Driver for the Actuator.

Create the additional port in the same way you create an additional Sensor/Actuator port on a Joint (see Creating Actuator and Sensor Ports on a Joint).

2. Drag an instance of a Driver Actuator from the Sensors & Actuators library into your model.

3. Connect the Actuator's output port to the Actuator port on the Driver.

4. Create a signal that specifies the time dependence of the Driver constraint.

5. Connect the actuation signal to the input port of the Driver Actuator.

### Specifying Initial Positions and Velocities

The Joint Initial Condition Actuator (JICA) block allows you to specify the initial positions and velocities of unactuated joints and hence the bodies attached to them. You can use JICA blocks to

• Specify nonzero initial joint velocities

The default initial velocity of a joint primitive is zero. You must use a JICA block to specify a joint's initial velocity if the initial velocity is not zero.

• Override the initial position settings of a body pair

The CG CS origin settings in the dialog boxes of Body blocks specify the bodies' initial positions. Using JICA blocks, you can override these initial body positions by resetting their relative positions in the Joints connecting them.

Your model simulation starts with your machines at first in their home configurations, defined by the Body dialog data. It then transforms your machines to their initial configurations by applying JICA data.

 Caution   You cannot simultaneously actuate a joint primitive with a Joint Initial Condition Actuator and motion actuation from a Joint Actuator block.

#### Using JICA Blocks

Specifying initial conditions on a joint primitive is a special kind of actuation, one that occurs only once at the beginning of simulation. That is why the JICA block resides in the Sensors & Actuators library.

 Note:   A JICA block, unlike other Actuators, does not have an input port. The JICA's dialog box specifies the Actuator input completely.

With a JICA block, you can specify the initial positions and velocities of any combination of prismatic and revolute primitives within a given Joint. (You cannot specify ICs for spherical and weld primitives.)

To specify the initial velocity and/or position of a joint primitive:

1. Drag a JICA block from the Sensors & Actuators library and drop it into your model window.

2. Create an additional connector port on the Joint block containing the primitive whose initial condition you want to specify.

3. Connect the connector port on the JICA block to the new connector port on the Joint block.

 Caution   Do not connect the JICA block to the Joint ports marked "B" or "F" (base or follower). These ports are intended for connecting to Bodies.
4. Open the JICA block's dialog box. From the primitive list for the Joint, choose the primitives you want to actuate by selecting their check boxes.

5. Enter the initial positions of the actuated primitives, relative to the Body CSs attached to the Joint, in the Position field.

From the pull-down menu on the right, select Units for the initial positions.

6. Enter the initial velocities of the actuated primitives, relative to the Body CSs attached to the Joint, in the Velocity field.

From the pull-down menu on the right, select Units for the initial velocities.

7. Click Apply or OK.

#### JICA Example: A Simple Pendulum

Open `mech_spen` , then open the Sensors & Actuators library. Follow the steps from the preceding section, Using JICA Blocks, to connect one Joint Initial Condition Actuator block to the Revolute block and configure it. This Joint contains only one primitive, `R1`, which is the primitive listed in the JICA dialog box.

Set the initial conditions in two ways and compare the resulting simulations in the scope:

1. First set the initial Position (angle) to `60 deg`, which is 60o down from the left horizontal (30o clockwise from vertically down), and set the initial Velocity to ```0 deg/s```.

2. Run the simulation for one second. Note in the scope that the initial angle (yellow curve) is displaced upward to 60o, while the initial velocity (purple curve) still starts at zero.

3. Now reset the initial Velocity to `30 deg/s`, leaving the initial Position (angle) at ```60 deg```.

4. Rerun the simulation for one second. Note in Scope that the initial angle is still displaced upward to 60o, but the initial velocity is also displaced upward to 30o/sec.

The joint directionality is assigned in `mech_spen` so that the positive rotation axis is the +z-axis. Looking from the front, positive rotation swings down and right, counterclockwise.