General

`pymbs.input`

The ‘world’, which is a kind of body, manages (mainly collects) all these elements: bodies, joints, loads, loops, sensors, constraints and expressions. It gives access to the transformation module which is the user interface to the functionality of pymbs.

`pymbs.input.MbsSystem`

class pymbs.input.MbsSystem(gravity_vect=[0, 0, -1], name='world')

The ‘world’, which is a kind of body, manages (mainly collects) all these elements: bodies, joints, loads, loops, sensors, constraints and expressions. It gives access to the transformation module which is the user interface to the functionality of pymbs.

addBody(mass, cg=<Mock name='mock.zeros()' id='140347210555472'>, inertia=<Mock name='mock.zeros()' id='140347210555472'>, name=None)

With addBody you can insert a rigid body to your multibody system. TODO: Mentioning of body fixed frame.

Parameters:

name (String.) – Name of the body.
mass (float/int or pymbs.Symbolics.Symbol as returned by pymbs.input.MbsSystem.addParam()) – Mass of the body in kg.
cg (3x1 Vector (pymbs.Symbolics.Matrix or list of float/int).) – Vector, describing the position of the Centre of Gravity with respect to the body fixed frame.
inertia (You can either specify a matrix (which must be symmetric) or pass a 6x1 vector having the elements [ $I_{xx}$ , $I_{xy}$ , $I_{yy}$ , $I_{xz}$ , $I_{yz}$ , $I_{zz}$ ]) – Tensor of inertia at the centre of gravity for this body written with respect to the body fixed frame.

Returns:

Reference to the generated Body object

Return type:

pymbs.input.Body

Note

A newly generated body needs to be connected to other bodies via a joint. (pymbs.input.MbsSystem.addJoint())

addConstraint(CS1, CS2, transLock=[0, 0, 0], rotLock=[0, 0, 0], name=None)

One way of closing kinematic loops is through the use constraints. This will introduce constraint forces at both coordinate systems as well as a set of constraint equations inhibiting certain relative movements which are specified by transLock and rotLock. This will ultimately lead to formulation as a DAE (Differential Algebraic Equations).

Parameters:

name (String.) – Name of the constraint.
CS1 (MbsSystem, Body or Coordinate System.) – Parent coordinate system on the parent body.
CS2 (MbsSystem, Body or Coordinate System.) – Child coordinate system on the child body.
transLock – Vector [x,y,z] that defines which relative translations are forbidden. Use 0 to allow relative motion along the corresponding axis and 1 to inhibit it.
rotLock – Vector [x,y,z] that defines which relative rotations are forbidden. Use 0 to allow relative motion around the corresponding axis and 1 to inhibit it.

addContactSensorsLoads(name, CS_C)

Add all sensors and force elements needed for a contact: * Position * Orientation * Velocity * Angular Velocity * CmpForce with 3x1 vector input * CmpTorque with 3x1 vector input

Parameters:

name – Name of this sensors (using r_, T_, v_, om_ as prefixes)
CS_C (Body or Coordinate System) – Contact-Frame

addController(symbol_str, controlfunc, shape=None, name=None)

Add a controller to the system. This will call the supplied controlfunc function and store its return value, so that it can be used later, e.g. as a load. Because this will execute any valid python function, this is not available for exporting to other languages.

Parameters:

name (String.) – Name of the controller.
symbol_str (String.) – Symbol that shall be used for the controller.
controlfunc (function) – Python function taking the time and current state, e.g. myfunction(t, y, sensors). Return value can be used e.g. as load.
shape (Tuple of two numbers (int/float).) – Optional parameter, defining the shape of the controller. Use (m,n) if it is a m x n Matrix. By default (1,1), i.e. a scalar input is assumed.

Returns:

Symbol representing the controller, which may consequently be used in expressions (pymbs.input.MbsSystem.addExpression()) and loads (ref:’Loads’).

Return type:

pymbs.Symbolics.Symbol

addExpression(symbol_str, exp, name=None, category=<Mock name='mock.VarKind.User_Exp' id='140347086759760'>, positive=False, negative=False, limits=None)

Add an expression to the system of equations. Expressions allow the user to include calculations of, say, forces from sensors and inputs, or to define own sensors. All symbols known to pymbs may be used in such an expression.

Parameters:

