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. The utility gnetlist is used to convert schematic files to netlist files, Gaw or Gwave to display simulation results and gschem is the preferred schematic capture tool. gSpiceUI is useless without the software tools it depends on, credit should go to the authors of those tools.

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.


Return to top

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 :

2.1.2   Import

Import one or more schematic files. 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.

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   Exit

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


Return to top

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 :

Notes :

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. Gwave or Gaw. The particular results file loaded into the viewer process dependents on the currently selected simulation results tab and analysis type tab.


Return to top

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 :


Return to top

2.4     Help Menu

The Help Menu contains the following options :

2.4.1   User Manual

Open the gSpiceUI HTML documentation in a basic HTML viewing window.

2.4.2   About

Open a dialogue containing application "About" information.


Return to top

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.


Return to top

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.


Return to top

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.


Return to top

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.


Return to top

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

NG-Spice :
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.
GNU-Cap :
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

NG-Spice :
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.
GNU-Cap :
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

NG-Spice :
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.
GNU-Cap :
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

NG-Spice :
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.
GNU-Cap :
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

NG-Spice :
Not yet implemented.
GNU-Cap :
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.

Return to top

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   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.4.5   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.


Return to top

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.


Return to top

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 gschem file test-amp1.sch is imported and every possible analysis type is run using both NG-Spice and GNU-Cap. The following is a list of files which would be created :

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

All file names begin with the prefix test-amp1 (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 :


Return to top

Last modified : 2015-04-30
Author : Mike Waters
E-Mail : mwaters517_AT_gmail_DOT_com