optiSLang interfaces and customizations 2026 R1

Integration Node

Last update: 24.09.2026

The following topics describe the framework for creating a Python-based integration node.

Basic Requirements

The following requirements must be met for optiSLang to detect, load, and execute a plugin you provide.

  • Use the following naming convention for the script files: *_ci.py.
  • The required functions must be implemented in one script file.
  • Place the scripts in a directory scanned by optiSLang. Custom nodes found in any of these locations are loaded when the application starts and are then available within optiSLang. There are several location options:
    • The default custom plugin folder belonging to the installation: [installation path]/scripting/integrations
    • An alternative customized integrations directory specified in the SC_AlternativeCIDirectories entry of the optiSLang configuration file.
    • An alternative customized integrations directory specified by the environment variable OSL_ALT_CI_SEARCH_DIRS

Functions to Implement

You can add a plugin for extending optiSLang by providing a Python file following a special naming convention and by implementing a set of functions within it following special naming and signature conventions.

To provide a few simple string or integer settings, implement the default_settings function and optiSLang will provide generic standard entry fields (without any QML-based user interface technology). The execute_custom function is only required when you need advanced interactivity for user interfaces with QML-based settings. Otherwise, it is optional.

You do not need to declare anywhere explicitly the set of functions you are implementing. The code in the top-level ci.py file is the declaration. Based on the presence of function implementation, optiSLang creates the nodes. When you add or remove functions, you can trigger optiSLang to rescan the libraries by closing and restarting it.

The following functions are available:

load

This function is called when opening the node’s edit dialog box. In this function, define inputs (InputValueDefinition) and outputs (OutputValueDefinition) which are used in the node’s edit dialog box to register parameters and responses.

Incoming Arguments

Return Values

execute

This function is used to call your solver.

Incoming Arguments

Return Values

default_settings

This function defines the set of default settings associated with each new node instance. In a dictionary, you supply name-value pairs. The value type is important, for example, by forwarding a boolean value this setting is determined to be a boolean switch. Your code should then not set any other value type later. Without supplying any QML code for drawing user interface elements, optiSLang will add generic user interface elements, and these are determined by the value type given here. For instance, a boolean value induces optiSLang to display a check box in the node edit dialog box, whereas for string values a text entry field is created. The value types supported are boolean, integer, float, and string.

This function returns a list of zero to two elements, where each element can be either a Python object or a list of tuples. If you intend to use the generic settings user interface only, a planar dictonary (name-value pairs) or a list of tuples is supported. If you intended to use QML code, the elements can be nested Python objects. By providing a list of tuples, you can preserve the order of the given settings. The first element is always treated as a set of settings that require a node reset when manipulated in the user interface (modifying_settings). The second element is treated as a set of settings where you do not need to reset the node after they are manipulated in the user interface (non_modifying_settings).

Note: In default_settings, you define the sequence of setting names and value types for your new node type. In all other functions, the settings container stored with the node is input using arguments. Wherever settings are consumed, you assume the same dictionary/list structure (the same sequence of names and value types).

Incoming Arguments

Return Values

  • List with zero to two elements containing modifying_settings and/or non_modifying_settings as Python objects or lists of tuples.

execute_custom

This function serves as flexible, general-purpose, signal and information channel between the QML layer and the Python layer. When you access tabs, entries, and buttons in the QML-based settings user interface, the QML layer is running the process. If you need logic evaluation or other small computations, the QML layer allows for lines of JavaScript. However, if you cannot solve all settings-related work steps in the QML layer, then the execute_custom function allows you to trigger work in the Python layer and collect work results from there.

The execute_custom function can be triggered from the QML layer using the following:

backend.executeCustom(JSON.stringify(info_container))

Information exchange between the QML and Python layers using execute_custom occurs using JSON which is represented as a dictionary on the Python side.

The function can be used for as many types of tasks as needed, and as often as needed. Various different QML user interface elements created by you can trigger execute_custom, and in the QML code you can put together any kind of cargo-containing JSON to pass over to the Python layer. At the same time, in the Python layer, inside execute_custom you can trigger any kind of work on the Python side. When a task is resolve, you can send the result of the Python work back to the QML layer in the same way. A dictionary is used for the communication back to the QML layer.

Incoming Arguments

Return Values

  • Return cargo, can represent a JSON dictionary.

check

This function is called at the start of execution. You can use it to check if there are any issues preventing successful execution, and if there are, provide an early stop to prevent a potential time-consuming run.

Incoming Arguments

Return Values

  • RunStatus: An object for documenting success and logging.

reset

This function is called when the node is reset.

Incoming Arguments

Return Values

  • RunStatus: An object for documenting success and logging.

reset_hid

This function is called when the node is reset for a single HID.

Incoming Arguments

Return Values

  • RunStatus: An object for documenting success and logging.

