Working with LinkageData

LinkageData can be considered as a small relational database that stores all relevant information of linkages. LinkageData consist of a list of records that are identified with record identifiers. Every records have to conform to a simple {_String, _List} pattern. The first part of the record is the record identifier, while the second part is the data.
Load LinkageDesigner package
Click for copyable input
CompileLinkageDataConverts list based LinkageData representation to the new LinkageDataMap representation.
ViewLDTreeDisplays the LinkageData of linkage in a tree form, which enables the user to browse LinkageData interactively.

Create and view LinkageData.

Create a simple LinkageData object from a serialized LinkageData
Click for copyable input
The format of the LinkageData object is -LinkageData, n-, where n is the number of records in the database. The test LinkageData contains currently three records.
Browse the test database
Click for copyable input
LinkageData object can be queried and modified with standard list manipulation functions such as Part or Delete.
linkage[["id"]]Overloaded Part function for LinkageData permits indexing with "id" record identifier string
linkage[["id"]]={data}Overloaded Set function for LinkageData permits to set part of LinkageData, which is indexed with record identifier
PrependTo[linkage[["id"]],elem]Overloaded PrependTo function for LinkageData permits to prepend the data list with elem for "id" record.
AppendTo[linkage[["id"]],elem]Overloaded AppendTo function for LinkageData permits to append the data list with elem for "id"record.
DeleteTo[linkage,"id"]Delete "id"record from linkage

LinkageData manipulation functions.

Retrive the "ID2" record using Part function
Click for copyable input
Get the second element of "ID2" record
Click for copyable input
It is possible to retrieve sub records, which is identified by strings
Click for copyable input
Add a new record to test LinkageData
Click for copyable input
Append one element to "myRecord"
Click for copyable input
Retrive the content of "myRecord"
Click for copyable input
Browse the test database
Click for copyable input
Delete "myRecord" from the LinkageData
Click for copyable input
LinkageData is defined a database, which is flexible enough to easily extend with new chunk of data. In order to find the information required by the functions of LinkageDesigner, certain number of pre-defined records are introduced. The record identifier and the record data of these pre-defined records are specified rigorously. Hovewer users can extend the LinkageData object by using his/her own record identifier and data.
The string identifiers of the pre-defined records are also defined with constants, which permits to look up using the standard command completion mechanism of Mathematica notebooks.
Record IdentifierDescription
$LDMechanismIDDefines the name of the linkage and other linkage instance specific informations (units, WorkBench 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)
$LDLinkGroundTransformationList of transformation of the Local Link Reference Frames to the Global Reference Frame
$LDTimeDependentVariablesList of rules of time dependent variables together with the first derivative.
$LDDrivingVelocitiesList of rules representing the first derivative of the driving variables together with their substitutional values..
$LDInteractiveDefStores linkage definition of a previous LinkageCAD session.
$LDMassPropertiesStores the mass properties of the links. Mass properties data consist of a list of {inertiaFrame,mass,momentOfInertia} sublist.
$LDForcesStores a list of forces that acting on the mechanism. Forces are stored as {{str1,vec},{str2,pointofAttack}} sublist
$LDTorquesStores a list of torques vectors acting on the linkage. Torques are stored as {{str1,vec},{str2,pointofAttack}}

Predefined record identifiers of LinkageData.

Structural records of the linkage

New LinkageData can be created with two function CreateLinkage and DefineLinkage. The resulted LinkageData object is not completely empty, because the minimal set of records are already inserted. Since DefineLinkage internally calls CreateLinkage function, therefore only the latter one will be discussed here.
CreateLinkage[str]creates an empty LinkageData object with str as the name of the linkage.
DefineLinkage[str, ls]creates a new linkage with str name and adds a list of kinematic pair definitions (ls).

Create new LinkageData.

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.
WorkbenchPlacementAutomaticHomogenous transformation matrix specifying the placement of the Workbench link w.r.t. the reference coordinate system.
PlacementName"Base-0"Name of the kinematic pair defining the Workbench placement.
LinkageUnitsAutomaticLinkageUnit specifies the default units used in the linkage. E.g. {Meter,Kilogramm,Second,Newton}

Options of CreateLinkage

