Python

Python settings

You can configure your python settings in Reves DSE by following these steps:

  1. Go to File, Python settings… in the menu bar.
  2. The Python settings window appears.
  3. Select a Python version from the dropdown list of supported versions: 3.6, 3.7, 3.8, 3.9 .
    • The Python version in the settings is used to determine which “Python.Runtime” library must be used to communication with the specified Python version.
  4. Add the path to your python.exe by clicking the Open button to open the dialog window where you can select your python.exe.
    • The python.exe path is used to determine if the system environment variables do contain the path to the python.exe directory which is needed for the python functionality work at all. Furthermore, the directory of the python.exe is used to add additional paths of the Python engine which are needed for finding Python modules.
  5. Test your settings by clicking the Try init button in the toolbar
  6. When the try is finished the textbox displays the information concerning the made checks and the result of the initialization attempt.
  7. You can also set the following optional setting:
    • Script execution location: Explicitly set an execution location for the python scripts in the model. Instead of executing the code lines in the Python interpreter the code will be written to a file in this folder and executed from this location. This folder is also added to the Python paths for Python 3.0 and higher, so any other Python scripts in this folder will be available to the Python interpreter.
    • Reinitialize python with each call: Start each Python call with a new interpreter. The initialization of the PythonEngine is usually only done once for each calculation session. As a result, the Python interpreter is kept alive during the whole calculation session and only shutdown when the calculation is finished. Starting each Python call with a new interpreter has the advantage of each call not being affected by the caching of a previous python call (e.g. python modules are reloaded etc…). Enabling this option can impacts the calculation time significantly since each solution will likely initialize and shutdown the PythonEngine at least once.
      You could also consider using the reload function in your python code to reload a previously imported module.
      Reves DSE models containing Python script which use numpy ignore this setting and will never be shutdown and re-initialized. This is due to the reason that numpy does not support the load/unload cycle which causes the PythonEngine and Reves DSE to crash.
    • Redirect python script messages to the progress output: With this option enabled the Python stdout/stderr will be redirected to a stream in Python be read by Reves DSE after the Python function call has ended. This option can impact the calculation time slightly since each calculation will execute the additional code to redirect the stdout/stderr.
If the selected Python version is changed after the Python initialization has been attempted (when try init is pressed, or any Python function is tested/called from Reves DSE) a restart is required to set the correct library file for the communication with the specific Python version.

Adding a Python function to the model

You can add a Python function to the canvas by following these steps:

  1. Drag the Python function item from the toolbox to the canvas or double click it.
  2. The Python function editor popup appears.
  3. Click the Open button to open the dialog window where you can browse to the Python file
  4. Click Open in the dialog window to load the Python code.
    • The file should have the following format:
      import sys
      import math
      
      def test1(F,E,r):
        return F/(E*r*(0.025-r))
      
      def test2():
        x = (5 * 6 * 7 + 8)/2.56
        result = x + 2.5
        return result

      All functional code must be contained inside a function definition. Additionally, the function requires a return statement at the end for Reves DSE to use the result.

  5. Select a function from the drop-down list which contains the recognized functions from the Python code lines.
    Check the formatting (white lines and indents) in your Python code if the  function seem to be missing from the list and reselect your Python file in the file browse dialog to reload the code.
  6. Enable the buffering of the results by checking the “Buffer the results” checkbox. This way the combination of input and output values will be remembered during the calculation session and prevent Reves DSE from executed the Python script unnecessarily.
  7. Link input and output parameters of the selected Python function to parameters in the model by selecting the corresponding parameter from the drop-down list.
  8. You can add multiple parameters to the single Python output parameter since Reves DSE cannot determine if this Python parameter contains a single value or multiple values.
    Reves DSE supports the use of scalar and array parameters and is able to link those to either the input or output of a Python script. Length checks are not performed so it is important to make sure that the array length in the script matches the array length of the DSE parameter.
  9. Click the OK button to add the Python function to the canvas.
You can also test your Python function settings in the ‘Test’ tab page. See the Python section for more detailed information about this.

Adding a Python function to the view

You can add a Python function to the design view canvas by following these steps:

  1. Drag the Python function item from the toolbox to the canvas or double click it.
  2. The Python function editor popup appears.
  3. Click the Open button to open the dialog window where you can browse to the Python file.
  4. Click Open in the dialog window to load the Python code.
  5. Select a function from the drop-down list which contains the recognized functions from the Python code lines.
