Getting Started with LinkageDesigner

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.
This loads the package
Click for copyable input

Build linkages

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.
LinkageDatais a new data type that represents the database of the linkage

LinkageData object.

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 IdentifierDescription
$LDMechanismIDdefines the name of the linkage and other linkage instance specific informations (units, Workbech name, etc).
$LDDrivingVariableslist of rules representing the driving variables of the linkage together with their substitutional values.
$LDSimpleParameterslist of rules representing the simple parameters of the linkage together with their substitutional values.
$LDStructurelist of records defininig the kinematic pairs of the linkage.
$LDLowOrderJointlist of records about the low order kinematic pairs ( type, joint marker, etc).
$LDLinkGeometrystores the geometric representation of the links.
$LDDerivedParametersAlist of explicitly derived parameters. (p is explicitly derived if it can be expressed as p = f[q1, q2, ...].
$LDDerivedParametersBlist 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.
CreateLinkage[str]creates an empty LinkageData object with str as the name of the linkage.
ViewLDTree[linkage]displays the LinkageData of linkage in a tree form that permits the user to browse interactively the database.

Create a new LinkageData object.

Create a new LinkageData
Click for copyable input
Browse the resulted LinkageData
Click for copyable input
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
GroundNameGroundGroundName defines the name of the ground link.
WorkbenchNameWorkbenchWorkbenchName specifies the name of the workbench link.
SimpleParameters{}SimpleParameters specifies the intial set of simple parameters that can be used in the linkage defintion.

Selected options fro CreateLinkage.

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
Click for copyable input
Planar rotational joint at {L1,0} point on link0 and {0,0} point on link1
Click for copyable input
Planar rotational joint at {L1,L2} point on link0 and {10,3} point on link1
Click for copyable input
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.
DefineLinkage[str, ls]creates a new linkage with str name and adds a list of kinematic pair definitions (ls).
DefineLinkage[linkage, ls]appends kinematic pair definitions (ls) to linkage.
DefLinkGeometryTo[linkage,type]assigns simplified geometries to every links of linkage. The geometries of the links are determined by the center points of the joint markers.

Linkage definition functions.

Define 3 rotational joint to the linkage
Click for copyable input
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.
SetDrivingVariables[linkage,{varixi..}] sets vari driving variable of linkage to xi and returns the resulted LinkageData
SetDrivingVariablesTo[linkage,{varixi..}]sett the vari driving variable to xi value and resets the resulted LinkageData to linkage.

Move the linkage.

Move the mechanism into the {1 -> 45°, 2 -> 35°, 3 -> -90°} posture
Click for copyable input
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.
Linkage3D[linkage,opts]renders the geometries of the links in the current posture of the linkage. Returns a Graphics3D object.
Linkage2D[linkage,opts]project the Graphics3D representation of the linkage, rendered by Linkage3D function, into the x-y plane and returns a Graphics object.

Render linkages.

Display mechanism as spatial linkage
Click for copyable input
Display mechanism and the LLRF of "D0" and "D3" links as planar linkage
Click for copyable input
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.
ShowLinkageGraph[linkage]displays the kinematic graph of the linkage.

Display the kinematic graph of the linkage

Browse the LinkageData of fourBar
Click for copyable input
Show the kinematic graph of the linkage
Click for copyable input
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
Click for copyable input
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
Click for copyable input
Show the kinematic graph of the resulted linkage
Click for copyable input
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.

Place linkage.

Define the placement matrix
Click for copyable input
Place the linkage
Click for copyable input
Browse the resulted LinkageData
Click for copyable input
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.
Render the placed linkage
Click for copyable input
This concludes the definition of the four-bar mechanism. The LinkageData contains all information that is required to analyze the four-bar mechanism digitally.

Save/Load linkages

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.
SaveLinkagesaves the linkage definition in a text file.
LoadLinkageloads the linkage definition from text file

Save and load linkage definition.

Save four-bar linkage into a text file
Click for copyable input
Print out the textual contents of the file
Load linkage definition from the text file
Click for copyable input
Browse the LinkageData of the loaded linkage
Click for copyable input

Analyze linkage

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
Click for copyable input
Move the two linkage to the same pose
Click for copyable input
Set the size of the image
Click for copyable input
Display the two linkages
Click for copyable input

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
ParameterInitialGuessAutomaticspecifies the intial values used in root finding.
JointLimitCheckFalseswitches on/off the limit check of driving variables
AccuracyGoalAutomaticspecifies how many effective digits of accuracy should be sought in the final results during root finding
MaxIterations100specifies the maximum number of iterations that should be tried during root finding.
PrecisionGoalAutomaticspecifies how many effective digits of precision should be sought in the final resul during root findingt

Selected options SetDrivingVariables and SetSimpleParameters.

ShakeLinkage[linkage] shakes linkage to jump to another solution branch of the loop closing equations. The function returns the linkage in a new posture if it is found.

Shake linkage.

Jump linkage to other solution branch using ParameterInitialGuess option
Click for copyable input
Jump linkage to other solution branch using ShakeLinkage
Click for copyable input
The explicit values of the loop variables could be listed using the GetLinkageRules function, or directly list the $LDDerivedParametersB record.
GetLinkageRules[linkage,opts]returns a list of parameter rules of the linkage.
GetLinkageRules[linkage,{recID1,recID2,...}]returns a list of parameter rules that are filtered with (recIDi).
GetLinkageRules[linkage,!{recID1,recID2,...}]returns all parameter rules, that are complementer with (recIDi).

Get actual values of the parameters and variables.

Get the actual values of the loop variables in the two solution branches
Click for copyable input


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.
AnimateLinkage2D[linkage,drvls]function projects the frames of AnimateLinkage3D onto the X-Y plane. The resulted projections are rendered as Graphics primitives. The function takes the same options as AnimateLinkage3D.
AnimateLinkage3D[linkage,ls]generates a list animation of linkage while the linkage interpolates through the poses corresponding to the driving variable list ls
WriteVRMLAnimation[linkage, filename,ls]generates a list animation of linkage while the linkage interpolates through the poses corresponding to the driving variable list ls, and exports it to the filename WRL file.

Animation functions.

option name
default value
JointMarkersNoneJointMarkers is an option for Linkage3D and AnimateLinkage3D function, that specifies the joint markers tob shown.
Resolution10Resolution is an option for GetLinkageRules function,that specifies the number of interpolation points between two base point.
LinkGeometryAllLinkGeometry is an option for Linkage3D and AnimateLinkage3D function, that defines whose geometry should be displayed.
LinkMarkersNoneLinkMarkers is an option for Linkage3D and AnimateLinkage3D function, that defines the name of the links,whose LLRFs should be displayed.
TracePointsNoneTracePoints is an option for AnimateLinkage3D function, that specifies the points of the linkage, of that trace should be displayed.
TraceStyleAutomaticTraceStyle is an option for AnimateLinkage3D function, that defines the specifies style of the trace graphics.

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°
Click for copyable input
Draw trace lines during animation
Click for copyable input
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,{varixi..}]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
Click for copyable input
Change the link lengths and the placement variables
Click for copyable input
Animate the modified linkage and draw the trace curves of 3 points on link2
Click for copyable input


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.

Measures on the linkage.

option name
default value
ReferenceFrameAutomaticReferenceFrame is an option for GetLLRFMatrix function, that specifies the name of the refrence link. The LLRF of this link is the reference coordinate system.
SubstituteParametersFalseSubstituteParameters 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.
SubstitutionListNoneSubstitutionList 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
Click for copyable input
Simplify the expression
Click for copyable input
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}
Click for copyable input
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
Click for copyable input
Display the trace curve with higher resolution and changing the position of trace point from {-10, 10}
Click for copyable input
Click for copyable input
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
Click for copyable input
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)
Click for copyable input
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.