Managing Macros

The File menu option Macros > Manage macros provides for viewing and managing both oSP3D-supplied macros and your user-defined macros. The Manage macro window supports:

Note: In the Toolbox Window, the Manage macros option is under the Field data models functional category heading.

Guidelines

Macros with duplicate identifiers fail to work.
User-defined macros are saved to the oSP3D database file. For more information, see Adding or Editing a User-Defined Macro.
Macros compatible with the oSP3D FMU exporter must take a database type as the first argument and a design ident as the second argument. For more information, see Writing Macros Compatible with the FMU Exporter.
To protect your intellectual property, you should obscure your macros. For more information, see Obscuring a User-defined Macro

Adding or Editing a User-Defined Macro

You can add a new or edit an existing user-defined macro for custom analysis and data processing and then test its validity.

This table describes the fields in the Edit chunks / macros window:

Field	Description
Identifier	The macro is added to the Lua table sos_chunks. You call the macro from the script with `sos_chunks.ident()`.
Name	A human-readable version of the identifier that appears in the FMU exporter.
Brief help	A brief function description of the macro that is displayed by the FMU exporter.
Help	An extended function description of the macro that is displayed by the FMU exporter.
Input arguments	Provides for defining the variable name, type, and help text for input arguments.
Return values	Provides for defining the variable name, type, and help text for return values.
Code	The oSP3D script code or Lua code. For more information, see the oSP3D API documentation on the Ansys API Documentation site.
Compatibility	Defines the macro's mesh compatibility.
Requires Mesh	Indicates whether the mesh is required.
Test code	Provides for testing your macro. You can write your own test code or click Generate test template to have oSP3D attempt to generate test code with sensible values. Clicking Test runs the macro tests for syntax errors and asserts the correct return values. For more information, see Testing User-defined Macros.

This next table describes the data types for input arguments and return values:

Data Type	Description
string	A basic string type.
integer number	A basic integer type.
floating point number	A basic floating point type.
bool	A basic Boolean type.
matrix	A tmath.Matrix.
input scalar ident	A string type for data object identifiers. Use this in combination with the `database` and `design ident` types. The macro expects that the key `sos.DataObjectKey(designIdent, objectIdent)` exists in the database.
input node ident
input element ident
output scalar ident	A string type for data object identifiers. Use this in combination with the `database` and `design ident` types. The macro writes a data object with key `sos.DataObjectKey(designIdent, objectIdent)` to the database.
output node ident
output element ident
remove scalar ident	A string type for data object identifiers. Use this in combination with the `database` and `design ident` types. The macro removes a data object with key `sos.DataObjectKey(designIdent, objectIdent)` from the database.
remove node ident
remove element ident
database	An `sos.Structure` object that lets the macro work on a specific database. Pass `sos.database()` to use the current global database.
design ident	A string type for design identifiers that let macros work on a specific design identifier.
unknown	Any other type.

Writing Macros Compatible with the FMU Exporter

The oSP3D FMU exporter writes FMU input variables to the global database (sos.database()) and reads FMU output variables from the global database.

For macros to be compatible with the FMU exporter, they must take a database type as the first argument and a design ident type as the second argument.
If the macro is to read a scalar FMU 2.0 input variable, it takes an input scalar ident type as an argument and reads the scalar input's value by calling database:scalarData():find(designIdent, scalarIdent).
If the macro is to provide a scalar FMU 2.0 output variable, it takes an output scalar ident type as an argument, and creates a scalar data object with key sos.DataObjectKey(designIdent, scalarIdent) in the database that is passed with the first argument.

Testing User-defined Macros

You should test your macros for syntax errors and output validity. You can let oSP3D attempt to generate test code with sensible argument values or write your own test code for more elaborate testing. When the test is executed, the macro is saved.

Caution: When you execute a test, you are using the global oSP3D scripting environment, which means that your tests can change the global database.

Copying a Macro

You can copy either a supplied or user-defined macro and then edit it to create a new user-defined macro. When oSP3D creates the copy, it adds the suffix _copy to the identifier. However, you can change the identifier to any unique value when you edit the new user-defined macro.

Deleting a User-defined Macro

You can delete a user-defined macro from the oSP3D database. It is excluded from the database when the database is saved. You cannot delete a standard macro.

Obscuring a User-defined Macro

To protect your intellectual property, you can obscure a user-defined macro. Once the macro is obscured, you cannot display or edit the macro's code. However, Ansys is able to restore the code.