GNU SPICE GUI
User Manual

Table of Contents

1.   Introduction

2.   Menu Bar

2.1   File Menu
2.2   Simulate Menu
2.3   Settings Menu
2.4   Help Menu

3.   Tool Bar

4.   Main Window

4.1   Node List
4.2   Component List
4.3   Analysis Notebook
4.4   Console Notebook
4.5   Status Bar

5.   Temporary Files

1.       Introduction

The name gSpiceUI is an abbreviation of the project title GNU SPICE GUI, which is itself an acronym standing for Gnu is Not Unix, Simulation Program with Integrated Circuit Emphasis, Graphical User Interface.

gSpiceUI is intended to provide a GUI for freely available electronic circuit simulation engines ie. NG-Spice and GnuCAP. If the gEDA (GNU Electronic Design Automation) tool set is used the utility gnetlist is used to convert schematic files to netlist files, Gaw or Gwave (no longer supported) display simulation results and gschem (part of the gEDA tool set) is the preferred schematic capture application. gSpiceUI is useless without the software tools it depends on, credit should go to the authors of those tools.

gSpiceUI can also be used in conjunction with the KiCAD tool set. KiCAD doesn't expose it's netlist utility like gEDA so this step must be performed by the user inside the schematic capture application eeschema. The import mechanism in gSpiceUI cannot be used in this case and as yet eeschema can't be envoked inside gSpiceUI. Gaw and Gwave are used to display simulation results.

The gSpiceUI GUI is designed to be as consistant as possible between analysis types and simulation engines. The intention is to abstract the technical particulars from the user so that the focus may be on the simulation rather than the simulation engine or even the analysis type.

Like all open source software gSpiceUI is a work in progress and probably always will be. It has been developed over a long period of time (since 2003) and has reached a relatively mature state. Experience in software development as well as using software in general has taught me that it's better to provide less functionality that works than more functionality that just promises a lot. Consequently, as a generally rule, bugs fixes and improvements to the underlying architecture will take precedence over new functionality. I believe this approach pays off in the long term.

It is worth noting that whereas NG-Spice is derived from the SPICE code base, GNU-Cap is not. GNU-Cap is an independent implementation of the principals used to analyses electronic circuits. As a consequence analysis results can be generated using two independant mechanisms and then compared. This is one of the reasons for supporting more than one simulation engine; if the same or similar results can be achieved using two different simulation engines then it's likely that the simulation results will bear some resemblence to what actually happens in reality.