Check the formatting (white lines and indents) in your Python code if function seem to be missing from the list and reselect your Python file in the file browse dialog to reload the code.
  1. Link input parameters of the selected Python function to parameters in the model by selecting the corresponding parameter from the drop-down list.
  2. Click the OK button to add the Python function to the canvas.
You can also test your Python function settings in the ‘Test’ tab page. See the Python section for more detailed information about this.

Progress output in the calculation environment

During calculations and after calculations you will find a Python progress panel and a Progress panel on the right side of the calculations environment. The first panel will show a log containing information related to the python calls. This information has been reduced compared to the information provided by the ‘Test’ tab page in the Python function editor to prevent information clutter. The log will provide:

  • A time stamp with certain messages.
  • The notification that a Python function call will be started.
  • The current counter for a Python function call during the calculation session.
  • Any redirected Python stdout/stderr output, if enabled in the settings.
  • Whether a Python function call has been skipped due to the results buffer.
  • Any caught error messages.

The Progress panel will display the current debug settings if these are enabled and provide progress metrics like run time, solutions generated, solve iterations and the random seed used at each solve thread.

Using the Python function in the calculation environment

You can perform post analysis on a solution with any of the Python canvas items added to the view canvas. You can select solutions in the solution explorer and then press the Start button on the right side of your Python canvas item. The input values for the Python function will be gathered from the selected solutions. If multiple solutions are selected then the Python function call will be performed for each individual solution in the selection. The progress and the results of each Python function call will be posted to the Python progress panel.

Be careful if multiple solutions are selected and the output of the python script is a file. If the python script does not handle the cases where the  output file already exists it will be likely be overwritten with every Python function call.

Python function test

You can test your Python function setting in the second tab page called Test in the Python function editor. It is recommended to test these settings to at least ensure the Python function call works and to check if your output parameter linkage is correct.

You can test your Python function settings in by following these steps:

  1. Complete your function settings in the Python function tab page.
  2. Enter your input values in the input column in the table on the left. These test values are entered as is and not converted.
  3. Press the Start button to test the Python functions with these input values.
  4. After completion the textbox below will display information regarding the Python function execution and the elapsed time. The output column in the table on the right will display the return values from the Python function.
Additional rows are added to the table on the right if the Python function returns more values than output rows available. Do not forget to adjust the output parameters in your settings if the amount of output parameters did not match in your test.

Limitations and remarks

The python functionality in DSE works by using an external Python application to execute the Python script. The coupling and calling are enabled by using a third-party library called ‘Python for .NET’ (Python.Engine.dll / Python Engine). DSE has limited control over the issues that might occur on the Python side due to the external nature of this approach. Errors or crashes on the Python side which are not reported back to DSE through the Python Engine cannot be handled by DSE and might crash the application. The following section contains any limitations of this Python integration approach and remarks concerning how to use it.

Please report any recurring (reproducible) crashes to us by e-mail: revesdse@reden.nl. (Providing an example python script or a DSE model to reproduce the error with would be appreciated.)

  • The Python functionality only works with a 64-bit Python installation.
  • The only supported Python versions are 3.6, 3.7, 3.8, 3.9.
  • This library “is an integration of the CPython engine” and therefore only compatible with CPython compatible modules/libraries.
  • The system environment variables PATH for python and any other python folder locations (like Scripts) is based the provided paths in the Python settings window with Python 3.0 and higher.
  • Reves DSE is limited to a single calculation thread when it contains a Python script. This is due to recurring instability issues with multithreaded calculations which result in sudden crashes and freezing of the application.
  • The ‘Reinitialize python with each call‘ option in the python setting will be ignored if the script contains numpy. This is due to the problem that “numpy does not support the python engine load unload cycle” which occurs on reinitialization. Importing the numpy module a second time will crash the application.
  • would cause the modules to be unloaded and reloaded and  The setting to reinitialize with each python call
  • The function input values are assumed to be real values when they are entered. Python functions that require an input value to be an integer (ex. an input value to determine the number of iterations) do not work.
  • Reves DSE supports the use of scalar and array parameters and can link those to either the input or output of a Python script. The use of dictionaries is currently not supported.
  • The Python function is required to have a “return” command so Reves DSE can receive the output values.
  • If the Python function settings has multiple output values specified, then it can only solve in one direction (only the output parameters) instead of solving both ways like a Reves DSE expression can. Due to this it is likely that your model will not generate solutions if you manually set a value for a model parameter that is linked to a Python function output.
  • For Python items in the model, it is crucial for the number of linked output parameters to match the output amount of the Python function. If the number does not match the solution generation could fail or the found solution is invalid/incorrect.