## On this page

  

 

 # Overview 

 Last update: 16.07.2025 

\*\* This documentation is BETA, not yet fully reviewed and may not reflect the true script documentation! \*\*

oSP3D provides embedded scripting. Nearly any command, including visualization, triggers a script execution. Hence, you can store the log of a session in a Lua script. By executing a previously stored script, you can:

- Execute a session to change input data
- Change certain session parameters
- Debug the application in case of an unforeseen event (crash)
- Theoretically, you can even use the script engine to enhance oSP3D functionality.

Features of Interest:

- oSP3D makes the Lua language (version 5.3) and Python fully available.
- Execute individual commands using the Lua console at the bottom of the main window.
- Execute multiple commands by copying and pasting them. Insert a block of commands from the clipboard or press Shift + Enter in the Lua console.
- Execute Lua script files from the command line using the command line parameter -s.
- oSP3D enhances the Lua language by adding methods to the Lua table "sos".
- Compatibility of the oSP3D script API cannot be guaranteed among different versions of oSP3D (as opposed to the binary data base format).

oSP3D currently supports two script languages:

- Python
    
    The optiSLang Python executable is called when using the Python node in optiSLang, allowing you to execute oSP3D script code directly in optiSLang. Use the oSP3D Python package for seamless development of optiSLang custom integration nodes.
- Lua
    
    Lua is a simple and high performance embeddable programming language for real-time processing. It is used in the oSP3D GUI and oSP3D macro development. Further, the FMOPSolver.DLL provides embedded scripting for Lua (See SoSP3DoS C-API documentation).

Both languages are extended using custom oSP3D functions and classes using the same API for both languages (with exception of a few language specific changes). Graphics commands (3D rendering) is supported only in oSP3D GUI.

---

# Introduction to oSP3D Python

The optiSLang Python executable is called when using the Python node in optiSLang, allowing you to execute oSP3D script code directly in optiSLang. You use the oSP3D Python package for seamless development of optiSLang custom integration nodes.

## Licensing the oSP3D Python Package

oSP3D Python module functions require optiSLang licenses. When using the module inside optiSLang, it shares the optiSLang licenses. When running optiSLang workflows with oSP3D Python Package API calls, the appropriate licenses must be checked out in the optiSLang License Management dialog, so licenses are shared with optiSLang.

See the [optiSLang Installation and Licensing Guide](https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v251/en/opti_inst_lic/opti_inst_lic.html)

Field metamodeling including signals (sensor) and 2D/3D fields functionality requires optiSLang Pro and AI+ licenses. Modeling of imperfect structures for UQ (Random Fields) functionality requires an optiSLang Enterprise license.

The licenses remain locked for the lifetime of the Python program. There is no method for releasing them earlier.

## Using the oSP3D Python Package

Here are some examples for using the oSP3D Python package:

