API Contents

Properties for MBS

Python does not require the data type of variables to be declared. Thus a variable can have any value. In the same session, you can do the following:
  • Pressure = 200.0
  • Pressure = "High"
  • Pressure = [1, "High", False]

While such generality is desirable from a programming perspective, it is not desired when defining a language for specifying multibody systems. In the multibody context, all user-defined inputs have very well defined "properties" and any value given to any variable must conform to its properties.

For instance:
  • A body's mass must be a double greater than or equal to zero. It cannot be an array of doubles, a string, a negative value or anything else.
  • A body's inertia is a positive semi-definite, symmetric, 3x3 matrix that is specified with 0, 3 or 6 values. It cannot be anything else.
  • The stiffness, K, and the damping, C, for Bushings are specified as diagonal 3x3 matrices.
    • K and C accept exactly three numeric values as input - no more and no less
    • Each of the numeric values must be greater than or equal to zero

The Python Interface for MotionSolve has introduced the concept of a "Property" to encapsulate this notion.

  • Classes have attributes (for instance, PART has mass as an attribute)
  • Attributes have values that must conform to the property the attribute has (for instance, mass has a numeric value and mass ≥ 0)
Properties define the user defined values of a MotionSolve object:
  • The mass of a Part
  • The error of an Integrator
  • The stiffness, k, of a SpringDamper
  • And so on...

All attributes have a property. Trying to set an attribute value to an incorrect property type raises an error. For example:

>>> Part1.mass = "A bad value"

TypeError: float() argument must be a number

Not all attribute value validation can be handled when the value is set. Some checking needs to ensure required values are specified and there are no conflicts with other property values. For example, the i and j markers for a Joint must be specified and they must by associated with different bodies. This checking is done when the model is validated. Model validation is done after the entire model is defined.

Some property values can be set after a simulation has been started, other properties cannot be changed. You can change the mass of a Part but you cannot change the CM location or orientation. This limitation exists because the CM changes will cause all mass properties to change also.

The properties supported by MotionSolve, along with a brief description of each property, are shown in the table below.

Property Name Description
Int A Python int value.

Defaults to 0

Bool A Python Boolean value.

Defaults to False

Double A Python float value.

Defaults to 0.0

Note: For some Doubles, like the Part velocities (vx, vy, vz, wx, wy, wz) a value of 0 is different than no value. These are defaulted to None
Str A Python string value.

Defaults to ""

Enum A Python Str value that must be one of a specified list of values.

For instance, an ARRAY must be one of the following 4 types: "X" "Y" "IC" "U". The type attribute for an ARRAY has the property Enum.

EnumStr An Enum that takes multiple values. Each of the values is a string.

For instance, the INPUT attribute for a Friction object can take multiple values. These values must be from: "PRELOAD", "NONE", "ALL", "REACTION_FORCE_BENDING_MOMENT", "TORSIONAL_MOMENT"

Reference Reference to an existing MotionSolve object.

For instance, the IGEOM attribute of a CONTACT object must reference one or more existing GRAPHICS objects.

Location An instance of the Point class.

For instance, the QP attribute of a MARKER object must be Point objects. A Point is a list, so you can specify a list of three numbers also.

Angles Three Double values.

Used to specify the properties of the REULER attribute of MARKERs and PARTs.

Ips 0, 3, or 6 Double values to specify a body's inertia matrix.

This property ensures that the inertia matrix is positive semi-definite.

Exact A Python string to specify a body's fixed exact position for.

Example: exact="X:Z:PSI"

Pattern (String) A Python string to specify up to 10 True False values for.

Example: pattern="TFFFTFFFTF"

Function A Python string that contains a legal MotionSolve function expression.

Example 1: "DX(21,11)*VX(21,11) + DY(21,11)*VY(21,11) + DZ(21,11)*VZ(21,11)"

Example 2: "USER(21,11,4,0e-4)"

Routine A Python string a DLL/SO name followed by a function name or a callable function pointer.

Example: "tires::pacejka2002". The DLL/SO name is "tires". The DLL/SO contains a function called "pacejka2002" that is to be executed by MotionSolve.

Classes for MBS

Modeling Class Library
These classes are used to define a model. Many of these can be used as commands also. Commands are used to change model or simulation attributes during a simulation.
Model Accgrav Array Beam Bushing
Contact Coupler Curve Cvcv Cvsf
Debug Dcurve Diff Dsurface Dv
Equilibrium Field FlexBody Friction Gcon
Gear Gforce Graphics Gse Ic
Integrator Joint Jprim Kinematic Lse
Marker Mate Matrix Mforce Motion
Nforce Output Part Pforce Pinput
PointMass Poutput Preferences Ptcv Ptdcv
Ptdsf Ptdsff Ptsf Request Rv
Sensors Sforce Sfsf Spline SpringDamper
String Surface Tfsiso Transient Ucon
Units Variable Vforce Vtorque  
Table 1. Results Class Library
BodyResult H3dOutput RequestResult ResultObject RvResult
SimulationResults Upost UserMsg    

Access Functions

The MSOLVE API supports all the access functions that MotionSolve provides. Access functions are meant to be invoked from within user-subroutines to get system state dependent information.

Unlike the XML interface, where modeling elements were identified with IDs, in the Python interface, you can pass in objects or IDs to these access functions. The interface will accept any combination of objects and IDs as arguments.

For instance, consider the function ACCX (I, J, K, L). It is defined as:

ACCX (I, J, K, L) =  d L 2 d t 2 ( R I R J ) · x ^ K

R I is the vector from the global origin to the origin of I

R J is the vector from the global origin to the origin of J

x ^ K is the unit vector along the x-axos of marker K

It accepts up to four arguments:
  • I: the origin of a marker for which the x-component of the acceleration is desired
  • J: the origin of a marker from which the displacement to I is being measured
  • K: the coordinate system marker in which the results are expressed
  • L: the reference frame marker in which the two time derivatives of the displacement vector from J to I are being taken.
The ACCX function is implemented in this interface in the following way:
  • I can be a marker object or a marker ID
  • J can be a marker object, a marker ID or 0 signifying the global origin
  • K can be a marker object, a marker ID or 0 signifying the global coordinate system
  • L can be a marker object , a marker ID or 0 signifying the inertial reference frame

The following access functions are supported in the manner described above:

AX AY AZ ACCM ACCX
ACCY ACCZ ACCXYZ DM DX
DY DZ DXYZ FM FX
FY FZ FXYZ TM TX
TY TZ TXYZ VM VR
VX VY VZ VXYZ WM
WX WY WZ WXYZ WDTM
WDTX WDTY WDTZ WDTXYZ PHI
PSI THETA YAW PITCH ROLL
INCANG Q QDOT QDDOT UVX
UVY UVZ BUSH SPDP VTORQ
BEAM_FNC FIELD_FNC SFORCE_FNC VFORCE_FNC GFORCE_FNC
NFORCE_FNC JOINT_FNC JPRIM_FNC MATE_FNC MOTION_FNC
COUPLER_FNC CVCV_FNC PTCV_FNC CVSF_FNC SFSF_FNC
ARYVAL DIF DIF1 PINVAL POUVAL
VARVAL SENVAL DVAL DSVAL DSVAL1
DSARY DSARY1 RVAL RVAL1