This chapter lists the basic interface functions which can be used to set up a Exudyn model in Python.

General information on Python-C++ interface

This chapter lists the basic interface functions which can be used to set up a Exudyn model in Python. Note that some functions or classes will be used in examples, which are explained in detail later on. In the following, some basic steps and concepts for usage are shown, references to all functions are placed hereafter:

To import the module, just include the Exudyn module in Python:

import exudyn as exu

For compatibility with examples and other users, we recommend to use the exu abbreviation throughout. In addition, you may work with a convenient interface for your items, therefore also always include:

from exudyn.itemInterface import *

Note that including exudyn.utilities will cover itemInterface. Also note that from ... import * is not recommended in general and it will not work in certain cases, e.g., if you like to compute on a cluster. However, it greatly simplifies life for smaller models and you may replace imports in your files afterwards by removing the star import.

The general hub to multibody dynamics models is provided by the classes SystemContainer and MainSystem, except for some very basic system functionality (which is inside the Exudyn module).

You can create a new SystemContainer, which is a class that is initialized by assigning a system container to a variable, usually denoted as SC:

SC = exu.SystemContainer()

Note that creating a second exu.SystemContainer() will be independent of SC and therefore makes no sense if you do not intend to work with two different containers.

To add a MainSystem to system container SC and store as variable mbs, write:

mbs = SC.AddSystem()

Furthermore, there are a couple of commands available directly in the exudyn module, given in the following subsections. Regarding the (basic) module access, functions are related to the exudyn = exu module, see these examples:

#  import exudyn module:
import exudyn as exu
#  print detailed exudyn version, Python version (at which it is compiled):
exu.GetVersionString(addDetails = True)
#  set precision of C++ output to console
exu.SetOutputPrecision(numberOfDigits)
#  turn on/off output to console
exu.SetWriteToConsole(False)
#  invalid index, may depend on compilation settings:
nInvalid = exu.InvalidIndex() #the invalid index, depends on architecture and version

Understanding the usage of functions for python object SystemContainer of the module exudyn, the following examples might help:

#import exudyn module:
import exudyn as exu
#  import utilities (includes itemInterface, basicUtilities,
#                  advancedUtilities, rigidBodyUtilities, graphicsDataUtilities):
from exudyn.utilities import *
#  create system container and store in SC:
SC = exu.SystemContainer()
#  add a MainSystem (multibody system) to system container SC and store as mbs:
mbs = SC.AddSystem()
#  add a second MainSystem to system container SC and store as mbs2:
mbs2 = SC.AddSystem()
#  print number of systems available:
nSys = SC.NumberOfSystems()
exu.Print(nSys) #or just print(nSys)
#  delete reference to mbs and mbs2 (usually not necessary):
del mbs, mbs2
#  reset system container (mbs becomes invalid):
SC.Reset()

If you run a parameter variation (check Examples/parameterVariationExample.py), you may reset or delete the created MainSystem mbs and the SystemContainer SC before creating new instances in order to avoid memory growth.

Item index

Many functions will work with node numbers (NodeIndex), object numbers (ObjectIndex),marker numbers (MarkerIndex) and others. These numbers are special Python objects, which have been introduced in order to avoid mixing up, e.g., node and object numbers.

For example, the command mbs.AddNode(...) returns a NodeIndex. For these indices, the following rules apply:

mbs.Add[Node|Object|...](...) returns a specific NodeIndex, ObjectIndex, …

You can create any item index, e.g., using ni = NodeIndex(42) or oi = ObjectIndex(42)

The benefit of these indices comes as they may not be mixed up, e.g., using an object index instead of a node index.

You can convert any item index, e.g., NodeIndex ni into an integer number using int(ni) of ni.GetIndex()

Still, you can use integers as initialization for item numbers, e.g.:

mbs.AddObject(MassPoint(nodeNumber=13, ...))

However, it must be a pure integer type.

