13.6.4. User-defined Macros

You can write your own macros and make them available in the Macro Calculator.

The following topics are discussed:

13.6.4.1. Writing a Macro

Using a text editor, you can write a macro in a CFD-Post session file format (file extension .cse).

A macro can contain:

Special commented lines that help define the graphical user interface for the macro
Power Syntax commands
For details, see Power Syntax in Ansys CFX.
CCL (see CFX Command Language (CCL) in CFD-Post)

A macro must contain at least one subroutine written using Power Syntax.

Following are two example subroutines written using Power Syntax:

! sub Hello1 {
! print "Hello !\n";
! }
! sub Hello2 {
! ($title, $name) = @_;
! print "Hello $title $name\n";
! }

Note that commas are used to separate arguments. Also note that strings are quoted.

You can embed graphical user interface controls into the macro by writing special comments between the # Macro GUI begin and # Macro GUI end lines. An example macro follows:

# Macro GUI begin
#
# macro name = Area Average Macro
# macro subroutine = mySub
#
# macro parameter = Var
#  type = variable
#  multiselect = true
#  default = Y
#
# macro parameter = Location
#  type = location
#  location category = surface
#
# Macro GUI end

! no warnings 'redefine';

! sub mySub {
! ($variable, $plane) = @_;

# Create an expression for the area average of the variable value on the plane
  LIBRARY:
   CEL:
    EXPRESSIONS:
! my $locationName = getObjectName($plane);
     Average Value = areaAve($variable)@$locationName
    END
   END
  END

! my $average = getExprVal("Average Value");

! print "Var = $variable, Location = $locationName, Area Average = $average\n";

!}

In the macro above, the special comments between the # Macro GUI begin and # Macro GUI end lines specify:

The macro name
The subroutine to call
The input parameters and details of them, including their types and default values

Macro Area Average Macro has two input parameters:

Var - The variable to average. The default is Y
Location - A surface locator.

When this macro is loaded, the entry Area Average Macro appears in the list of available macros (under the Macro setting).

When this macro is run:

Expression Average Value is updated (created if necessary). This expression evaluates to the area average of the specified variable on the specified location.
The specified values Var and Location, and the value of Average Value, are printed to the console window (which is viewable when starting CFD-Post in stand-alone mode).

The following example macro writes text output to a file.

! open(FH,">myOut.txt");
! $val = ave("Pressure", "Point 1");
! $time = getValue( "DATA READER", "Current Timevalue");
! print FH "$time $val\n";
! close(FH);

In this example, the output filepath is specified using redirection of output from the Perl print command.

In order to better learn how to create your own macro, you can view the existing macros in <CFDPOSTROOT>/etc/*.cse and study the definitions.

13.6.4.2. Macro GUI Definition

The portion of a macro definition that falls between the # Macro GUI begin and # Macro GUI end lines contains special comments that provide basic information about the macro, including the information required to populate the graphical user interface of the Macro Calculator with the settings (input parameters) required by the macro. The following table lists the special comments that can be added to a macro:

Special Comment	Description
`# macro name = <name>`	The macro identifier to appear in the macro combo
`# macro subroutine = <subname>`	The subroutine to call. A macro must contain at least one subroutine.
`# macro report file = <filename>`	The file generated by the macro (if any). This enables the View Report button, which attempts to load the file in a text/html browser.
`# macro related files = <file1>, <file2>`	Other related files to load when loading this macro. The main use of this feature is to load subroutines from other files so that these subroutines can be used in the macro. Each specified file can contain one or more subroutines.
`# macro parameter = <name>` `#type = <type>` `#<option1> = <val>` `#<option2> = <val>` `#..`	Defines an input parameter and its properties: its name, type, and other options as described in the next table. Specify this group of comments once for each input parameter that is required by the macro. The input parameters are displayed (in the order defined) in the graphical user interface, and, upon running the macro, are passed (in the order defined) to the macro’s (main) subroutine as input arguments.

The following table provides details on the # macro parameter comment, including the options available for each parameter type:

Type	Option	Example	Notes
string	default	My String
integer	default range	10 1, 100
float	quantity type default range	0.1 [s] 0.1 [s], 0.4 [s] Time	The quantity type controls which units are allowed. A full list of quantity types can be found in `<CFDPOSTROOT>/etc/<version>/common_units.cfx`. To specify that the float is dimensionless, omit the specification of a quantity type.
triplet	default range quantity type	0.5[m], 0[m], 1[m] -1[m], 1[m] Length	The quantity type controls which units are allowed. A full list of quantity types can be found in `<CFDPOSTROOT>/etc/<version>/common_units.cfx`. To specify that the triplet is dimensionless, omit the specification of a quantity type.
location	default location type location category	Inlet Boundary surface	The location type can be any object type listed in `<CFDPOSTROOT>`/etc/CFXPostRules.ccl after an occurrence of the string "OBJECT: ", provided that the object description contains the string "Category =" followed by a list of categories that includes the word "selectable". Valid location types include (but are not limited to): boundary chart chart series domain isosurface line plane point polyline streamline turbo line turbo surface user surface volume The location category can be any category listed in `<CFDPOSTROOT>`/etc/CFXPostRules.ccl after the string "Categories =". Valid location categories include: geometry line plane point region2d selectable surface variable viewer-viewable volume You can specify a location category to allow locations of various related types. For example, the "surface" category includes any locations of type "boundary", "isosurface", or "turbo surface". The location parameter returns either the object’s CCL path or just its name. The object’s name is returned for surfaces that are read from the file, for example, boundaries or regions. For other objects, the object’s path is returned; to get the object’s name, use getObjectName(Object Path). ^[a]
list	default list	orange apple, orange, fig
variable	default	Pressure
domain	default	Stator

^[a]CFD-Post normally refers to boundaries in other objects by name, not path (for example, a contour plot on a boundary), so that the object can be re-used in other files or for file comparisons. For example, a contour in "inlet" will automatically turn into two separate objects when two files are loaded and both have "inlet".