initialize

You can use the initialize and shutdown functions to create and close a Python work environment. In some use cases, it can be difficult to use separate, atomic, agnostic functions, so it may be easier to work in a session-based manner. Initialize and shutdown allow you to, for example, avoid loading a heavy solver program multiple times during the lifecycle for one design and repeatedly for many designs by keeping a session/connection with one solver program instance alive all the time.

In the initialize function, you can generate a set of global variables which you can use in all other functions. A variable name can handle to simple things like numbers or strings, or, it can handle to more complex things like an open file, a spawned sub-process, an object of a class you write for managing solver program sessions, and so on.

You can find a simple demo exploiting the initialize-shutdown mechanism in the integration examples package.

Incoming Arguments

Return Values

  • Returns nothing or None.

shutdown

You can use the initialize and shutdown functions to create and close a Python work environment. In some use cases, it can be difficult to use separate, atomic, agnostic functions, so it may be easier to work in a session-based manner. The shutdown function allows you to close logs, any other open files, terminate sub-processes, close client program sessions, remote connections, and so on. In short, close down and tidy up the session workspace you have created with INI and which has evolved over many cycles of calling the other elementary integration functions.

Incoming Arguments

Return Values

  • Returns nothing or None.

get_required_license_caps

This function provides the license capabilities of the integration node plugin.

Incoming Arguments

Return Values

  • List of license capabilities as strings.

migrate_settings

This function can be used to update the settings of a node that was saved with an older version of the integration with different settings.

Incoming Arguments

Return Values

  • List with zero to two elements containing modifying_settings and/or non_modifying_settings as Python objects or lists of tuples.

node_renamed

This function can be used to react on a change of the node's name.

Incoming Arguments

Return Values

  • RunStatus: An object for documenting success and logging.

Data Exchange

Data exchange is done using exported optiSLang built-in types, lists, and dictionaries.

The following types are essential for implementing the data exchange between optiSLang and the node:

The following tables describe the standardized data structures of important objects transferred to several of the plugin functions where they are received in a structure of arguments.

Table 7: Common Incoming Key Word Arguments (KWARGs)

Name Type Description
project_working_directory String Path of the project's working directory.
modifying_settings Python object User interface editable settings that require a node reset if changed.
non_modifying_settings Python object User interface editable settings that do not require a node reset if changed.
properties Dictionary Properties of the node ("read_mode" - Bool, "environment" - String, "environment_mode" - String, "base_environment" - dict with the system environment of the calling process).
node_name String The current node's name.
osl_variables Dictionary Dictionary of optiSLang variables. Does not vary per HID.
reference_file_path RelativeSplittedPath Optional: Path to the reference file.
Only available if FileBased is not set to false in the configuration file.
reference_file_is_relative_to_working_directory Bool Optional: Whether or not the path to reference file is relative to the working directory.
Only available if FileBased is not set to false in the configuration file.
reference_file
Deprecated.		 String Deprecated.
Optional: Path to the reference file.
Only available if FileBased is not set to false in the configuration file.

Table 8: Additional Incoming KWARGs for the Execute Function

Name Type Description
input_container List of HidSpecificInputDataIntegrations Aggregate of arguments per HID.
registered_inputs Dictionary Dictionary of inputs that are registered in optiSLang.
registered_outputs Dictionary Dictionary of outputs that are registered in optiSLang.

Table 9: optiSLang Variables That Do Not Vary Per HID

Name Type Description
OSL_PROJECT_WORKING_DIR String Absolute path of the current project working directory (*.opd).
OSL_PROJECT_FILE_DIR String Absolute path of the current directory containing the project file (*.opf).
OSL_NODE_NAME String Name of the current node.
OSL_RLS_VER String The version number of optiSLang.
OSL_RLS_REV String The revision number of optiSLang.
OSL_RLS_FLG String A version suffix which is normally empty unless a specific build is set.
OSL_PROJECT_DIR
Deprecated.		 String Deprecated.
Absolute path of the current project (*.opd).

Table 10: optiSLang Variables that Vary Per HID in Execute Function

Name Type Description
OSL_DESIGN_NO String Design number.
OSL_DESIGN_NAME String Design directory name (for example, Design_0001).
OSL_DESIGN_DIR String Absolute path of the current design directory.

Table 11: HidSpecificInputDataIntegrations Attributes

Name Type Description
hid HID Hierarchical ID of a design variation, for example, [0.99.4].
hierarchy Dictionary The node's position within the surrounding systems.
input_slot_values Dictionary The values of the input slots.
osl_variables Dictionary Dictionary of optiSLang variables that vary per HID.
working_directory String The nodes working directory.
reference_file_path RelativeSplittedPath Optional: Path to the reference file.
Only available if FileBased is not set to false in the configuration file.
reference_file_is_relative_to_working_directory Bool Optional: Whether or not the path to reference file is relative to the working directory.
Only available if FileBased is not set to false in the configuration file.
parameter_values PyOsDesignPoint Parameter values for a specific HID.
reference_file
Deprecated.		 String Deprecated.
Optional: Path to the reference file.
Only available if FileBased is not set to false in the configuration file.

