KinematicsSolver

Solve kinematics problems for a multibody model

Description

KinematicsSolver objects allow users to formulate and numerically solve kinematics problems for their Simscape™ Multibody™ models. You can use the object to solve standard forward and inverse kinematics problems, as well as more general problems with closed-loop kinematic systems and multiple targets.

A kinematics problem is formulated using kinematic variables. These variables have scalar values that specify the relationships between frames in the corresponding Simscape Multibody model. There are two types of kinematic variables: joint and frame. Joint variables correspond to joint position and velocity states and are created automatically when the object is constructed. You can view the joint variables using the jointPositionVariables and jointVelocityVariables object functions. Frame variables correspond to position and velocity relationships between arbitrary frames in the model and must be defined using the addFrameVariables object function. Once defined, they can be viewed using the frameVariables object function.

To formulate a kinematics problem, you must assign roles for the relevant kinematic variables. There are three roles: targets, initial guesses, and outputs. Variables are assigned to these roles using the addTargetVariables , addInitialGuessVariables, and addOutputVariables object function. To solve the problem with the assigned variables, use the solve object function. Starting from an initial state, the solver attempts to find a final state of the system consistent with the values of the target variables. The initial state is synthesized using the values of the initial guess variables. The initial states that are not specified by initial guess variables are initialized to zero. The values of the output variables are derived from the final state returned by the solver. If the solver is unable to find a final state that satisfies all the targets, it tries to at least return a state that is kinematically feasible.

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. Joint targets, and actuation inputs are ignored, as is joint mode—disengaged joints are always treated as normal. 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.

ks = simscape.multibody.KinematicsSolver(modelName,Name,Value) creates a KinematicsSolver object with new default units for joint variables. Use the Name-Value pair arguments DefaultAngleUnit, DefaultLengthUnit, DefaultLinearVelocityUnit, and DefaultAngularVelocityUnit to specify your own default units.

Properties

expand all

Name of the Simscape Multibody model from which the object derives.

Example: 'sm_four_bar'

Data Types: char | string

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

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

Example: 'rad/s'

Data Types: char | string

Unit of translation 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

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

Example: 'in/s'

Data Types: char | string

Object Functions

expand all

frameVariablesList all kinematic variables associated with frame pairs
initialGuessVariablesList all kinematic variables assigned as initial guesses
jointVelocityVariablesList all kinematic variables associated with joint velocities
jointPositionVariablesList all kinematic variables associated with joint positions
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
setVariableUnitChange physical unit of kinematic variable
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
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
solveRun kinematic analysis for KinematicsSolver object
generateCodeGenerate C code to run kinematic analysis on KinematicsSolver object
viewSolutionOpen Kinematics Solver Viewer window to visualize KinematicsSolver solution
closeViewerClose the Kinematics Solver Viewer window

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.

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

    The object contains a kinematic representation of the model and a list of all the joint variables that it contains. Enter jointPositionVariables(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';
    addFrameVariables(ks,'Hand','translation',base,follower);
    addFrameVariables(ks,'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 frameVariables(ks) 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.

    jointPositionVariables(ks)
    targetIDs = ["j2.Rz.q";"j6.Rz.q";"j7.Rz.q";"j8.Rz.q"];
    addTargetVariables(ks,targetIDs);

    The joint variables are referenced by position in the ID column of the joint variables table. Use jointPositionVariables(ks) to determine which joint variables to specify. Entries j2.Rz.q, j6.Rz.q, j7.Rz.q, and j8.Rz.q correspond respectively to the elbow, shoulder frontal, shoulder sagittal, and wrist joints.

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

    frameVariables(ks)
    outputIDs = ["Hand.Translation.x";"Hand.Translation.y";...
    "Hand.Translation.z";"Hand.Rotation.x";"Hand.Rotation.y";"Hand.Rotation.z"];
    addOutputVariables(ks,outputIDs);

    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 = solve(ks,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. View the Solution.

    viewSolution(ks);

  7. Close the viewer.

    closeViewer(ks);
  8. 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.

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

    The object contains a kinematic representation of the model and a list of all the joint variables that it contains. Enter jointPositionVariables(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';
    addFrameVariables(ks,'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 frameVariables(ks) 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.

    frameVariables(ks)
    targetIDs = ["Hand.Translation.x";"Hand.Translation.y";"Hand.Translation.z"];
    addTargetVariables(ks,targetIDs);

    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.

    jointPositionVariables(ks)
    outputIDs = ["j2.Rz.q";"j6.Rz.q";"j7.Rz.q";"j8.Rz.q"];
    addOutputVariables(ks,["j2.Rz.q";"j6.Rz.q";"j7.Rz.q";"j8.Rz.q"]);

    The joint variables are referenced by position in the ID column of the joint variables table. Use jointPositionVariables(ks) to determine which joint variables to specify. Entries j2.Rz.q, j6.Rz.q, j7.Rz.q, and j8.Rz.q 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 [0.16,-0.12,0] m.

    targets = [0.16,-0.12,0];
    outputVec = solve(ks,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. Visualize the solution in the Kinematics Solver Viewer and determine if it is reasonable.

    viewSolution(ks);

    Click Front View button on the toolstrip to view the result.

    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.

    addInitialGuessVariables(ks,"j2.Rz.q");
    guesses = -50;
    outputVec = solve(ks,targets,guesses)

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

    outputVec =
    
      -52.8406
     -108.3936
       55.5089
       43.6655
  8. Click the Update Visualization button to update the Kinematics Solver Viewer to visualize the results.

  9. Close the viewer.

    closeViewer(ks);
  10. Clear all target and output variables to ready the ks object for another analysis.

    ks.clearTargetVariables;
    ks.clearOutputVariables;

Introduced in R2019a