You can make integer calculations with such indices, e.g., oi = 2*ObjectIndex(42)+1 restricing to addition, subtraction and multiplication. Currently, the result of such calculations is a int type andoperating on mixed indices is not checked (but may raise exceptions in future).

You can also print item indices, e.g., print(ni) as it converts to string by default.

If you are unsure about the type of an index, use ni.GetTypeString() to show the index type.

Copying and referencing C++ objects

As a key concept to working with Exudyn , most data which is retrieved by C++ interface functions is copied. Experienced Python users may know that it is a key concept to Python to often use references instead of copying, which is sometimes error-prone but offers a computationally efficient behavior. There are only a few very important cases where data is referenced in Exudyn , the main ones are SystemContainer, MainSystem, VisualizationSettings, and SimulationSettings which are always references to internal C++ classes. The following code snippets and comments should explain this behavior:

import copy                        #for real copying
import exudyn as exu
from exudyn.utilities import *
#create system container, referenced from SC:
SC = exu.SystemContainer()
SC2 = SC                           #this will only put a reference to SC
                                   #SC2 and SC represent the SAME C++ object
#add a MainSystem (multibody system):
mbs = SC.AddSystem()               #get reference mbs to C++ system
mbs2=mbs                           #again, mbs2 and mbs refer to the same C++ object
og = mbs.AddObject(ObjectGround()) #copy data of ObjectGround() into C++
o0 = mbs.GetObject(0)              #get copy of internal data as dictionary

mbsCopy=copy.copy(mbs)             #mbsCopy is now a real copy of mbs; uses pickle; experimental!
SC.Append(mbsCopy)                 #this is needed to work with mbsCopy

del o0                             #delete the local dictionary; C++ data not affected
del mbs, mbs2                      #references to mbs deleted (C++ data still available)
del mbsCopy                        #now also copy of mbs destroyed
del SC                             #references to SystemContainer deleted
#at this point, mbs and SC are not available any more (data will be cleaned up by Python)

Exceptions and Error Messages

There are several levels of type and argument checks, leading to different types of errors and exceptions. The according error messages are non-unique, because they may be raised in Python modules or in C++, and they may be raised on different levels of the code. Error messages depend on Python version and on your iPython console. Very often the exception may be called ValueError, but it mustnot mean that it is a wrong error, but it could also be, e.g., a wrong order of function calls.

As an example, a type conversion error is raised when providing wrong argument types, e.g., try exu.GetVersionString('abc'):

Traceback (most recent call last):

File "C:\Users\username\AppData\Local\Temp\ipykernel_24988\2212168679.py", line 1, in <module>
    exu.GetVersionString('abc')

TypeError: GetVersionString(): incompatible function arguments. The following argument types are supported:
    1. (addDetails: bool = False) -> str

Invoked with: 'abc'

Note that your particular error message may be different.

Another error results from internal type and range checking, saying User ERROR, as it is due to a wrong input of the user. For this, we try

mbs.AddObject('abc')

Which results in an error message similar to:

=========================================
User ERROR [file 'C:\Users\username\AppData\Local\Temp\ipykernel_24988\2838049308.py', line 1]:
Error in AddObject(...):
Check your python code (negative indices, invalid or undefined parameters, ...)

=========================================

Traceback (most recent call last):

  File "C:\Users\username\AppData\Local\Temp\ipykernel_24988\2838049308.py", line 1, in <module>
    mbs.AddObject('abc')

RuntimeError: Exudyn: parsing of Python file terminated due to Python (user) error

Finally, there may be system errors. They may be caused due to previous wrong input, but if there is no reason seen, it may be appropriate to report this error on github.com/jgerstmayr/EXUDYN/ .

Be careful in reading and interpreting such error messages. You should read them from top to bottom, as the cause may be in the beginning. Often files and line numbers of errors are provided (e.g., if you have a longer script). In the ultimate case, try to comment parts of your code or deactivate items to see where the error comes from. See also section on Trouble shooting and FAQ.