ArbitraryBodePlot()

The ArbitraryBodePlot() function allows you to create a Bode plot with gain and/or phase curves from reference designators or from a pair of net names on a specified graph address.

The ArbitraryBodePlot() function can create  the following types of curves:

  • The ratio of two complex voltages
  • The gain and phase curves of the complete feedback loop
  • The gain and phase of various portions of the loop, such as the error amplifier.

Although the Bode Plot Probe - w/ Measurements schematic symbol has similar functionality, the ArbitraryBodePlot() testplan function includes formatting options that increase the flexibility of this function. One such option makes it possible to probe between schematic hierarchical levels.

For example, plotting the gain and phase of the compensation error amplifier in the LTC3406B circuit is difficult with the schematic-based probe because the output of the error amplifier is not at the top level of the hierarchy. Bringing the output of that error amplifier to the top level would require a modification to the LTC3406B symbol. Using the ArbitraryBodePlot() function, however, solves this problem because with this function, you can directly probe the nets in the schematic hierarchy and generate the curves without making any changes to the schematic.

ArbitraryBodePlot() Syntax

The ArbitraryBodePlot() function has four forms as listed below.

  • ArbitraryBodePlot(REFIN, REFOUT, curve_name, graph_name, grid_index, axis_name, OPTIONAL_PARAMETER_STRING)
  • ArbitraryBodePlot(netIN+, netIN-, REFOUT, curve_name, graph_name, grid_index, axis_name, OPTIONAL_PARAMETER_STRING)
  • ArbitraryBodePlot(REFIN, netOUT+, netOUT-, curve_name, graph_name, grid_index, axis_name, OPTIONAL_PARAMETER_STRING)
  • ArbitraryBodePlot(netIN+, netIN-, netOUT+, netOUT-, curve_name, graph_name, grid_index, axis_name, OPTIONAL_PARAMETER_STRING)
    Argument Name Description
    REF IN Reference designator for positive and negative input net (See note at bottom of table.)
    REFOUT Reference designator for positive and negative output net (See note at bottom of table.)
    netIN+ Positive input net name
    netIN- Negative input net name
    netOUT+ Positive output net name
    netOUT- Negative output node
    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 for the graph as seen on test report*
    grid_index Grid on which to place the curve*
    axis_name Name for the axis on a particular grid*
    OPTIONAL_PARAMETER_STRING Optional curve formatting parameters**
    Note: If you use reference designators as the arguments to this function, the symbol must have two terminals or be a DVM load symbol. The program resolves the net names from the symbol and then plots the differential voltage across  the power pins on the symbol.

    * 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

Example

This example generates a closed loop gain of an op-amp using the last function form listed above.

ArbitraryBodePlot(netIN+, netIN-, netOUT+, netOUT-, curve_name, graph_name, grid_index, axis_name, OPTIONAL_PARAMETER_STRING)
The specific function call is as follows: 
ArbitraryBodePlot(input, 0, out, 0, DVM Closed Loop, Closed Loop, A1, ignoreme, curve=splitphase color=Medium violet red)
  • This example plots the gain, db(out/input), and the phase, ph(out/input), on two grids with the phase on the upper grid.
  • Both the gain and phase curves are set to the same color based on the value of color in the optional parameter string.
  • Because the optional parameter string contains the curve=splitphase option, the grid_index and axis_name arguments are ignored.
  • The phase curve is placed on upper grid which is grid_index=A2 and the gain curve on the lower which is grid_index=A1.
  • The default names of the two axes are bodephase and bodemag, and the fixed Bode plot probe uses these axis names, allowing the ArbitraryBodePlot() curves to be placed on the same axis as the fixed probe.
  • The y-axis labels are also renamed Phase and Gain, since the default label is the same as curve_name.
  • Since on a split grid, the curve names are almost always too long to fit, the curve names are concatenated from the curve_name argument with the following logic:
    • If the curve_name argument contains the substirng Gain or gain, the program assumes that is the gain curve name and then replaces Gain with Phase to generate the phase curve name.
    • If the curve name argument contains the substring Phase or phase, the program assumes that is the phase curve name and then replaces Phase with Gain to generate the gain curve name.
    • Finally, if the specified curve name contains neither gain or phase, the program adds "Gain" and " Phase" with the leading space to the end of the specified name.
    • As a result, all of the following specified curve names produce the same names for the gain and phase curves.
      Specified Curve Name Resulting Gain Curve Name Resulting Phase Curve Name
      DVM Loop Gain DVM Loop Gain (as specified) DVM Loop Phase (replaces Gain with Phase)
      DVM Loop Phase DVM Loop Gain (replaces Phase with Gain) DVM Loop Phase (as specified)
      DVM Loop DVM Loop Gain (adds Gain to specified name) DVM Loop Phase (adds Phase to specified name)
    • Explicit curve names can be assigned by making two calls to the ArbitraryBodePlot() function - one with curve=gain and another with curve=phase. When a single curve is generated by the ArbitraryBodePlot() function, all arguments to the ArbitraryBodePlot() curve function are taken literally, with no substitutions.

▲ 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.
curve=gain | phase One of following options:
  • gain: generates a gain curve.
  • phase:generates a phase curve.
 Generates a curve based on the graph address parameters: graph_name, grid_index, and axis_name.
curve=splitphase | splitgain One of the following options:
  • splitphase: generate gain and phase curves with the phase curve on the upper grid and gain on the lower.
  • splitgain: generates a gain and phase curves with  the gain curve on the upper grid and phase on the lower.
 Generates both a gain curve and a phase curve based on the graph_name parameter only. Both grid_index and axis_name are ignored since the parameter itself determines the grid that is used.
format=center String value: center Centers both the gain 0-dB and 0-degree grid lines on the gain and phase grids so that they are aligned. The maximum or minimum y axis values are not scaled, and the grid spacing is automatically selected by SIMetrix.
format=center_m_n Alphanumberic string that starts with center Centers the grid lines as with format=center, but also sets the gain grid to m dB and the phase grid to n degrees. For example, format=center_20_45 sets the gain axis major grid to 20dB and the phase axis major grid to 45 degrees.
format=alignzero String value: alignzero Aligns the gain 0-dB grid line with the phase 0-degree grid line and changes the gain grid to 20dB/division and the phase axis grid to 45 degrees.
format=alignzero_m_n Alphanumberic string that starts with alignzero Aligns the grid lines as with format=alignzero, but also sets the gain grid to m dB and phase grid to n degrees. For example, format=alignzero_40_90 sets the gain axis major grid to 40dB and the phase axis major grid to 90 degrees.
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 ArbitraryBodePlot() in a Script

The ArbitraryBodePlot() 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: 

SimplisDVMAdvancedUtilMeasurementArbitraryBodePlot(array, log_file)
Argument Description
array A string array that contains the normal arguments to the CreateArbitraryBodePlot() function
log_file The DVM log file that is an argument passed into the post and final process scripts

The Example 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 = SimplisDVMAdvancedUtilMeasurementArbitraryBodePlot([ 'input', '0', 'out', '0', 'DVM Closed Loop', 'Closed Loop', 'A1', 'ignoreme', 'curve=splitphase color=Medium violet 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.
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

Collected links
Example