Postprocessing_Whitepaper

V1.0, 03/2013 FSR 1

Customized Post Processing Using the Result Template Concept

1) Introduction

Arguably, the point of any simulation is the result. However, the number of possible results types an engineer might be looking for is endless. It is therefore common for commercial tools, such as CST STUDIO SUITE®, to calculate the most commonly used results, from which more specialized results can be derived. For example, typical results from a transient EM-simulation are: Port signals, S-Parameters, E- and H-fields (near field), or the VSWR. Typical examples for more specialized results derived from these results are: Field values along a line, far field values for various frequencies, SAR calculations, or a complex superposition of port excitations. To obtain these more complex results, the user could export the basic results from CST and re-import them into MATLAB, Octave, Mathematica, or a similar software package and carry out further calculations there. However, CST STUDIO SUITE® offers the option to do this directly in CST as well. This eliminates the need to export/import data and the issues caused by different data formats. Advanced post processing within CST is possible using VBA (Visual Basic for Applications), a simple yet powerful scripting engine. The user may either create his own post processing module from scratch or make use of the more than 200 predefined result templates and macros. The second approach replaces the tedious programming task by simply filling out a user dialog, according to the desired results. The main difference between macros and result templates is when and how they are evaluated. Macros are typically only evaluated once: Either before a solver run to create structure (so-called structure macros) or after a solver run or parameter sweep to perform a specific action (so-called control macros). Result templates are typically set up once and then evaluated automatically after every solver run. The corresponding template results will be stored in a result table, together with the values of all parameters used in the simulation. This way, template results from multiple solver runs (e.g., after a parameter sweep) can be accessed and compared easily. This document focuses on the result templates, not the macros. Results from one template can even be used as input for another, which makes the result template concept even more versatile. Template results may also be used directly to define a goal function for the CST optimizer. The template based post processing is available in CST MICROWAVE STUDIO®, CST EM STUDIO®, CST PARTICLE STUDIO®, CST MPHYSICS STUDIO®, CST CABLE STUDIO®, and CST DESIGN STUDIO™. The basics will be explained within the CST MICROWAVE STUDIO® environment. CST DESIGN STUDIO™ offers some additional features, which will be explained in a separate section at the end.

V1.0, 03/2013 FSR 2

2) How to Set Up and Run a Template

The template based post processing may be reached by clicking on the corresponding icon in the ribbon, or by using the pre-defined keyboard shortcut “Shift-P”:

A new dialog window will come up, listing all presently defined templates (none in this example):

Figure 2: The template overview window

Figure 1: Access to the template based post processing from the main ribbon in CST MWS

V1.0, 03/2013 FSR 3

To add a template to the list, click on the first drop-down list and select a template group:

Figure 3: Templates are grouped according to topics. This figure shows the template groups available within CST MWS.

Available groups in CST DS or other CST STUDIO SUITE components will vary.

After selecting a template group, use the second drop-down list to select a template from within the group. Some simple templates do not require any settings and will simply be added to the list. Most of the templates will bring up a user dialog so that the user can adjust the template settings as necessary. After the template has been set up, it will appear in the list. The user may then highlight it and use the “Evaluate” button to execute the template. The “Evaluate All” button will execute all templates in the list sequentially, equivalent to the automatic template evaluation after a solver run. The user may also delete, duplicate, or move templates up or down in the list, using the corresponding buttons at the bottom. Because the templates are evaluated sequentially, care needs to be taken when moving templates up or down in the list, as this has the potential to break the sequence. The next screenshot shows an example where 3 templates have been defined:

Figure 4: An exemplary list of templates.

The four columns contain the result name, result type, template name, and result value, respectively. The template name in the third column is the name selected in the second drop-down box described before, it is not unique. The result name in the first column contains a unique name that specifies the result further. It can be used by other templates to refer back to a specific template. A typical combination of result name and template name would be “S2,1” and “S-Parameter (complex)”. A unique result name will be generated automatically, but the user may also change this name in the first column afterwards.

V1.0, 03/2013 FSR 4

The result type in the second column consists of up to three elements:

1) “M”: If present, this element indicates that a template will create multiple

results. For example, the template result “All S-Parameters” in the

example above will store all possible combinations of “Sn,m” for a given

model.

2) 0D/1D: This element will always be present and indicates whether the

result is a simple number (0D) or a set of x and y data pairs (1D). (Note: y

may be complex-valued, see below.)

3) “C”: If present, this element indicates that the result is complex valued.

Going back to the example shown in figure 4, we can identify two templates that will return a single, real-valued number (“0D”) and one template that will return multiple, complex-valued x-y curves (“M1DC”). After evaluation, all result values will be available in the “Tables” folder within the navigation tree. For templates of result type “0D”, the result value will also be shown in the fourth column of the template list, see figure 4.

V1.0, 03/2013 FSR 5

3) List of Commonly Used Templates The following section introduces some often-used templates and shows setups for typical post processing needs. 2D/3D Field Results->Evaluate Field in Arbitrary Coordinates

Figure 5: This example shows how to integrate the normal component of the electric field over a spherical surface with

radius R=3.

V1.0, 03/2013 FSR 6

Farfield and Antenna Properties -> Farfield Result

