#
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. Files
> 6. Software Design

## 1. Introduction

GNU Spice GUI (gSpiceUI) is intended to provide a GUI for freely available electronic circuit simulation engines ie. GnuCAP and NG-Spice. (It should be noted that GNU-Cap is not derived from the SPICE code base but is an independent implementation of the principals used to analyses electronic circuits.) gSpiceUI uses gnetlist to convert schematic files to netlists, gWave or Gaw to display simulation results and gschem is the preferred schematic capture tool.

Here are two screen shots of gSpiceUI in action; the first with GNU-Cap as the simulation engine, the second with NG-Spice as the simulation engine. The 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 analysis type.

It is important to realise that a simulation engine "models" the performance of a system and therefore can never be 100% accurate. And the simulation engine itself is an implementation in software of the model and so is subject to bugs. Consequently, as the underlying model and implementation improve the modelling performance improves. One of the reasons for the choice of simulation engines to support was that they be in constant development. This is also 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.

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 :

- 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 give gSpiceUI a copy of you're file.
- 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. 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 on which gSpiecUI 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 to the Simulation control contents.

If any changes are made to the GUI 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 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 OR in the Simulation text control. If the user has made changes since the last Create operation then a Create operation is 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 then an Import operation must be performed after closing gschem in order for gspiceui to "know" about the changes.

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

- 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 be names 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.

Note :

- 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 op amp examples.

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

#### 2.3.2 Preferences Dialog

The preferences dialog contains the following settings :

- Waveform viewer :
  A choice box containing the available waveform viewer utilities. The currently selected waveform viewer utility name is displayed in the status line.
- Temporary files :
  A choice box containing the available temporary file management strategies ie. when gSpiceUI exits 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. Files.
- 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.
- 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.
- 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.
- Show tool tips :
  A check box which enables or disables tool tips.
- The paths to the various utilities used by gSpiceUI may be manually set via this menu selection. (Not yet implemented)

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

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.

NG-Spice :

> This analysis type is not directly supported by NG-Spice however similiar functionality is provided in the DC Analysis panel.

#### 4.3.2 DC Analysis

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.

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.

#### 4.3.3 AC Analysis

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.

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.

#### 4.3.4 Transient Analysis

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.

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.

#### 4.3.5 Fourier Analysis

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.

NG-Spice :

> Not yet implemented.

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

Whilst running gSpiceUI various 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.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)
> <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)

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 :

- gSpiceUI can manage (eg. delete) temporary files, refer to Settings Menu.
- Not all analysis types mentioned above have been implemented.

Return to top

## 6. Software Design

The following links are to object models depicting the static architecture of gSpiceUI :

- The overall gSpiceUI application.
- The main application frame
- The analysis notebook
- The processes which gSpiceUI may execute.
- The value panels which display data variables.

Note :

- The object models depicted here largely show the actual application architecture. However, the software is under development and is often in a state of flux, it will not always exactly match the information shown in the object models.

Return to top