%***************************************************************************************************
%                                         gspiceui-man.tex                                         *
%                                        ------------------                                        *
% Comment : GNU SPICE GUI user manual TEX source file.                                             *
% Started : 2020-08-09                                                                             *
% Updated : Refer to Title section below.                                                          *
% Authors : MSWaters                                                                               *
%***************************************************************************************************
% Notes :
%  - Convert to PDF  format using the command : "pdflatex -halt-on-error gspiceui-man.tex"
%  - Convert to HTML format using the command : "htlatex gspiceui-man.tex"
%***************************************************************************************************

%***************************************************************************************************
%                                                                                                  *
%       This program is free software; you can redistribute it and/or modify it under the          *
%       terms of the GNU General Public License as published by the Free Software Foundation;      *
%       either version 3 of the License, or (at your option) any later version.                    *
%                                                                                                  *
%***************************************************************************************************

%***************************************************************************************************
% Things to Do :
%
% 2020-08-21 Complete implementation of the Installation section 
% 2020-08-08 Remove/resolve all ??? marked segments
%***************************************************************************************************

\documentclass[english,a4paper,11pt]{article}

\usepackage[top=2.5cm, bottom=3cm, left=3cm, right=3cm]{geometry}
\usepackage[T1]{fontenc}
\usepackage[latin9]{inputenc}
\usepackage{textcomp}             % Provides extra symbols, eg. arrows
\usepackage{babel}                % Provides the internationalization of LaTeX
\usepackage{graphicx}             % Enables the inclusion of graphic files within a document
\usepackage{parskip}              % Don't indent paragraphs
\usepackage{enumitem}             % Add functionality for list structures
\usepackage[hidelinks]{hyperref}  % Clickable hyperlinks (but hide links ie. no color or border)
\usepackage{framed}               % Draws a box around text
\usepackage{fancyvrb}             % Allows font size to be set inside verbatim environment
\usepackage{pifont}               % Postscript ZipfDingbats font, print symbol with \ding{number}

\setlength{\itemsep}{0pt}         % Set the default vertical separation of item in lists
\setlength{\tabcolsep}{2pt}       % Set the default column separation in tables
\renewcommand{\arraystretch}{1.3} % Set the default row separating in tables

\graphicspath{ {../images/} }     % Tell LaTeX where to look for images (need trailing forward slash)

\makeatletter
\makeatother

% Create a new command to indent paragraphs
\newcommand{\forceindent}{\parindent=1em\indent\parindent=0pt\relax}

\begin{document}

%***************************************************************************************************
%                                          Document Title
%***************************************************************************************************

\title
{
  GNU SPICE GUI \\
  (gSpiceUI)    \\
  \vspace{20pt} 
  User Manual
}
\author{ M.S.Waters}
\date{Version 1.1.03 \hspace{2pt}(2021-08-29)}
\maketitle                                     % Create a title page
\addcontentsline{toc}{subsection}{Title Page}  % Add the title page to the TOC

\pagebreak

%***************************************************************************************************
%                                         Table of Contents
%***************************************************************************************************

\setcounter{tocdepth}{2}                              % Set the TOC depth (can be set to 2 or 3)
\tableofcontents                                      % Create a TOC
\addcontentsline{toc}{subsection}{Table of Contents}  % Add the TOC to the TOC (good for side panel)

\pagebreak

%***************************************************************************************************

\listoffigures
\addcontentsline{toc}{subsection}{List of Figures}

\pagebreak

%***************************************************************************************************
%                                           Introduction
%***************************************************************************************************
% Reviewed 2020-08-22

\section{Introduction}
\label{sec:Introduction}

If you are "of an impatient temper", you may stop reading now and go straight to section
\emph{\ref{sec:Getting_Started}\hyperref[sec:Getting_Started]{ Getting Started}}, it's written with
you in mind. For everyone else, read on.

The name \emph{gSpiceUI} is an abbreviation of the project title \emph{GNU SPICE GUI}, which is
itself an acronym standing for {\bf G}nu is {\bf N}ot {\bf U}nix, {\bf S}imulation {\bf P}rogram
with {\bf I}ntegrated {\bf C}ircuit {\bf E}mphasis, {\bf G}raphical {\bf U}ser {\bf I}nterface.

This document has become a central repository for all things gSpiceUI. Primarily it is still
\emph{user documentation} but it also includes material more appropriate to project design and
management. Rather having many documents, some of which get forgotten, I'm hoping by using one
document it will be easier for me to keep things more organised and up to date.

No GUI can encapsulate all the functionality of a non-trivial command-line application and
electronic simulation engines are definitely not trivial. gSpiceUI doesn't attempt to plumb anything
like the depths of the simulation engines it interfaces to. Rather, applying the Pareto principle
(80/20 rule) to software, it's been said that 20\% of the available functionality is used 80\% of
the time. The design of gSpiceUI attempts to encapsulate as much of that 20\% of simulation engine
functionality as possible. Thereby delivering as much high usage functionality as possible without
making the development process too onerous.

gSpiceUI is intended to provide a GUI front-end for freely available electronic circuit simulation
engines ie. \emph{NG-SPICE} and \emph{GNU-CAP}. The user opens a schematic (which is converted to a
netlist) or netlist file, enters analysis information and gSpiceUI generates the necessary
simulation engine instructions and appends them to a netlist file. The netlist file, now including
the simulation instructions is then run by the simulation engine and a results file is generated.

Basically, the only function gSpiceUI performs itself is to generate simulation engine instructions.
All other functionality is provided by other freely available applications and utilities written and
supported by other authors. An EDA ({\bf E}lectronic {\bf D}esign {\bf A}utomation) tool suite,
usually \emph{gEDA-gaf} or \emph{Lepton-EDA} takes care of schematic capture and netlisting.
Waveform data results can be displayed using \emph{Gaw}, \emph{Gwave} or \emph{Kst}. PDF
documentation is viewed using one of many utilities eg. evince, xpdf, mupdf, etc., depending on what
is installed on your system.

gSpiceUI can also be used in conjunction with the \emph{KiCAD} EDA tool suite. KiCAD doesn't expose
it's netlister utility like Lepton-EDA or gEDA-gaf so this step must be performed by the user inside
the schematic capture application \emph{eeschema}. The import mechanism in gSpiceUI cannot be used in
this case and eeschema can't be envoked inside gSpiceUI. Gaw, Gwave or Kst are still 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 NG-SPICE is derived from the SPICE code base, whereas GNU-CAP is not.
GNU-CAP is an independent implementation of the principals used to analyses electronic circuits.
Consequently 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 mechanisms then it's highly likely that the results will
bear some resemblence to what actually happens in the real world.