Figure 6: This example shows how to obtain the maximum directivity from a farfield monitor. Please note that the

screenshot shows the “Advanced” mode. The basic mode allows loading of often-used setups much faster.

General 1D -> Mix Template Results

Figure 7: This example shows how to normalize the output spectrum of a simulation to the corresponding input

spectrum. The two complex-valued inputs (Input Signal_FT and Output Signal_FT) are result templates themselves, generated by the ‘Fourier Transform’ result template.

V1.0, 03/2013 FSR 7

General 1D -> 0D/1D Value from 1D Result

Figure 8: This example shows how to integrate the output signal at port 1 over the time interval from [0.2 … 0.4].

V1.0, 03/2013 FSR 8

4) Result Table Handling As mentioned above, the list of defined result templates will be evaluated automatically after each solver run. Accordingly, a large number of results will typically be available after a parameter sweep or optimization run:

Figure 9: A large number of result curves, created by a parameter sweep over multiple parameters.

There are different ways to look at certain subsets only:

1) Right-click on the plot and go to “Select Curves”. The user may then select

and de-select the desired curves, according to the curve names.

2) Right-click on the plot and go to “Table Properties”. This option does not

allow to select or to de-select on a curve-by-curve basis, but rather on base

of parameter values. Different plot modes are available:

a. ‘All’ or ‘Run ID’: Plots all curves. If more than one parameter was

varied, these two options are the same and all curves will be labeled

according to the Run ID. (Every solver run is assigned a unique Run

ID.) If only one parameter was varied, ‘All’ will label the curves

according to the varied parameter.

b. ‘Parametric’: Shows all curves that match the selected parameter

values, varying only one parameter as defined by “Curve set

parameter”:

V1.0, 03/2013 FSR 9

Figure 10: The 'Parametric' plot mode under 'Table Properties' allows the user to vary one parameter only, while keeping all other parameters constant.

c. ‘Tune’: This option displays a slider for each parameter that was

varied during a parameter sweep. The user may “tune in” to exactly

one parameter combination and the single curve corresponding to

this combination is displayed.

Figure 11: The 'Tune' plot mode allows the user to easily display the curve for a certain parameter combination by using sliders to change parameter values.

3) The parameter view: Clicking on “Tables” in the Navigation Tree will bring

up an Excel-like table that enables the user to very easily put together

customized data plots. Simply select the desired columns and/or single cells

(multi-selections are possible) and click on “Plot Selected” to generate the

plot. Various filter options are also available.

V1.0, 03/2013 FSR 10

Figure 12: The parameter view allows easy selection of multiple results from all available results and combine them in a single plot.

Figure 13: Available filter options and their location in the main ribbon.

Sidenote: A similar tool is available for parametric primary plots under ‘1D Results’. To access it, use the little arrow in the ‘Parametric Plot’ icon:

Figure 14: The 'Parametric Plot' option for primary 1D results is very similar to the Parameter View.

V1.0, 03/2013 FSR 11

5) Templates in Design Studio The template based post processing is similar in CST DESIGN STUDIO. Additionally to the features shown so far, it is possible to have multiple sets of post processing templates. Each set is defined as a separate task that can be embedded in a more complex task structure:

Figure 15: A design studio task list containing several post processing tasks, some nested within other tasks.

Each post processing task shares all other advantages of the other CST DESIGN STUDIO tasks: It can be moved, deleted, run in sequence with other tasks or run independently, temporarily disabled or renamed.

V1.0, 03/2013 FSR 12

6) Advanced: Write your own template It was mentioned in the beginning that, if necessary, users may modify the existing templates or even write their own template from scratch. The source code for all existing templates can be found in the “Library\Result Templates” subfolder of the CST installation folder. Please note that modifying any of the files in this folder will directly affect the CST installation. It is strongly recommended not to edit the files themselves but to create copies first. These copies will show up as new template options in the dialog. The subfolder structure in the “Library\Result Templates” folder is equivalent to the group structure in the template dialog. The user may create a new group by simply creating a new subfolder. (The 0D and 1D folders and all files therein are present only for legacy reasons and should be considered obsolete.)

Figure 16: Overview of the result template subfolder. It contains the source code for all result templates.

The basic requirements for a result template are rather simple:

- The template must not have a Sub Main()

- The template needs to contain a

Function Define(String, Boolean, Boolean) As Boolean

V1.0, 03/2013 FSR 13

- The ‘Define’ function needs to specify the template type. For example, a

0D template would have to include a call

StoreTemplateSetting(“TemplateType”, “0D”)

- The template needs to contain an ‘Evaluate’ function according to the

selected template typ, for example:

Function Evaluate0D() As Double

The source code below demonstrates these requirements:

' Begin Template

Function Define(sName As String, _

bCreate As Boolean, _

bNameChanged As Boolean) As Boolean

sName = "My First Template"

StoreTemplateSetting("TemplateType","0D")

Define = True

End Function

' ---------------------------------------------------

Function Evaluate0D() As Double

ReportInformationToWindow("Hello World!")

Evaluate0D = 1.6180339887

End Function

' End Template

More information can be found in the “Post Processing Template Layout” section of the online help. Please note than CST can only provide very limited support for customer-written source code.