.GRAPH

In this topic:

Parameters

.GRAPH signal_name|"expression"
+ [ persistence = persistence ]
+ [ axisname = axisname ]
+ [ gridname = gridname ]
+ [ graphname = graphname ]
+ [ axistype = digital|grid|gridauto|axis|auto ]
+ [ curvelabel = curvelabel ]
+ [ xlabel = xlabel ]
+ [ ylabel = ylabel ]
+ [ xunit = xunit ]
+ [ yunit = yunit ]
+ [ xmin = xmin ]
+ [ ymin = ymin ]
+ [ xmax = xmax ]
+ [ ymax = ymax ]
+ [ analysis = analyses_list ]
+ [ ylog = lin|log|auto ]
+ [ xlog = lin|log|auto ]
+ [ nowarn = true|false ]
+ [ initXLims = true|false]
+ [ bus = bustype ]
+ [ complete = true|false ]
+ [ order = order ]
+ [ colour | color = colour ]
+ [ colourname | colorname = colourname ]
+ [ disabled = true|false]
+ [ xdelta = xdelta ]
+ [ ydelta = ydelta ]
+ [ proberef = proberef ]
+ [ measure[index] = measure_expression]
+ [ measureLabel[index] = measure_label]
+ [ useNameAsTitle = true|false ]
+ [ separateCurves = true|false ]
+ [ guid = guid ]
+ [ ownXAxis = true|false ]
.GRAPH instructs SIMetrix to plot a graph of the specified signal or expression. The graph can be plotted incrementally as the simulation proceeds or may be delayed until the run is complete.

Note that although .GRAPH is a simulator statement, it is implemented in the front end and will only function in full GUI mode. Batch mode simulation does not support .GRAPH.

Parameter name Type Description
signal_name | expression string Specifies item to be plotted. If this is an expression, then it must be enclosed in double quotation marks.
persistence integer Number of curves to be displayed at once. On repeated runs, any curves from earlier runs remain until the number of curves exceeds this value at which point the oldest is deleted automatically. If this parameter is absent or zero, the curves are never deleted.
graphname string If specified, the curves will be directed to their own graph sheet within the current window. The value of graphname is arbitrary and is used to identify the graph so that multiple .graph statements can specify the same one. It works in a similar way to axisname an example of which is given below. This name is not used as a label for display purposes but simply as a means of identification.
axistype string Can be one of four values to specify type of y-axis:
  • DIGITAL. Use a digital axis. This is a small axis that carries only one curve. It is intended for digital signals but may also carry analog curves.
  • GRID. Use a separate grid stacked on top of the main one. The AXISNAME parameter may be used to identify a particular grid used by another .GRAPH statement.
  • GRIDAUTO. As GRID but separate y-axes will be used for curves representing distinct physical quantities (e.g. voltage, current, power etc)
  • AXIS. Use a separate y-axis alongside the main one. The AXISNAME parameter may be used to identify a particular axis used by another .GRAPH statement.
  • AUTO. This is the default value. A suitable axis is chosen automatically.
axisname string This is only used if AXISTYPE is specified. The value of AXISNAME is arbitrary and is used to identify the axis so that multiple .GRAPH statements can specify the same one. An example of this is given below. This name is not used as a label for display purposes but simply as a means of identification. Axes can be labelled using ylabel and xlabel.
gridname string This is used when AXISTYPE is set to GRID or GRIDAUTO. The value of GRIDNAME is arbitrary and is used to identify the grid so that multiple .GRAPH statements can specify the same one. For compatibility with earlier versions, if GRIDNAME is not specified, the value given to AXISNAME will be used instead.
curvelabel string Label for curve displayed in graph legend. If omitted, the label will be the signal name or expression.
xlabel string Label for x-axis. Default is reference of curve being plotted (E.g. time, frequency etc.)
ylabel string Label for y-axis. If there is only a single curve, this will default to the label for the curve otherwise the default is blank.
xunit string Units for x-axis. Default is units of reference.
yunit string Units for y-axis. Default is units of curves plotted provided they are all the same. If any conflict, the default will be blank
xmin real Minimum limit for x-axis. Must be used with xmax.
xmax real Maximum limit for x-axis. Must be used with xmin.
ymin real Minimum limit for y-axis. Must be used with ymax.
ymax real Maximum limit for y-axis. Must be used with ymin.
analysis string Specifies for what analysis modes the plot should be enabled. By default it will be enabled for all analysis modes. Any combination of the following strings, separated by a pipe ('|') symbol.
  • TRAN. Transient analysis
  • AC. AC analysis
  • DC. DC sweep analysis
  • NOISE. Noise analysis
  • POP. POP analysis - SIMPLIS only