**Note: Always treat quotation marks (', ") carefully.**

Load modules "sos" and "tmath"

try:

 from sos_package import sos, tmath

except:

 print("ERROR: failed to load SoS module. An optiSlang Enterprise license is required. An Ansys licensing client installation is required. Check your environment variables, see https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v212/en/opti_inst_lic/opti_inst_lic_config_requirements.html")



### Run oSP3D Lua code

From Python, you can call any oSP3D Lua code that is generated by the oSP3D GUI and written to the command log:

sos.execLua( 'settings = sos.LoadDataBaseSettings("myDatabase.sdb"); sos.loadDataBase(sos.database(), settings)' ) # load a database using Lua code

sos.printMeshInfo(sos.database()) # print mesh information of the loaded database using Python code



### Lua versus Python oSP3D script

To call class member methods, Lua uses ":" while Python uses ".".

Lua code:

-- select all field data objects of quantity "pstrain"

pstrainDataObjects = sos.database():data():filterQuantity("pstrain")



Python code:

\# select all field data objects of quantity "pstrain"

pstrainDataObjects = sos.database().data().filterQuantity("pstrain")



Some reserved words in Python can not be wrapped directly, for example *import* or *clear*. Append an underscore to call such oSP3D functions, e.g.

sos.database()._clear()



### Python lists and sos.StringVector

Input arguments of type sos.StringVector are compatible with Python lists of strings.

\# select all field data objects of quantities "pstrain" and "thickness"

dataObjects = sos.database().data().filterQuantity(["pstrain", "thickness"])



### Tmath Module and numpy

The module tmath is a fast linear algebra library. It is based on the C++ library Eigen2 and exposes most of its API directly to scripts. The following examples illustrate the compatibility with Python lists and numpy arrays.

\# vector in numpy

vec_np = numpy.array([1,2,3])



\# vector in tmath

vec_tmath = tmath.Matrix([1,2,3]) # tmath.Matrix() constructor accepts lists and tuples



\# matrix in numpy

mat_np = numpy.array([[1,2,3],[4,5,6]])



\# matrix in tmath

mat_tmath = tmath.Matrix([[1,2,3],[4,5,6]]) # tmath.Matrix() constructor accepts lists of lists



\# numpy.array to tmath.Matrix

mat_tmath = tmath.Matrix(mat_np.tolist())



\# tmath.Matrix to numpy.array

mat_np = numpy.array(list(mat_tmath))



\# functions with tmath.Matrix input arguments

dataObject = sos.createElementDataObject(sos.database(), vec_tmath)

dataObject = sos.createElementDataObject(sos.database(), vec_np.tolist())

dataObject = sos.createElementDataObject(sos.database(), [1,2,3])



---

# Introduction to oSP3D Lua

The oSP3D GUI script language is based on Lua 5.3, allowing execution of any Lua code. oSP3D script code is executed via

- the GUI's script command line
- executing an .ssc script file at program start
- by command line argument -s <file.ssc> (run script in GUI)
- by command line argument -b <file.ssc> (run script in batch mode)

## oSP3D Lua script examples

### A function with return value

> \-- Load reference mesh  
>  mesh = sos.[importMesh\_LSDynaK](group__import.xhtml#ga1b3d4d7a9aa07b994d5788f64dce55a3)("/path/to/reference\_mesh.k");

In Lua, comments always begin with "--". The function [importMesh\_LSDynaK()](group__import.xhtml#ga1b3d4d7a9aa07b994d5788f64dce55a3 "imports the mesh from a single LS-DYNA K file ") is defined in Lua table "sos" and returns a [MetaStructure](class_meta_structure.xhtml "Defines a meta structure which contains all data that is used to create a finite element mesh...") object, stored in the *mesh* variable.

### A function without return value

> \-- Set reference mesh  
>  sos.[setReferenceMesh](group__import.xhtml#ga380830b2ab7587d1c03c5ea245d0d139)(sos.[database()](group__data.xhtml#gaebcac3a2836ec9fdf2e47bd812994b6b), mesh);

The function [database()](group__data.xhtml#gaebcac3a2836ec9fdf2e47bd812994b6b "Gives access to the global database. ") returns the global database [Structure](class_structure.xhtml "The central data structure for SoS. ") object.

### Calling object member functions

> \-- Import field designs  
>  sos.[referenceDesign()](group__import.xhtml#gaeebdfe2e2b08f67a2a3e5c9873171679):[setBasePath](class_reference_design.xhtml#aa2ba2b1794ac9bad08da653ea8c99eda)("/path/to/Design0001"); -- set location of reference design  
>  sos.[referenceDesign()](group__import.xhtml#gaeebdfe2e2b08f67a2a3e5c9873171679):[addFile\_LSPrePost](class_reference_design.xhtml#ac4b1f9b78214f1ad46dead046c98659e)(sos.[database()](group__data.xhtml#gaebcac3a2836ec9fdf2e47bd812994b6b), "/path/to/Design0001/field.k");  
>  importer = sos.[ImportDesigns](class_import_designs.xhtml)(sos.[referenceDesign()](group__import.xhtml#gaeebdfe2e2b08f67a2a3e5c9873171679)); -- call the ImportDesigns class constructor  
>  importer:[scanDesignRanges()](class_import_designs.xhtml#a54f34c64e9326398eaaf5cdcb8127e08); -- search for folders named DesignXXXX  
>  importer:[import](class_import_designs.xhtml#a73dd3f56399568385400db0c3fc08295)(sos.[database()](group__data.xhtml#gaebcac3a2836ec9fdf2e47bd812994b6b)) -- store the field designs in the global database

Object member functions are called by the ":" syntax. The function [referenceDesign()](group__import.xhtml#gaeebdfe2e2b08f67a2a3e5c9873171679 "gives access to the reference design information ") returns the global [ReferenceDesign](class_reference_design.xhtml "defines information on imported data and files given a reference design ") object.

### Calling static member functions

> sortedIdentVector = sos.<a class="el" href="">ElementDataObjectFilter</a>.<a class="el" href="">sortDesignIdents(identVector)</a>

Static member functions are called by the '.' syntax. No object instantiation is required.

### Lua script examples

See [Scripting examples with Lua](lua_examples.xhtml)

---

## Lua tables

Functions and class constructors are collected in Lua tables.

Table name sos. [Import](group__import.xhtml), [Export](group__export.xhtml), [Data](group__data.xhtml), [Field models](group__fieldmodels.xhtml), [Statistics](group__statistics.xhtml), [Toolbox](group__toolbox.xhtml), [Graphics](group__graphics.xhtml), [Mesh mapper](group__meshmapper.xhtml), [Mop](group__mop.xhtml), [Miscellaneous](group__misc.xhtml) fs. [File system](group__file.xhtml) tmath. [tmath](group__tmath.xhtml)An especially helpful command is *info(object)*. You can use this command to list information on a given variable, table, or meta table (including methods and member variables).

---

## The &lt;TYPE&gt; Class Template

The oSP3D script API provides four specializations. To use the class suitable for the desired data type, replace &lt;TYPE&gt; with:

- Scalar
- Node
- [Element](class_element.xhtml "Repesents the geometry of a finite element within a mesh. ")
- Intpt

> sos.[ComputeMeanElement()](class_compute_mean.xhtml)  
>  sos.[ComputeMeanNode()](class_compute_mean.xhtml)

WarningIn module [Data](group__data.xhtml), template specializations are *prepended*. > filter1 = sos.<a class="el" href="">ElementDataObjectFilter</a>(sos.[database()](group__data.xhtml#gaebcac3a2836ec9fdf2e47bd812994b6b):[elementData()](class_structure.xhtml#ae5a367f5f54310b57d68222455e61e26))  
>  filter2 = sos.<a class="el" href="">NodeDataObjectFilter</a>(sos.[database()](group__data.xhtml#gaebcac3a2836ec9fdf2e47bd812994b6b):[nodeData()](class_structure.xhtml#a539f561c03982da57200d2ed47807d74))

---