name (String.) – Name of the expression.
symbol (String.) – Symbol that shall be used for the parameter.
exp (pymbs.Symbolics.Basic) – Term to calculate the expression, like c*x[0]+d*x[1]
category ((List of) Strings.) – (Optional) Each expression may be categorised. Use VarKind.Sensor, to let pymbs recognise it as a sensor, for example.
positive (Boolean.) – (Optional) Let pymbs.Symbolics assume that it is positive, which makes it easier to simplify.

Returns:

Symbol of the expression.

Return type:

pymbs.Symbolics.Symbol

addFlexibleBody(filepath, name=None)

With addFlexibleBody you can insert a flexible body to your multibody system.

Parameters:

name (String.) – Name of the body.
mass (float/int or pymbs.Symbolics.Symbol as returned by pymbs.input.MbsSystem.addParam()) – Mass of the body in kg.
cg (3x1 Vector (pymbs.Symbolics.Matrix or list of float/int).) – Vector, describing the position of the Centre of Gravity with respect to the body fixed frame.
inertia (You can either specify a matrix (which must be symmetric) or pass a 6x1 vector having the elements [ $I_{xx}$ , $I_{xy}$ , $I_{yy}$ , $I_{xz}$ , $I_{yz}$ , $I_{zz}$ ]) – Tensor of inertia at the centre of gravity for this body written with respect to the body fixed frame.

Returns:

Reference to the generated Body object

Return type:

pymbs.input.Body

Note

A newly generated body needs to be connected to other bodies via a joint. (pymbs.input.MbsSystem.addJoint())

addFrame(name, p=zeros((3,)), R=eye((3, 3)))

Add a new Coordinate System (CS) as a Child.

Parameters:

name (String) – Name of CS
p – Position vector of coordinate origin
R – Rotation matrix

addGraphicSensors(cs, name=None, category=<Mock name='mock.VarKind.Sensor' id='140347107147344'>)

You may use this function to manually add a Position and a Orientation sensor for a Coordinate System.

Parameters:

name (String.) – Name of the visualisation sensors (r_ and T_ are used as prefix for the position and orientation sensor, respectively)
cs (MbsSystem, Body, Frame.) – Coordinate System from which the position and orientation shall be measured.
category (list of Strings.) – May be used to manually override the category (not recommended)

Returns:

list of symbols for position and orientation.

Return type:

list of pymbs.Symbolics.Symbol

addHydCylSensorsLoads(name, CS1, CS2)

Add all Sensors and load elements needed for a hydraulic cylinder: * DistanceSensor (distance and velocity at which the distance changes) * PtP-Force with scalar input

Parameters:

CS1 (Body or Coordinate System) – Coordinate System at the bottom of a hydraulic cylinder
CS2 (Body or Coordinate System) – Coordinate System at the end of the rod

addInput(symbol_str, shape=None, limits=None, name=None)

Add an input to the system. It may be used for values that are calculated externally, like tire forces. Its implementation depends on the format the generated code is exported. Look at the corresponding documentation for more information.

Parameters:

name (String.) – Name of the input.
symbol_str (String.) – Symbol that shall be used for the input.
shape (Tuple of two numbers (int/float).) – Optional parameter, defining the shape of the input. Use (m,n) if it is a m x n Matrix. By default (1,1), i.e. a scalar input is assumed.
limits (List of (int/float), e.g. [-10, 10]) – Limits for the corresponding slider in the simulation tab. Default is [-1,1]

Returns:

Symbol representing the input, which may consequently be used in expressions (pymbs.input.MbsSystem.addExpression()) and loads (ref:’Loads’).

Return type:

pymbs.Symbolics.Symbol

addJoint(CS1, CS2, dofList=None, startVals=None, startVals_d=None, name=None)

addJoint introduces a joint linking two bodies together. It is defined using two coordinate systems which define the position on each body. The parent coordinate system (body) should be the body which is closest to the inertial frame (world/MbsSystem). The movements allowed by this joint are defined by supplying a dofList. It is a list of strings where each element consists of the type: * Translational (T) * Rotational (R) and the axis of the parent coordinate system: * x, y, z. Thus a translational joint along the x-axis would be abbreviated by ‘Tx’. A rotational joint around the z-axis would be ‘Rz’. By supplying a list of such elementary rotations and translations more complex joints may be defined. A 6dof joint using cardan-angles, for example, is characterised by dofList = [‘Tx’, ‘Ty’, ‘Tz’, ‘Rx’, ‘Ry’, ‘Rz’]. Note that each elementary movement is carried out consecutively. In addition initial values, both for the position and the velocity, may be supplied for each elementary movement.