Other analysis modes do not produce results that can be probed
ylog string One of three values
LIN Use linear axis
LOG Use log axis
AUTO Axis will be log if x values are log spaced. (E.g for decade AC sweep) and all values are positive

Default if omitted: LIN
xlog string One of three values
LIN Use linear axis
LOG Use log axis
AUTO Axis will be log if x values are log spaced. (E.g for decade AC sweep) and all values are positive.

Default if omitted: AUTO
nowarn Boolean If true, no warnings are given if an attempt is made to plot a non-existent signal. Default: false.
initXLims Boolean When this is TRUE, the x-axis limits are initialised according to the analysis. E.g. if the analysis is transient and runs from 0 to 1mS, the x-axis will start with these limits. If set to FALSE, the x-axis limits are calculated to fit the curve and updated incrementally. You should set this to FALSE if you are plotting an expression whose x values are not the same as the x values for the analysis e.g. using the XY() function for an X-Y plot

The default value of this option is usually true but can be changed using the option NoInitXAxisLimits . Type at the command line:

"Set NoInitXAxisLimits" to change default to false.
complete Boolean If true, the plot is not produced until the analysis is completed. Otherwise the plot is updated at a rate determined by the global option ProbeUpdatePeriod. This is forced for some types of plot as certain expressions cannot be plotted incrementally

This can be set using the options dialog box (File > Options > General... ). Default: false.
order string Arbitrary string used to control the display order of digital traces. Digital traces are displayed in an order that is determined by the alphanumeric sort order of the order value. If omitted, the curvelabel value is used instead
colour string Number representing an RGB value of the colour of the final trace. The number, when converted to hexadecimal, is in the form:

bbggrr

where bb is the blue value, gg is the green value and rr is the red value. So, 16711680 - FF0000 in hexadecimal is deep blue.
color string alias to colour

colourname
string arbitrary name used to match colours between multiple .GRAPH statements. The first .GRAPH statement encountered that specifies a colourName parameter will set the colour for all other .GRAPH atatements that specify the same colourName parameter

disabled
Boolean If set to TRUE, the statement is disabled and no curve will be generated.
xdelta real specifies the spacing between major grid lines on the x-axis

ydelta
real specifies the spacing between major grid lines on the y-axis

proberef
string Identifies a fixed probe schematic symbol that generated the .GRAPH statement and is used to create history data

measure[index]
string Defines an expression that will create a measurement object attached to the curve. Multiple measure parameters may be defined but each must specify a distinct index value. Index values used for multiple measure parameters should be contiguous starting at zero. The expression should return a scalar value. It may access the curve's data using the sub-expression cv(%curve%). For example Mean1(cv(%curve%)) will create a measurement object that will display the mean of the curve created

measureLabel

[index]
string Defines the label for the corresponding measure definition

useNameAsTitle
Boolean If set, the name provided in the graphname parameter will also be used to label the caption and tab of the graph window

separateCurves
Boolean If true, new curves will be created for each new run. Otherwise a single curve will be updated. When a single curve is updated, the data for earlier runs is stored and may be displayed subject to the setting of the Persistence property of the curve

guid
string If set, the value given will set the curve property ProbeGUID. This is expected to be a conventional 128 bit globally unique identifier. This should not be enclosed with curly braces as the simulator will then interpret the value as an expression. The value passed to the curve will automatically have the curly braces added. Probe GUIDs are used to map probes with the curves they generate. Typically the GUID sent will be the instance GUID of the schematic probe. This is used by the auto probe colouring scheme.

ownXAxis
Boolean If set to TRUE, any grid created to display the probed result will have an independent x-axis allowing individual x-axis zoom.

