KinematicsSolver

Kinematic representation of multibody model to analyze

Description

The KinematicsSolver object contains a kinematic representation of a multibody model around which to formulate, and for which to solve, a kinematic problem. The analysis can be the standard inverse or forward kinematics or it can be another type. The distinction rests solely on the variables known and sought, and of these many arrangements are possible.

A new object contains only some of the kinematic variables likely to feature in the kinematic analysis. These it inherits from the model. It also has no indication of which variables to compute and which to assume for its arguments. The task of preparing the analysis is one of adding variables to the object and assigning them to suitable roles. Variables derive either from joints or from frame pairs:

  • Joint variables

    The displacements of joint primitives. They are translations for prismatic primitives and rotations for revolute and spherical primitives. Spherical rotations bundle with auxiliary variables to express also the vector components of the 3-D rotation axis.

    The KinematicsSolver object contains all joint variables compatible with the underlying model from its start. Those variables are a snapshot of the model as it is when the object is created. You can neither add nor drop them.

  • Frame variables

    The transforms between select frame pairs. The pairs are often from bodies not connected by joints, the world sometimes in the place of a body. The transforms can be translations or rotations from one frame (the base) to the second (the follower).

    The KinematicsSolver object starts without frame variables. Those that it gains result from calls to addFrameVariables. You can drop them if they turn obsolete. Use removeFrameVariables to remove a few at a time and clearFrameVariables to remove them all in one call.

Consider a robotic arm with revolute joints for its shoulder, elbow, and wrist. The revolute angles each suit a joint variable. The position of the hand relative to the shoulder, two bodies which do not normally connect through joints, require a group of frame variables—one each for the x, y, and z position offsets between the bodies, or, more precisely, between frames local to them.

The source of a variable does not determine its role in the analysis. A joint variable can be an input argument or an output argument. So can a frame variable. The KinematicsSolver object recognises two input types: targets to aim for and guesses to start the analysis from, the latter to bias the solution when alternatives exist.

Targets and outputs feature in a typical analysis. Guesses are less common but valuable in problems with multiple solutions, as a means to bias the solver toward one thought suitable. In a robotic arm, a guess for the elbow helps to keep its rotation angle in the natural range of 0145 degrees during analysis. The KinematicsSolver object provides methods for each role:

  • Target variables

    Use the addTargetVariables object function to assign joint and frame variables as targets. Use removeTargetVariables to drop one or a few from the KinematicsSolver object and clearTargetVariables to drop them all in one call.

    Targets work with a caveat: conflicts with constraints in the model, some posed by still other targets, may keep them all from being precisely satisfied. Targets guide but do not force joints and bodies into place for analysis. The unknowns are solved for whatever multibody configuration the targets manage to produce.

  • Output variables

    Use the addOutputVariables object function to assign joint and frame variables as outputs. Use removeOutputVariables to drop one or a few from the KinematicsSolver object and clearOutputVariables to drop them all in one call.

  • Guess variables

    Use the addInitialGuessVariables object function to assign joint and frame variables as guesses. Use removeInitialGuessVariables to drop one or a few from the KinematicsSolver object and clearInitialGuessVariables to drop them all in one call.

See the figure for a summary of the variables and their roles in a KinematicsSolver object. An object can have joint variables (J) and frame variables (F). These can serve as targets (T) to guide assembly during analysis, as guesses (G) to bias the solution toward a suitable configuration, and as outputs (O), the unknowns to solve for and report on. Variables assigned as targets cannot double as guesses but they each can double as output.

The KinematicsSolver object is ready for analysis once the necessary kinematic variables are in place and their roles are set. For inverse kinematics of the robotic arm, for example, it suffices to create three frame variables—one each for a translation component between hand and shoulder frames. Joint frames are native to the object and available from the start. Assigning the frame variables as targets and the joint variables as outputs readies the object for analysis.

To run the analysis, the object provides a solver. Call it using the solve object function. The function takes the numerical values of the targets and guesses as input to calculate the outputs. Often, if the specified targets are within reach, these can be satisfied. Such an outcome is not always possible. A target may be out of the reach of the solver, for example.

To warn of such issues, the solver returns not only the actual values achieved for the variables assigned as targets, but also a series of flags. One gives the overall assembly status. If any target is missed or constraint violated, or if the solution leaves the assembly in a singular configuration and so with reduced mobility, it will reflect there. The remainder appear in a vector indicating which targets were satisfied and which were not.

Creation

Syntax

ks = simscape.multibody.KinematicsSolver(modelName)
ks = simscape.multibody.KinematicsSolver(modelName,Name,Value)

Description

ks = simscape.multibody.KinematicsSolver(modelName) creates a KinematicsSolver object for the model named in mdl. The object contains a representation of the model suitable for kinematic analysis. The representation is a snapshot of the model as it is when the object is created. Subsequent changes to the model do not carry over to the object. Create a new object, if necessary to capture those changes.