Parameters:

name (String.) – Name of the joint.
CS1 (MbsSystem, Body or Coordinate System.) – Parent coordinate system on the parent body.
CS2 (Body or Coordinate System.) – Child coordinate system on the child body.
dofList (List of Strings.) – List of strings describing the allowed elementary movements. ‘Ty’ stands for translation along the y-axis. ‘Rx’ allows rotations around the x-axis. dofList = [], creates a fixed joint.
startVals (List of int/float. Dimension must be the same as dofList) – Initial position for each elementary movement.
startVals_d (List of int/float. Dimension must be the same as dofList) – Initial velocity for each elementary movement.

Returns:

Reference to the newly generated joint.

Return type:

pymbs.input.Joint

Note

A joint may not be used to close a kinematic loop. This can only be achieved by using Loops (Explicit Handling of Kinematic Loops) or Constraints (pymbs.input.MbsSystem.addConstraint())

addJointLoad(loadSymb, thejoint, name=None)

Adds a load object to the joint. The load is a force or a torqe, depending on the type of the joint

Returns:: None

addLoad

addLoad contains a pymbs.input.MbsSystem.AddLoad instance, see Loads (Forces and Torques) for the different load types available

>>> world.addLoad.PtPForce(F, body_one, body_two)

addLoop

addLoop contains a pymbs.input.MbsSystem.AddLoop instance, see Kinematic Loops for the different loops available

>>> world.addLoop.FourBar(body_one, body_two)

addMotionSystemSensors(CS_D, name='BWS')

Add all sensors that are needed for the motion platform, i.e. * Position * Orientation * Velocity * Angular Velocity * Acceleration * Angular Acceleration

Parameters:: CS_D (Body, Coordinate System) – Coordinate System where the driver sits

addParam(symbol_str, defaultValue, positive=False, negative=False, name=None)

Creates a new parameter. A parameter is considered to be a value which is constant during simulation but may vary between different simulation runs. The dimension of a parameter is determined by its defaultValue. Furthermore, it is possible to supply a positive flag which, when set, allows simplifications like $\sqrt{x^2} = x$ , otherwise it would be $\left\vert x \right\vert$ .

Parameters:

name (String.) – Name of the parameter.
symbol_str (String.) – Symbol that shall be used for the parameter.
defaultValue (int/float, list of int/float, symbolic term.) – Value which is used by default. Note that this option defines the dimension of this parameter. The defaultValue may also be formula consisting of parameters.
positive (Boolean.) – Will the parameter always be positive, which holds true for a mass, for example.

Returns:

Symbol to the parameter.

Return type:

pymbs.Symbolics.Symbol

addSensor

addSensor contains a pymbs.input.MbsSystem.AddSensor instance, see Sensors for the different sensors available

>>> world.addSensors.Acceleration('a', CS1, CS2)

addSpringDamper(CS1, CS2, c, d, l0, name)

Add parameters, sensor and force element for a linear springdamper. This a parallel combination of a spring and a velocity-proportional damper that exerts a force between its two connection points. * Parameter for stiffness * Parameter for damping * DistanceSensor (distance and velocity at which the distance changes) * PtP-Force

Parameters:

CS1 (Body or Coordinate System) – Coordinate System 1
CS2 (Body or Coordinate System) – Coordinate System 2
c (Number or Parameter) – Linear spring stiffness in [N/m]
d (Number or Parameter) – Linear damping in [Ns/m]
l0 (Number or Parameter) – Unstretched length of the spring in [m]

addTyreSensorsLoads(name, CS_C, CS_R)

Add all sensors and force elements needed for a tire model: * Position * Orientation * Velocity * Angular Velocity * CmpForce with 3x1 vector input * CmpTorque with 3x1 vector input

Parameters:

name – Name of this sensors (using r_, T_, v_, om_ as prefixes)
CS_C (Body or Coordinate System) – Carrier-Frame - Wheel centre, attached to the vehicle (does not rotate with the wheel)
CS_R – Rim-Frame - Wheel centre, attached to the wheel (does rotate with the wheel)

