oSP3D Script API 2024 R1

Overview

Last update: 22.02.2024

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

Importing the oSP3D 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](https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v212/en/opti_inst_lic/opti_inst_lic.html]

The license remains locked for the lifetime of the Python program. There is no method for releasing it 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("/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
sos. Import, Export, Data, Field models, Statistics, Toolbox, Graphics, Mesh mapper, Mop, Miscellaneous
fs. File system
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 oSP3D script API provides four specializations. To use the class suitable for the desired data type, replace <TYPE> with:

sos.ComputeMeanElement()
sos.ComputeMeanNode()

Warning
In module Data, template specializations are prepended.

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

Connect with Ansys