The model must contain a Simscape Multibody network. It must also be loaded to memory—for example by use of the load_system command. If blocks are parameterized in terms of MATLAB variables, those variables must be numerically defined in the model workspace or in the MATLAB workspace. Position targets and actuation inputs for joint blocks are ignored. Block parameters set to Run-Time are evaluated when creating the object and cannot be modified afterward.

A KinematicsSolver object is a handle object. A variable created from it contains not a copy of the object but a reference to it. The variable acts as a pointer or handle. Modifying a handle modifies also the object and all of its remaining handles. Copying a KinematicsSolver object and adding a frame variable to the copy, for example, adds that frame variable to the object and so also to any other handles it might have.

Note

Do not save a KinematicsSolver object to a MAT file. Important detail about the underlying model is lost during the save. The object becomes unusable once reloaded into MATLAB.

ks = simscape.multibody.KinematicsSolver(modelName,Name,Value) creates a KinematicsSolver object with new defaults for units of angle or length. Use the Name-Value pair arguments DefaultAngleUnit and DefaultLengthUnit to specify the new defaults.

Properties

expand all

This property is read-only.

Name of the model from which the object derives.

Example: 'sm_four_bar'

Data Types: char | string

This property is read-only.

Unit of angle for new kinematic variables. The default is deg. A change in default units affects only variables added after the change. Older variables remain in their original units.

Example: 'rad'

Data Types: char | string

This property is read-only.

Unit of length for new kinematic variables. The default is m. A change in default units affects only variables added after the change. Older variables remain in their original units.

Example: 'in'

Data Types: char | string

Object Functions

expand all

frameVariablesList all kinematic variables associated with frame pairs
initialGuessVariablesList all kinematic variables assigned as initial guesses
jointVariablesList all kinematic variables associated with joints
outputVariablesList all kinematic variables assigned as outputs
targetVariablesList kinematic variables assigned as targets
addFrameVariablesCreate kinematic variables from select frame pair in KinematicsSolver object
addInitialGuessVariablesAssign kinematic variables from the KinematicsSolver object as guesses
addOutputVariablesAssign kinematic variables from the KinematicsSolver object as outputs
addTargetVariablesAssign kinematic variables from the KinematicsSolver object as targets
clearFrameVariablesDrop all frame variables from the KinematicsSolver object
clearInitialGuessVariablesDrop all guess variables from the KinematicsSolver object
clearOutputVariablesDrop all output variables from the KinematicsSolver object
clearTargetVariablesDrop all target variables from the KinematicsSolver object
removeFrameVariablesDrop select frame variables from the KinematicsSolver object
removeInitialGuessVariablesDrop select guess variables from the KinematicsSolver object
removeOutputVariablesDrop select output variables from the KinematicsSolver object
removeTargetVariablesDrop select target variables from the KinematicsSolver object
generateCodeGenerate C code to run kinematic analysis on KinematicsSolver object
setVariableUnitChange physical unit of kinematic variable
solveRun kinematic analysis for KinematicsSolver object

Examples

collapse all