addVisualisation

addVisualisation contains a pymbs.input.MbsSystem.AddVisualisation instance, see Visualisation for the various visualisation options

>>> world.addVisualisation.Box(body, length=1, width=1, height=1)

exportGraphReps(fileName)

Create a text file for saving the information / parameters of the graphical representations of the system. Data is stored plain text in a *.cfg file which can be used by other tools.

Parameters:: fileName (String.) – Path and file name for saving the generated ouput.

genCode

genCode contains a pymbs.input.MbsSystem.GenCode instance, see Code generation for all the writers and options available

>>> world.genCode.Python()

genEquations

genEquations contains a pymbs.input.MbsSystem.GenEqns instance, see Equation generation for the different equation generators and their options

>>> world.genEquations.Recursive()

genMatlabAnimation(modelname, dirname='.', **kwargs)

Use genMatlabAnimation to generate a MATLAB Animation file which will visualise your graphical objects using the simulation results from the MATLAB script which has been generated using genCode.

Parameters:

modelname (String.) – Name of the model - will be used as filename.
dirname (String.) – Directory where the MATLAB-Files will be put.
kwargs (Dictionary.) – Additional Settings may be passed as kwargs: * axislimits = list of six values [Xmin, Xmax, Ymin, Ymax, Zmin, Zmax]

genSarturisXml(modelname, dirname='.')

This function writes an XML-File for the Simulation Framework SARTURIS (ref:’http://www.sarturis.de’) developed at the institute of mobile machinery at Dresden University. The XML-File includes a sample definition of the HDAE-System as well as all graphical nodes for OpenSceneGraph. In order to use this output lxml needs to be installed.

Parameters:

modelname (String.) – Name of the model - will be used as filename.
dirname (String.) – Directory where the XML-File will be put.

getController(): Returns symbol and shape of the controller in a dictionary.

getMotionEquations(): liefert eine Liste von symbolischen Ausdrücken aus denen man qdd für gegebene q, qd berechnen kann

getParameters(): Returns dictionary with all the parameters (added with addParam) and their values.

getSensorEquations(): liefert eine Liste von symbolischen Ausdrücken aus denen man jeden Sensor-Wert für gegebene q, qd Werte berechnen kann

setGravity(value)

setGravity may be used to change the value of the gravitational acceleration which is set by default to 9.81.

Parameters:: value (float or integer) – New value of gravitational acceleration
Returns:: Nothing

Note

With this function only the value but not the direction of gravity can be changed. Changing direction can be achieved through the constructor of pymbs.input.MbsSystem

setJointRange(joint, minVal, maxVal)

Use this function to set the range in which the joint coordinate can be adjusted by the corresponding slider in the GUI.

Parameters:

joint (Joint-Object) – Reference to joint
minVal (int/float) – Minimum Value
maxVal (int/float) – Maximum Value

show(modelname=None, options={}, **kwargs)

Produces a GUI (graphical user interface) in which your model will be displayed as long as you provided graphic objects using pymbs.input.MbsSystem.addVisualisation(). Next to the model there will be sliders with which you can manipulate each joint coordinate directly and thus test your assembly.

Note

You must call pymbs.input.MbsSystem.genEquations() before you may call show!

Parameters:

modelname (String.) – Name of the model - will be displayed in the title bar.
options (Dict.) –
used to customise some gui features. Example showing the default values of the keys
```
>>> options = {'qFlexScaling':20,
               'qTransRange' :[-3, 3],
               'qRotRange':[-3.14, 3.14]}
```
qFlexScaling - a factor to scale the state of a flexible body

qTransRange - 2-list or tuple setting the limits of translational / prismatic joints values are interpreted as SI-unit [m]

qRotRange - dito for rotational /revoule joints values are interpreted as SI-unit [rad]

simulate(q0, t, modelname=None, text_output=False)

Simulates the motion of your system with the initial conditions given by q0 up to the time t and outputs the coordinates to a file.

Parameters:

q0 (List) – Initial conditions
t (Float) – Length of simulation
modelname (String.) – Name of the model - will be used as output filename
text_output (Boolean) – Set to True for CSV output instead of binary numpy file

General

pymbs.input

pymbs.input.MbsSystem

`pymbs.input`

`pymbs.input.MbsSystem`