UP

VIEWING SIMULATION DATA WITH XSCHEM


Usually when a spice simulation is done you want to see the results, this is usually accomplished with a waveform viewer. There are few open source viewers, like GAW...

...Or ngspice internal plotting facilities:

There is also an interesting commercial product from Analog Flavor, called BeSpice (bspwave) that offers a free of charge one year evaluation license for non commercial use:

All these waveform viewers are supported by xschem and more can be added, just by giving the command line to start the viewer to xschem in the Simulation-> Configure simulators and tools dialog:

For gaw and bespice xschem can automatically send nets to the viewer by clicking a net on the schematic and pressing the Alt-G key bind or by menu Hilight->Send selected nets/pins to Viewer

Using XSCHEM's internal graph functions

Xschem can now display waveforms by itself in the drawing area. in the Simulation menu there is an entry to add a graph: Graph -> Add waveform graph. When this menu is pressed a box can be placed in the schematic:

Xschem graphs are embedded into a rectangle object. Resizing graphs is done in the same way as resizing a rectangle object. See the related page. To select a graph (to delete it or move it to a different position) click the left mouse button while in the area shown in this picture:

The next step is loading the simulation data, This is done by menu Waves->Op | Ac | Dc | Tran | Tran | Noise | Sp . This command loads the user selected .raw file produced by a ngspice/Xyce simulation.

The raw file is usually located in the simulation/netlisting directory Simulation ->set netlist dir.
After placing a graph box and loading simulation data a wave can be added. If you place the mouse on the inside of the box, close to the bottom/left/right edges and click the graph will be selected. You can also select a graph by dragging a selection rectangle all around it. This tells xschem where new nodes to be plotted will go, in case you have multiple graphs. Then, select a node or a net label, press 'Alt-G', the net will be added to the graph. Here after a list of commands you can perform in a graph to modify the viewport. These commands are active when the mouse is Inside the graph (you will notice the mouse pointer changing from an arrow to a +).

if set graph_use_ctrl_key 1 is set in the xschemrc file all bind keys shown below will need the Control key pressed to operate on the graphs. This setting can be used to make it more explicit when the user wants to operate on graphs. Without the Control key pressed the usual functions on schematic are performed instead of graph functions.
Example: the key a will create a symbol if used in a schematic while it shows a cursor if done when the mouse pointer is inside a graph. With the set graph_use_ctrl_key 1 option you will need to press Control-a with the mouse pointer inside a graph to show a cursor.

if the mouse is outside the graph the usual Xschem functions will be available to operate on schematics:


The graph configuration dialog box which is shown by left button double clicking inside the graph, allows to change many graph attributes, like number of X/Y labels, minor ticks, wave colors, add waves from the list of waves found in the raw file, select the dataset to show in case of multiple sweep simulations and more.

The text area with the colored wave names is just a text widget. You can manually edit it to add / remove waves, or you can place the cursor somewhere in the text, select some waves from the listbox on the left, press the Add button to have these waves added. If you place the insertion cursor in the middle of a node name in the text area, you can click the color radio buttons on the bottom to change the color. The Search entry can be used to restrict the list of nodes displayed in the listbox. The Search entry supports regular expression patterns. For example, ^X will match all nodes that begin with X, xm[0-9]\. will match all nodes containing xm followed by one digit and a dot.

Display bus signals

If you have a design where digital signals are present you might want to group some of these to form a bus and display these bundled signals. After placing a graph box and loading the simulation data as explained above, left-double click the graph to show the configuration dialog, check the bus and digital check boxes, use the Search text entry to restrict the list of signals, then select all the signals you want to show as a bus and click the Add button. Also set the Min value and the Max value of the signals in the bus. This information is needed by Xschem to calculate the logic high and logic low thresholds. Currently the logic '1' is set at 80% of the signal min-max range and the logic '0' level is set at 20% of the signal range. After pressing the Add button a bus is shown in the text area. The first field is a template BUS_NAME that you should change to give a meaningful name to the bus. The bus name is separated from the rest of bits by a , or ; character.

You will then see your bussed signal in the graph:

If you have bussed signals in the schematic , like LDA[12:0] and your graph has the Digital and Bus checkboxes set you can simply add the LDA bus to the graph by clicking the net in the schematic (with the configuration dialog open) and pressing Alt-G:

You can add many signals to see them stacked in a very compact view:

It is possible to switch the graph to analog mode, by unchecking the Digital checkbox in the graph configuration dialog, to better see the waveforms. Switching back to Digital yields the previous view. In analog mode buses are not shown, but are not lost. You will see them again when switching back to Digital mode.

Many graphs can be created in a schematic, and the configuration of all graphs (viewport, list of signals, colors) is saved together with the schematic. If you re-run a simulation just unloading/loading the data from the simulation menu will update the waveforms.

Expression evaluation on waves

It is possible to enter math expressions combining simulation data, for example multiply current and voltage to get the power. The syntax of expressions uses postfix (RPN) notation. When entering an expression use double quotes in the graph edit attribute dialog box, so the expression will be considered as a single new wave to display. Operands are loaded onto a stack like structure and then evaluated. The syntax is:
"alias_name;operand operand operator ..."
Example:
"supply power;i(vcurrvnn) vnn * i(vcurrvpp) vpp * +"
that means: i(vcurrvnn) * vnn + i(vcurrvpp) * vpp.
"i(vcurrvnn) 1e6 *"
that means: i(vcurrvnn) * 1e6.