Table 12: HidSpecificOutputDataIntegrations Attributes

Name Type Description
hid HID Hierarchical ID of a design variation, for example, [0.99.4].
output_slot_values Dictionary A dictionary of name-value pairs that should be written to the output slots specified in the configuration file.
status RunStatus An object for documenting success and logging.
responses PyOsDesignPoint The responses and their values.
adapted_parameter_values PyOsDesignPoint Optional: The parameter values used by the solver.
Normally these are equal to parameter_values of HidSpecificInputDataIntegrations but if the solver requires adaptation (formatting, precision) of the parameters, the integration author can communicate theses parameters and their values to optiSLang. They are then shown in the design table.

Table 13: Contents of InputValueDefinition

Name Type Description
name String Name of the input.
reference_value PyOsDesignEntry The input's reference value.
additional_data Dictionary Specifies additional data (for example, unit). It is then used to create an additional column in the parameter registration in the node edit dialog box.
Tree view: When providing entry_n with n from 1-9 as key and a leaf name as value, a tree structure for grouping purposes can be created in the parameter registration.
lower_bound Float An object for documenting success and logging.
upper_bound Float The node's position within the surrounding systems.
input_slot_ discrete_states Dictionary The values of the input slots.
random_variable_type Enum
mean Float Optional: Mean of the data.
std_dev_ Float Optional: Spread of the data.

Table 14: Contents of OutputValueDefinition

Name Type Description
name String Name of the output.
reference_value PyOsDesignEntry The input's reference value.
additional_data Dictionary Specifies additional data (for example, unit). It is then used to create an additional column in the parameter registration in the node edit dialog box.
Tree view: When providing entry_n with n from 1-9 as key and a leaf name as value, a tree structure for grouping purposes can be created in the parameter registration.

Essential and Additional Files

The following image shows a standard set of files for creating a Python-based integration node.

files_overviewplugin.png

In the Python code inside the *_ci.py file, you can import other libraries, allowing you to add a larger package of files to a complex integration plugin. With each additional *_ci.py file, you provide an additional node in optiSLang’s module library. For the sake of organizational clarity, modularity, reusability, and testability, it can be beneficial to keep only small portions of code in the *_ci.py files and concentrate the function and class definitions in a library of one or several files to import from. This way, you can create multiple nodes which build on a common modular library.

Node Python Script (Essential)

This file is the only truly essential one. This file, when it contains a viable set of implemented functions can be sufficient to create a simple custom integration node.

File name convention: *_ci.py.\

Configuration File (Essential)

The configuration file allows you to set options determining the general function and appearance of your integration plugin.

File name convention: *_ci.json

For more details, see Configuration Files for Nodes.

Icon File

You can provide an icon for optiSLang to display on the node and make them easily recognizable. Accepted file types are .svg, .ico, .png, .jpg, .jpeg, and .bmp. Use the alpha channel for transparency. optiSLang uses color shading for depicting states, for example, running nodes are blue, failure states appear reddish. Those color messages are blocked if the quadratic icon does not contain transparent areas.

File name convention: *_ci.svg, *_ci.ico, *_ci.png, *_ci.jpg, *_ci.jpeg, *_ci.bmp

QML Files

These file enables you to design a graphical user interface for settings using the Qt markup language (QML). The settings user interface is embedded in the central area of the node edit dialog box. QML files are optional.

When you implement a QML-based settings user interface, you can offer fields and buttons with Qt-powered file and directory browser capabilities for a path setting. This compares to a simple string entry field displayed by the edit dialog box when you are not using QML. Check out the different demonstrators to see the differences.

If not present, then optiSLang falls back to displaying a vertical stacking of generic user interface elements. Working with that fallback level, you cannot control the logic of settings combinations or range of useful values. If a user enters an impossible combination of values in the edit dialog box, the only way of showing the problem is to throw an error in the CI code at runtime.

The demonstrator examples show you the benefits you can gain by designing a QML-based settings user interface. The settings are structured into groups, their activation states are interdependent, you can pull up file browse dialogs, you can work with sizable and scrollable areas and grid layouts.

File name convention: *_ci.qml

Description File

This is an optional file. You can use it to write a description of your plugin which is displayed in optiSLang's About Add-Ins dialog box. There is no file name convention, the file name is specified in the configuration file.

This is an optional file. You can use it to write a legal note of your plugin which is displayed in optiSLang's About Add-Ins dialog box. There is no file name convention, the file name is specified in the configuration file.

Connect with Ansys