Create a linkage with the name "test" and assign the resulted linkage to test symbol
Click for copyable input
CreateLinkage returns a LinkageData object containing 5 records. To investigate the contents of the records brows the LinkageData with ViewLDTree function
Display the records of the LinkageData object in ColumnForm
Click for copyable input
The first element of $LDMechanismID record is the name of the linkage (referred as LinkageName) . LinkageDesigner use a composite naming strategy to identify the entities such as links, geometries, forces,kinematic pairs etc. The name of the linkage is used to create the full name of entities. Every entities have a tring identifier that is called EntityName . The full name of identifiers are composed by concatenating the LinkageName and the EntityName.
There are two help function implemented in LinkageDesigner to manipulate composite names, the GetFullName and GetStrippedName functions.
GetFullName[linkage,"id"]returns the full name of the "id" using the linkage name of linkage LinkageData
returns the entity name of fullName, by dropping the substrings up to the first @ character

Functions for composite name manipulation. .

Define the full name of the "myLink" entity name
Click for copyable input
Get the entity name back form the full name
Click for copyable input
Beside the name of the linkage, $LDMechanismID contains the full name of the Ground (test@Ground) and the Workbench (test@Workbench) links. These two links were created by CreateLinkage function, together with the first kinematic pair of the $LDStructure record. The Ground link is the reference rigid body of the entire linkage. The LLRF of Ground is the global reference frame for the linkage. The Workbench link is by default connected with a fixed joint to the ground link, and represents the local reference body of the linkage. The LLRF of the Workbench link is the working reference frame of the linkage. This duplication of the reference links has two advantages:
i.) the reference link can be described with a kinematic pair
ii.) the linkage can be placed anywhere by changing only the Ground-Workbench transformation .
By parameterizing the Ground-Workbench transformation the movement of the mechanism -relative to the global reference frame- can be easily modeled. This movement could be used to model mobil or walking mechanism.
List the $LDStructure record of test linkage
Click for copyable input
The $LDStructure record stores the list of kinematic pairs of the mechanism. The kinematic pairs are the backbone structure of the mechanism, which detemines the movements of the links. Every kinematic pair is described with a subrecord in $LDStructure record. These sub-records stores three information of the kinematic pair:
  • String identifier of the kinematic pair ( test@Base-0 )
  • String identifier of the lower and upper links ( {test@Ground,test@Workbench} )

Independent variables of linkages

Independent variables are such placeholders that can substituted with any numerical values. Typical independent variables are the joint variables and dimensional parameters. There are two records dedicated to store the independent variables of the linkages:
$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.

Records of the independent variables.

Define a simple pendulum mechanism
Click for copyable input
Browse the database of the linkage
Click for copyable input
The $LDStructure record of the returned LinkageData object contains three kinematic pairs ( { pendulum@RotationalJoint-1, pendulum@FixedJoint-2} ). The generated homogeneous transformation matrices contain the independent variables q1 and l1. The first symbol is a driving variable, while the second is a simple parameter. Both the driving variables and the simple parameters are independent variables of the linkage. This implies that their values can be changed independently (Note that linkages with connected kinematic graph, the values of the independent variables might constrained by the loop closure equations. Certain combinations of independent variable values result non-real value solution of the loop closure equations. However even in this case there exist a feasibility interval of the variables, where the values can be arbitrarily changed.)
The most important difference of driving variables and simple parameters is their influence on the mobility of the linkage. The driving variables determines the mobility of the linkage, while the simple parameters does not influences it. In case of open kinematic pair definition the mobility of the linkage is increased with the number of joint variables. In this case the joint variables represent the remaining Degree of Freedom (DoF) of the upper link relative to the lower link after the kinematic pair definition is applied. In case of rotational joint- out of the possible 6 DoF of the upper link- removes 5 DoF from the upper link. This DoF is the rotation around the z-axis of the joint marker. The value of joint variable "drives" this remaining DoF.
The simple parameters, on the other hand, are basically placeholders of dimensional values. If they are used instead of numbers, all kinematic equations or transformation are generated using the parameter symbols. This way the dimensional values can be easily changed without redefine the whole linkage.
SetDrivingVariables[linkage,{varixi..}]sets vari driving variable of linkage to xi and return the resulted LinkageData
SetDrivingVariablesTo[linkage,{varixi..}]Set the vari driving variable to xi value and resets the resulted LinkageData to linkage.
SetSimpleParameters[linkage,{varixi..}] sets vari simple parameter to xi and returns the resulted LinkageData object.
SetSimpleParametersTo[linkage,{varixi..}]sets vari simple parameter to xi and resets the resulted LinkageData object to linkage.