The optional alias_name is just a string to display as the wave label instead of the whole expression. The following operators are defined:
3 argument operators:

2 argument operators:

1 argument operators:

Display a specific dataset for a node

The following syntax: node%n where node is a saved node or a bus or an expression and n is an integer number will plot only the indicated dataset number. Dataset numbers start from 0. This syntax is accepted for single nodes, bus names and expressions:

"DATA_4; en, cal, saout % 4"
saout%3
"Power dataset 6; I(VVCC) VCC * %6"


Specify a different raw file in a graph

It is now possible (xschem 3.4.5+) to load more raw files for a schematic in xschem.
Each graph may optionally refer to a different raw file. If you double click on a graph while waveforms are loaded you see the graphdialog dialog box:

The dialog box has now a simulation type listbox and a Raw file: text entry box. Specifying an existing .raw file name and a simulation type from the listbox will override the 'base' raw file loaded in xschem. (the 'base' raw file is the only one that was loaded previously and applied to all graphs) If no raw file is specified in a graph it will use the loaded 'base' raw file if any, like it used to work before. It is also possible to have multiple graphs all referring to the same raw file, each graph showing a different simulation. It is for example possible to show a dc, tran, ac simulation all loaded from a common .raw file. Image below shows an example: DC, AC, Transient simulation each one done with 3 runs varying the Bias current. In addition the xschem annotate_op is also used to annotate the operating point into the schematic. Ctrl-Left-button-clicking the Backannotate launcher will instantly update all graphs with data taken from the updated raw file(s).

Specify a different raw file for a single signal in a graph

The general syntax for a signal in a graph is the following:
"alias_name; signal_name % dataset# raw_file sim_type
where:
dataset# is the dataset index to display (only meaningful and needed if multiple datasets are present like in Montecarlo / Mismatch simulations). If empty or -1 then show all datasets.
raw_file is the location and name of the raw file to load. You can use $netlist_dir to quickly reference the simulation directory where usually such raw files are located.
sim_type is the simulation type, like ac, sp, spectrum, dc, op, tran, noise.
Example:
"SAOUT; saout % 2 $netlist_dir/autozero_comp.raw tran


Change sweep variable

The graph dialog box has a Sweep textbox where you can write the X-axis variable. By default xschem uses the first variable in the raw file for the X-axis, and this is the sweep variable the simulation was done, so time for transients, frequency for AC sims, voltage or current sweep for DC sims. Example below shows a cmos latch where a DC simulation has been done sweeping the voltage generator on the a input from 0 to 3V.


If v(a) v(z) is specified in the Sweep textbox (or a z) the z signal will be plotted vs a and the a signal will be plotted vs z.


Plot vs an expression (custom sweep axis)

The Sweep textbox also accepts the same "label; expression" format used for graph waves. The RPN expression is evaluated point by point and its result is used as the X-axis for all the waves in the graph, and label is shown on the X-axis instead of a raw file variable name.
Example: Gain; v(out) v(in) / db20() plots all the waves in the graph as dB20(out/in) and labels the X-axis Gain.
If the text after the semicolon is just a raw file variable name, like Time; time, that variable is used for the X-axis and Time is shown on the X-axis instead of time.
Inside the sweep expression the operators that need a sweep reference, like integ(), deriv(), del() and avg(), use the first variable in the raw file as sweep axis. Note that when an expression is used, the same X-axis is applied to all the waves in the graph, so the one-variable-per-wave syntax like v(a) v(z) above is not available in that case.

Smith plots

A Smith chart displays the reflection coefficient Γ for a port, normalized to a reference impedance Z0 that is configurable in the graph properties dialog, with a default of 50 Ω. The center of the chart is a load equal to Z0, and the outer ring is a short or an open circuit.
Unlike normal graphs, a Smith chart ignores the X/Y range settings: xschem always shows the square window |Γ| ≤ 1.05, centered on the chart rectangle. Points outside this window are clipped at the edge of the graph rectangle.
The grid is made of constant-R circles at 0.1, 0.2, 0.5, 1, 2, 5 and 10 and constant-X arcs at +/-0.1, +/-0.2, +/-0.5, +/-1, +/-2 and +/-5, all in units of Z0, plus the unit circle and the real axis; R and jX values are labelled on the grid. The Z0 value of the chart is shown as a readout at the bottom-right corner of the chart.
Smith charts are useful to view impedance, matching and S-parameter behavior over frequency, from AC or SP simulations.
The example below is the LNA_SP schematic from the examples library, showing two Smith charts stacked one above the other: S11 and S22 from an SP simulation (top chart) and the input impedance Zin = -v(vx1)/i(vmes) computed from a plain AC simulation (bottom chart); the gain and noise graphs of the same design are visible on the right.

Creating a Smith plot