The .GRAPH statement is the underlying simulator mechanism used by the schematic's fixed probes. See User's Manual/Graphs, Probes and Data Analysis/Fixed Probes for details.

.GRAPH supersedes the older and less flexible .TRACE. The latter is, however, still supported and may sometimes be convenient for specifying multiple signals on one line.

Using Multiple .GRAPH Statements

If specifying several .GRAPH statements to plot a number of curves on the same graph, you should make sure that the various parameters are consistent. If for example, a conflict arises if you specify xmin and xmax for two .GRAPHs that plot curves in the same graph sheet, and the values for xmin and xmax are different for each. You can specify xmin and ymin for just one of the .GRAPH statements or you can specify for all and make sure they are all the same. The same applies to other non-Boolean parameters i.e. ymin, ymax, xlabel, ylabel, xunits and yunits. The parameter initXLims, however must be specified with the same value for all .GRAPH statements specifying the same graph sheet.

Conflicting values of ylog and xlog are resolved by plotting the curves on separate axes or graph sheets respectively.

Creating X-Y Plots

To create an X-Y plot, use the XY() function (Script Reference Manual/Function Reference/XY for full details of available functions). You should also specify "initXLims=false". E.g.
.GRAPH "XY( imag(vout), real(vout) )" initXLims=false
+ xlog=LIN complete=true

The above will create a Nyquist plot of the vector VOUT.

Using .GRAPH in Subcircuits

Using Expressions with .GRAPH

You can enter an expression as well as single vectors to be plotted. A problem arises when plotting expressions incrementally that are regularly updated while the simulation is running. SIMetrix versions prior to v5 could not incrementally evaluate expressions, so each time the plot of an expression was updated, the expression had to be recalculated from the beginning. This was inefficient and it has always been recommended that the complete=true flag was added in these circumstance to inhibit incremental plotting.

SIMetrix - from version 5 - now has the ability to incrementally evaluate some expressions and there is no longer a recommendation to set complete=true. However, certain expression cannot be incrementally evaluated and when such expressions are entered, incremental plotting will automatically be disabled and the plot won't appear until the run is complete.

A notable example of expressions that cannot be incrementally evaluated is anything containing the phase() function. This is because the phase() function uses a state machine to determine when the phase wraps from -180 to 180 and back. An offset is then applied to make the phase plot continuous. Because of the state machine, it is always necessary to evaluate this function from start to finish which makes incremental evaluation difficult. An alternative is to use instead the arg() function. This is the same as phase, but does not have the state machine and always gives an output that lies between +/- 180 degrees.

Plotting Spectra with .GRAPH

You can use .GRAPH to create spectrum plots using FFTs or Fourier. However, FFT is quite difficult to use on its own as it needs interpolated data. So, a new user defined function called Spectrum() has been developed that is especially designed for use with .GRAPH. Usage is:

Spectrum(vector, numPoints [, start [, stop]])
Where:
vector Vector or expression
numPoints FFT size - must be a binary power of 2
start Start time - default = 0
stop Stop time - default = end of data
Spectrum() cannot be incrementally evaluated and so incremental plotting will automatically be disabled for any .GRAPH statement that uses it. See Using Expressions with .GRAPH.

Examples

.GRAPH C2_P curveLabel="Amplifier output" nowarn=true

Plots the vector C2_P and gives it the label 'Amplifier output'. As NOWARN is TRUE, no warning will be given if C2_P does not exist.

.GRAPH vout_quad
+ axisType="grid"
+ axisName="grid1"
+ persistence=2
+ curveLabel="Quadrature"
+ nowarn=true
+ analysis = TRAN|DC

.GRAPH vout
+ axisType="grid"
+ axisName="grid1"
+ persistence=2
+ curveLabel="In Phase"
+ yLabel="Filter Outputs"
+ nowarn=true
+ analysis = TRAN|DC

The above illustrates the use of the parameters AXISTYPE and AXISNAME. Both the vectors specified by the above .GRAPH statements will be plotted on the same but separate grid. Because both grids have been given the AXISNAME grid1, each curve will be plotted on the same one. If the values of axisname for the above were different, each curve would be plotted on a separate grid. The ANALYSIS parameter has been specified in both cases, so plots will only be created for transient and dc sweep analyses.