\chapter{Running the software with the GUI} \label{running_with_GUI}

This chapter should be read in conjunction with the other chapters of this user guide, it does not contain sufficient information to be read as a standalone document. As outlined in the previous chapter there are three processes involved in the creation of any Spice cable bundle model. These are:

\begin{enumerate}
\item cable model building process
\item cable bundle model building process
\item spice cable bundle model building process
\end{enumerate}

\noindent
This chapter will describe how the SACAMOS graphical user interface (GUI) is used to drive these processes as described in chapters \ref{creating_a_cable_model} to \ref{creating_a_spice_cable_bundle_model}, i.e.:

\begin{enumerate}
\item create a cable model
\item create a cable bundle model
\item create a Spice cable bundle model 
\end{enumerate}

\noindent
Aiding the creation of all cable types. Namely:

\begin{enumerate}
\item Frequency Dependent Cylindrical conductor with dielectric
\item Frequency Dependent Coaxial cable with transfer impedance and shield surface impedance loss
\item Frequency Dependent Twinax cable with transfer impedance and shield surface impedance loss
\item Frequency Dependent Twisted pair
\item Frequency Dependent Shielded twisted pair with transfer impedance and shield surface impedance loss
\item Frequency Dependent Spacewire cable with transfer impedance and shield surface impedance loss
\item Frequency Dependent Overshield with transfer impedance and shield surface impedance loss
\item Frequency Dependent flex cable
\item D connector
\end{enumerate}

\noindent
\textbf{Please Note:} When using the GUI a strict directory structure must be adhered to. A parent SACAMOS folder must exist that follows the illustrative directory structure outlined in the figure below:

\begin{verbatim}
SACAMOS
|--BIN
|  `--All SACAMOS Executables (command line and GUI)
|--MOD1
|  |-- CABLE
|  |   |--single_wire.cable_spec
|  |   `--single_wire.cable
|  |-- BUNDLE
|  |   |--2_wire.bundle_spec
|  |   `--2_wire.bundle
|  `--SPICE
|     |--SYMBOL
|     |  |--2_wire.asy
|     |  `--2_wire.sym
|     |--2_wire.spice_model_spec
|     |--2_wire_Ngspice.lib
|     `--2_wire_LTspice.lib
|	
|--MOD2
|  |-- CABLE
|  |-- BUNDLE
|  `-- SPICE
|      `-- SYMBOL
`--MOD3	
   |-- CABLE
   |-- BUNDLE
   `-- SPICE
       `-- SYMBOL	
\end{verbatim}

\clearpage

In the file structure schematic more than one MOD folder is shown by way of illustrating the use of multiple cable model libraries. MOD1 shows the case for a; single wire cable model, bundle of 2 single wires, Spice model of 2 wire bundle and the associated library (.lib) and symbol files for Ngspice (.sym) and LTspice (.asy). MOD2 and MOD3 are shown empty, with only the required sub\-folder structure present.

\section{Starting the GUI for the Creation of Spice Cable Bundle Models}
The GUI for the creation of Spice cable bundle models is started by running the application 'SW1\_GUI' which will open the main application window shown in figure \ref{fig:SW1_GUI_Main} below:

%Include SW1_GUI_Main figure here 

\begin{figure}[h!]
\centering
\includegraphics[scale=0.60]{./Imgs/SW1_GUI_Main.pdf}
\caption{GUI main application window}
\label{fig:SW1_GUI_Main}
\end{figure}

With the exception of the File menu all items are initially disabled to force the selection or creation of a MOD library. Once selected (or created) the other menu items will become available - note the earlier stated constraint that any MOD library folder structure must sit at the same level as the executable (BIN) folder.

Throughout the following the example of an unshielded twisted pair cable will be used to illustrate the steps necessary to create a Spice model of a cable bundle. 

\subsection{Creation of the Cable Model} \label{GUI_Cable_Model}
Select the required cable model type from the 'Cable Model' menu in the toolbar. In figure \ref{fig:SW1_GUI_Selection} a Shielded Twisted Pair model has been selected:

%Include SW1_GUI_Main figure here 

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Selection.pdf}
\caption{Cable Model Selection}
\label{fig:SW1_GUI_Selection}
\end{figure}

This will open the cable designer form, figure \ref{fig:SW1_GUI_Cable_Gen}. On opening, the Cable Name (1) and \textbf{general} properties (2) can be defined, as each property is selected it will be highlighted on the cable \textbf{cross section} (3). Once completed, clicking the \textbf{material} tab allows for the material properties to be defined, figure \ref{fig:SW1_GUI_Cable_Mat}. For constant dielectric properties enter the required values (4), or for frequency dependent properties click the check box (5).

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Cable_Gen.pdf}
\caption{Cable Model Parameters, General Properties.}
\label{fig:SW1_GUI_Cable_Gen}
\end{figure}

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Cable_Mat.pdf}
\caption{Cable Model Parameters, Material Properties.}
\label{fig:SW1_GUI_Cable_Mat}
\end{figure}

\clearpage

If \textbf{Frequency Dependent} properties are selected the dialogue box, figure \ref{fig:SW1_GUI_Cable_fMat} will be presented. Here the properties for the \textbf{inner dielectric} and \textbf{outer dielectric} materials, (6 \& 7), can be set by specifying the rational functions that define the frequency dependence as described in chapter \ref{FD_cable_models}. The filter fitting parameters as described in chapter \ref{Cable_spec_file_formats} are then set in (8), where the greyed values are suggested defaults. Note: not all cable types require all this information, for those types having only a single layer of dielectric or for those not requiring the filter fitting process the appropriate elements of the dialogue will be greyed out.

\begin{figure}[h!]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Cable_fMat.pdf}
\caption{Cable Model Parameters, Frequency Dependent Material Properties.}
\label{fig:SW1_GUI_Cable_fMat}
\end{figure}

The \textbf{transfer impedance} tab allows the definition of the shield conductor transfer impedance which may be constant (9) or frequency dependent, figure \ref{fig:SW1_GUI_Cable_fTrans}. The latter enabled by selecting the check box (10). Further information on these properties can be found in chapter \ref{FD_cable_models}.

\begin{figure}[h!]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Cable_fTrans.pdf}
\caption{Cable Model Parameters, Frequency Dependent Transfer Impedance Properties.}
\label{fig:SW1_GUI_Cable_fTrans}
\end{figure}

\vbox{
Finally the choice of whether to use an approximate analytic formula or the numerical Laplace solver to calculate the per unit length parameters is to be made, figure \ref{fig:SW1_GUI_Cable_Laplace}. Selecting \textbf{Use Laplace} (11) will invoke the Laplace solver and populate the mesh list (12). Selecting a mesh from this list will display the mesh used by the Laplace solver for a specific domain, a decision can then be made whether to \textbf{refine} the mesh (13) or accept the default mesh. If the mesh parameters are changed then the model must be saved again and the build process selected to re-build the model. A description of the mesh parameters can be found in chapter \ref{Cable_spec_file_formats}.

Once the cable has been completely specified, click \textbf{Save}. If the cable has been specified correctly click save will result in the button being greyed out, any errors will result in an appropriate error message indicating any incorrect or missing parameters. Next click build to generate the cable model which should result in a \textbf{Run Status} dialogue box, figure \ref{fig:SW1_GUI_Cable_Build} indicating that the process has finished correctly. The cable model form can now be closed.
}

\begin{figure}[h]
	\centering
	\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Cable_Laplace.pdf}
	\caption{Cable Model Parameters, the Laplace Solver.}
	\label{fig:SW1_GUI_Cable_Laplace}
\end{figure}

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Cable_Build.pdf}
\caption{Cable Model Parameters, the Build Process Completed.}
\label{fig:SW1_GUI_Cable_Build}
\end{figure}

\clearpage

Figures \ref{fig:SW1_GUI_Cable_STP01}, \ref{fig:SW1_GUI_Cable_STP02} and \ref{fig:SW1_GUI_Cable_STP03} show the completed forms for an example shielded twisted pair cable model, named \textbf{STP}.

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Cable_STP01.pdf}
\caption{Cable Model Parameters: General Properties.}
\label{fig:SW1_GUI_Cable_STP01}
\end{figure}

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Cable_STP02.pdf}
\caption{Shielded Twisted Pair: Material Properties.}
\label{fig:SW1_GUI_Cable_STP02}
\end{figure}

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Cable_STP03.pdf}
\caption{Shielded Twisted Pair: Transfer Impedance Properties.}
\label{fig:SW1_GUI_Cable_STP03}
\end{figure}

\clearpage

The result is the creation of two files, STP.cable\_spec and STP.cable, the specification and model files respectively, within the \textbf{CABLE} folder of the MOD libray.

\vbox{%
\begin{verbatim}
|--MOD1
   |-- CABLE
   |   |--STP.cable_spec
   |   `--STP.cable
   |-- BUNDLE
   `-- SPICE
       `-- SYMBOL	