Functions for setting the independent variables of LinkageData.

The numerical substitution value of the independent variables ( driving variable, simple parameter ) are stored together with the placeholder symbols, since they are wrapped with a Rule function. Their values can be changed with the SetDrivingVariables and SetSimpleParameters functions.
Set the q1 driving variable to -45
Click for copyable input
Set the l1 simple parameters to
Click for copyable input
Display linkage
Click for copyable input
In case of linkages with simple kinematic graph (serial chain or tree) setting the independent variable is nothing else but replacing the second argument of the Rule function. However for more complicated linkages, setting the independent variables includes the solution of the constraint equations for the new set of independent variables. This is the reason while it is advised to use the setter function instead of directly replace the values of the LinkageData.

Dependent variables of the linkage

There are two kind of dependent variables defined in LinkageData. If the dependent variable (y) can be expressed as the explicit function of the independent variables (x1, x2, ...), than it is stored in the $LDDerivedParametersA record. However if the dependent variable y is defined implicitly with an equation, it is stored in the $LDDerivedParametersB record
y = f[x1,x2,...]
y is an explicitly defined variable
g[y,x1,x2,...] = 0
y is an implicitly defined variable

Different type of dependent variables.

Implicitly defined dependent variables

Implicitly defined variables are generated automatically if a loop closing kinematic pair is defined. DefineKinematicPair function detects, whether the kinematic pair is a loop closing or an open one. In the first case it calculates the mobility of the upper link of the kinematic pair relative to the lower one. Based on the result it constructs the set of non-redundant constraint equations. Finally it removes as many driving variables from the $LDDrivingVariables record as the number of constraint equations. The constraint equations are stored in the $LDDerivedParametersB record.
Load the pre-defined crank-slider mechanism
Click for copyable input
Display the linkage and its kinematic graph
Click for copyable input
List the independent variables of the linkage
Click for copyable input
Click for copyable input
List the implicitly defined dependent variables of crank-slider mechanism
Click for copyable input
Implicitly defined variables are {q2, q3}. Their value are calculated with FindRoot function after the actual values of the independent variables are substitued. Implicitly defined variables can be converted into explicitly defined variables if the constraint equations are solved in a closed form.

Explicitly defined dependent variables

The loop closing constraint equations of the crank-slider mechanism can be easily solved in closed form. It is possible to use the standard Solve function or utilize the PatternSolve utility function of LinkageDesigner.
Simplify the loop closing constraint equations
Click for copyable input
One solution method is to eliminate the q3 variable from the two equations and solve the remaining equation for q2.
Eliminate q3 from the equations
Click for copyable input
Solve the remaining equation for q2
Click for copyable input
Solve the eliminated equation for q3
Click for copyable input
Merge the solutions
Click for copyable input
In crankSlider linkage the {q2, q3} variables are stored as implicitly defined variables. Using the ReplaceVariables function a new LinkageData can be defined, which defines explicitly these variables.
ReplaceVariables[linkage,{vars}->{eqs}]deletes existing definition of vars and insert eqs as new definition of vars into $LDDerivedparametersB records.
ReplaceVariables[linkage,{vars}->{varsterms}]deletes existing definition of vars and insert terms as new definition of vars into $LDDerivedParametersA records.
Replace variables.
Replace the implicitly defined variables with explicit functions
Click for copyable input
Browse the original and new LinkageData
Click for copyable input
Animate the new linkage
Click for copyable input

Utility records

The pre-defined LinkageData records contains some auxiliary utility records that are used in the visualization and simulation of the linkages.
$LDLinkGeometryStores the geometric representation of the links.
$LDLowOrderJointStores kinematic data of the low order joints.
$LDLinkGroundTransformationStores the transformation of every LLRF to the Global Reference Frame.

