ArbitraryCurve()

The ArbitraryCurve() function allows you to generate a curve from an arbitrary mathematical expression of node-voltage and branch-current waveforms. Additionally, the arbitrary mathematical expression can include built-in vector functions, which are all described in Function Reference.

ArbitraryCurve() Syntax

The syntax of the ArbitraryCurve() function has the following syntax with the arguments explained in the table below:

ArbitraryCurve(vector_expression, vectors_to_keep, curve_name, graph_name, grid_index, axis_name, OPTIONAL_PARAMETER_STRING)
Argument Description
vector_expression A mathematical expression of node-voltage and branch-current waveforms. This expression can include built-in vector functions.
vectors_to_keep A space-delimited list of vectors from the vector expression that the program produces in the .PRINT statements for each vector during SIMPLIS simulations and in the .KEEP statements during SIMetrix simulations. This ensures that the vectors supplied in vector expressions are available for plotting after the simulation is complete.
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".
graph_name Name of the graph for the new test report*
grid_index Grid on which to place the curve*
axis_name Axis on a particular grid*
OPTIONAL_PARAMETER_STRING A space-separated set of KEY=VALUE pairs that defines additional formatting 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.

▲ back to top

Examples

Example 1

Suppose a node out is the output of an op-amp and its voltage is plotted with a fixed probe on a graph named DVM Output.

The following call to the ArbitraryCurve() function will plot the slew rate of the op-amp output on a new grid above the default grid.

ArbitraryCurve(1u*diff(out), out, DVM Slew Rate, DVM Output, A2, slew rate, yUnits=V/us)
  • The vector expression, 1u*diff(out), contains engineering notation as well as the vector function diff().
  • The diff() function calculates the first derivative with respect to the reference vector of the supplied argument, namely out.
  • With the scaling factor 1u, the graph output is in the units of V/us and the supplied optional parameter labels the vertical axis with V/us.
  • For additional information about general options that can be set with the optional parameter string, see Optional Parameters.

Example 2

Suppose that, after a simulation run, you want to plot two vectors against each other in an X-Y plot. A simple example plots the forward current against the forward voltage of a MOSFET body diode.

The following call to the ArbitraryCurve() function will generate the XY plot on a new graph sheet named Forward Biased.

ArbitraryCurve(XY(-QDUT#D, #S - #D), QDUT#D #D #S, DVM SIMPLIS, Forward Biased, A1, vertical, xlabel=Body Diode Forward Voltage ylabel=Body Diode Forward Current)
  • The vector_expression argument in this example is fairly complex, using the built-in SIMetrix vector function XY() to plot the two arguments (Y, X) against each other.
  • The vectors_to_keep list contains the MOSFET drain current, as well as the drain and source voltage.
  • The net names are fixed on the schematic by adding terminals with names S and D, and the resulting vectors from a SIMPLIS simulation are prefixed with a #.
  • Finally, using the optional parameter string, the graph axes are given labels appropriate to the graph.

▲ 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.
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 ArbitraryCurve() in a Script

The ArbitraryCurve() function is also available as a SIMetrix script function and can be called from a post-process or final-process 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:  
SimplisDVMAdvancedUtilMeasurementArbitraryCurve(array, log_file)
Argument Description
array A string array that contains the normal arguments to the CreateArbitraryCurve() function
log_file The DVM log file that is an argument passed into the post and final process scripts

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 = SimplisDVMAdvancedUtilMeasurementArbitraryCurve([ '1u*diff(out)', 'out', 'DVM Slew Rate', 'DVM Output', 'A2', 'slew rate', 'yUnits=V/us' ], 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.
Note: Using the script function in a post or final process script produces slightly different results than calling this function from a testplan. The post-process script does not set the vectors_to_keep argument because this would need to be performed before the simulation run executes. The simplest way to keep the necessary vectors during a simulation run is to place a voltage probe on the required schematic node and uncheck each Analysis checkbox in the edit dialog. This probe would then keep the voltage or current to which it is attached but would not create a curve.

▲ back to top