Skip to main content

SoS Script API

2023 R2 Documentation - Overview

Last update: 12.07.2023

SoS 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 SoS functionality.

Features of Interest:

  • SoS 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.
  • SoS enhances the Lua language by adding methods to the Lua table sos.
  • Compatibility of the SoS script API cannot be guaranteed among different versions of SoS (as opposed to the binary data base format).

SoS currently supports two script languages:

  • Python

    The optiSLang Python executable is called when using the Python node in optiSLang, allowing you to execute SoS script code directly in optiSLang. Use the SoS 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 SoS GUI and SoS macro development. Further, the FMOPSolver.DLL provides embedded scripting for Lua (See SoS C-API documentation).

Both languages are extended using custom SoS 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 SoS GUI.

Introduction to SoS Python

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

Licensing the SoS Python Package

Importing the SoS Python module requires an optiSLang enterprise license. When using the module inside optiSLang, it shares the optiSLang Enterprise license.

See the [optiSLang Installation and Licensing Guide](]

The license remains locked for the lifetime of the Python program. There is no method for releasing it earlier.

Using the SoS Python Package

Here are some examples for using the SoS Python package:

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

Load modules "sos" and "tmath"

from sos_package import sos, tmath
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")

Run SoS Lua code

From Python, you can call any SoS Lua code that is generated by the SoS 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 SoS 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 SoS functions, e.g.


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 SoS Lua

The SoS GUI script language is based on Lua 5.3, allowing execution of any Lua code. SoS 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)

SoS Lua script examples

A function with return value

-- Load reference mesh
mesh = sos.importMesh_LSDynaK("/path/to/reference_mesh.k");

In Lua, comments always begin with "--". The function importMesh_LSDynaK() is defined in Lua table "sos" and returns a MetaStructure object, stored in the mesh variable.

A function without return value

-- Set reference mesh
sos.setReferenceMesh(sos.database(), mesh);

The function database() returns the global database Structure object.

Calling object member functions

-- Import field designs
sos.referenceDesign():setBasePath("/path/to/Design0001"); -- set location of reference design
sos.referenceDesign():addFile_LSPrePost(sos.database(), "/path/to/Design0001/field.k");
importer = sos.ImportDesigns(sos.referenceDesign()); -- call the ImportDesigns class constructor
importer:scanDesignRanges(); -- search for folders named DesignXXXX
importer:import(sos.database()) -- store the field designs in the global database

Object member functions are called by the ":" syntax. The function referenceDesign() returns the global ReferenceDesign object.

Calling static member functions

sortedIdentVector = sos.ElementDataObjectFilter.sortDesignIdents(identVector)

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

Lua script examples

See Scripting examples with Lua

Lua tables

Functions and class constructors are collected in Lua tables.

Table name Modules
sos. Import, Export, Data, Field models, Statistics, Toolbox, Graphics, Mesh mapper, Mop, Miscellaneous
fs. file
tmath. tmath

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 <TYPE> Class Template

The SoS script API provides four specializations. To use the class suitable for the desired data type, replace <TYPE> with:


In module Data, template specializations are prepended.

filter1 = sos.ElementDataObjectFilter(sos.database():elementData())
filter2 = sos.NodeDataObjectFilter(sos.database():nodeData())