CreateXYScalarPlot()

The CreateXYScalarPlot() function creates an X-Y plot from scalar data recorded in all tests previous to the test where the function is called. The scalar expressions, x-expression and y-expression, can include any number of scalars, arithmetic operators as well as all variables declared with a Var(), GlobalVar(), Change(), or Temp() testplan entry. These variables are made available by default and should not be placed in the list of scalars to extract.

CreateXYScalarPlot() Syntax

The CreateXYScalarPlot() function has the following syntax with the seven required arguments and one optional argument as explained in the table below. 
CreateXYScalarPlot(x-expression, y-expression, scalars to extract, curve_name, graph_name, grid_index, axis_name, OPTIONAL_PARAMETER_STRING)
Arg # Argument Name Description
1 x-expression The expression of scalars to be plotted on the x-axis
2 y-expression The expression of scalars to be plotted on the y-axis
3 scalars_to_extract A space delimited list of scalars to extract from the previous reports.
4 curve_name Name of the curve as it appears in the report.
Note: For your curve to appear in the report, you must prefix the curve name with "DVM".
5 graph_name Name of the graph for the new test report*
6 grid_index Grid on which to place the curve*
7 axis_name Axis on a particular grid*
8 OPTIONAL_PARAMETER_STRING A space-separated set of KEY=VALUE pairs that define additional parameters**

* For additional information about graph_name, grid_index, and axis_name, see Graph Address System.

** For additional information about OPTIONAL_PARAMETER_STRING, see Optional Parameters.

Important: Scalar names with spaces will produce errors when used with the CreateXYScalarPlot() function. The best solution is to create unique scalar names without spaces.

▲ back to top

Examples

Example 1

A good example of this function is to plot efficiency versus average load current. The scalar values for efficiency and average load current are automatically generated after any SIMPLIS POP simulation. This includes all Power Assist AC objectives as well as the steady-state objectives. The following example is taken from the built-in efficiency testplan.

CreateXYScalarPlot(ILOAD, Efficiency_Nom, ILOAD Efficiency_Nom, DVM Vin Nom, DVM Efficiency, A1, vert, xlabel=Load Current xunits=A ylabel=Efficiency yunits=%%% showpoints=true color=red)

This call to CreateXYScalarPlot() generates the efficiency curve for the nominal input voltage.

Note: This example uses the Alias() function to create a new scalar name for efficiency with its value measured by DVM Power Assist. This alias is necessary because the efficiency testplan has three sets of data—one for each input voltage. In this case, the x-expression and y-expression are the actual scalars.

Example 2

This example uses algebraic expressions to calculate the input-to-output voltage gain for an LLC converter. The converter is operating open-loop with the normalized switching frequency swept.

CreateXYScalarPlot(Fnormalized, 2 * N * VOUT2 / VIN2, VOUT2 VIN2, DVM SIMPLIS(Q=0.4), DVM Gain, A1, vert, showpoints=true color=red)

In this example, notice the following:

  • The y-expression 2 * N * VOUT2 / VIN2 is the mathematical expression for the gain of the converter.
  • The variable N representing the ratio of transformer turns was set with a Var() function.
  • VOUT2 and VIN2 were renamed from the DVM fixed probe using the Alias() function. Since multiple cases were simulated, the alias was required to make the scalar values for the input and output voltages unique to the test conditions.
  • The program automatically searches through the previous test reports, acquiring the scalars to extract and attempts to evaluate the x- and y- expressions for each test report.
Note: When one or more scalars are not found, the test report is skipped and the program proceeds to the next test report. A warning is reported in the command shell if all previous test reports are searched and no resulting vectors can be evaluated.

▲ back to top

Optional Parameters

The following syntax rules apply to the OPTIONAL_PARAMETER_STRING  argument:

  • The OPTIONAL_PARAMETER_STRING  value must not contain a comma.
  • The OPTIONAL_PARAMETER_STRING  is parsed on the equal sign.
  • Since the argument is parsed on the equal sign, the value itself must not contain an equal sign. For example, the following is an invalid entry: 
    ylabel=Body Diode Forward Current Temp=-40
    In this case , the program would read this incorrectly as two optional parameters:
    • ylabel=Body Diode Forward Current
    • Temp=-40

Spaces in values are allowed as long as no spaces are on either side of the equal sign. Thee three examples below illustrate this:

  • ylabel=Body Diode Forward Current: valid entry with no spaces around the equal sign
  • ylabel =Body Diode Forward Current: invalid entry with space before equal sign
  • ylabel= Body Diode Forward Current: invalid entry with space after equal sign

The following table lists the available formatting options for use in the OPTIONAL_PARAMETER_STRING argument.

Parameter Syntax Value Type Description
xgrid=positive_integer Any positive integer Specifies space between the x gridlines
ygrid=positive_integer Any positive integer Specifies space between the y gridlines
xscale=lin | log One of two options:
  • lin: plot x-axis in linear units
  • log: plot x-axis in logarithmic units
 Specifies the units for the x axis
yscale=lin | log O ne of two options:
  • lin: plot y-axis in linear units
  • log: plot y-axis in logarithmic units
 		 Specifies the units for the y axis
xlabel=string Any alphanumeric string Specifies a label for the x axis
ylabel=string Any alphanumeric string Specifies a label for the y axis

The ArbitraryBodePlot()function ignores this option if curves are placed on multiple grids.
xunits=string Any alphanumeric string Specifies the units label for the x axis
yunits=string Any alphanumeric string Specifies the units label for the y axis.

