 Linkage Designer Package Tutorial Functions »

LinkageDesigner is an add-in package for virtual prototyping linkages. It is designed to analyze, synthesize and simulate linkages with serial chain, tree and graph structure. Using the symbolic calculation capabilities of Mathematica LinkageDesigner supports fully parametrized linkage definition and analysis too.
Linkages are modelled as multibody systems that build up from a set of constarined rigid bodies. Rigid bodies are often referred as links. Constraints between the links restricts their relative movements. These constraints are referred as joints or kinematic pairs.
The basic definition of multibody kinematics and dynamics is introduced in this tutorial, but by no means substitute to a standard text book of the topic.

In order to analyse mechanisms in LinkageDesigner they have to be digitally modelled - equivalently build the mathematical model of the mechanism. This mathematical model is stored in an internal database. This database is implemented as a new data type called LinkageData.
 LinkageData is a new data type that represents the database of the linkage

LinkageData can be considered as a small relational database that stores all the relevant information of linkages. LinkageData consist of a list records. Every record comply to a simple template {id, data}, where id is string record identifiers and data is a List.
Beside other information LinkageData stores the kinematic graph of the linkage. The edges of this graph represents the kinematic pairs, while the vertexes correspond to the links of the linkage. From kinematic point of view the links are specified with body attached frames, called Local Link Reference Frames (LLRF). The kinematic pairs are represented with parameterized homogeneous transformation matrices that constraints the relative motion of the two links.
 Record Identifier Description \$LDMechanismID defines the name of the linkage and other linkage instance specific informations (units, Workbech name, etc). \$LDDrivingVariables list of rules representing the driving variables of the linkage together with their substitutional values. \$LDSimpleParameters list of rules representing the simple parameters of the linkage together with their substitutional values. \$LDStructure list of records defininig the kinematic pairs of the linkage. \$LDLowOrderJoint list of records about the low order kinematic pairs ( type, joint marker, etc). \$LDLinkGeometry stores the geometric representation of the links. \$LDDerivedParametersA list of explicitly derived parameters. (p is explicitly derived if it can be expressed as p = f[q1, q2, ...]. \$LDDerivedParametersB list of implicitly derived parameters. (p is implicitly derived if it can be expressed as the solution of f[p, q1, q2, ...]= 0).

Most important record identifiers of LinkageData.

Every linkage has one separate and independent LinkageData object, which can be assigned to variables, merged with other LinkageData objects, renamed etc. Building a linkage in LinkageDesigner is equivalent with creating and populating the LinkageData object of the linkage.
In this quick tour a simple planar linkage called four-bar mechanism is built. The schematic figure of this mechanism is shown below. The first step in defining the four-bar mechanism is to create a new LinkageData object with the help of the CreateLinkage function.

 Out= Out= CreateLinkage by default inserts two rigid bodies, the Ground and the Workbench links and a placement transformation between them. The LLRF of Ground link represent the global reference of the linkage. The Workbench link is the base link, or the local ground of the linkage. By default the LLRF of these links are super-positioned. One can imagine that the linkage is built on a workbench, which can be placed anywhere in the "world" by changing the placement transformation between the Workbench and the Ground links.
The string identifiers are stored in a so called full name form. A full name is made up of the name of the linkage (like the surname) and the entity name (as the given name). For example the name of the linkage is "fourBar" and the entity name of the link is "link0" then the full name of this link will be "fourBar@link0".
CreateLinkage defines automatically a name of the two base links. To change the default name of the Ground and Workbench links the GroundName and WorkbenchName options of CreateLinkage function should be used.
 option name default value GroundName Ground GroundName defines the name of the ground link. WorkbenchName Workbench WorkbenchName specifies the name of the workbench link. SimpleParameters {} SimpleParameters specifies the intial set of simple parameters that can be used in the linkage defintion.

LinkageData can be populated as the kinematic pairs (or joints) of the mechanism are defined. One kinematic pair inserts two links and the constraints, which restricts the movements of this two links. The basic tool for creating kinematic pairs is the DefineKinematicPair function.
 DefineKinematicPair[linkage,type,{vars},{link1,mx1},{link2,mx2}] inserts a kinematic pair between link1 and link2 into linkage. The joint markers are placed with mx1 and mx2 homogeneous matrix w.r.t LLRF of link1 and link2 . DefineKinematicPair[linkage,type,{vars},{link1,LLRF1},{link2,LLRF2},mx] inserts a kinematic pair between link1 and link2 into linkage. The local reference frames of the links LLRF1, LLRF2 and the placement of the joint marker mx are specified w.r.t global reference frame. DefineKinematicPair[linkage,type,{vars},{link1,link2},{a,d, , }] inserts a kinematic pair definition to linkage between link1 and link2 links using the {a, d, , } Denavit-Hartenberg parameters.

Insert a kinematic pair definition into LinkageData.

DefineKinematicPair function might look complicated to use, therefore a number of joint macro function are defined. These joint macro functions ( R2, R3, T2, T3, S3, U3 etc ) are calculating the input arguments of the DefineKinematicPair function based on a much simpler input.
In case of planar kinematic pairs the following assumptions permits the simplification:
1. The Local Reference Frames of every links are defined with their z-axis perpendicular to the plane. This z-axis also coincides with the z -axis of the World Reference Frame.
2. The axis of the rotational joint is always the z-axis of the World Reference Frame.
3. The axis of the translational joint is perpendicular to the z-axis of the World Reference Frame.
 R2[i->j,p1,p2] function defines the input arguments of a planar rotational joint definition between i and j links as the DefineKinematicPair function expects. T2[i->j,p1,p2] function defines a list of input arguments of a planar translational joint definition between i and j links as the DefineKinematicPair function expects. F2[i->j,p1,p2] function defines a list of input arguments of a planar fixed joint definition between i and j links as the DefineKinematicPair function expects

Planar joint macros of DefineKinematicPair function.

Based on these assumption the planar rotational joint definition simplifies to specifying the center points of joints on the two links. The center point definition can be made with 0, 1 or 2 coordinates.
Planar rotational joint at {0,0} point on link0 and {0,0} point on link1
 Out= Planar rotational joint at {L1,0} point on link0 and {0,0} point on link1
 Out= Planar rotational joint at {L1,L2} point on link0 and {10,3} point on link1
 Out= Using the joint macro functions the kinematic pairs can be defined and inserted into the LinkageData object using the DefineLinkage function. This function maps the output of the joint macro function to DefineKinematicPair function. Also it executes some other useful function such as DefLinkGeometryTo function that assigns simplified geometries to every links of the linkage.
Since the link geometries are defined by connecting the center points of the joint markers, therefore it is a good practice to add fixed joints to the significant points of the links, which is not used in other joint definitions.

Define 3 rotational joint to the linkage
 Out= The generated linkage is not yet a mechanism with closed kinematic graph, but a 3 degree of freedom planar manipulator. Linkages can be iteratively defined in LinkageDesigner, if the user prefer that way. It is possible to add a couple of kinematic pair to the LinkageData, than move the mechanism to another pose, visualize how it is look like and return to define additional kinematic pairs.
Rotational joint definition above specifies the joint variables with the JointVariable option. Joint variables are the so called generalized coordinates of the mechanism, whose functionality is determined by the type of the kinematic pair. In case of rotational joint, the joint variable represent the angle of the connected links.
If a linkage has open kinematic chain, than the joint variables of the kinematic pairs become the so called driving variables of the linkage. The driving variables are the independent kinematic variables that determines the mobility of the mechanism. By changing the value of any driving variable the mechanism moves into a new posture.

Move the mechanism into the { 1 -> 45°, 2 -> 35°, 3 -> -90°} posture
 Out= LinkageDesigner models every mechanism (planar or non-planar) as spatial mechanism. This implies that geometries that represent the links, must be defined as Graphics3D objects. Hoverer there are functions that can display planar mechanism in a plane as Graphics object. Linkage2D is one of these functions that can project the 3D geometries of the linkage onto the x-y plane and displays the linkage as a Graphics object.

 Out= Display mechanism and the LLRF of "D0" and "D3" links as planar linkage
 Out= Beside rendering the mechanism, there are some other functions to visualize the LinkageData object of the mechanism. The two most important parsing functions of the LinkageData are ViewLDTree and ShowLinkageGraph. The first browses the LinkageData object in an interactive tree view, while the second displays the kinematic graph of the linkage.

Display the kinematic graph of the linkage

 Out= Show the kinematic graph of the linkage
 Out= To close the four-bar mechanism definition, the link3 link should be pinned down to link0. This will close the kinematic graph, because it will create a loop in the graph. The simplest way to define this rotational joint is to join D3 and D0 links that are rigidly connected to link3 and link0. If the DefineKinematicPairTo function is used the resulted kinematic pair will be automatically inserted into the input LinkageData.
Define a rotational kinematic pair between D3 and D0
 Out= The number of records in the LinkageData has increased from 7 to 8 after this kinematic pair definition. This follows form the fact the kinematic pair between D3 and D0 links create a loop in the kinematic graph, therefore it will decrease the mobility of the linkage.
DefineKinematicPair function will automatically calculate the non-redundant constraint equations imposed by the loop closing kinematic pair, and remove as many driving variables from \$LDDrivingVariables record as the number of non-redundant constraint equations. The removed driving variables are expressed from the generated constraint equations, since they are not independent variables of the linkage any more. The constraint equations are inserted into the new \$LDDerivedParametersB record of the LinkageData.
List the constraint equations of the loop closing kinematic pair
 Out= Show the kinematic graph of the resulted linkage
 Out= As a final step the four-bar linkage should be placed in a posture where the link0 inclined with angle with respect to the x-axis of the World Reference Coordinate system. Linkages can be placed into an arbitrary position and orientation if the transformation matrix between the Ground and Workbench links is changed.
PlaceLinkage function replaces this transformation matrix with the one specified in its argument. The placement transformation can contain parameters, provided that you have added these parameters to the LinkageData object. Since the symbol has already been added to the simple parameters of the linkage, it can be used to define the placement matrix.
 PlaceLinkage[linkage,mx] sets the transformation matrix between Ground and Workbench link to mx homogeneous matrix. MakeHomogenousMatrix[m,v] creates a homogeneous transformation matrix from a 3 x 3 rotation matrix m and a 3 x 1 translation vector v. MakeHomogenousMatrix[m] creates a homogeneous transformation matrix from a 3 x 3 rotation matrix m with a {0,0,0} translation vector. MakeHomogenousMatrix[ax,ang] creates a homogeneous transformation matrix from a 3 x 3 rotation matrix that rotates with ang around ax vector with a {0,0,0} translation vector.

Define the placement matrix
 Out//MatrixForm= Out= Out= Since the symbol has a substituted value of 15°, therefore the placed linkage should be rotated in such a way that link0 and x-axis of the reference coordinate frame has 15° angle.
 Out= This concludes the definition of the four-bar mechanism. The LinkageData contains all information that is required to analyze the four-bar mechanism digitally.

Linkages defined in LinkageDesigner can be saved for further usage. By saving a linkage the LinkageData is serialized and saved into a text file. Loading the linkages from text file build a new LinkageData object from the serialized data. This way linkages can be shared with other user without redefining them.

Save four-bar linkage into a text file
 Out= Print out the textual contents of the file
 Out= Out= Before we continue with the linkage analysis, the linkage definition, which was created in the previous chapter, can repeated using only one command. The new definition will be assigned to fourBar2 variable. The only difference of the two linkages is the generated link's geometry, because for the fourBar2 linkage Line type geometry primitives will be used.
Redefine the four-bar mechanism with one command
 Out= Move the two linkage to the same pose
 Out= Set the size of the image
 Out= ### Solution branches

It could also happen that the two linkages are displayed in a different pose. The difference is caused by the so called solution branch of the loop closing equation. The loop closing equation is a trigonometrical polynomial that implicitly determines the values of the so called loop variables. In the case of four-bar mechanism the 2 and 3 joint variables are selected as loop variables, when the 4th rotational joint is defined.
The values of these dependent variables are re-calculated every time the independent variables (\$LDDrivingVariables, \$LDSimpleParameters) are changed. The re-calculation is completed by calling the FindRoot function for the generated constraint equation (stored in the \$LDDerivedParametersB record). The result of the FindRoot funtion call depends on the initial values, which is always set to the current value of the loop variables, so the result of the root finding might belongs to different solution branch.
To control the branch switching the user can use the ParameterInitialGuess option of SetDrivingVariables and SetSimpleParameters function, or use the ShakeLinkage function that explicitly switch solution branches without changing the values of the independent variables
 option name default value ParameterInitialGuess Automatic specifies the intial values used in root finding. JointLimitCheck False switches on/off the limit check of driving variables AccuracyGoal Automatic specifies how many effective digits of accuracy should be sought in the final results during root finding MaxIterations 100 specifies the maximum number of iterations that should be tried during root finding. PrecisionGoal Automatic specifies how many effective digits of precision should be sought in the final resul during root findingt

Selected options SetDrivingVariables and SetSimpleParameters.

Jump linkage to other solution branch using ParameterInitialGuess option
 Out= Out= The explicit values of the loop variables could be listed using the GetLinkageRules function, or directly list the \$LDDerivedParametersB record.

Get actual values of the parameters and variables.

Get the actual values of the loop variables in the two solution branches
 Out= ### Animations

The most often used analysis tool is the linkage animation that helps the designer to check the motion of the mechanism. Animation can be used as a simple quantitative check for such problems like reach-ability, workspace analysis or other tests. LinkageDesigner provide a number of tool to support the linkage animation in either 2D, 3D or even in VRML97/X3D worlds.

Animation functions.

Common options of animation.

Animations are generated as a list of postures of the linkage. The postures - or frames of the animations- are calculated by incrementing the values of the driving variables from the start to finishing value. The number of frames generated between two driving variable's base point of the linkage is determined by the Resolution option. The Resolution is equal to 10 by default. • Internal point generation for Resolution →10
Animate four-bar linkage by incrementing the driving variables with 10°
 Out= Draw trace lines during animation
 Out= Since the linkage is defined parametrically, the length of the links can be easily changed by simply changing the substitution value of the simple parameters. The trace point or the movement of the resulted linkage can be investigated with the help of the animation.
In the following example some of the dimensional parameter of the linkage is changed and the resulted linkage is animated.
 SetSimpleParameters[linkage,{vari→xi..}] sets vari simple parameter to xi and returns the resulted LinkageData object. SetSimpleParameters[linkage,{x1,x2,..}] sets the ith simple parameters' value to xi and returns the resulted LinkageData.

Change the dimensional parameters.

List the actual substitution values of the simple parameters
 Out= Change the link lengths and the placement variables
 Out= Animate the modified linkage and draw the trace curves of 3 points on link2
 Out= ### Measurements

Trace points of the linkages define planar curves. The parametric definition of the curve could be obtained from the mechanism by simply measure the selected points with respect to the reference frame. Measurements can be made on any linkages using the MeasureDistance function.
 MeasureDistance[linkage,p1,p2] calculates the vector from p1 to p2, where p1 and p2 are points defined on the linkage. p1 and p2 points are specified on a link in form as {linkName,coord}. coord is a vector relative to the LLRF of linkName. The reference coordinate system of the measurement is specified with the ReferenceFrame option. MeasureDistance[linkage,p2] calculates the position vector of p2 point from the origin of the LLRF of the Ground's link.

 option name default value ReferenceFrame Automatic ReferenceFrame is an option for GetLLRFMatrix function, that specifies the name of the refrence link. The LLRF of this link is the reference coordinate system. SubstituteParameters False SubstituteParameters is an option for GetLLRFMatrix and GetLinkageRules functions, that specifies, whether the numerical values of the linkage parameters should be substitued into the result or not. SubstitutionList None SubstitutionList is an option for GetLLRFMatrix function that defines the substitution list for the calculation

Options for MeasureDistance.

Measurements are common analysis tool, because it is capable of not only measuring numerical distances, but parameterical distances too. Parametric distance measurement might contain the independent variables - \$LDDrivingVariables, \$LDSimpleParameters - or dependent variables - \$LDDerivedParametersA, \$LDDerivedParametersB - records. The parametric expressions resulted from the measurement could be further processed to set up constraint equations or other kind of design equations.
Measure the coordinates of {X,0,0} point on link2
 Out= Simplify the expression
 Out= The resulted expression looks simple, but keep in mind that 2 variable is not independent, but an implicitly derived variable. In order to calculate the 2 value, the loop closing equation should be solved. Linear interpolation of derived variables can be obtained using the GetLinkageRules function.
 GetLinkageRules[linkage,drvls] returns a two dimensional list of interpolated parameters. The interpolation is specified with the drvls list of driving variable.

Get interpolated values of linkage parameters.

Calculate the list of interpolated linkage parameters while 1 runs from {0,2 }
 Out= The calculated interpolated parameters is a two dimensional list. The list is defined by changing the value of the independent driving variable ( 1) and calculating the values of all other independent and dependent variables. This way the list stored in sub contains all relevant information to display the trace point of one body fixed point such as the point defined in dist.
Display the trace curve for X= 3 point
 Out= Display the trace curve with higher resolution and changing the position of trace point from {-10, 10}
Angle measurements are also often needed for the analysis of linkages. Angel measurements could be easily obtained using MeasureDistance function. In case the two measured points belong to the same link, the norm of the measured vector will not change if the value of the driving variables are changing. This follows from the fact that links are assumed to be rigid bodies. The angle of the measured vector and a reference vector could be calculated with ArcTan function.
Measure the distance between {0,0,0} and {1,0,0} vector on link3 Out= It is easy to see that the angle between the measured vector and the x-axis ( {1, 0, 0} vector) of the reference frame is + 1+ 2+ 3. This angle is often called the output angle of the four-bar mechanism.
Plot the output angle of the four-bar mechanism with respect to the driving variable ( 1)
 Out= This concludes the introduction of the LinkageDesigner program. Other tutorials discusses specific features of the package such as kinematic, static, dynamic modeling of mechanism as well as synthesis of four-bar mechanism , definition of gear-trains etc.  