/
Python 3 Scripting Extension inside Dynamics Content

Python 3 Scripting Extension inside Dynamics Content

 

This document describes how to extend and add additional functionality to a dynamics content by using the built in scripting extension.

Supported Use Case

The Dynamics Script Extension (Python 3) allows you to use the Python 3 programming language to modify the behaviour of dynamic elements of your simulation while it is running.

For example, if a mechanism consists of two parts that are constrained by a hinge, adding tension to that mechanism will not cause the hinge to break. However, a simple script that reads the tension and disables the constraint if it reaches a certain threshold will accurately simulate breaking the hinge.

A Dynamics Script is part of your content. The extension can be added to either a scene, mechanism or assembly document.

Basic Concepts

Python Interpreter Support

The Dynamics Script extension makes it easy to work with a Python 3 interpreter installed on your system. Vortex Studio comes bundled with a default interpreter but if you want to use third party packages or a different Python distribution you should point your Vortex application
towards an external interpreter that you previously installed.

The only restriction is that the supported Python version is Python 3.8. The default interpreter currently bundled with Vortex Studio is 3.8.6.

Workflow

  1. (Optional) Setting the Python Interpreter

  2. Adding a Dynamics Script extension to your content

  3. Adding Fields

  4. Writing a Dynamics Script's Code

Setting the Python Interpreter

Vortex provides a default Python Interpreter. If you need your own, you can specify it at the root level of a setup document, under the container Python 3.

Python 3 Environment Parameters

Interpreter

You can select which Python 3 environment you want to use on your system from the Setup document.  Please note that these settings are only available on the root item of your Setup document.

By default, the "Interpreter Directory" parameter is not specified. In this case, a version of Python 3 packaged with Vortex Studio will be used(you can find it under "C:\CM Labs\Vortex Studio 2020b\resources\Python3DefaultInterpreter").

If a directory is specified, Vortex Studio will use the Python 3 environment in this directory. Please note that the given directory must point to the directory where "python.exe" can be found.

The current recommended Python 3 interpreter is Python 3.8.6 64-bit, as Vortex Studio provides. Any distribution should be compatible as long as it uses Python 3.8 64-bit.

However, there may be incompatibilities between Vortex Studio and some Python modules present in your Python distribution.

Shared Python Modules

After specifying your preferred Python 3 environment, you can also specify Python modules that you want to share between all Python 3 scripts running in Vortex Studio.  This can be done by using the "Shared Python Modules" parameter.

The Vortex module is always shared, but additional user modules can be added to the list. 

Adding modules to this list can save memory for heavy modules. It also provides a unique initialization entry point for some modules.  For most Python modules, it is not necessary to add them in this "Shared Python Modules" parameter.

However, some Python modules cannot be imported, or cannot be imported for multiple Python sub-interpreters. It can result in a freeze of the application or even a crash. This is a limitation for some Python modules. In this case, it is needed to add this Python module in the "Shared Python Modules" parameter.

Here is a list of known Python 3 modules that must be added to the Shared Python Modules list before they can be used:

  • numpy

  • asyncio

  • doctest (relies on asyncio)

  • unittest (relies on asyncio)

Python Module Search Paths

By default, the Python 3 integration in Vortex Studio will look in the following directories when importing Python modules:

  • default sub-directories in the selected Python 3 interpreter's installation folder

  • Vortex Studio's "bin" directory

When developing content with Vortex Studio, it can be useful to share Python code between scripts. In this case, it is recommended to create a custom Python module where this reusable code can be defined. Here is an example of such a Python module:

  • custom_module

    • __init__.py

    • helpers.py

This folder structure represents a Python module named "custom_module" having a "helpers" script. This Python module can be packaged alongside the Vortex Studio content using it. Here is an example of DynamicsScript using "myTestFunction" defined in helpers.py:

from custom_module import helpers def on_simulation_start(extension): helpers.myTestFunction()

The path to the "custom_module" can be specified in the Setup document under the "Python 3" section under the field named "Python Module Search Paths":

The provided search path must point to the parent directory of your custom Python module. In the example above, the specified path should point to the parent directory of the "custom_module" directory.

Unless the saved search paths are saved as an absolute path using the filename option, they will be saved relative to the location of the Setup document. In that case, the custom Python modules should always be packaged at the same relative path from the Setup document where they are referred.

Embedded Dynamics Scripts

Dynamics script extensions can be added to the content to modify dynamics behavior and will use the Python modules available in the Python 3 distribution specified in your Setup document.

External Modules

To use Python modules that are not included with the default version of Python installed with Vortex (for example, NumPy), you can install and use those modules from your system's Python interpreter instead. To do so, follow these steps:

  1. Install the new module to your system's Python interpreter

  2. Follow the instructions on this page in the section Setting the Python Interpreter to change the version of Python that Vortex will use to your system's Python interpreter

  3. Check the list of modules on this page that must be added to the Shared Python Modules. If your module requires it, add it to the list. Failing to do so will result in Vortex freezing or even crashing.

Adding a Dynamics Script extension to your content

Prerequisites: If you need to use another Python 3 interpreter than the one bundled with Vortex Studio, follow the steps labeled Setting the Python Interpreter above.

  1. Launch the Vortex Studio Editor.

  2. Open your content file or create a new assembly, mechanism, or scene.

  3. In the Toolbox panel, under the Scripting category, add a Dynamics Script extension.

  4. In the Properties panel, set the path to the script you want to use to the parameter Script Path.

Your script will be automatically analyzed and any syntax error will be reported to you as warnings on the extension.
Every time, you edit and save your script in your code editor, it will be reimported into Vortex.

Adding Fields