\end{verbatim}
}

\subsection{Creation of the Cable Bundle Model} \label{GUI_Cable_Bundle_Model}
A cable bundle is built from constituent cable models that exist in MOD. To construct a bundle model, click \textbf{Bundle Model} from the menu bar and select Create Bundle to display the \textbf{Cable Bundle Builder} dialogue, figure \ref{fig:SW1_GUI_Bundle_Spec01}. The \textbf{Bundle Name} can be specified here (1). In the \textbf{Cable Component Browser} all the available cables from which to build a bundle will be contained within the Cable folder. Click the \(+\) to expand the selection if necessary. The required cable components can be selected by double clicking them, opening a dialogue box with which to specify the location of the centre of the cable, figure \ref{fig:SW1_GUI_Bundle_Spec02}.

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Bundle_Spec01.pdf}
\caption{Bundle Model Builder: Selection of Component Cables}
\label{fig:SW1_GUI_Bundle_Spec01}
\end{figure}

Once the position of the cable has been defined, clicking OK will add the cable to the \textbf{Component Cables} list and show the cable cross section, figure \ref{fig:SW1_GUI_Bundle_Spec03}.

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Bundle_Spec02.pdf}
\caption{Bundle Model Builder: Placement of Component Cables}
\label{fig:SW1_GUI_Bundle_Spec02}
\end{figure}

\begin{figure}[h]
	\centering
%	\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Bundle_Spec03.pdf}
	\includegraphics[width=\textwidth]{./Imgs/figure_8_14.eps}
	\caption{Bundle Model Builder: Selection of Component Cables}
	\label{fig:SW1_GUI_Bundle_Spec03}
\end{figure}

\clearpage

From here further cables can be added to the bundle and/or a ground plane added, figure \ref{fig:SW1_GUI_Bundle_Spec04}. Finally the use of the Laplace solver to calculate inductance and capacitance matrices for the external domain and any overshielded domains (by default, approximate analytic formulae are used), figure \ref{fig:SW1_GUI_Bundle_Spec05}. See chapter \ref{Cable_bundle_spec_file_formats} for further information. As previously described, if the Laplace solver is used the mesh list will be populated and the meshes can be viewed by selecting them from the drop down list and a decision then made whether to refine the mesh or accept the default.

\begin{figure}[h]
\centering
%\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Bundle_Spec04.pdf}
\includegraphics[width=\textwidth]{./Imgs/figure_8_15.eps}
\caption{Bundle Model Builder: Ground Plane Inclusion}
\label{fig:SW1_GUI_Bundle_Spec04}
\end{figure}

\begin{figure}[h]
\centering
%\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Bundle_Spec05.pdf}
\includegraphics[width=\textwidth]{./Imgs/figure_8_16.eps}
\caption{Bundle Model Builder: Laplace Solver}
\label{fig:SW1_GUI_Bundle_Spec05}
\end{figure}

\begin{figure}[h]
	\centering
%	\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Bundle_Spec06.pdf}
        \includegraphics[width=\textwidth]{./Imgs/figure_8_17.eps}
	\caption{Bundle Model Builder: Bundle Build Process Completed}
	\label{fig:SW1_GUI_Bundle_Spec06}
