API Contents
Properties for MBS
- 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.
- 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)
- 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:
is the vector from the global origin to the origin of I
is the vector from the global origin to the origin of J
is the unit vector along the x-axos of marker K
- 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.
- 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 |