API Structure

The structure of the API takes full advantage of the object-oriented nature of python. In the msolve library, each model entity is represented by a class. These classes are all derived from a base class called SolverObject.

Each model entity class has attributes that it inherits from the SolverObject base class, as well as attributes specific to that particular model entity. These attributes, when set by the user, define the behavior of the entity.

Base Class Methods

The base class SolverObject provides several utility methods that can be used across all derived classes. The most commonly used methods are listed below.

SolverObject methods

Name	Description
lookupByName(type, name)	Fetch a model entity by specifying its class type and name.
lookupById(type, id)	Return a model entity given its class type and id.
getChildren(type=None, name=None, recursive=True, context=None)	Return a list of child objects matching type, name (supports wildcards), and/or context. Can search recursively through hierarchy.
getChild(name=None, context=None, **kwds)	Return the first matching child object by name, type, or context. Performs a primary search in Composite children and a fallback in the full hierarchy.
summary(output=None, recursive=None, type=None, format=None)	Print a summary of this object to stdout. If output is provided, write the summary to a Jupyter notebook (with hyperlinks between referring entities). When format='json', writes a JSON summary file suitable for JSON viewers.

One such method is summary(output=None, recursive=None, type=None).

This method, when invoked on a SolverObject instance, provides a concise summary including the instance relevant attributes and their current values (when they differ from the defaults). When summary is 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, type=None)

Keyword Parameters:

output:

(str or None) Specifies the output stream. If None, the default output is used. If set to an .ipynb file, the result will be written to a Jupyter notebook where entities that refer to each other generate hyperlinks.

recursive:

(bool) If set to True, the method will include all children recursively. If False, only the current object is summarized.

type:

(type or None) Filters the summary to include only objects of the specified type. If None, all objects are included.

format:

(‘ascii’, ‘json’ or None) Determines if the model summary is to be generated as a json file or printed to screen. If None, a rich table is printed to the screen.

Note

If format='json', a JSON file is written (useful for JSON viewers and tooling).

Example:

Below are some example outputs.

# calling summary on `part`, an instance of the Part class
part.summary()

The command above will generate a table showing various attributes of a Part object, outlining its id, name, center of mass (cm), inertia properties (ip), mass.

Part
┏━━━━━━━━┳━━━━┳━━━━━━┳━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Entity ┃ id ┃ name ┃ planar ┃ mass ┃ cm       ┃ ip                             ┃
┡━━━━━━━━╇━━━━╇━━━━━━╇━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Part_2 │ 2  │ part │ None   │ 4.0  │ Marker/1 │ [1272.0, 1272.0, 1272.0, 0.... │
└────────┴────┴──────┴────────┴──────┴──────────┴────────────────────────────────┘

The next command shows the summary of all the markers in a simple model containing a single part.

# Calling summary on a model and only display its Markers
model.summary(recursive=True, type=Marker)

model.summary(recursive=True, type=Marker)

Model
┏━━━━━━━━━┳━━━━┳━━━━━━┓
┃ Entity  ┃ id ┃ name ┃
┡━━━━━━━━━╇━━━━╇━━━━━━┩
│ Model_0 │ 0  │ -    │
└─────────┴────┴──────┘

Info
┏━━━━━━━━┳━━━━━━━┓
┃ Entity ┃ Count ┃
┡━━━━━━━━╇━━━━━━━┩
│ Marker │ 1     │
└────────┴───────┘

Marker (1)
┏━━━━━━━━━━┳━━━━┳━━━━━━┳━━━━━━━━┳━━━━━━━━┓
┃ Entity   ┃ id ┃ name ┃ part   ┃ body   ┃
┡━━━━━━━━━━╇━━━━╇━━━━━━╇━━━━━━━━╇━━━━━━━━┩
│ Marker_1 │ 1  │ -    │ Part/2 │ Part/2 │
└──────────┴────┴──────┴────────┴────────┘

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 plays a crucial role in automatic reference resolution, especially in hierarchical models.

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. This is determined by the next “property”.

Count

Specifies how many entries a property may hold. count=1 means that exactly one entry is expected, for example a part.mass attribute can have only one value. count=0 means that a variable number of entries is allowed. This is used in documentation and strict count is generally not enforced, but can be during model validation.

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	Provides an alternative name for a property to support compatibility and flexible naming.
Angles	A set of three Double values representing 3-1-3 Euler angles.
Bool	A Boolean value (True or False).
Color	Specifies a color using a predefined palette. Use Color.colorMap for all available options.
Double	A double-precision floating-point number.
Enum	A string value selected from a predefined list of allowed options.
EnumStr	A list of string values, each chosen from a predefined set.
Faces	A list of triangles defined by vertex indices, used for creating mesh geometry with Nodes.
FileName	A file path string that checks the existence of the specified file.
Function	A string containing either a valid MotionSolve expression or parameters for a user-defined subroutine.
Int	An integer value.
Ips	A set of 0, 3, or 6 Double values used to define an inertia tensor.
Location	A 3D point defined as a list of three Double values, a Point, or a Marker.
Nodes	A list of Location instances representing mesh vertices.
Pattern	A string pattern of up to 10 values T for True, F for False (e.g., ‘TFTFTF’).
Property	The base class for all property descriptors.
Reference	A reference to another MotionSolve object (e.g., a Body, Marker, etc.).
Routine	Specifies a callable function via Python, or a DLL/SO path with a function name (e.g., ‘lib.so::myFunc’).
Script	The path to an external script that defines a user routine.
Str	A string value.