\end{figure}


\clearpage

Once the bundle has been completely specified, click \textbf{Save}. If the bundle has been specified correctly clicking save will result in the button being greyed out, any errors will result in an appropriate error message indicating any incorrect or missing parameters. Next click build to generate the bundle model which should result in a \textbf{Run Status} dialogue box, figure \ref{fig:SW1_GUI_Bundle_Spec06} indicating that the process has finished correctly. The cable model form can now be closed. The result is the creation of two files, STP.bundle\_spec and STP.bundle within the \textbf{Bundle} folder of the MOD library, the specification and model files respectively.

\vbox{%
\begin{verbatim}
|--MOD1
   |-- CABLE
   |   |--STP.cable_spec
   |   `--STP.cable
   |-- BUNDLE
   |   |--STP.bundle_spec
   |   `--STP.bundle
   `-- SPICE
       `-- SYMBOL	
\end{verbatim}
}

\subsection{Creation of the Spice Cable Bundle Model} \label{GUI_reating_a_spice_cable_bundle_model}
A Spice cable bundle is built from a cable bundle model that exists in the MOD library. To construct a Spice cable bundle model, click \textbf{Spice Model} from the menu bar and select \textbf{Create Spice Bundle Model} to display the \textbf{Spice Model  Builder} dialogue, figure \ref{fig:SW1_GUI_Spice_Spec01}. The \textbf{Spice Model Name} can be specified here. In the \textbf{Browser} all the available cables from which to build a Spice model will be contained within the Bundle folder. Click the \(+\) to expand the selection if necessary. The required bundle can be selected by double clicking the relevant bundle\_spec file, displaying its cross section in the viewer, figure \ref{fig:SW1_GUI_Spice_Spec02}.

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Spice_Spec01.pdf}
\caption{Spice Model Builder: Spice Model Specification Dialogue}
\label{fig:SW1_GUI_Spice_Spec01}
\end{figure}

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Spice_Spec02.pdf}
\caption{Spice Model Builder: Spice Model Specification}
\label{fig:SW1_GUI_Spice_Spec02}
\end{figure}

From here the length of cable represented by the Spice model is set (1). An incident field may also be defined here (2), see chapter \ref{creating_a_spice_cable_bundle_model} for further information on the definition of an incident field. In order to include a transfer impedance model (3) the conductor number of the shield of interest must be specified along with the direction of the coupling. The coupling direction is specified as either +1 or -1 where +1 indicates coupling direction from inside the shield to outside and -1 indicates coupling from the outside to the inside, further information can again be found in chapter  \ref{creating_a_spice_cable_bundle_model}.

Once the Spice model has been completely specified, click \textbf{Save}. If the Spice model has been specified correctly clicking save will result in the button being greyed out, any errors will result in an appropriate error message indicating any incorrect or missing parameters. Next click build to generate the Spice model which should result in a \textbf{Run Status} dialogue box, figure \ref{fig:SW1_GUI_Spice_Spec03} indicating that the process has finished correctly. The Spice model form can now be closed. The result is the creation of the spice\_model\_spec file, two files defining the Spice library files (one each for LTspice and Ngspice) in the SPICE folder and their associated symbols in the SYMBOL FOLDER.

\vbox{%
\begin{verbatim}
|--MOD1
   |-- CABLE
   |   |--STP.cable_spec
   |   `--STP_wire.cable
   |-- BUNDLE
   |   |--STP.bundle_spec
   |   `--STP.bundle
   `-- SPICE
       |-- SYMBOL
       |   |--STP.asy
       |   `--STP.sym
       |-- STP.spice_model_spec
       |-- STP_Ngspice.lib
       `-- STP_LTspice.lib	
\end{verbatim}
}

\begin{figure}[h]
\centering
\includegraphics[width=\textwidth]{./Imgs/SW1_GUI_Spice_Spec03.pdf}
\caption{Spice Model Builder: Spice Build Process Completed}
\label{fig:SW1_GUI_Spice_Spec03}
\end{figure}

The process for building all Spice bundle models is similar to that , only differing in the individual description of the different cable geometries.