/
Python 3 Scripting

Python 3 Scripting

Apr 05, 2022



This section describes how to extend and add additional functionality by using the built in scripting tool.

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

Refer to the following documentation for additional information on a Vortex application's setup file and how to modify it.

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.

See Python 3 Scripting - Python Usage and Environment Configuration



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 labelled 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

The most direct way to communicate between Vortex and your Python script is to use fields (inputs, outputs and parameters) on the Dynamics Script extension. Both the Vortex application and the Python script can access those fields.
But before accessing fields you must first add them to the extension.

Using the Vortex Studio Editor

Right click on the dynamics script extension and select "Edit"

In the window that appears you can add inputs, outputs and parameters to your script.



There are 3 field containers on each scripts,

  • Inputs

  • Outputs

  • Parameters

in Python access the fields using the syntax

"extension.inputs.field_name"

"extension.outputs.field_name"

"extension.parameters.field_name"

See code below as an example accessing fields created earlier.

Accessing fields in Python 3
def pre_step(extension): # The boolean input field in the screenshot above is named "boolean input" # Notice that spaces are replaced by underscores my_field = extension.inputs.boolean_input # my_field is a boolean input, you can read its value like so bool_value_of_my_field = my_field.value if bool_value_of_my_field: extension.outputs.an_output_double.value = 3.1415 else: parameter_number = extension.parameters.number.value extension.outputs.an_output_double.value = parameter_number

Using Python Code only

Fields can be created directly from Python code if you prefer.  The following code is functionally the same as the previous example.

Creating fields from a script in python 3
import Vortex def on_simulation_start(extension): # Creating an input of type boolean extension.createInput("boolean input", Vortex.Types.Type_Bool) # Creating an output of type double extension.createOutput("an output double", Vortex.Types.Type_Double) # Creating a parameter of type double extension.createParameter("number", Vortex.Types.Type_Double) def pre_step(extension): # The boolean input field we created on simulation start is named "boolean input" # Notice that spaces are replaced by underscores my_field = extension.inputs.boolean_input # my_field is a boolean input, you can read its value like so bool_value_of_my_field = my_field.value if bool_value_of_my_field: extension.outputs.an_output_double.value = 3.14159265359 else: parameter_number = extension.parameters.number.value extension.outputs.an_output_double.value = parameter_number



More information on creating and getting fields in python

The functions createInput(), createOutput() and createParameter() are utility functions each encapsulating a frequent use case of this API. There is several things to mention about these functions.

  • The new functions have the following signatures

    create field functions signatures

    def createInput(name, type, defaultValue = None, description = None, physicalDimension = None) def createParameter(name, type, defaultValue = None, description = None, physicalDimension = None) def createOutput(name, type, defaultValue = None, description = None, physicalDimension = None)



  • The available types for the parameter type are in Vortex.Types enumeration. If this parameter is an invalid value, this function will fail. 

  • The available types for the parameter physicalDimension are in Vortex.VxPhysicalDimension enumeration. By default, Vortex will assign a value corresponding to VxSim.VxPhysicalDimension.kNone to fields whose physical dimension are not defined. This means the function getPhysicalDimension() will never return None even if explicitly declared in the call to createInput(), createOutput() or createParameter(). This behavior also is consistent with the addInput(), addParameter(), addOutput() functions.

  • The functions createInput() and createParameter() ignore the parameter defaultValue if the field already exists. This allows experimenting with different values in the editor's interface without having to change the script.

  • The function createOutput() reset the output field's value to defaultValue even if the field already exists. This behavior is different from createInput() and createParameter().