2023 R2 Documentation - OverviewLast 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:
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 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](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 SoS Python Package
Here are some examples for using the SoS Python package:
Note: Always treat quotation marks (', ") carefully.
Load modules "sos" and "tmath"
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:
Lua versus Python SoS script
To call class member methods, Lua uses ":" while Python uses ".".
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.
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.
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");
A function without return value
Calling object member functions
-- Import field designs
sos.referenceDesign():setBasePath("/path/to/Design0001"); -- set location of reference design
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
Calling static member functions
Static member functions are called by the '.' syntax. No object instantiation is required.
Lua script examples
Functions and class constructors are collected in Lua tables.
|sos.||Import, Export, Data, Field models, Statistics, Toolbox, Graphics, Mesh mapper, Mop, Miscellaneous|
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.