It is important to realise that a simulation engine models the behaviour of a system and therefore can never be 100% accurate. In addition the simulation engine itself is an implementation in software of a mathematical model and so is also subject to bugs. As the underlying mathematical model and software implementation improve the simulation performance improves. One of the reasons for the choice of simulation engines to support was that they are both in constant development. (Not to mention the inherent goodness and righteousness of open source software, so I won't mention it.)

The skills and judgement of the user have a profound impact on the usefulness of electronic simulation. It can be a technically demanding process requiring considerable thought, practice and persistence. The alternative is to go straight to building prototypes; in any case, ultimately prototypes must be created to finalize a design. However simulation is generally a rewarding step in the development process, even if it only provides a better understanding of the internal workings of a design.

2.       Menu Bar

The menu bar provides access to almost all of the functionality provided by gSpiceUI. However there are a few functions that can only be accessed via command line options.

2.1     File Menu

This file menu contains options mainly associated with handling netlist and schematic files.

2.1.1   Open

Open a netlist (circuit description) file containing component definitions and load it into the NetList text control. If the netlist contains simulation instructions gSpiceUI attempts to parse them and the settings are displayed in the GUI.

Notes :

• Be aware that gSpiceUI will modify the netlist file; it will change the formatting and remove things it doesn't understand. If this isn't OK, create a copy of the netlist file and give that to gSpiceUI.
• When using the gEDA tool set the netlist file extension is ".ckt". For the KiCAD tool set the netlist extension is "cir". Be sure to specify the appropriate file extension for the tool set.
• There is an upper limit to the number of lines which may be displayed in any text control (the underlying file isn't truncated). This setting maybe adjusted by the user, refer to 2.3.2 Preferences Dialog.

2.1.2   Import

Import one or more schematic files. The utility gnetlist is used to convert the schematic file/s to a single netlist file. The netlist file name is automatically derived from the first schematic file name in the list with the file extension changed to ".ckt". Eg. if schem1.sch, schem2.sch, schem3.sch were specified as the schematic file names to be imported the netlist file name would be schem1.ckt.

Notes :

• If you are using the KiCAD tool set Import won't work. The gEDA utility gnetlist can't convert KiCAD schematics to a netlist file. The netlist utility in KiCAD is built into the schematic capture application eeshema so gSpiceUI can't envoke it. The netlist file must be created or updated from within eeshema by the user and reloaded into gSpiceUI using the Reload operation.

2.1.3   Reload

Reload the netlist file. If the netlist was imported from one or more schematic files, the import operation will be repeated. As far as possible the simulation settings shown in the currently displayed analysis notebook page are retained.

When gSpiceUI is used to create a netlist file from schematic file/s it inserts a reference to the schematic file/s near the beginning of the netlist file. If the currently open netlist has this schematic reference, reload performs an import operation otherwise the netlist is simply reloaded. In either case the simulation settings shown in the currently displayed analysis notebook page are retained as far as possible.

2.1.4   Close

If a netlist file is open then close it and resets all GUI parameters to default values.

2.1.5   Quit

Close all files and child applications, delete temporary files if required and exit the application.

2.2     Simulate Menu

The simulate menu contains options associated with circuit simulation operations and provides access to other useful applications upon which gSpiceUI dependends.

2.2.1   Create

Create a simulation file based on the values currently displayed on the GUI or the contents of the Simulation text control. Note, any changes made to the GUI have priority over changes made by the user to the Simulation text control contents.

If any changes are made to the GUI control contents the simulation file is completely re-constructed, which then causes the Simulation control contents to be over-written and lost. However, if changes have been made to the Simulation text control contents alone then it is written verbatim to the simulation file.

If a problem is encountered a message box is displayed giving a brief explanation as to why the operation could not be completed. The raw console spew generated by the process will have been sent to the Console text control, a careful perusal of this generally reveals the cause of the problem/s.

2.2.2   Run

Run a simulation based on the values currently displayed on the GUI controls or in the Simulation text control. If the user has made changes since the last Create operation then a Create operation is automatically executed as described above.

If the simulation file is created successfully then gSpiceUI attempts to run the simulation. The simulation results are formatted then sent to a data file (refer to section 5. Files) and are displayed in the appropriate Simulation Results text control.

If a problem is encountered a message box is displayed giving a brief explanation as to why the operation could not be completed. The raw console spew generated by the process will have been sent to the Console text control, a careful perusal of this generally reveals the cause of the problem/s.

2.2.3   Stop

Stop a running simulation immediately. This option can only be executed if a simulation is actually running. This is a useful option if a simulation is running too long or appears as if it won't converge.

2.2.4   Schematic

Edit a schematic file. If there is a schematic file associated with an open netlist file it is opened using gschem and may be viewed or edited by the user. Note : if changes are made to the schematic file (and the schematic file has been updated on disk by gschem) then an Import operation must be performed in gSpiceUI in order for gSpiceUI to "know" about new the changes.

It's important to be aware that gSpiceUI cannot run a simulation based on any old schematic file eg. generated by gschem. In fact, the simulation will fail unless the schematic is trivial or you're just lucky. Certain prerequisites must be met before a schematic may be simulated. The schematic must be translated into a form which can be interpreted by the simulation engine (eg. by gnetlist), in short everything must be explicitly defined. The extra information required over that sufficient for human readability is :

• At present if the KiCAD tool set is used this function will not work. The KiCAD schematic capture application eeschema must be manually started by the user and the netlist file updated by the user from within eeschema whenever the schematic is changed. Perform a Reload operation and then proceed as normal.
• All power supply sources must be explicitly defined.
• All signal sources must be explicitly defined.
• Components not already defined in the simulation environment must be defined using models.
• Component labels must adhere to the rules specified for the simulation engine eg. resistor names always start with the letter 'R'. In particular be aware that often a model file contains a sub-circuit which must have a name starting with the character 'X'.
• Net labels must adhere to the rules specified for the simulation engine eg. they can't start with a digit. Refer to the specific simulation engine documentation.

Notes :

• In gschem, models may be included by setting the component's file attribute or by use of a SPICE Model object. Either way the component value is set to the model or sub-circuit label. Check the example schematics that come with gSpiceUI to see how it's done eg. the LM555 or operational amplifier examples.
• gSpiceUI recognizes a component type by the first letter of the component name eg. an inductor name is expected to start with the letter 'L'. The following is list of the first letter of various component types (this format is derived from NG-Spice) :

  	B	-	Non-Linear Dependent Source
  	C	-	Capacitor
  	D	-	Diode
  	E	-	Voltage Controlled Voltage Source
  	F	-	Current Controlled Current Source
  	G	-	Voltage Controlled Current Source
  	H	-	Current Controlled Voltage Source
  	I	-	Independent Current Source
  	J	-	JFET (Junction Field-Effect Transistor)
  	K	-	Coupled (Mutual) Inductors
  	L	-	Inductor
  	M	-	MOSFET (Metal-Oxide Semiconductor Field-Effect Transistor)
  	O	-	Lossy Transmission Line (LTRA)
  	P	-	Coupled Multi-conductor Transmission Line (CPL)
  	Q	-	BJT (Bipolar Junction Transistor)
  	R	-	Resistor
  	S	-	Voltage Controlled Switch
  	T	-	Lossless Transmission Line
  	U	-	Uniform Distributed RC Transmission Line (URC)
  	V	-	Independent Voltage Source
  	W	-	Current Controlled Switch
  	X	-	Sub-circuit
  	Y	-	Single Lossy Transmission Line (TXL)
  	Z	-	MESFET (Metal-Semiconductor Field Effect Transistor)

2.2.5   View Results

View simulation results in a graphical form. One of the simulation results files is opened using a data viewer application eg. Gaw or Gwave. The particular results file loaded into the viewer process dependents on the currently selected simulation results tab and analysis type tab.

2.3     Settings Menu

The settings menu contains application configuration options.

2.3.1   Simulation Engine Selection

The first section of the Settings Menu contains radio buttons allowing the selection of the electronic circuit simulation engine to be used. The analysis notebook is updated based on the chosen simulation engine, the selected simulation engine name is displayed in the status line and any simulation results are sent to the appropriate console tab.

When the simulation engine is changed gSpiceUI attempts to transfer simulation information to the new simulator environment. The information is tranferred via the simulation file so if information appears on the GUI but not in the simulation file it will be lost. If this is a problem create a fresh simulation file prior to changing the simulation engine.

2.3.2   Preferences Dialog

The preferences dialog contains the following settings :

• Waveform data viewer :
  A choice box containing the available waveform data viewer utilities. The currently selected waveform data viewer utility name is displayed in the status line.
   
• Temporary files :
  A choice box containing the available temporary file management strategies, ie. automatically delete temporary files, prompt the user or just keep the temporary files. Most of the files in question contain simulation results data and may be useful outside gSpiceUI. Refer to section 5. Temporary Files.
   
• Main frame layout :
  A choice box containing the available main frame layout schemes. The main has two layout schemes to choose from : longer probes (Nodes and Component) controls or a wider console notebook control.
   
• Phase / angle units :
  A choice box containing the available phase or angle units, ie. degrees or radians.
   
• Results precision :
  A choice box containing the available precisions which may be applied to simulation results. The data are rounded to the selected precision not just truncated.
   
• gnetlist Guile backend :
  A choice box containing the available gnetlist Guile backend procedures. This list of Guile backends is derived by querying gnetlist directly so whatever procedures gnetlist can detect are listed.
   
• Max text control lines :
  A value control which sets the maximum number of lines which may be displayed in any of the console text controls. Simulation results files can potentially be very large, this value allows the user to have some control over the system resources used by gSpiceUI.
   
• Spin control period :
  A value control which sets the period (in msec) between successive spin button control updates.
   
• Tool tip delay :
  A value control which sets the delay (in msec) before a tool tip is displayed.
   
• Show tool tips :
  A check box which enables or disables tool tips.
   
• Sync. sweep sources :
  A check box which enables or disables synchronization of the sweep sources. If a sweep source is selected in one analysis page, where possible the same source will appear in other analysis pages. Note : the sweep source value is not carried over between pages (I'm not convinced this behaviour would be helpful).
   
• Sync. temperatures :
  A check box which enables or disables synchronization of the ambient temperature values between analysis pages and the OPTIONS dialogue.
   
• Keep the netlist file :
  A check box which controls whether netlist files are included in the list of temporary files and therefore the temporary file management strategy.
   
• gnetlist verbose mode :
  A check box which enables or disables gnetlist verbose mode. With this enabled gnetlist generates lots of lovely console spew which appears in the Console tab of the console notebook. It's useful for debugging when gnetlist is have problems importing schematic file/s.
   
• Include model defs. :
  A check box which controls whether .INCLUDE directives are used for model files or the model file contents are inserted in the netlist file. )This option controls the the gnetlist SPICE backend "include_mode".)
   
• Embed include files :
  A check box which controls how gnetlist behaves when it encounters a .INCLUDE directive. With this option checked gnetlist embeds (inserts) the file contents into the netlist file. (This option controls the the gnetlist SPICE backend "embedd_mode".)
   
• Fix component prefixes :
  A check box which controls whether component label prefixes are automatically tested and modified if the incorrect prefix is used. SPICE recognizes different components based on the first character of the component label eg. R1 would be identified as a resistor. If an incorrect prefix is detected the correct prefix is prepended to the component label. (This option controls the the gnetlist SPICE backend "nomunge_mode".)
   
• The paths to the various programs and utilities used by gSpiceUI may be manually set via this menu selection. (Not yet implemented)

Note :

• All preferences work if the gEDA tool set is used but some aren't pertinent if the KiCAD tool set is used.

2.4     Help Menu

The Help Menu contains the following options :

2.4.1   User Manual

Open the gSpiceUI HTML documentation in a HTML view window (more specifically this document). At the time of writing the HTML viewer only performs the basic functions (eg. it is monochrome) but it is sufficient for the purpose.

2.4.2   About

Open a dialogue containing application "About" information.

3.       Tool Bar

The tool bar contains buttons which give easy access to the most used functions. The buttons are presented in groups associated with the different types of activities. Refer to the matching menu bar function in section Menu Bar.

4.       Main Window

The main window is made up of various display objects which are described in the following sub-sections. There are lists of possible test points, analysis settings, console output and a status bar.

The main window title bar always contains at least the application name. If a file is open, whether it be a netlist or schematic file/s, the name of a netlist file will be appended to the normal window title banner. Keep in mind that this netlist file is the main file that gSpiceUI works on.

4.1     Node List

Display the list of node labels extracted from the netlist file. One or more nodes may be selected (or deselected) by clicking on the node/s in the list with the mouse. The probes for the selected nodes will be calculated and included in the simulation results.

A single node may be selected from the list by left clicking on it with the mouse. To select multiple nodes press the control key and left click on the desired nodes with the mouse. To select a range of nodes left click on the desired range with the mouse while holding down the shift key.

4.2     Component List

Display the list of components extracted from the netlist file. One or more components may be selected (or deselected) by clicking on the component/s in the list with the mouse. The probes for the selected components will be calculated and included in the simulation results. At present only two terminal components are included in this list.

A single component may be selected from the list by left clicking on it with the mouse. To select multiple components press the control key and left click on the desired components with the mouse. To select a range of components left click on the desired range with the mouse while holding down the shift key.

4.3     Analysis Notebook

There are two mildly different analysis notebooks associated with the two simulation engines supported by gSpiceUI ie. GNU-Cap or NG-Spice. Each analysis notebook contains analysis pages reflecting the various analysis types supported by the associated simulation engine. The following brief outlines the various analysis types current supported. For further information refer to the user documentation for the appropriate simulation engine (much of what follows is taken from this documentation).

4.3.1   Operating Point Analysis

This analysis type is supported using the DC command in NG-Spice. The DC analysis determines the DC operating point of the circuit with inductors shorted and capacitors opened. In this instance the DC analysis is used to generate DC transfer curves for temperature stepped over a user-specified range and the DC output variables are stored for each sequential temperature value.

Performs a nonlinear DC steady state analysis. If a temperature range is given, it sweeps the temperature. If there are numeric arguments, they represent a temperature sweep. They are the start and stop temperatures in degrees Celsius, and the step size, in order. This command also sets up the quiescent point for subsequent AC analysis. It is necessary to do this for nonlinear circuits. The last step in the sweep determines the quiescent point for the AC analysis.

4.3.2   DC Analysis

The DC analysis determines the DC operating point of the circuit with inductors shorted and capacitors opened. A DC analysis is automatically performed prior to a Transient analysis to determine the transient initial conditions, and prior to an AC small-signal analysis to determine the linearized, small-signal models for nonlinear devices. The DC analysis can also be used to generate DC transfer curves : a specified independent voltage, current source, resistor or temperature is stepped over a user-specified range and the DC output variables are stored for each sequential source value.

Performs a nonlinear DC steady state analysis, and sweeps the signal input, or a component value. If there are numeric arguments, without a part label, they represent a ramp from the generator function. They are the start value, stop value and step size, in order. In some cases, you will get one more step outside the specified range of inputs due to internal rounding errors. The last input may be beyond the end point. The program will sweep any simple component, including resistors, capacitors, and controlled sources.

4.3.3   AC Analysis

The AC small-signal analysis determines the output variables as a function of frequency. The DC operating point of the circuit is first determined and used to generate linearized, small-signal models for all of the nonlinear devices in the circuit. The resultant linearized version of the circuit is then analyzed over a user-specified range of frequencies. The desired output of an AC small-signal analysis is usually a transfer function (trans-impedance, voltage gain, etc.). If the circuit has only one AC input, it is convenient to set that input to unity and zero phase, so that output variables have the same value as the transfer function of the output variable with respect to the input.

Performs a small signal, steady state, AC analysis. Sweeps frequency. The AC command does a linear analysis about an operating point. It is absolutely necessary to do an OP analysis first on any nonlinear circuit. Not doing this is the equivalent of testing it with the power off. If the start frequency is zero, the program will still do an AC analysis. The actual frequency can be considered to be the limit as the frequency approaches zero. It is, therefore, still possible to have a non-zero phase angle, but delays are not shown because they may be infinite.

4.3.4   Transient Analysis

The Transient analysis determines the transient output variables as a function of time over a user-specified time interval. The initial conditions are automatically determined by a DC analysis. All sources which are not time dependent (for example, power supplies) are set to their DC value.

Performs a nonlinear time domain (transient) analysis. Do not use a step size too large as this will result in errors in the results. If you suspect that the results are not accurate, try a larger argument to skip. This will force a smaller internal step size. If the results are close to the same, they can be trusted. If not, try a still larger skip argument until they appear to match close enough. The most obvious error of this type is aliasing. You must select sample frequency at least twice the highest signal frequency that exists anywhere in the circuit. This frequency can be very high, when you use the default step function as input. The signal generator does not have any filtering.

4.3.5   Fourier Analysis

Not yet implemented.

Performs a nonlinear time domain (transient) analysis, but displays the results in the frequency domain. Actually, this command does a nonlinear time domain analysis, then performs a Fourier transform on the data to get the frequency data. The transient analysis parameters (start, stop, step) are determined by the program as necessary to produce the desired spectral results. The internal time steps are selected to match the Fourier points, so there is no interpolation done.

4.4     Text Control Notebook

The console notebook contains various text controls which display text data generated by the different operations initiated by gSpiceUI.

4.4.1   Console

Display the console input/output for the last process executed by gSpiceUI. If an error occurs this is a good place to look for indications of what has gone wrong.

4.4.2   Circuit

Display the raw netlist file which was opened or imported via the file menu. The variables and values contained in the netlist file are those displayed in the GUI's display objects.

4.4.3   Simulation

Display the simulation file to be run. It is basically the netlist file plus simulator commands based on user input to the GUI objects. It can be manually edited by the user and will be run as is if the Run button is pressed. NOTE : if the create button is pressed the contents of this tab will be over-written destroying any user input.

4.4.4   NG-Spice Results

Display the results from the last run of the NG-Spice simulation engine. The raw data is reformatted to aid readability; non-data records are removed and the precision is set according the value set in the Preferences dialog. If required the raw output from the simulation engine may be viewed in the Console tab.

4.4.5   GNU-Cap Results

Display the results from the last run of the GNU-Cap simulation engine. The raw data is reformatted to aid readability; non-data records are removed and the precision is set according the value set in the Preferences dialog. If required the raw output from the simulation engine may be viewed in the Console tab.

4.5     Status Bar

The status bar is located at the bottom of the application main frame. It consists of three panes which contain text messages showing the state of gSpiceUI. From left to right the panes contain :

1. The last application status or error message.
2. The currently selected simulation engine.
3. The currently selected waveform viewer utility.

5.       Temporary Files

Whilst running gSpiceUI various temporary files may be generated in the directory occupied by the schematic or netlist file/s. To illustrate, consider the situation where the schematic file "test-cct.sch" is imported and every possible analysis type is run, using both NG-Spice and GNU-Cap. Along with the schematic file the following temporary files which would be created :

<path>/sch/test-cct.sch		(The schematic file to be analysed)
<path>/sch/test-cct.ckt		(Netlist file with simulation commands)
<path>/sch/test-cct.sch~		(Backup file to the schematic file)
<path>/sch/gspiceui.log		(Temporary file for raw process output)
<path>/sch/test-cct.ngspice.op		(Results file - operating point analysis)
<path>/sch/test-cct.ngspice.dc		(Results file - DC analysis)
<path>/sch/test-cct.ngspice.ac		(Results file - AC analysis)
<path>/sch/test-cct.ngspice.tr		(Results file - transient response analysis)
<path>/sch/test-cct.gnucap.op		(Results file - operating point analysis)
<path>/sch/test-cct.gnucap.dc		(Results file - DC analysis)
<path>/sch/test-cct.gnucap.ac		(Results file - AC analysis)
<path>/sch/test-cct.gnucap.tr		(Results file - transient response analysis)

All file names begin with the prefix "test-cct" (taken from the schematic file name). File name extensions then depend on the file type. Files containing simulation results include the name of the simulation engine used to generate the data and an abbreviation indicating the analysis type.

Notes :

• gSpiceUI has various mechanisms for managing temporary files (eg. delete them), refer to Settings Menu.
• If temporary files are deleted this includes the schematic backup file.