It is important to realise that a simulation engine \emph{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.

\pagebreak

%***************************************************************************************************
%                                          Getting Started
%***************************************************************************************************
% Reviewed 2020-08-14

\section{Getting Started}
\label{sec:Getting_Started}

At first glance, I'm told gSpiceUI can appear unintuitive. This section is aimed at trying to
dispell some of the mystery. When first encountering gSpiceUI you might expect to see a electronic
circuit schematic and to be able to click on any component and see simulation results displayed in a
graph. This is what I would've liked before starting development of gSpiceUI but there just wasn't
anything of the kind available for Linux.

What did exist, however, where simulation engine backends, schematic capture applications and
waveform data viewer utilities. What was missing was something to simplify the interface to the
simulation engine backend. That's the function I intended gSpiceUI to provide. However, over the
years it has also evolved to become center point for tying together useful functionality.

Basically, all gSpiceUI does is generate simulation engine instructions. All other functionality is
provided by other applications and utilities. An EDA tool suite, usually gEDA-gaf or Lepton-EDA
takes care of schematic capture and netlisting. Waveform data results can be displayed using Gaw,
Gwave or Kst. PDF documentation is viewed using one of many utilities eg. evince, xpdf, mupdf, etc.,
depending on what is installed on your system.

Like most applications gSpiceUI has the usual controls along with various application specific
regions. Refer to \emph{Figure~\ref{fig:gspiceui} : gSpiceUI Main Window} for an image of gSpiceUI
with the various regions of it's main window explicitly labeled.

\vspace{10pt}

\begin{figure}[h]
  \centering
  \includegraphics[scale=0.67]{gspiceui.png}
  \caption{gSpiceUI Main Window.}
  \label{fig:gspiceui}
\end{figure}

\pagebreak

The purpose for the different application specific regions is briefly describe below :

\vspace{5pt}

\begin{description}[leftmargin=135pt,itemindent=-10pt,labelwidth=105pt]
  \item [Node List]         {\bf :} A list of node labels extracted from the netlist file. One or
                    more nodes may be selected (or deselected) by clicking on them with the mouse.
                    The probes for the selected nodes will be calculated and included in the
                    simulation results.
  \item [Component List]    {\bf :} A list of components extracted from the netlist file. One or
                    more components may be selected (or deselected) by clicking on them 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.
  \item [Analysis Notebook] {\bf :} The analysis notebook contains pages reflecting the various
                    analysis types supported by the chosen simulation engine. Controls on each allow
                    the entry of parameters such as sweep range, steps size and signal source
                    component.
  \item [Console Notebook]  {\bf :} The console notebook contains various text controls which
                    display text data generated by the different operations initiated by gSpiceUI.
\end{description}

\vspace{5pt}

Now to try a simple example. As part of the gSpiceUI installation a number of demonstration
schematics should have been included (usually in "/usr/share/gspiceui/sch/demos/"). We'll open one
and do a simple simulation to illustrate the basic functionality of gSpiceUI. Follow the steps
listed below :

\begin{enumerate}
  \item Start gSpiceUI using the following command-line (to simplify these instruction use the
        NG-SPICE simulation engine and Gaw as the waveform data viewer) :
        \begin{Verbatim}[fontsize=\small]
  gspiceui -s ngspice -w gaw
        \end{Verbatim}
  \item Import (create a netlist file) from the schematic file "bjt-amp-ce-1.sch" found amoung the
        demo. schematics. The \emph{Import} operation can be initiated from the \emph{File} menu or
        by clicking on the the tool bar icon with the tool tip "Import a schematic file". If all
        goes well the file should load without errors.
  \item View the schematic by selecting the \emph{Schematic} item from the \emph{Simulate} menu or
        clicking on the tool bar icon with the tool tip "View / edit the schematic".
  \item Prepare a simulation by first selecting the \emph{AC} analysis page in the Analysis Notebook
        and entering the sweep parameters : \emph{Start Frequency} 100 Hz, \emph{Stop Frequency}
        500 kHz and 100 \emph{Steps/Decade}. Select the \emph{Signal Source} to be \emph{Vin} and
        the output probe \emph{Rout} from the \emph{Components} list.
  \item Now run the simulation by selecting the \emph{Run} item from the \emph{Simulate} menu or
        clicking on the tool bar icon having the tool tip "Run the simulation". If all goes well the
        simulation will run without error and the message "Simulation ran successfully" will appear
        in the left panel of the status bar.
  \item To view the simulation results select the \emph{Results} item from the \emph{Simulate} menu
        or click on the tool bar icon having the tool tip "View simulation results".
  \item Gaw uses a MDI (Multiple Document Interface) comprised of a smaller window containing a list
        parameters and a larger waveform display window. Select the parameter \emph{VDB(Rout)} and
        drag it to one of the waveform display regions. From the \emph{Preferences} menu select
        \emph{Show Grid} and \emph{log x scale}. You should now see a bode plot of the amplifier
        transfer function and be able to confirm the specifications given in the schematic file.
        Refer to \emph{Figure \ref{fig:gaw} : Gaw Main Window}.
        \vspace{5pt}
        \begin{figure}[h]
          \raggedleft
          \includegraphics[scale=0.49]{gaw.png}
          \caption{Gaw Main Window.}
          \label{fig:gaw}
        \end{figure}
\end{enumerate}

The gSpiceUI Help menu contains links to user documentation for the simulation engines (assuming it
has been installed in the appropiate place on your system, refer to the Install file).
  
\pagebreak

%***************************************************************************************************
%                                           Installation
%***************************************************************************************************
% Reviewed 2020-10-11

\section{Installation}
\label{sec:Installation}

These instructions provide information required to compile and install gSpiceUI. Many operating
systems have ready made packages for installing gSpiceUI, this is the preferred option. 

%***************************************************************************************************
% Requirements
%***************************************************************************************************
% Reviewed 2020-10-11

\subsection{Requirements}
\label{subsec:Requirements}

There are various requirements for building gSpiceUI and running it in a meaningful way. The
different requirements are listed below :

\begin{tabular}[c]{ @{\hspace{16pt}} c @{\hspace{6pt}} l l l l }

  $\bullet$ & Compilation   & (Essential) & : wxWidgets  & - C++ library                          \\
  $\bullet$ & Run time      & (Desirable) & : GNU-CAP    & - electronic circuit simulation engine \\
  $\bullet$ & Run time      & (Desirable) & : NG-SPICE   & - electronic circuit simulation engine \\
  $\bullet$ & Run time      & (Optional)  & : Gaw        & - analogue waveform data viewer        \\
  $\bullet$ & Run time      & (Optional)  & : GWave      & - analogue waveform data viewer        \\
  $\bullet$ & Run time      & (Optional)  & : Kst        & - analogue waveform data viewer        \\
  $\bullet$ & EDA           & (Optional)  & : gEDA-gaf   & - EDA tool suite                       \\
  $\bullet$ & EDA           & (Optional)  & : Lepton-EDA & - EDA tool suite                       \\
  $\bullet$ & Documentation & (Optional)  & : NG-SPICE   & - user manual                          \\
  $\bullet$ & Documentation & (Optional)  & : GNU-CAP    & - user manual                          \\

\end{tabular}

Notes :
\begin{itemize}

  \item On Linux systems the NG-SPICE user manual is installed in :
        \begin{verbatim}
   /usr/share/doc/ngspice/manual.pdf
        \end{verbatim}
        \vspace{-10pt}

  \item On Linux systems the GNU-CAP user manual is installed in :
        \begin{verbatim}
   /usr/share/doc/gnucap/gnucap-man.pdf
        \end{verbatim}
        \vspace{-10pt}

\end{itemize}

%***************************************************************************************************
% wxWidgets Library
%***************************************************************************************************
% Reviewed 2020-10-12

\subsection{wxWidgets Library}
\label{subsec:wxWidgets_Lib}

gSpiceUI is written in C++ and makes use of the wxWidgets library. The wxWidgets library provides
all the functionality required by gSpiceUI in one library, thereby reducing external dependencies to
one package. Is also possible to compile the same source code under Linux/UNIX, MS Windows, OSX and
various other platforms. This library must be installed before gSpiceUI can be compiled.

Many systems now come with a version of wxWidgets pre-installed or provide it as a pre-built package
which can be installed using the systems packaging system, this is the preferred option. There are
circumstances however where building and installing the wxWidgets library from it's sources may be
necessary. One such instance may be if the ABI (Application Binary Interface) of the pre-built
wxWidget library package differs from the ABI used by the compiler used to build gSpiceUI. The ABI
version using when building gSpiceUI can also be set within the gSpiceUI file src/Makefile.

The wxWidgets library home page is :

\hspace{15pt}
\url{http://www.wxWidgets.org/}

The recommended version of the wxWidgets library to use is the v3.0.x series. The archive file for a
Linux based system is :
\begin{verbatim}
   wxWidgets-3.0.x.tar.bz2
\end{verbatim}

Untar the wxWidgets archive and change to the wxWidgets root directory using the following commands :
\begin{verbatim}
   tar -jxvf wxWidgets-3.0.x.tar.bz2
   cd wxWidgets-3.0.5
\end{verbatim}

Installation of wxWidgets is based around autoconf and automake, so it should be straight forward.
If necessary refer to the installation instructions provided with the wxWidgets sources (in the docs
directory). Enter the following commands in the wxWidgets root directory :

\begin{verbatim}
   mkdir my-build
   cd my-build
   ../configure --without-subdirs --disable-compat28
   make
   su
   Password:         <-- enter the root password
   make install
\end{verbatim}

Notes :
\begin{itemize}
  
  \item To view all available options to the {\tt configure} script enter :
        \begin{verbatim}
   ../configure --help
        \end{verbatim}
        \vspace{-10pt}
        
  \item Some options to the {\tt configure} script of particular interest are :

        \begin{tabular}{ @{\hspace{15pt}} l @{\hspace{8pt}} l }
          -{\tt -prefix=<DIR>}        & (Installation directory, default /usr/local)             \\
          -{\tt -without-subdirs}     & (Don't generate makefiles for "{\tt samples/demos/...}") \\
          -{\tt -disable-compat28}    & (Disable wxWidgets 2.8 compatibility)                    \\
          -{\tt -enable-debug}        & (Build the library for debugging)                        \\
          -{\tt -enable-debug\_info}  & (Create code with debugging information)                 \\
          -{\tt -enable-debug\_gdb}   & (Create code with extra GDB debugging information)       \\
          -{\tt -disable-debug\_flag} & (Disable debugging support, unset
                                        {\tt \_\_WXDEBUG\_\_} flag)                              \\
          -{\tt -with-gtk[=VERSION]}  & (Use GTK+, {\tt VERSION} can be 3, 2 (default), 1 or
                                        "any")                                                   \\
        \end{tabular}
          
        At the time of writing there appears to be display problems when wxWidgets is compiled
        against GTK3, so building against GTK2 is recommended. Alternatively some distributions
        offer a compatibility layer, eg. for Fedora there is a package called "compat-wxGTK3-gtk2".

  \item The wxWidgets library can be uninstalled as follows :
        \begin{verbatim}
   sudo make uninstall
        \end{verbatim}
        \vspace{-10pt}

\end{itemize}

\pagebreak

%***************************************************************************************************
% Build System
%***************************************************************************************************
% Reviewed 2020-10-11

\subsection{Build System}
\label{subsec:Build_System}

After the wxWidgets library has been installed properly, go to the gSpiceUI root directory and enter
the following :

\begin{verbatim}
   make          (for Linux and Windows)
\end{verbatim}
\vspace{-5pt}
\hspace{25pt} or
\vspace{-6pt}
\begin{verbatim}
   gmake         (for FreeBSD)
\end{verbatim}
\vspace{-5pt}
\hspace{25pt} or
\vspace{-6pt}
\begin{verbatim}
   make maccfg   (for MAC OSX)
   make
\end{verbatim}

Note :
\begin{itemize}
  \item Apple MAC OSX users are required to execute the extra target (ie. {\tt make maccfg}) to
        create some directories and copies some files specific to their system, it is only required
        once per installation.
\end{itemize}

If all goes well the binary file "{\tt gspiceui}" should have been generated in the directory
{\tt <ROOT>/bin}.

%***************************************************************************************************
% Installation
%***************************************************************************************************
% Reviewed 2020-10-13

\subsection{Installation}
\label{subsec:Installation}

After building gSpiceUI, it may be installed into the default directory {\tt /usr/local/} by
entering the following command as root :

\begin{verbatim}
   make install
\end{verbatim}
\vspace{-5pt}
\hspace{25pt} or
\vspace{-6pt}
\begin{verbatim}
   gmake install (for FreeBSD)
\end{verbatim}

The application binary is intalled in {\tt /usr/local/bin/}. The documentation and other supporting
files are installed in {\tt /usr/local/share/gspiceui/}.

The application may be uninstalled by entering the following command as root :

\begin{verbatim}
   make uninstall
\end{verbatim}
\vspace{-5pt}
\hspace{25pt} or
\vspace{-6pt}
\begin{verbatim}
   gmake uninstall (for FreeBSD)
\end{verbatim}

An alternative install path may be specified by manually changing the make variable {\tt DESTDIR} in
the main Makefile or by specifying it on the command-line as the following example illustrates :

\begin{verbatim}
   make install DESTDIR=/alternative/install/directory
\end{verbatim}

The same applies for the uninstall operation :

\begin{verbatim}
   make uninstall DESTDIR=/alternative/install/directory
\end{verbatim}

\pagebreak

%***************************************************************************************************
% Microsoft Windows Support
%***************************************************************************************************
% Reviewed 2020-10-??

\subsection{Microsoft Windows Support}
\label{subsec:MSWin_Support}

This section provides a broad outline of how to build gSpiceUI on MS Windows. The methodology has
been developed and tested on Windows 7 and may work on other releases. Detailed instructions are
not provided since this information can change and so is best sourced from the Web sites providing
the required packages which are outline below :

\begin{itemize}
  \item \emph{MinGW} (Minimalist GNU for Windows) is a minimalist development environment for native
        Microsoft Windows applications.
  \item \emph{MSYS} (Minimal SYStem) is a Bourne Shell command line interpreter system. It's an
        alternative to Microsoft's {\tt cmd.exe} providing a general purpose command line
        environment particularly suited to use with MinGW.
  \item \emph{wxWidgets} is a C++ library that lets developers create applications for MS Windows,
        Apple Mac OSX, Linux and other platforms with a single code base.
\end{itemize}

An article written by Oliver Kohl \emph{Using wxWidgets under Windows} was very helpful in
formulating these instructions. The article can be found at :

\hspace{15pt}
\url{http://www.codeproject.com/Tips/630542/Using-wxWidgets-under-Windows}

Note : The MinGW environment can be accessed from Windows, outside of the MSYS shell. Paths
       containing forward slashes ('/') are from within MSYS and paths containing backslashes
       ('\textbackslash{}') are from Windows. Eg. the path to my home directory within MSYS is
       {\tt /home/msw}, whereas from MS Windows it's \verb+C:\MinGW\msys\1.0\home\msw+.

The steps to building gSpiceUI for Windows are as follows :

1. Install MinGW and MSYS :
  
    \begin{itemize}
      \item Go to \url{http://www.mingw.org/} and retrieve the MinGW installer : \\
              \verb+    mingw-get-setup.exe+
      \item Run the installer and select at least the following packages : C \& C++ compilers and
            MSYS. If MinGW is installed in the root of your system drive (ie.~\verb+C:\MinGW+)
            you'll have no problems with navigation and paths.
      \item The installer will retrieve the selected packages from the Web and install them.
      \item Ensure that the file \verb+C:\MinGW\msys\1.0\etc\fstab+ exists and contains at least the
            following line, followed by an empty line : \\
              \verb+    C:\MinGW   /mingw+
      \item Now navigate to the directory \verb+C:\mingw\msys\1.0+ and run msys.bat, this creates
            your home folder.
      \item It is worth creating a start menu item and/or a desktop icon for msys.bat.
    \end{itemize}

2. Install the wxWidgets sources :
  
    \begin{itemize}
      \item Go to the web site \url{http://www.wxwidgets.org/} and retrieve the wxWidgets sources
            eg.~{\tt wxWidgets-3.0.5.zip}.
      \item Create a folder (eg. \verb+C:\wxWidgets+) and unpack the wxWidgets sources archive into
            it.
    \end{itemize}

3. Build wxWidgets using MinGW :
  
    \begin{itemize}
      \item Open MSYS and go to the wxWidgets sources root directory eg. : \\
              \verb+    cd /c/wxWidgets/wxWidgets-3.0.5+
      \item Create the build folder and navigate into it eg. : \\
              \verb+    mkdir build-msw+ \\
              \verb+    cd build-msw+
      \item Run the wxWidgets configure script which creates the make files and sets system
            dependent variables : \\
              \verb+../configure --build=x86-winnt-mingw32 --disable-shared --disable-threads+ \\
             \vspace{-5pt} \\
            Notes :
            \vspace{-3pt}
            \begin{itemize}
              \item My AVG virus scanner breaks the configuration process when the TIFF library is
                    processed. There are two solutions : disable the TIFF library by adding the
                    option "{\tt --without-libtiff}" to the above command line or temporarily
                    disable the AVG Resident Shield component.
              \item The build process can be sped up if the wxWidgets samples and demos are skipped.
                    Add the option "{\tt --without-subdirs}" to the above command line.
            \end{itemize}
      \item Build wxWidgets : \\
              \verb+    make MONOLITHIC=1 SHARED=0 UNICODE=1 BUILD=release DEBUG_FLAG=0+
      \item Install the wxWidgets libraries : \\
              \verb+    make install+
    \end{itemize}

4. Build gSpiceUI using MinGW :
  
\begin{itemize}
  \item Retrieve the gSpiceUI sources and store them in eg. your MinGW home directory.
  \item Open MSYS and unpack the gSpiceUI sources eg. : \\
          \verb+    tar -zxvf gspiceui-v1.2.00.tar.gz+
  \item Enter to the wxWidgets sources root directory eg. : \\
          \verb+    cd ~/gspiceui-v1.2.00+
  \item Build the gSpiceUI sources (the same as for Linux) : \\
          \verb+    make GSPICEUI_MSWIN=1+
  \item If all goes well you can now run gSpiceUI under Windows : \\
          \verb+    bin/gspiceui.exe+
\end{itemize}

Note : There will be things that don't work in gSpiceUI under Windows eg. opening the online manual.
       The Windows setup seems to be a bit different from Linux but it's a start (for someone else
       to build on).

%***************************************************************************************************
% Apple Mac OSX Support
%***************************************************************************************************
% Reviewed 2020-10-13

\subsection{Apple Mac OSX Support}
\label{subsec:Mac_OSX_Support}

There is good and bad news for Mac users. The good news is that gSpiceUI can be installed and run
under OSX (based on user reports). The bad news is that I don't have any instructions on how to do
it, since I don't have access to an OSX system. I've added patches to the code base provided by Mac
user who are running gSpiceUI on OSX.  I've tried to run a OSX client under Qemu but without success
so far. If anyone wants to provide some instructions I'm happy to insert them here.

\pagebreak

%***************************************************************************************************
%                                           Command-Line
%***************************************************************************************************
% Reviewed 2020-08-12

\section{Command-Line}
\label{sec:Command_Line}

Generally, envoking gSpiceUI simple requires entering the binary name (eg. gspiceui) at the command
prompt. Various options and/or arguments may also be passed to gSpiceUI via the command-line.
Configuration settings are recorded in a configuration file so preference entered in previous
invocations are carried over to future sessions. Options entered via the command-line over-ride
configuration file settings. What follows if the output generated by entering the "-h" option :

\vspace{5pt}

\begin{Verbatim}[fontsize=\small]
  $ gspiceui -h
    
  Analyse a electronic circuit using a GUI front-end to numerical simulation
  engines

  USAGE   : gspiceui [-OPTION [ARG]] [FILE/S]

  OPTIONS : -h          : Print usage (this message) and quit
            -v          : Print version information and quit
            -c          : Rebuild/clean the configuration file and quit
            -d          : Enable debug mode (generate console spew on stderr)
            -r <RCFILE> : Specify a configuration file
                          <RCFILE> = ~/.gspiceui.conf (default)
            -s <SIMENG> : Specify the simulation engine to be used
                          <SIMENG> = ngspice or gnucap
            -e <EDA>    : Specify the EDA tool suite to be used
                          <EDA>    = lepton (Lepton-EDA) or geda (gEDA-gaf)
            -w <WAVWR>  : Specify the waveform data viewer to be used
                          <WAVWR>  = gaw, gwave or kst
            -g [<PROC>] : Import schematic file/s and (optionally) specify the
                          Guile procedure to use
                          <PROC>   = spice-sdb (default), protelii, verilog, etc.
            -a <PAGE>   : Specify the analysis page to be displayed
                         <PAGE>   = op (default), dc, ac, tr

  FILE/S  : Load a circuit description (netlist) file or import schematic file/s 
\end{Verbatim}

\vspace{5pt}

The available command-line options are explained in further detail below :

\begin{description}[leftmargin=30pt,itemindent=-10pt]
  \item [-h] Print the usage message (as shown above) to the console and quit.
  \item [-v] Print the application version information to the console and quit.
  \item [-c] Clear disused configuration items from the configuration file and quit. As gSpiceUI is
             developed the format of the configuration file (ie. ~/.gspiceui.conf) may change. Over
             time it can become cluttered with superseded variable and/or group names. Although it
             is not essential, rebuilding the configuration file occasionally is a good idea, eg.
             whenever gSpiceUI is updated to a newer version.
  \item [-d] Enable debug mode. As the application runs debug messages will be printed to the
             console. This is mainly used as development tool, it will generally not be of interest
             to the normal user.
  \item [-r] Specify a alternative configuration file other than the default.
  \item [-s] Specify the simulation engine to be used. This option can only work if the chosen
             simulation engine is installed on the system.
  \item [-e] Specify the EDA tool suite to be used. This option can only work if the chosen EDA tool
             suite is installed on the system.
  \item [-w] Specify the waveform data viewer application to be used. This option can only work if
             the chosen application is installed on the system.
  \item [-g] Import schematic file/s and optionally specify the Guile procedure to be used.
             Importing schematic file/s means converting them to a single netlist file. The netlist
             conversion utility uses a Guile procedure to do the actual conversion. Different
             schematic file formats (eg. Protel or gEDA) require different processes to generate the
             netlist file. (If no Guile procedure is specified a default is used.)
  \item [-a] Specify the analysis page to be displayed at startup.
\end{description}

There are two types of file which may be passed to gSpiceUI via the command-line (these file types
cannot be mixed) :

\vspace{5pt}

\begin{description}[leftmargin=85pt,itemindent=-10pt,labelwidth=55pt]
  \item [Netlist]   {\bf :} A single netlist file may be specified by placing it at the end of the
                    command-line.
  \item [Schematic] {\bf :} One or more \emph{related} schematic files may be specified at the end
                    of the command-line. In addition the {\bf -g} must be given to indicate that
                    files are schematic. The file/s are converted to a single netlist file as part
                    of gSpiceUI startup process.
\end{description}

Notes :

\begin{itemize}
  \item The default configuration file is called ".gspiceui.conf" and is stored in the user's home
        directory. The configuration file is intended to be human readable although under normal
        circumstances it shouldn't be necessary to do so.
  \item Schematic file/s cannot be imported with the KiCAD EDA tool suite since it has no
        command-line netlister utility. A netlist file must be manually generate from within the
        KiCAD schematic capture application eeschema and then loaded / reloaded into gSpiceUI.
\end{itemize}

\pagebreak

%***************************************************************************************************
%                                  Graphical User Interface (GUI)
%***************************************************************************************************
% Reviewed 2020-08-12

\section{Graphical User Interface (GUI)}
\label{sec:Graphical_User_Interface}

The main window is made up of various display objects which are described in detail in the following
sub-sections. The GUI design attempts to facilitate the electronic circuit analysis work flow. There
are two list boxes on the left containing possible test points, either electronic circuit nodes or
single port components. To the right are analysis panels which each define a type of analysis which
may be performed and allowing the user to enter parameters defining the analysis itself. The lower
section of the GUI contains the text input and output of the various stages of the simulation. From
the netlist created from the circuit schematic to the results generated by the simulation engine.

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 operates on.
  
%***************************************************************************************************
% File Menu
%***************************************************************************************************
% Reviewed 2020-08-14

\subsection{File Menu}
\label{subsec:File_Menu}

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

%***************************************************************************************************
% Reviewed 2020-08-14

\subsubsection[Open Netlist]{File \ding{221} Open Netlist}
\label{subsubsec:File_Open}
This option opens a file dialogue allowing the user to choose a netlist (circuit description) file
to open. The components and circuit nodes are loaded into the associated list controls and the
netlist file contents are also loaded into the NetList text control in the Console notebook. If the
netlist file contains simulation instructions gSpiceUI attempts to parse them and the settings are
displayed in the appropriate page of the Analysis notebook.

Notes :
\begin{itemize}
  \item Be aware, gSpiceUI is very likely to modify the netlist file. It will change file the
        formatting and remove things it doesn't understand. If this isn't OK, create a copy of the
        netlist file and open the copy with gSpiceUI.
  \item When using the gEDA tool set the netlist file extension is ".ckt". For the KiCAD tool suite
        the netlist extension is "cir". Be sure to specify the appropriate file extension for the
        EDA tool suite you are using.
  \item There is an upper limit to the number of lines which may be displayed in any text control
        (although the underlying file isn't truncated). This setting maybe adjusted by the user,
        refer to \emph{\ref{subsubsec:Preferences}\hyperref[subsubsec:Preferences]{ Preferences}}.
\end{itemize}

%***************************************************************************************************
% Reviewed 2020-08-14

\subsubsection[Import Schematic/s]{File \ding{221} Import Schematic/s}
\label{subsubsec:File_Import}

This option opens a file dialogue allowing the user to choose one or more \emph{related} schematic
files to import. A utility provided by the EDA tool suite (eg. for gEDA-gaf it's gnetlist) is used
to convert 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 the
schematic files \emph{schem1.sch}, \emph{schem2.sch}, \emph{schem3.sch} were specified to be
imported the netlist file name would be \emph{schem1.ckt}.
  
Notes :
\begin{itemize}
  \item If you are using the KiCAD tool suite the \emph{Import} option won't work. The netlister
        utility associated with KiCAD is built into the schematic capture application \emph{eeshema}
        so gSpiceUI can't envoke it. The netlist file must be created or updated from within
        \emph{eeshema} by the user and the netlist file must be updated in gSpiceUI using the
        \emph{Reload} operation.
\end{itemize}

%***************************************************************************************************
% Reviewed 2020-08-14

\subsubsection[Reload]{File \ding{221} Reload}
\label{subsubsec:File_Reload}

This option reloads the netlist file. If the netlist was imported from one or more schematic files,
the import operation is repeated and then the resulting netlist file is reloaded. 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 a netlist file is opened and has this
schematic reference, the reload operation performs an import operation first before reloading the
netlist file, 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.

Notes :
\begin{itemize}
  \item There is a preference which enables automatic re-generation of the netlist file from the
        schematic file/s if the modification timestamp of the netlist file is older than that of a
        schematic file/s. Refer to Section
        \emph{\ref{subsubsec:Preferences}\hyperref[subsubsec:Preferences]{ Preferences}}.
\end{itemize}

%***************************************************************************************************
% Reviewed 2020-08-14

\subsubsection[Close]{File \ding{221} Close}
\label{subsubsec:File_Close}

Close any/all open schematic and/or netlist file and resets all GUI parameters to default values.

%***************************************************************************************************
% Reviewed 2020-08-14

\subsubsection[Quit]{File \ding{221} Quit}
\label{subsubsec:Quit}

Close all files and child processes (eg. Gaw), delete temporary files if required and exit the
application.

%***************************************************************************************************
% Simulate Menu
%***************************************************************************************************
% Reviewed 2020-08-15

\subsection{Simulate Menu}
\label{subsubsec:Simulate_Menu}

The simulate menu contains options associated with circuit simulation operations and provides access
to schematic capture and waveform data viewing applications.

%***************************************************************************************************
% Reviewed 2020-08-15

\subsubsection[Create Simulation]{Simulate \ding{221} Create Simulation}
\label{subsubsec:Create_Sim}

The \emph{Create Simulation} operation tranforms the netlist file (displayed in the \emph{Netlist}
page of the Console notebook) into a simulation file (displayed in the \emph{Simulation} page of the
Console notebook). 

The \emph{Create Simulation} operation has some subtleties which are worth noting. The simplist way
to use it is to enter your preferences into the GUI, \emph{Create Simulation} then parses the
netlist file, creates the appropriate simulation engine commands and then generates the simulation
file. The simulation file can then be passed directly to the simulation engine to be executed.

Prior to running the simulation, there is a extra step possible that often proves useful. The
simulation file, once created, can be edited by the user, eg. to temporarily change a component
value. It is important to note however that the simulation file should only be edited \emph{after}
the \emph{Create Simulation} operation or the edits will be lost when the simulation file is
recreated.

If a problem is encountered during the \emph{Create Simulation} operation 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 is sent to the Console page of the Console notebook; a careful perusal of
this output generally helps to reveal the cause of the problem/s.
  
%***************************************************************************************************
% Reviewed 2020-08-15

\subsubsection[Run Simulation]{Simulate \ding{221} Run Simulation}
\label{subsubsec:Run_Sim}

The \emph{Run Simulation} operation creates a new simulation engine process and passes the
simulation file (displayed in the \emph{Simulation} page of the Console notebook) to the new process
for execution.

The \emph{Run Simulation} operation has some subtleties which are worth noting. If the analysis
parameters entering in the GUI have changed since the simulation file was last created a
\emph{Create Simulation} operation is initiated automatically before creating the simulation
process. Refer to the section
\emph{\ref{subsubsec:Create_Sim}\hyperref[subsubsec:Create_Sim]{ Create Simulation}}.

If the simulation runs successfully then the results are formatted and written to a data file (refer
to section \emph{\ref{sec:Temp_Files}\hyperref[sec:Temp_Files]{ Temporary Files}}) and are displayed
in the appropriate simulation results page of the Console notebook.

If a problem is encountered during the \emph{Run Simulation} operation 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 is sent to the Console page of the Console notebook; a careful perusal of
this output generally helps to reveal the cause of the problem/s.

%***************************************************************************************************
% Reviewed 2020-08-15

\subsubsection[Stop Simulation]{Simulate \ding{221} Stop Simulation}
\label{subsubsec:Stop_Sim}

The \emph{Stop Simulation} operation stops a running simulation immediately. This option only works
if a simulation is actually running. This is a useful option if a simulation is running too long or
appears not to be converging.

%***************************************************************************************************
% Reviewed 2020-08-17

\subsubsection[Schematic Capture]{Simulate \ding{221} Schematic Capture}
\label{subsubsec:Schematic}

The \emph{Schematic Capture} operation starts a schematic capture application where the schematic
can be viewed and/or edited. If there is a schematic file associated with an open netlist file it is
opened using the EDA tool suite schematic capture application (eg. gschem or lepton-schem). It is
very useful (almost essential) to view a schematic file whilst simulating a circuit. It provides a
context for the various components and circuit nodes. Values in the circuit can be adjusted as the
simulation process reveals new knowledge and understanding. Such changes are not, however,
automatically reflected in gSpiceUI.

Remember that the schematic capture program and gSpiceUI are separate applications. Communication
between the two happens via file/s on a storage device. When a schematic is changed, the associated
file has to be updated and gSpiceUI told to re-read the file and updates it's GUI. This is a very
simple but important process to keep in mind. Save your schematic to file and then reload it in
gSpiceUI. Refer to section
\emph{\ref{subsubsec:File_Reload}\hyperref[subsubsec:File_Reload]{ File Reload}}.

It's important to be aware that gSpiceUI cannot just run a simulation based on "any old" schematic
file. In fact, the simulation will probably fail unless the schematic is trivial or you're just
lucky. Certain prerequisites must be met before a schematic can be simulated. It must be possible
to translated it into a form which can be interpreted by the simulation engine, by the EDA tool
suite's netlist conversion utility (eg. gnetlist or lepton-netlist).

The extra information that must be explicitly defined in the schematic over that sufficient for
human readability is :

\begin{itemize}
  \item All power supply sources must be explicitly defined.
  \item All signal sources must be explicitly defined.
  \item Components not already defined in the simulation environment must be defined using models.
  \item 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'.
  \item 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.
\end{itemize}

Notes :
\begin{itemize}
  \item In gschem and lepton-schem, 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.
  \item 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) :
        \vspace{5pt}
        \begin{center}
          \begin{tabular}{l@{\hspace{6pt}}c@{\hspace{8pt}}l}
            
            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)       \\
            
          \end{tabular}
        \end{center}
  \item If the KiCAD EDA tool suite is used the \emph{View Schematic} function will not work. The
        KiCAD schematic capture application \emph{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.
\end{itemize}

%***************************************************************************************************
% Reviewed 2020-08-19

\subsubsection[View Results]{Simulate \ding{221} View Results}
\label{subsubsec:View_Results}

The \emph{View Results} operation starts a waveform data viewing application (ie. Gaw, Gwave or Kst)
where the simulation results can be viewed and analysed. In the majority of cases, the first
operation following a simulation run is to view the waveform data results. The run simulation tool
bar button is pressed followed immediately by the view simulation results button. In these instances
everything happens seemlessly, the results are generated and then viewed. However, gSpiceUI can
generate a number of different data files any of which you may wish to view. Refer to section
\emph{\ref{sec:Temp_Files}\hyperref[sec:Temp_Files]{ Temporary Files}}. You can load the desired
results file manually into the waveform data viewer or configure gSpiceUI so that the desired data
will be displayed when the waveform data viewer is started by gSpiceUI.

For this reason there is a mechanism for deciding which data file is opened by the waveform data
viewer. The choice is made according to the following criteria in descending priority :

\begin{enumerate}
  \item The currently selected page in the Analysis Notebook.        \\
        \vspace{-8pt} \\
        Eg. if the \emph{Quiescent} analysis page is selected in the Analysis Notebook then gSpiceUI
        will only attempt to display operating point data, if none has been generated an error
        message is displayed.
  \item The currently selected results page in the Console Notebook. \\
        \vspace{-8pt} \\
        Eg. if the \emph{AC} analysis page is selected in the Analysis Notebook and
        data for NG-SPICE has been generated but the GNU-CAP result page is selected in the Console
        Notebook an error message will be displayed re no GNU-CAP result existing.
  \item The currently selected Simulation Engine.                    \\
        \vspace{-8pt}                                                \\
        Eg. if the \emph{Transient} analysis page is selected in the Analysis Notebook and data has
        been generated by both simulation engines and the Netlist page in the Console Notebook is
        selected then the data for the currently select simulation engine will be displayed. 
\end{enumerate}

%***************************************************************************************************
% Reviewed 2020-10-03

\subsubsection[Calculator]{Simulate \ding{221} Calculator}
\label{subsubsec:Calculator}

The \emph{Calculator} operation starts a calculator application (eg. Xcalc). This calculator
application is not part of gSpiceUI but is one of many freely available applications which can be
downloaded and installed from the Web. A calculator is frequently a useful tool when simulating
electronic circuits. The particular application to be launched can be configured in 
\emph{\ref{subsubsec:Preferences}\hyperref[subsubsec:Preferences]{ Preferences}}.

%***************************************************************************************************
% Settings Menu
%***************************************************************************************************
% Reviewed 2020-08-19

\subsection{Settings Menu}
\label{subsec:Settings_Menu}

The settings menu contains application configuration options. This menu begins with three blocks of
radio buttons which allow easy access to options that are used frequently. Less often accessed
options are contained in a preferences dialogue.

%***************************************************************************************************
% Reviewed 2020-08-20

\subsubsection[Select Simulation Engine]{Settings \ding{221} Simulation Engine Selection}
\label{subsubsec:Sel_Sim_Engine}

The first pair of radio buttons allow the selection of the electronic circuit simulation engine to
be used (assuming it has been installed). The analysis notebook is updated based on the chosen
simulation engine, the selected simulation engine name is displayed in the second status bar pane
and, when simulation results are generated, they 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
entered on the GUI is 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.
  
%***************************************************************************************************
% Reviewed 2020-08-20

\subsubsection[Select EDA Tool Suite]{Settings \ding{221} EDA Tool Suite Selection}
\label{subsubsec:Sel_EDA_Tool_Suite}

The second pair of radio buttons allow the selection of the EDA (Electronic Design Automation) tool
suite to be used (assuming it has been installed). This specifies the schematic capture / edit
application and the netlister utility to be used. The currently selected EDA tool suite name is
displayed in second last pane of the status bar.

%***************************************************************************************************
% Reviewed 2020-08-20

\subsubsection[Select Waveform Data Viewer]{Settings \ding{221} Waveform Data Viewer Selection}
\label{subsubsec:Sel_Waveform_Vwr}

The third block of radio buttons allow the selection of the waveform data viewer application to be
used (assuming it has been installed). The currently selected waveform data viewer application name
is displayed in last pane of the status bar.

%***************************************************************************************************
% Reviewed 2020-08-20

\subsubsection[Preferences]{Settings \ding{221} Preferences}
\label{subsubsec:Preferences}

The preferences dialog allows the user to configure gSpiceUI and contains the following settings :

\begin{itemize}
  
  \item Simulation engine :        \\
        \vspace{-8pt}              \\
        A choice box containing the available simulation engines (assuming they have been
        installed). The currently selected simulation engine name is displayed in second pane of the
        status bar.
        
  \item EDA tool suite :           \\
        \vspace{-8pt}              \\
        A choice box containing the available EDA (Electronic Design Automation) tool suites
        (assuming they have been installed). The currently selected EDA tool suite name is displayed
        in second last pane of the status bar.
        
  \item Waveform data viewer :     \\
        \vspace{-8pt}              \\
        A choice box containing the available waveform data viewer applications (only applications
        which are currently installed will be listed). The currently selected waveform data viewer
        application name is displayed in last pane of the status bar.
        
  \item Calculator :               \\
        \vspace{-8pt}              \\
        A choice box containing the available calculator applications currently installed on your
        system.
        
  \item PDF viewer :               \\
        \vspace{-8pt}              \\
        A choice box containing the available PDF viewer applications currently installed on your
        system. The PDF viewer is used to display PDF documentation, eg. this gSpiceUI User Manual.
        
  \item Temporary files :          \\
        \vspace{-8pt}              \\
        A choice box containing the available temporary file management strategies, ie.
        automatically delete temporary files, prompt the user for permission or keep all temporary
        files. Most of the files in question contain simulation results data and may be useful
        outside gSpiceUI. Refer to section
        \emph{\ref{sec:Temp_Files}\hyperref[sec:Temp_Files]{ Temporary Files}} for more details.
        
  \item Main frame layout :        \\
        \vspace{-8pt}              \\
        A choice box containing the available main frame layout schemes. There are two schemes to
        choose from : longer probes (Nodes and Component list) controls or a wider console notebook
        control.
        
  \item Phase / angle units :      \\
        \vspace{-8pt}              \\
        A choice box containing the available phase / angle units, ie. degrees or radians.
        
  \item Results precision :        \\
        \vspace{-8pt}              \\
        A choice box allowing the precision of the simulation results to be specified. The data are
        rounded to the chosen precision, not truncated.
        
  \item Netlister Guile backend :  \\
        \vspace{-8pt}              \\
        A choice box containing the available netlist conversion utility Guile backend procedures.
        This list of Guile backends is derived by querying the netlister utility directly so
        whatever procedures are listed are available.
        
  \item Max. text control size :   \\
        \vspace{-8pt}              \\
        A value control which sets the maximum number of lines which may be displayed in any of the
        Console Notebook pages (text controls). Simulation results files can, potentially, be very
        big; this value places an upper limit on how many lines are loaded into any text control.
        The files themselves are not changed in any way, ie. truncated.

  \item Spin control period :      \\
        \vspace{-8pt}              \\
        A value control which sets the period (in msec) between successive spin button updates.
        
  \item Tool tip delay :           \\
        \vspace{-8pt}              \\
        A value control which sets the delay (in msec) before a tool tip is displayed.
        
  \item Show tool tips :           \\
        \vspace{-8pt}              \\
        A check box which enables or disables tool tips.
        
  \item Auto. config. file clean : \\
        \vspace{-8pt}              \\
        A check box which enables or disables automatic configuration file clean / rebuild. As
        gSpiceUI is developed the configuration file format may change (ie. ~/.gspiceui.conf). Over
        time it can become cluttered with superseded variable and/or group names. Although it is
        not essential, rebuilding the configuration file occasionally is a good idea, if nothing
        else it helps with human readability. If this option is enabled and the application is
        updated to a newer version, on first startup the configuration file is automatically
        rebuilt.

  \item Sync. sweep sources :      \\
        \vspace{-8pt}              \\
        A check box which enables or disables synchronization of the sweep sources. If a sweep
        source name is selected in one analysis page of the Analysis Notebook, where possible the
        same source name will appear in other analysis pages. Note : the sweep source \emph{value}
        is not carried over between pages.
        
  \item Sync. temperatures :       \\
        \vspace{-8pt}              \\
        A check box which enables or disables synchronization of the ambient temperature values
        between analysis pages of the Analysis Notebook and the OPTIONS dialogue.
        
  \item Keep the netlist file :    \\
        \vspace{-8pt}              \\
        A check box which controls whether netlist files are included in the list of temporary files
        and therefore the temporary file management strategy.
        
  \item Netlister verbose mode :   \\
        \vspace{-8pt}              \\
        A check box which enables or disables the netlist conversion utility (eg. gnetlist) verbose
        mode. With this enabled the netlister generates lots of console spew which appears in the
        Console tab of the Console Notebook. It's useful for debugging when the netlister is having
        problems importing schematic file/s.
        
  \item Include model defs. :      \\
        \vspace{-8pt}              \\
        A check box which controls whether .INCLUDE directives are used for model files or the model
        file contents are inserted in the netlist file by the netlister (eg. gnetlist). (This option
        controls the the SPICE Guile backend option "include\_mode".)
        
  \item Embed include files :      \\
        \vspace{-8pt}              \\
        A check box which controls how the netlister (eg. gnetlist) behaves when it encounters a
        .INCLUDE directive. With this option checked the netlister embeds (inserts) the file model
        contents into the netlist file. (This option controls the netlister SPICE backend option
        "embedd\_mode".)
        
  \item Fix component prefixes :   \\
        \vspace{-8pt}              \\
        A check box which controls whether component label prefixes are automatically tested and
        modified if the incorrect prefix is used. SPICE simulation engines recognizes different
        components based on the first character of the component label (eg. R1 would be identified
        as a resistor). When this option is checked, if an incorrect prefix is detected the correct
        prefix is prepended to the component label. (This option controls the netlister (eg.
        gnetlist) SPICE backend option "nomunge\_mode".)
        
  \item Auto. regenerate netlist : \\
        \vspace{-8pt}              \\
        A check box to control whether the netlist is automatically regenerationed from the
        associated schematic file/s. If this option is checked, before each simulation run the
        schematic file modification timestamp/s are compared to that of the netlist file. If a
        schematic file is newer than the netlist a reload operation is automatically executed (ie.
        the netlist file is regenerated from the schematic file/s).
        
\end{itemize}

%***************************************************************************************************
% Help Menu
%***************************************************************************************************
% Reviewed 2020-08-18

\subsection{Help Menu}
\label{subsec:Help_Menu}

The Help Menu contains the options to display various user manuals (assuming they are installed
properly) as well as gSpiceUI "About" information. These options are described in the following
sections.

%***************************************************************************************************
% Reviewed 2020-08-17

\subsubsection[gSpiceUI Manual]{Help \ding{221} gSpiceUI Manual}
\label{subsubsec:gSpiceUI_Man}

Open the gSpiceUI HTML documentation (ie. this document) in a HTML viewer window. The HTML viewer
is part of the wxWidgets library and only provides basic browser functionality however it is quite
adequate for the purpose. This document can, of course, also be opened in any web browser outside of
gSpiceUI. This options is included for convience.

%***************************************************************************************************
% Reviewed 2020-08-17

\subsubsection[NG-SPICE Manual]{Help \ding{221} NG-SPICE Manual}
\label{subsubsec:NG-SPICE_Man}

Open a PDF viewer application to read the NG-SPICE user manual. The NG-SPICE user manual must be
installed on the system. Refer to the gSpiceUI install instructions for the location gSpiceUI
expects to find the PDF file.

%***************************************************************************************************
% Reviewed 2020-08-17

\subsubsection[GNU-CAP Manual]{Help \ding{221} GNU-CAP Manual}
\label{subsubsec:GNU-CAP_Man}

Open a PDF viewer application to read the GNU-CAP user manual. The GNU-CAP user manual must be
installed on the system. Refer to the gSpiceUI install instructions for the location gSpiceUI
expects to find the PDF file.

%***************************************************************************************************
% Reviewed 2020-08-17

\subsubsection[About]{Help \ding{221} About}
\label{subsubsec:About}

Open a dialogue containing application "About" information, including gSpiceUI version details, the
version of wxWidgets library gSpiceUI is built against, supported external applications and
warranty / copyright information.

%***************************************************************************************************
% Tool Bar
%***************************************************************************************************
% Reviewed 2020-08-17

\subsection{Tool Bar}
\label{subsec: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. The following table shows the
button icon with a brief explanation of it purpose and a link to the section dealing with it's
function in detail :

\vspace{10pt}

\begin{tabular}[c]{ @{\hspace{15pt}} c @{\hspace{10pt}} c l l }
  
  \parbox[c]{20pt}{\includegraphics[scale=0.80]{file-open.png}  } &
  \ding{221} &
  Open a netlist file &
  (refer to section \emph{\ref{subsubsec:File_Open}\hyperref[subsubsec:File_Open]{ File Open}})
  \vspace{5pt} \\
  
  \parbox[c]{20pt}{\includegraphics[scale=0.80]{file-import.png}} &
  \ding{221} &
  Import schematic file/s &
  (refer to section \emph{\ref{subsubsec:File_Import}\hyperref[subsubsec:File_Import]{ File Import}})
  \vspace{5pt} \\
  
  \parbox[c]{20pt}{\includegraphics[scale=0.87]{file-reload.png}} &
  \ding{221} &
  Reload netlist/schematic file/s &
  (refer to section \emph{\ref{subsubsec:File_Reload}\hyperref[subsubsec:File_Reload]{ File Reload}})
  \vspace{5pt} \\
  
  \parbox[c]{20pt}{\includegraphics[scale=0.87]{file-close.png} } &
  \ding{221} &
  Close netlist/schematic file/s &
  (refer to section \emph{\ref{subsubsec:File_Close}\hyperref[subsubsec:File_Close]{ File Close}})
  \vspace{5pt} \\
  
  \parbox[c]{20pt}{\includegraphics[scale=0.87]{sim-create.png} } &
  \ding{221} &
  Create simulation file &
  (refer to section \emph{\ref{subsubsec:Create_Sim}\hyperref[subsubsec:Create_Sim]{ Create Simulation}})
  \vspace{5pt} \\
  
  \parbox[c]{20pt}{\includegraphics[scale=0.87]{sim-run.png}    } &
  \ding{221} &
  Run simulation &
  (refer to section \emph{\ref{subsubsec:Run_Sim}\hyperref[subsubsec:Run_Sim]{ Run Simulation}})
  \vspace{5pt} \\
  
  \parbox[c]{20pt}{\includegraphics[scale=0.80]{sim-stop.png}   } &
  \ding{221} &
  Stop simulation &
  (refer to section \emph{\ref{subsubsec:Stop_Sim}\hyperref[subsubsec:Stop_Sim]{ Stop Simulation}})
  \vspace{5pt} \\

  \parbox[c]{20pt}{\includegraphics[scale=0.80]{sim-edit.png}   } &
  \ding{221} &
  Schematic capture &
  (refer to section \emph{\ref{subsubsec:Schematic}\hyperref[subsubsec:Schematic]{ Schematic Capture}})
  \vspace{5pt} \\
 
  \parbox[c]{20pt}{\includegraphics[scale=0.87]{sim-plot.png}   } &
  \ding{221} &
  View simulation results &
  (refer to section \emph{\ref{subsubsec:View_Results}\hyperref[subsubsec:View_Results]{ View Results}})
  \vspace{5pt} \\
  
  \parbox[c]{20pt}{\includegraphics[scale=0.60]{calculator.png} } &
  \ding{221} &
  Calculator &
  (refer to section \emph{\ref{subsubsec:Calculator}\hyperref[subsubsec:Calculator]{ Calculator}})
  \vspace{5pt} \\
  
  \parbox[c]{20pt}{\includegraphics[scale=0.80]{preferences.png}} &
  \ding{221} &
  Preferences &
  (refer to section \emph{\ref{subsubsec:Preferences}\hyperref[subsubsec:Preferences]{ Preferences}})
  \vspace{5pt} \\
  
  \parbox[c]{20pt}{\includegraphics[scale=0.60]{help.png}       } &
  \ding{221} &
  View gSpiceUI user manual &
  (refer to section \emph{\ref{subsubsec:gSpiceUI_Man}\hyperref[subsubsec:gSpiceUI_Man]{ gSpiceUI Manual}})
  \vspace{5pt} \\
  
\end{tabular}

%***************************************************************************************************
% Node List
%***************************************************************************************************
% Reviewed 2020-08-20

\subsection{Node List}
\label{subsec:Node_List}

The \emph{Node List} contains node labels extracted from the netlist file. These labels can be used
as probes into the circuit being simulated. A probe is a point where electrical parameters (eg.
voltage) are calculated by the simulation engine. One or more nodes may be selected (or deselected)
by clicking on them 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.
  
%***************************************************************************************************
% Component List
%***************************************************************************************************
% Reviewed 2020-08-20

\subsection{Component List}
\label{subsec:Component_List}

The \emph{Component List} contains component labels extracted from the netlist file. These labels
can be used as probes into the circuit being simulated. A probe is a point where electrical
parameters (eg. voltage) are calculated by the simulation engine. One or more components may be
selected (or deselected) by clicking on them 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.
  
%***************************************************************************************************
% Analysis Notebook
%***************************************************************************************************
% Reviewed 2020-08-21

\subsection{Analysis Notebook}
\label{subsec:Analysis_Notebook}

The \emph{Analysis Notebook} contains analyis pages, each page reflects the a different analysis
type supported by the associated simulation engine. There are two slightly different analysis
notebooks associated with the two different simulation engines supported by gSpiceUI ie. GNU-CAP or
NG-SPICE. The following sections \emph{briefly} outline the analysis types supported by gSpiceUI.
For more information refer to the user documentation for the appropriate simulation engine (much of
what follows is taken from this documentation). Refer to section
\emph{\ref{subsec:Help_Menu}\hyperref[subsec:Help_Menu]{ Help Menu}}.

%***************************************************************************************************
% Reviewed ???

\subsubsection{Operating Point Analysis}
\label{subsubsec:OP_Analysis}

\vspace{5pt}

\begin{description}
  
  \item [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.
  
  \item [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.
        
\end{description}

%***************************************************************************************************
% Reviewed ???

\subsubsection{DC Analysis}
\label{subsubsec:DC_Analysis}

\vspace{5pt}

\begin{description}
  
  \item [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.
  
  \item [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.
  
\end{description}

%***************************************************************************************************
% Reviewed ???

\subsubsection{AC Analysis}
\label{subsubsec:AC_Analysis}

\vspace{5pt}

\begin{description}
  
  \item [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.
  
  \item [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.
  
\end{description}

%***************************************************************************************************
% Reviewed ???

\subsubsection{Transient Analysis}
\label{subsubsec:TR_Analysis}

\vspace{5pt}

\begin{description}
  
  \item [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.
  
  \item [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.
  
\end{description}

%***************************************************************************************************
% Reviewed ???

%\subsubsection{Fourier Analysis}
%\label{subsubsec:FO_Analysis}

%\vspace{5pt}

%\begin{description}
  
%  \item [NG-SPICE :]
  
%        Not yet implemented.
 
%  \item [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.
  
%\end{description}

%***************************************************************************************************
% Console Notebook
%***************************************************************************************************
% Reviewed 2020-08-20

\subsection{Console Notebook}
\label{subsec:Console_Notebook}

As a normal part of gSpiceUI operations, alot of text output is generated (eg. by command-line
utilities like gnetlist) and collected by gSpiceUI. This text may be in the form of file contents or
output sent to standard out. (Like many UNIX applications gSpiceUI mostly communicates with the
outside world via files.) It collects the console output of the processes it runs for debugging
purposes but mostly gSpiceUI depends on files. These files are human readable and can be of use to
the user. The Console Notebook is the repository for this text output. It is divided into various
pages (described below) according to category of the text output.

%***************************************************************************************************
% Reviewed 2020-08-20

\subsubsection{Console}
\label{subsubsec:Console}

Display the console input/output for the last process executed by gSpiceUI. This includes the
command-line used by gSpiceUI followed by all text output sent to stdout and stderr. If an error
occurs this is a good place to look for indications of what has gone wrong.

%***************************************************************************************************
% Reviewed 2020-08-20

\subsubsection{Netlist}
\label{subsubsec:Netlist}

Display the raw contents of a netlist file. The variables and values contained in the netlist file
are displayed in the GUI objects. In particular the Node and Component Lists are derived from the
netlist file.

%***************************************************************************************************
% Reviewed 2020-08-20

\subsubsection{Simulation}
\label{subsubsec:Simulation}

Display the contents of the simulation file. This is the file sented to the simulation engine when a
run operation is intiated. It is the netlist file (as displayed in the Netlist tab of the Console
Notebook) plus simulator commands generated by gSpiceUI based on user input. The simulation file can
be manually edited by the user before executing a simulation. NOTE : if  \emph{Create Simulation}
operation is initiated, the contents of this tab will be over-written, destroying any user input.

%***************************************************************************************************
% Reviewed 2020-08-20

\subsubsection{NG-SPICE Results}
\label{subsubsec:NG-SPICE_Results}

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

%***************************************************************************************************
% Reviewed 2020-08-20

\subsubsection{GNU-CAP Results}
\label{subsubsec:GNU-CAP_Results}

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

%***************************************************************************************************
% Status Bar
%***************************************************************************************************
% Reviewed 2020-08-19

\subsection{Status Bar}
\label{subsec:Status_Bar}

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

\begin{enumerate}
  \item The last application status or error message (abbreviated to fit if necessary).
  \item The currently selected simulation engine.
  \item The currently selected EDA tool suite.
  \item The currently selected waveform viewer application.
\end{enumerate}

\pagebreak

%***************************************************************************************************
%                                          Temporary Files
%***************************************************************************************************
% Reviewed 2020-08-19

\section{Temporary Files}
\label{sec:Temp_Files}

As part of normal operations gSpiceUI can generate various temporary files in the directory occupied
by the schematic and netlist files. To illustrate, consider the situation where the schematic file
"test-circuit.sch" is imported and every possible analysis type is run, using both NG-SPICE and
GNU-CAP. Along with the schematic file (also listed below) the following temporary files which would
be created :

\vspace{5pt}

\begin{center}
  \begin{tabular}{l@{\hspace{20pt}}l}
    <path>/sch/test-circuit.sch         &  (The schematic file to be analysed)           \\
                                        &                                                \\
    <path>/sch/test-circuit.ckt         &  (Netlist file with simulation commands)       \\
    <path>/sch/test-circuit.sch$\sim$   &  (Backup file to the schematic file)           \\
    <path>/sch/gspiceui.log             &  (Temporary file for raw process output)       \\
                                        &                                                \\  
    <path>/sch/test-circuit.ngspice.op  &  (Results file - operating point analysis)     \\
    <path>/sch/test-circuit.ngspice.dc  &  (Results file - DC analysis)                  \\
    <path>/sch/test-circuit.ngspice.ac  &  (Results file - AC analysis)                  \\
    <path>/sch/test-circuit.ngspice.tr  &  (Results file - transient response analysis)  \\
%   <path>/sch/test-circuit.ngspice.di  &  (Results file - distortion analysis)          \\
%   <path>/sch/test-circuit.ngspice.no  &  (Results file - noise analysis)               \\
%   <path>/sch/test-circuit.ngspice.pz  &  (Results file - pole-zero analysis)           \\
%   <path>/sch/test-circuit.ngspice.se  &  (Results file - sensitivity analysis)         \\
%   <path>/sch/test-circuit.ngspice.tf  &  (Results file - transfer function analysis)   \\
                                        &                                                \\
    <path>/sch/test-circuit.gnucap.op   &   (Results file - operating point analysis)    \\
    <path>/sch/test-circuit.gnucap.dc   &   (Results file - DC analysis)                 \\
    <path>/sch/test-circuit.gnucap.ac   &   (Results file - AC analysis)                 \\
    <path>/sch/test-circuit.gnucap.tr   &   (Results file - transient response analysis) \\
%   <path>/sch/test-circuit.gnucap.fo   &   (Results file - fourier analysis)            \\
  \end{tabular}
\end{center}

\vspace{12pt}

All file names begin with the schematic file name less the file extension, in this example
"test-circuit". File name extensions are then generated depending on the file type. In particular,
files containing simulation results have two extension, the first based on the the simulation engine
used to generate the data, the second is an abbreviation indicating the analysis type.

These temporary files can quickly proliferate and clutter your file system. As a consequence
gSpiceUI offers several ways to manager these temporary files. The simplest methods is to allow
gSpiceUI to delete them when they no longer required. If a schematic file is closed or gSpiceUI is
exited then any temporary files are deleted. The second option is for gSpiceUI to prompt the user
prior to deleting temporary files asking for permission. The last option is to just do nothing and
not delete anything. There are occasions where you may wish to retain results data to be view later
perhaps.

Notes :
\begin{itemize}
  \item For details on how to set the temporary file for management scheme refer to section
        \emph{\ref{subsubsec:Preferences}\hyperref[subsubsec:Preferences]{ Preferences}}.
  \item If temporary files are deleted this also includes the schematic backup file.
\end{itemize}

\pagebreak

%***************************************************************************************************
%                                     Demonstration Schematics
%***************************************************************************************************
% Reviewed 2020-08-21

\section{Demonstration Schematics}
\label{sec:Demo_Schems}

This section is intended to serve the dual purpose of providing user documentation for the
demonstration schematics that come with gSpiceUI, and to help me (the developer) keep track of them
(ie. try to make ensure that they work). The directory <install-dir>/sch/demos/ contains the
demostration schematic files. They are intended to illustrate the simulation of specific circuit
elements eg. a diode.

In addition, the directory <install-dir>/sch also contains various schematic files which may be used
to experiment with gSpiceUI. These examples show how to prepare a schematic for simulation, which is
not always a trivial task. These files are a collection of things that have taken my interest over
the years, some work and some don't. It's worth noting that although these schematics are definitely
circuit designs, they may not be good designs, so use them in the real world at your own risk.

The directory <install-dir>/lib/symbols/ contains various circuit element symbol that I've developed
over the years. They may also be of use.

Below is a list of the available demonstration schematics and a brief description of what each is
intended to accomplish :

\begin{description}[leftmargin=30pt,itemindent=110pt,labelwidth=120pt]

  \item [\emph{amp-bjt-ce-1.sch}]      : BJT Common Emitter Amplifier
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a NPN BJT in it's linear mode using AC analysis.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)     & \ding{219} (2020-08-22) & OK    \\
          GNU-CAP  (v20171003) & \ding{219} (2020-08-22) & Fault \\
        \end{tabular}
        
  \item [\emph{amp-bjt-ce-2.sch}]      : BJT Common Emitter Amplifier
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a NPN BJT in it's linear mode using AC analysis
        (an alternative implementation of the previous example).
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)     & \ding{219} (2020-08-22) & OK    \\
          GNU-CAP  (v20171003) & \ding{219} (2020-08-22) & Fault \\
        \end{tabular}
        
  \item [\emph{amp-bjt-diff.sch}]      : Audio Amplifier Differential Input Stage
        \vspace{5pt} \\
        Demo. circuit showing a common audio amplifier input stage topology using NPN BJTs.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)     & \ding{219} (2020-08-23) & OK    \\
          GNU-CAP  (v20171003) & \ding{219} (2020-08-23) & Fault \\
        \end{tabular}
        
  \item [\emph{amp-jfet-cs-1.sch}]     : N-Channel JFET Common Source Amplifier
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a N-Channel JFET using either DC or AC analysis.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)     & \ding{219} (2020-08-23) & OK    \\
          GNU-CAP  (v20171003) & \ding{219} (2020-08-23) & Fault \\
        \end{tabular}

  \item [\emph{amp-mosfet-cs-1.sch}]   : N-Channel MOSFET Common Source Amplifier
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a N-Channel MOSFET using either DC or AC analysis.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)     & \ding{219} (2020-09-06) & OK    \\
          GNU-CAP  (v20171003) & \ding{219} (2020-09-06) & Fault \\
        \end{tabular}

  \item [\emph{astable-bjt-npn.sch}]   : NPN BJT Astable Multivibrator
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a NPN BJT when operated as a switch using Transient
        analysis.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)     & \ding{219} (2020-08-22) & OK \\
          GNU-CAP  (v20171003) & \ding{219} (2020-08-22) & OK \\
        \end{tabular}
        
  \item [\emph{astable-bjt-pnp.sch}]   : PNP BJT Astable Multivibrator
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a PNP BJT when operated as a switch using Transient
        analysis.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)     & \ding{219} (2020-08-22) & OK    \\
          GNU-CAP  (v20171003) & \ding{219} (2020-08-22) & Fault \\
        \end{tabular}
        
  \item [\emph{diode-led-1.sch}]       : Light Emitting Diode
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a LED using DC analysis.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)        & \ding{219} (2020-09-08) & OK \\
          GNU-CAP  (v20200806dev) & \ding{219} (2020-09-08) & OK \\
        \end{tabular}

  \item [\emph{diode-signal-1.sch}]    : Signal Diode
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a signal diode using DC analysis.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)        & \ding{219} (2020-09-08) & OK \\
          GNU-CAP  (v20200806dev) & \ding{219} (2020-09-08) & OK \\
        \end{tabular}

  \item [\emph{diode-zener-1.sch}]     : Zener Diode
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a zener diode using DC analysis.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)        & \ding{219} (2020-09-08) & OK    \\
          GNU-CAP  (v20200806dev) & \ding{219} (2020-09-18) & Fault \\
        \end{tabular}

  \item [\emph{filter-bp-1.sch}]       : Series Resonant Band Pass Filter
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a simple series resonant band pass filter using AC
        analysis.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)        & \ding{219} (2020-09-20) & OK \\
          GNU-CAP  (v20200806dev) & \ding{219} (2020-09-20) & OK \\
        \end{tabular}

  \item [\emph{filter-bp-2.sch}]       : T-Section Resonant Band Pass Filter
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a T-section resonant band pass filter using AC
        analsis.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)        & \ding{219} (2020-09-20) & OK \\
          GNU-CAP  (v20200806dev) & \ding{219} (2020-09-20) & OK \\
        \end{tabular}

  \item [\emph{filter-lp-1.sch}]       : Single Pole Low Pass Filter
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a simple single pole low pass filter using AC analsis.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)        & \ding{219} (2020-09-20) & OK \\
          GNU-CAP  (v20200806dev) & \ding{219} (2020-09-20) & OK \\
        \end{tabular}

  \item [\emph{lm555-timer.sch}]       : LM555 Timer
        \vspace{5pt} \\
        Demo. circuit showing how to simulate using a model based on a sub-circuit.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)        & \ding{219} (2020-09-23) & OK \\
          GNU-CAP  (v20200806dev) & \ding{219} (2020-09-23) & OK \\
        \end{tabular}
        
  \item [\emph{lvl-shftr-bjt.sch}]     : ???
  \item [\emph{lvl-shftr-opamp.sch}]   : ???

  \item [\emph{subckt-1.sch}]          : MOSFET Switch Circuit
        \vspace{5pt} \\
        Demo. circuit showing how to simulate using a model based on a sub-circuit.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)        & \ding{219} (2020-09-23) & OK    \\
          GNU-CAP  (v20200806dev) & \ding{219} (2020-09-23) & Fault \\
        \end{tabular}

  \item [\emph{tline-1.sch}]           : Loss-Less Transmission Line
        \vspace{5pt} \\
        Demo. circuit showing how to simulate a loss-less transmission line.
        \vspace{7pt} \\
        \begin{tabular}{@{\hspace{0pt}} l @{\hspace{5pt}} l @{\hspace{5pt}} l}
          NG-SPICE (v32.1)        & \ding{219} (2020-09-20) & Fault \\
          GNU-CAP  (v20200806dev) & \ding{219} (2020-09-20) & OK    \\
        \end{tabular}
    
\end{description}

\pagebreak

%***************************************************************************************************
%                                              Design
%***************************************************************************************************
% Reviewed 2020-10-08

\section{Design}
\label{sec:Design}

This section provides information related to the design of gSpiceUI. In reality, this application
was designed in my head as it went along. A fair amount of it has been re-written as I found better
ways of doing things. The design methodology would be best described as prototyping.

The following object models where developed to help provide a better picture of how things went
together (as the project got to the point where I couldn't remember how it all worked). The object
models also depict how wxWidgets binds into gSpiceUI.

\emph{\hyperref[fig:om-gspiceui]{Figure \ref{fig:om-gspiceui} : gSpiceUI Application Object Model}}
depicts the top level application architecture. The class App\_gSpiceUI inherits from the wxWidgets
library wxApp class which is the entry point to the application (ie. it contains main( )).

\begin{figure}[ht]
  \centering
%  Include PDF image file (according to Latex docs PDF is preferred over PNG for better resolution)
  \includegraphics[scale=1.25, angle=90]{OM-gSpiceUI.pdf}
  \caption{Overall gSpiceUI application object model.}
  \label{fig:om-gspiceui}
\end{figure}

\emph{\hyperref[fig:om-frmmain]{Figure \ref{fig:om-frmmain} : Main Frame Class Object Model}}
depicts the top level of the GUI architecture. The FrmMain class inherits from the wxWidgets library
wxFrame class which contains all display objects within this class hierarchy.

\begin{figure}[ht]
  \centering
%  Include PDF image file (according to Latex docs PDF is preferred over PNG for better resolution)
  \includegraphics[width=\textwidth]{OM-FrmMain.pdf}
  \caption{Main application frame object model.}
  \label{fig:om-frmmain}
\end{figure}

\emph{\hyperref[fig:om-analysis]{Figure \ref{fig:om-analysis} : Analysis Class Object Model}}
depicts the class structure of the objects which fill the analysis notebook (the notebook with the
analysis tabs). It inherits from the wxWidgets library wxNotebook class.

\begin{figure}[ht]
  \centering
%  Include PDF image file (according to Latex docs PDF is preferred over PNG for better resolution)
  \includegraphics[width=\textwidth]{OM-Analysis.pdf}
  \caption{Analysis notebook object model.}
  \label{fig:om-analysis}
\end{figure}

\emph{\hyperref[fig:om-process]{Figure \ref{fig:om-process} : Process Class Object Model}} depicts
the class structure of the objects which maybe executed as tasks by the application. It inherits
from the wxWidgets library wxProcess class.

\begin{figure}[ht]
  \centering
%  Include PDF image file (according to Latex docs PDF is preferred over PNG for better resolution)
  \includegraphics[width=\textwidth]{OM-Process.pdf}
  \caption{Process object model (tasks gSpiceUI may envoke).}
  \label{fig:om-process}
\end{figure}

\emph{\hyperref[fig:om-pnlvalue]{Figure \ref{fig:om-pnlvalue} : PnlValue Class Object Model}}
depicts the class structure of the display control used to contain numeric values. It combines
wxWidgets library text, spin and choice controls so that numeric values (either integer or floating
point) can be set using the mouse or keyboard.

\begin{figure}[ht]
  \centering
  % Include PDF image file (according to Latex docs PDF is preferred over PNG for better resolution)
  \includegraphics[width=\textwidth]{OM-PnlValue.pdf}
  \caption{Value panel object model (displays data variables).}
  \label{fig:om-pnlvalue}
\end{figure}

Notes :
\begin{itemize}
  \item The GNU SPICE GUI project is comprised of many C++ classes, more than are depicted in the
        object models shown here. However, all the major classes have been depicted giving a good
        idea of the overall application architecture.
  \item 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
        \emph{exactly} match the information shown in the object models.
\end{itemize}

The source code is heavily commented and has been designed and written so that it may be maintained
(or reused) by myself or anyone else for that matter. The project has well and truely got to the
stage where it can no longer be maintained simply from memory.

\pagebreak

%***************************************************************************************************

\end{document}