Utility records.

In order to visualize a linkage, the geometric representation of the links should be stored. The $LDLinkGeometry record stores the geometric representations of the link, which is a Graphics3D object. Geometries can be defined to the links using different functions such as:
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[[$LDLinkGeometry,link]]=Graphics3D[...]Sets the geometry of the link in the $LDLinkGeometry record of LinkageData.

Geometry input functions.

option name
AppendLinkGeometryAutomaticthe geometric representation contains only a text primitive, withthe name of the link.
AppendLinkGeometryNonethe geometric representation is an empty Graphics3D object
AppendLinkGeometrygrBotth link will use the same Graphics3D object gr
AppendLinkGeometry{grLower,grUpper}the geometric representation of the lower link is grLower while the upper link is grUpper

AppendLinkGeometry options of DefineKinematicPair function

List the link' geometries of crank-slider mechanism
Click for copyable input
Set the geometry of link0 to a cylinder
Click for copyable input
Replace the geometry of link3 link with Cuboid
Click for copyable input
Display the linkage
Click for copyable input
During the simulation of the linkage the position of every LLRF should be calculated relative to the global reference frame. These transformation matrices are calculated using the kinematic graph of the linkage. Sometimes it speeds up the animation if the link-ground transformations are calculated in advance to spare the time of calculations before each animation steps. The $LDLinkGroundTransformation record is calculated and appended if the PlaceLinkage function is called. All animation function recognize the presence of $LDLinkGroundTransformation record and use it if it is defined.
PlaceLinkage[linkage,mx]Sets the transformation matrix between Ground and Workbench link to mx homogeneous matrix
PlaceLinkage[linkage]Recalculates the $LDLinkGroundTransformation matrices and returns the resulted LinkageData.
PlaceLinkageTo[linkage]Recalculates the $LDLinkGroundTransformation matrices and re-sets to linkage.
AppendLinkGroundTransformationOption of PlaceLinkage function. If true re-calculate and inserts the $LDLinkGroundTransformation record to the linkage.

Manipulate $LDLinkGroundTransformation record.

List the link-ground transformation of link3
Click for copyable input
The pre-defined crank slider mechanism has already a placement transformation which parameterize the orientation and position of the whole linkage. This placement transformation is stored in the Ground-Workbench kinematic pair.
Retrieve the Ground-Workbench transformation of crank slider mechanism (Note that the name of the Workbench is link0)
Click for copyable input
Place linkage to the global reference frame and retrieve the link-ground transformation of link3
Click for copyable input

Kinematics and dynamics

LinkageData by default does not contains kinematic records, because the basic analysis does not requires it. In order to calculate the velocity or acceleration, the linkage should be converted into a time dependent linkage. As the linkage is converted into time dependent linkage LinkageDesigner calculates and stores the required records in $LDTimeDependentVariables and $LDDrivingVelocities records.
$LDTimeDependentVariablescontains the contains the first derivative of the time dependent variables with respect to the time symbol.
$LDDrivingVelocities stores the velocity values of the driving variables.
$LDDerivedParametersBstores the list of implicitly derived dependent parameter record of the linkage.

Kinematics related records in LinkageData.

Two function is defined in LinkageDesigner to calculate kinematics record: ToTimeDependentLinkage or NToTimeDependentLinkage functions. The primary task of these functions is to calculate the first derivatives of all time dependent variables and store them in the $LDTimeDependentVariables record.
ToTimeDependentLinkage[linkage,t]Calculates the first derivatives of the time dependent variables with respect to t and fill up the $LDTimeDependentVariables and $LDDrivingVelocities records of linkage.
NToTimeDependentLinkage[linkage,t]Generates the equations of the first derivatives of the time dependent variables with respect to t. The generated equations are appended to the $LDDerivedParametersB record.

Convert linkages into time dependent ones.