Run forward kinematics on a model of a humanoid robot arm. The model is named sm_import_humanoid_urdf, and it is part of the Simscape Multibody installation. For the analysis, specify the rotations of the wrist, elbow, and shoulder joints. Solve for the translation and rotation of the hand in the world frame.

  1. Load the humanoid robot model into memory and create KinematicsSolver object for its current state.

    sys = 'sm_import_humanoid_urdf';
    load_system(sys);
    ks = simscape.multibody.KinematicsSolver(sys);

    The object contains a kinematic representation of the model and a list of all the joint variables that it contains. Enter ks.JointVariables or jointVariables(ks) at the MATLAB command prompt to list those variables when necessary. Open the model for use as reference by entering its name at the MATLAB command prompt.

  2. Add to ks a group of frame variables for the hand relative to the world. Specify the F frame of the left_hand subsystem as follower and the world frame as base. Name the frame variable group Hand.

    base = 'sm_import_humanoid_urdf/World/W';
    follower = 'sm_import_humanoid_urdf/left_hand/F';
    ks.addFrameVariables('Hand','translation',base,follower);
    ks.addFrameVariables('Hand','rotation',base,follower);

    The object gains its first six frame variables—three for the x, y, and z translation components and three for the x, y, and z rotation components, each from the world frame to the F frame of the hand. Enter ks.frameVariables at the MATLAB command prompt to list those variables when necessary.

    The paths in base and follower are the full block paths from the root of the model to the port of the block associated with the port desired. That port is W in the World Frame block for the base frame and F of the left_hand subsystem block for the follower.

  3. Assign as targets the joint variables for the left wrist, elbow, and shoulder.

    ks.addTargetVariables(ks.jointVariables.ID([2,6:8]));

    The joint variables are referenced by position in the ID column of the joint variables table. Use jointVariables to determine which joint variables to specify. Entries 2, 6, 7, and 8 correspond respectively to the elbow, shoulder frontal, shoulder sagittal, and wrist joints.

  4. Assign as outputs all the frame variables in the Hand group.

    ks.addOutputVariables(ks.frameVariables.ID);

    Not all frame variables need feature in the analysis. Use the frameVariables function to list all frame variables and determine which to specify when necessary.

  5. Solve the forward kinematics problem given the elbow, shoulder frontal, shoulder sagittal, and wrist joint angles of 30, 45, 45, and 15 degrees.

    targets = [30,45,45,15];
    outputVec = ks.solve(targets)
    outputVec =
    
        0.2196
        0.0584
       -0.0983
      135.0000
        0.0027
             0

    The solve function returns the values of the output variables. The values are sorted in the order of the variables—translation components first, rotation components second. The units are the defaults of m, for translation components, and deg, for rotation components.

  6. Clear all target and output variables to ready the ks object for another analysis.

    ks.clearTargetVariables;
    ks.clearOutputVariables;

    Use the closely related removeTargetVariables and removeOutputVariables functions to drop just a few target and output variables from the object, when necessary. Use removeFrameVariables and clearFrameVariables if some or all frame variables are no longer necessary for analysis.

  1. Load the humanoid robot model into memory and create KinematicsSolver object for its current state.

    sys = 'sm_import_humanoid_urdf';
    load_system(sys);
    ks = simscape.multibody.KinematicsSolver(sys);

    The object contains a kinematic representation of the model and a list of all the joint variables that it contains. Enter ks.JointVariables or jointVariables(ks) at the MATLAB command prompt to list those variables when necessary. Open the model for use as reference by entering its name at the MATLAB command prompt.

  2. Add to ks a group of frame variables for the hand relative to the world. Specify the F frame of the left_hand subsystem as follower and the world frame as base. Name the frame variable group Hand.

    base = 'sm_import_humanoid_urdf/World/W';
    follower = 'sm_import_humanoid_urdf/left_hand/F';
    ks.addFrameVariables('Hand','translation',base,follower);
    

    The object gains its first three frame variables, one each for the x, y, and z translation components from the world frame to the F frame of the hand. Enter ks.frameVariables at the MATLAB command prompt to list those variables when necessary.

    The paths in base and follower are the full block paths from the root of the model to the port of the block associated with the port desired. That port is W in the World Frame block for the base frame and F of the left_hand subsystem block for the follower.

  3. Assign as targets the frame variables in the Hand group.

    ks.addTargetVariables(ks.frameVariables.ID);

    Not all frame variables need feature in the analysis. Use the frameVariables function to list all frame variables and determine which to specify when necessary.

  4. Assign as outputs the joint variables for the left wrist, elbow, and shoulder.

    ks.addOutputVariables(ks.jointVariables.ID([2,6:8]));

    The joint variables are referenced by position in the ID column of the joint variables table. Use jointVariables to determine which joint variables to specify. Entries 2, 6, 7, and 8 correspond respectively to the elbow, shoulder frontal, shoulder sagittal, and wrist joints.

  5. Solve the inverse kinematics problem given the hand frame translation components of [16,-12,0] cm or, in the default units of length, [0.16,-0.12,0] m.

    targets = [0.16,-0.12,0];
    outputVec = ks.solve(targets)

    The solve function returns the values of the output variables—the rotation angles of the elbow, shoulder frontal, shoulder sagittal, and wrist joints, each in the default units of deg.

    outputVec =
    
       52.8406
     -108.3936
        7.0457
       15.0565

  6. Specify the output values as joint state targets in the sm_import_humanoid_urdf model and update the block diagram to visualize the solution in Mechanics Explorer and determine if it is reasonable.

    for i = 1:length(outputVec)
    	path = ks.outputVariables.JointVariableInfo.BlockPath(i);
    	angle = num2str(outputVec(i));
    	set_param(path, 'PositionTargetSpecify', 'on',...
    	'PositionTargetValue', angle);
    end

    Select Simulink > Update Diagram in the Simulink menu bar to update the diagram.

    The hand is in the right place, but the elbow has an unnatural bend outside of its normal range of motion. The solution is merely one of several and a better one is possible by specifying the elbow rotation as a guess variable.

  7. Set the elbow joint variable—the only that needs guidance—as a guess variable and run the analysis once again for an elbow rotation guess of -50 deg.

    ks.addInitialGuessVariables(ks.jointVariables.ID(2));
    guesses = -50;
    outputVec = ks.solve(targets,guesses);

    The solve function returns a new solution for the joint angles.

    outputVec =
    
      -52.8406
     -108.3936
       55.5089
       43.6655
  8. Specify the new outputs as joint state targets in the sm_import_humanoid_urdf model and update the block diagram to visualize the results.

    for i = 1:length(outputVec)
    	path = ks.outputVariables.JointVariableInfo.BlockPath(i);
    	angle = num2str(outputVec(i));
    	set_param(path, 'PositionTargetSpecify', 'on',...
    	'PositionTargetValue', angle);
    end

Introduced in R2019a