The  ArbitraryBodePlot()  function ignores this option.

xMinlimit=integer Any positive or negative integer Specifics the minimum x-axis limit
xMaxlimit=integer Any positive or negative integer Specifics the maximum x-axis limit
yMinlimit=integer Any positive or negative integer Specifics the minimum y-axis limit
yMaxlimit=integer Any positive or negative integer Specifics the maximum y-axis limit
showpoints=TRUE | FALSE TRUE or FALSE Specifies whether or not to show points on graph.
usescalars=single | multi | both
Note: This option is only recognized in version 8.00g and later.
 One of three options:
  • single: only scalar values from single step runs are used (default value)
  • multi: only scalars generated from a Multi-Step Analysis run are used
  • both: Scalars generated from single and Multi-Step Analysis runs are used for the plot.
 Determines the scalars used for the plot.
sort=xascend | yascend One of two options:
  • xascend: resulting vector is ordered with its x values in ascending order (default value)
  • yascend: resulting vector is ordered with its y values in ascending order.
 Determines the order of the data points on the resulting curve
color=color_specification One of three options to specify the color:
  • Color-name alias
  • Hexadecimal color
  • SIMETRIX sequence
 Specifies the color for the curve.

Note: See the next section for information on these three methods for specifying a color..

Specifying a Color

You have three options for specifying the color for a curve:

  • Color-name Alias
  • Hexadecimal Color
  • SIMetrix Sequence

Color-name Alias

The syntax for the color-name alias is as follows: 
color=color_name
where color_name is one of the 16 built-in color aliases as listed in the following table with the hexadecimal code.
Color Name Alias Hex Code
 
 Red #FF0000
 
 Green #008000
 
 Blue #0000FF
 
 Teal #008080
 
 Purple #800080
 
 Maroon #800000
 
 Navy #000080
 
 Black #000000
 
 Magenta #FF00FF
 
 Lime #00FF00
 
 Salmon #FA8072
 
 Medium violet red #C71585
 
 Brown #A52A2A
 
 Indigo #4B0082
 
 Medium orchid #BA55D3
 
 Blue violet #8A2BE2

Hexadecimal color

The syntax for the hexidecimal color is as follows: 
color=#rrggbb
where rr, gg, and bb are hex numbers from 00 to FF.

You can specify any color for the curve by using a hexadecimal specification.

SIMetrix Sequence

The syntax for the SIMetrix sequence method of specifying a color is as follows: 
color=SEQ:n
where n is a positive integer between 1 and 20.

SIMetrix has eight default curve colors, starting with red, green, blue, etc.

To change and extend these colors to a maximum of 20 user-defined curve colors, follow these steps:

  1. From the menu bar, select File ▶ Options ▶ Colour....
  2. Double click a curve item in the list and then select another color from the palette, and click OK.
Note: If you do not set each Curve item in the list, the sequence wraps; for example, with the default curve colors, SEQ:9 yields the same curve color as SEQ:1.

▲ back to top

Using CreateXYScalarPlot() in a Script

The CreateXYScalarPlot() function is also available as a SIMetrix script function and can be called from a PostProcess or FinalProcess script. Calling this function from a script is useful when you need to generate a large number of curves and/or if the length of the arguments makes the testplan difficult to read or edit.

The syntax for the function in a script is as follows: 
SimplisDVMAdvancedUtilMeasurementCreateXYScalarPlot(array, log_file)
Argument Description
array A string array that contains the normal arguments to the CreateXYScalarPlot() function
log_file The DVM log file that is an argument passed into the post and final process scripts

The efficiency example (Example 1 above) could be generated in a post-process script with the statement below.

Note: The array argument is bounded by open and close brackets [ ], and the string elements in the array are each enclosed in single quotes. 
Let return = SimplisDVMAdvancedUtilMeasurementCreateXYScalarPlot([ 'ILOAD', 'Efficiency_Nom', 'ILOAD Efficiency_Nom', 'DVM Vin Nom', 
+             'DVM Efficiency', 'A1', 'vert','xlabel=Load Current xunits=A ylabel=Efficiency yunits=%%% showpoints=true color=red' ], log_file)
  • The return value from this function is a real value with 0 indicating success and 1 indicating an error.
  • Error messages are displayed in the command shell for each function call.
  • CreateXYScalarPlot() is a post-process function only; that is, it does not need to set .PRINT or .KEEP statements prior to running the simulation. Therefore, this function behaves identically if called from a fina-lprocess script or from a testplan.
  • Multiple CreateXYScalarPlot() functions can be called and some may fail without causing DVM execution to stop. For example, the final test in the built-in efficiency testplan creates three efficiency curves for the three input voltages. If only one set of input voltage tests is selected, two of the CreateXYScalarPlot() functions will fail. DVM, however, will continue to execute even though those functions failed.

▲ back to top

What Can Go Wrong?

Small syntax errors and order of operation issues will cause this function to fail and not produce the expected results. A few common errors include:

  • The scalars produced in any DVM test do NOT exist when this function is called in the same test. This "order of operations" issue means that you must call this function from a separate, following NoSimulation test after all scalar values are created. This is true no matter how the scalars are created during the test.
  • The curve name to create as supplied in the 4th argument must start with the three characters "DVM" for the graph image to be created and displayed in the test report. The actual curve will be created without the special three character sequence, but the PNG formatted image used in the report will not be created, and you will not be able to promote the graph to the overview report using PromoteGraph().