API Structure#

The structure of the API takes full advantage of the object-oriented nature of python. In msolve, every model entity is a class that derives from a Base class named SolverObject.

Every model entity is equipped with inherited and native attributes that, when defined by the user, can explicitly describe their behavior.

Base Class Methods#

The base class SolverObject provides several utility methods that can be used across all derived classes. One such method is summary.

This method, when invoked upon a SolverObject instance, provides a concise summary including all its relevant attributes and their current values. If invoked on a model or on a msolve.Base.Composite class all its entities will be included in the summary.

Syntax:

solver_object.summary(output=None, recursive=True)

Parameters:

output (str): Optional file name for the output Jupyter Notebook (.ipynb).
If provided, links between various entities and references will be generated in the output HTML tables. If unspecified, the summary for this object will be printed to stdout.

recursive (bool): Optional flag defaulted to False.
If True all the children of this solver_object will be listed in a summary table.

Example:

# Assuming `part` is an instance of the Part class
part.summary()

This will output a detailed ASCII table that summarizes the key attributes of a SolverObject instance.

Below is an example output displaying various attributes of a Part object, outlining its id, name, center of mass (cm), ground status, inertia properties (ip), mass, and velocity along the y-axis (vy).

*--------*----*--------*----------*--------*--------------------------------------------*------*-------*
| Entity | id | name   | cm       | ground | ip                                         | mass | vy    |
*========*====*========*==========*========*============================================*======*=======*
| part_1 | 2  | part_1 | Marker/3 | -      | [40000.0, 40000.0, 40000.0, 0.0, 0.0, 0.0] | 2.0  | 500.0 |
*--------*----*--------*----------*--------*--------------------------------------------*------*-------*

Base Attributes#

There are four attributes that every MotionSolve entity inherits from the SolverObject class and they are described below.

SolverObject attributes#
Name	Description
id	An integer number that is unique among all objects of the same type. If not specified during the creation of a MotionSolve entity, msolve will automatically generate and assign an `id` to it.
label	A string assigned to an entity, serving as a label. If not specified, `label` defaults to an empty string.
active	A boolean value that determines whether the entity will be considered by MotionSolve during simulation. The default value of `active` is True, meaning that the entity will be taken into account by the solver.
name	A string value, used as a nametag for the entity. It is used to reference an entity that has been defined in a different python session, in reporting, doe, and for the Composite auto-attachment functionality.

Attribute Characterization#

While Python does not require the data type of variables to be declared, this is not desired when defining a language for specifying multibody systems.

For this reason, an msolve attribute is not just a simple python variable. Besides its value, an attribute contains information that establish its characteristics in detail.

These characteristics are described below:

Type

The “property” associated with the attribute. This is a type definition that allows attributes to be initialized and validated. An extended definition of the available properties can be found in the following section.

When an attribute requires multiple instances to be fully determined, Type is followed by an integer in square brackets (eg. Double [3]) that specifies the necessary number of entries. If zero, the number of entries is unrestricted.

Required

A boolean flag that defines if the attribute is required or not.

Default

A value that is assigned to the attribute if not specified by the user.

Modifiable

A boolean flag that defines if the attribute is modifiable by command, meaning that the user can change its value during simulation.

Designable

A boolean flag that defines if the attribute is designable, meaning that it can be used as a Design Variable for Optimization or Design Sensitivity Analysis (DSA).

Base Properties#

In the multibody context, all user-defined inputs to msolve objects have very well defined properties and any value given to any variable must conform to these properties.

The Python Interface for MotionSolve has introduced the concept of a “Property” to encapsulate this notion. Properties define the user settable values of a MotionSolve object.

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

Example#

Part.mass = "A wrong value"

PropertyException: Error setting Part.mass
could not convert string to float: 'A wrong value'

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

Properties#
Name	Description
Alias	A property that creates compatibility between objects.
Angles	A set of 3 Double values, used to define the 3-1-3 Euler angles.
Bool	A Boolean value.
Color	A color property. Use Color.colorMap for a list of the available colors.
Double	A double precision value.
Enum	A string value. It must be chosen from a specified list of values.
EnumStr	Multiple string values. They must be chosen from a specified list of values.
Exact	A string value. It specifies a body’s exact fixed position.
Faces	A list of lists of Int values. Each list contains three ids corresponding to the vertices (Nodes) of a triangular surface. Faces and Nodes are used in conjunction to create a triangular mesh geometry.
FileName	A string value. It specifies the location of a file and checks for its existence.
Function	A string value. It contains a legal MotionSolve expression or the parameters passed to the user defined subroutine.
Int	An integer value.
Ips	A set of 0, 3 or 6 Double values. It defines the Inertia Tensor.
Location	A set of 3 Double values. It can be defined using a Point, a list or a Marker instance.
Nodes	A list of Location instances.
Pattern	A string value. It can specify up to a pattern of 10 Boolean values.
Property	The Base class for all the properties.
Reference	A reference to an existing MotionSolve object.
Routine	A string value or a python callable. A DLL/SO name followed by a function name (eg.’DLL::function’) or a callable function.
Script	A string value. The path of the script containing the routine.
Str	A string value.