Load the pre-defined crankSlider mechanism
Click for copyable input
Convert crank-slider mechanism to time dependent linkage symbolically
Click for copyable input
List the first derivatives of the time dependent variables
Click for copyable input
Retrieve the $LDDrivingVelocities record
Click for copyable input
Get the velocity and angular velocity of the slider
Click for copyable input
Plot the vx and vy coordinate functions of the slider's velocity
Click for copyable input
Dynamical calculation requires also some pre-defined records where the mass properties of the links, the forces and torques acting on the linkage can be stored.
$LDMassPropertiesStores the mass properties of the links. Mass properties data consist of a list of {inertiaFrame,mass,momentOfInertia} sublist.
$LDForcesStores a list of forces that acting on the mechanism. Forces are stored as {{str1,vec},{str2,pointofAttack}} sublist
$LDTorquesStores a list of torques vectors acting on the linkage. Torques are stored as {{str1,vec},{str2,pointofAttack}}

Records of the dynamical calculation.

Load the double pendulum linkage
Click for copyable input
Browse the LinkageData
Click for copyable input
The double pendulum linkage has already defined $LDMassProperties record. LinkageDesigner provides a number of function that calculates the mass properties of links based on their geometries. If the mass properties are not known the CalculateMassProperties function can determine the mass, center of gravity and moment of inertia of closed polyhedron geometrical models assuming uniform density.
CalculateMassProperties[linkage,dens]calculates the mass properties of all links of linkage using dens density value and assigns the {frame,mass,moment of inertia } values to the $LDMassProperties record. The function returns the updated LinkageData record.
CalculateMassProperties[linkage,{name1→dens1,name2→dens2,...}]calculates the mass properties of the specifies links using the specified densities.
CalculateMassProperties[linkage]calculates the mass properties of all geometries using unit density.

Calculate mass properties.

Calculate weight vectors of the pendulum
Click for copyable input
List the force vectors of the linkage
Click for copyable input
Display the linkage with the force vectors
Click for copyable input
CalculateWeight[linkage,gvec]function calculates the the weight vector to links based on the mass property definition. The weight vector is inserted into the $LDForces record of linkage. Weight vector is calculated as m*gVec, where m is the mass of the link and gVec is the gravity vector. Weight vector is acting at the center of mass of the link. The function returns the resulted LinkageData record.
CalculateWeight[linkage]function calculates the the weight vector to all links assuming that the gravity vector is {0,-9.81,0}
DefineForceVector[linkage,{lName1,pt},{lName2,f}]function adds one force vector to the LinkageData of linkage. The force vector is defined with a point of attack (pt) which is defined w.r.t lNamei's LLRF and the force vector (f), which is defined w.r.t lName2's LLRF. lName1 and lName2 are link names of linkage. The function returns the resulted LinkageData.
DefineForceVector[linkage,lName,f]function adds a force definition to the LinkageData of linkage assuming that the point of attack is the origin of lName and the force (f) is defined with respect to the Ground of the linkage.

Force definition functions.

Define a torque vector that is acting on link1
Click for copyable input
Define a torque vector that is acting on the link2
Click for copyable input
Click for copyable input
DefineTorqueVector[linkage,{lName1,pt},{lName2,t}]function adds a torque vector to the LinkageData of linkage. The torque vector is defined with a point of attack (pt) which is defined w.r.t lName1's LLRF and the torque vector (t) which is defined w.r.t lName2's LLRF. lName1 and lName2 are link names defined in linkage. Torque definition is inserted to LinkageData of linkage. The function returns the resulted LinkageData.
DefineTorqueVector[linkage,lName,t]function adds a torque definition to the LinkageData of linkage assuming that the point of attack is the origin of lName and the force (t) is defined with respect to the Ground of the linkage.

Define Torque vector.

As soon as the mass properties and forces/torques are defined on the linkage, the LinkageData contains all information that is required for static or dynamical analysis of the mechanism.
Set the driving velocities to 0. These values will be used as initial velocities at start time.
Click for copyable input
Set the driving variables to 15° and 45° respectively these value will be used as initial values at start time
Click for copyable input
SolveLagrangian[linkage,{t,start,end}]function calculates the Lagrangian of the linkage, define the Lagrange's equations and numerically differentiateit. It returns the list of interpolation functions of the driving variables.

Solve dynamical simulation.

Solve the Lagrangian's equation fro (0,10) interval
Click for copyable input
Plot the time function of the generalized coordinates
Click for copyable input
Animate the dynamical simulation
Click for copyable input