The menu Graph -> Add waveform graph adds a Smith plot just like any other graph: the box is placed in the schematic and works like the other graphs; placement, resizing, moving and selecting are covered in the "Using XSCHEM's internal graph functions" section above.
Double-clicking the graph opens the properties dialog, the same dialog described in the sections above. It is a regular waveform graph until the Mode combobox at the top of the dialog is set to Smith.

The Z0 entry, next to the Mode selector, sets the reference impedance of the chart in ohms; it defaults to 50. All values shown on the chart and in the cursor readouts are normalized to this impedance.

In Smith mode the fields that set the X/Y view range (min/max X and Y values), the Log X / Log Y checkboxes, the axis units and the div/subdiv counts are ignored: the chart always shows the fixed plane described in the Smith plots section above, centered on the graph rectangle.
The simulation data loading (menu Waves -> Ac | Sp | ...) works exactly as for a regular graph; nothing else needs to be configured for the chart to appear.

Adding waves to a Smith plot

A Smith plot wave is entered in the graph's wave list, the dialog text area or the Waves menu, with the same syntax as a regular graph. There are two Smith-specific twists: what a bare name means, and a new operator called imp().

Form 1: a bare scattering variable. If the entry is just a variable name, like s_1_1, xschem plots it directly as a reflection coefficient. The real and imaginary parts of that variable in the raw file are the Gamma value of each point, no conversion. This is how S-parameter data (from an SP simulation) is usually shown. A Smith plot of this kind is driven by an SP raw, loaded with Waves -> Sp.

Form 2: the imp() operator. To plot a Z-domain quantity as a Smith curve, append the zero-argument operator imp() to a wave expression. It pops the top stack value (an impedance in ohms, complex) and pushes its reflection coefficient, computed with the chart Z0: Gamma = (Z - Z0) / (Z + Z0). It works in the same postfix (RPN) expression syntax described in the "Expression evaluation on waves" section; imp() takes no arguments. The example in the hero picture is entered as: "Zin(vx1); vx1 i(vmes) / -1 * imp()". The alias Zin(vx1) is shown as the wave label. The expression computes v(vx1) / i(vmes) * -1 (the port impedance seen by the measuring source, Vmes) and imp() converts it to Gamma. imp() needs the raw file to contain the actual port voltage and port current: -v(port node)/i(port source) is then the physical port impedance. S-parameter raw files must not be used with imp(): their saved port sources are not the real excitations, so the v()/i() values in an SP raw do not represent the port impedance.

Form 3: dataset / raw file override per wave. Like regular graphs, a wave entry can end with the "dataset / raw file / sim type" suffix: alias; expression % dataset rawfile simtype (see the "Specify a different raw file for a single signal in a graph" section; the fields are not re-documented here). All three forms can be combined in one entry.

The wave label shown on the chart is the alias (or the variable name), and wave colors are chosen exactly as for a regular graph, with the dialog color buttons or by editing the text area.

Smith chart cursors

The a and b keys place cursor A and cursor B; on a Smith plot each cursor has a frequency and each wave shows its own point on the plane at that frequency. Placing a cursor with the mouse inside a Smith chart snaps the cursor to the trace point closest to the mouse pointer; all waves in all Smith charts of the schematic share the cursor frequency.

At each cursor frequency every wave is marked at its Γ point in the wave color: cursor A as a filled dot, cursor B as a cross (x). Marker size follows the global zoom: the marker size scales with the chart under the display zoom.
The picture shows cursor A: one marker per wave, and the cursor frequency at the bottom-left corner.
With both cursors active, each wave shows its dot (A) and cross (B) and both frequency labels are shown.

A cursor can be dragged: press the left mouse button on (or close to) one of its markers and move; the cursor follows the closest trace point to the pointer, so you can sweep the cursor along the curves.

With a cursor active, every wave shows its values below the wave label, in the wave color, two lines per cursor (cursor A's lines first, then cursor B's): for waves plotted directly as Γ (S-parameters): |Γ| and the angle in degrees on the first line, and the impedance Z = R+jX in ohms on the second; for waves converted with imp() the two lines are swapped (impedance first, Γ second). Values are shown with at most 3 decimals.

Probing a Smith chart

Pressing m with the mouse on the chart shows the text probe at the pointer: the Γ value (u+jv, magnitude, angle) and the impedance value (R+jX, magnitude, angle) at that point.

Pressing the right mouse button on a cursor marker opens a prompt preset with the current frequency; enter a value in hertz to move that cursor to that exact frequency. Cancelling the prompt moves the cursor to 0, inherited from regular graphs.

Pressing the right mouse button on a wave (not on a marker) hilights that wave, like in a regular graph; with a wave hilighted, t switches its dataset when multiple datasets are present in the raw file (see the "Display a specific dataset for a node" section above).

Because the plane is fixed, the in-graph zoom and pan commands (the f key, the arrow keys, the right-button zoom boxes and the drag panning) have no effect on a Smith plot. Only the overall display zoom changes the size of the chart, and the cursor markers are drawn at the zoomed size (see the cursors section above).

With the mouse outside the chart, the usual schematic functions apply; the graph_use_ctrl_key option behaves exactly as documented above.

Smith chart notes and limitations