\chapter{Running the test cases} \label{running_test_cases}

The TEST\_CASES directory contains a number of test cases which are designed to
test the functionality of the Spice cable model building project.

The script \textbf{generate\_spice\_cable\_bundle\_model} automatically generates Spice cable bundle models,
validation test circuits and analytic results for multi-conductor cable test cases.
The Spice model results are plotted against the analytic solution for both frequency domain
and transient analyses. The process also calculates a figure of merit for the model based on
the difference between the analytic and Spice model data using the code \textbf{compare\_results}.

In order to run the test cases you will need the following to be installed:
Ngspice
gnuplot

The script may need to be changed for your system. It is set up by default to work with
a library of cable models in the TEST\_CASES directory. This may be changed to suit the 
user by for example changing the path for the library of cable models (MOD) by changing the variable in the \textbf{generate\_spice\_cable\_bundle\_model} script:

\textbf{LIBRARY\_OF\_MODELS\_TOP\_LEVEL="/home/user/LIBRARY\_OF\_CABLE\_MODELS"}

The user may also want to specify a directory for the circuit symbols produced by the system.
The default action is to keep these in the directory where the cable models are developed.
This may be changed by setting the variable SYMBOL\_DIR in the script \textbf{generate\_spice\_cable\_bundle\_model}. For example for use by gshem you may need to following:

\textbf{SYMBOL\_DIR="/usr/share/gEDA/sym/local"}

 ( NOTE: you may need to change ownership of \textbf{SYMBOL\_DIR} with something like the following command:    
\textbf{sudo chown chris:chris /usr/share/gEDA/sym/local} )


Test cases are found in sub-directories in the TEST\_CASES directory. In each test case directory the 
following files should exist:

\begin{enumerate}
\item A number of files (or zero if they already exist in the library) for cable specification information 
    \textbf{*.cable\_spec}
    
\item Zero or a maximum of one file for cable bundle specification
    \textbf{*.bundle\_spec}
     
\item One (and only one) file for the Spice cable bundle specification
    `\textbf{*.spice\_model\_spec}
\end{enumerate} 

The automatic testing script is run using the following command:

\textbf{generate\_spice\_cable\_bundle\_model action}

\textbf{action} is the process to perform:


\begin{center}
    \begin{tabular}{ | l | p{8cm} |}
    \hline

action=run NAME               &  Generate cable models, bundle model and 
                                Spice bundle model and validation Spice model
                                as required for the test case NAME.
                                Run Ngspice on the validation model and compare
                                the Spice result against the analytic solution          \\ \hline                     
				
action=plot NAME              &  Plot the results of the Spice validation model and
                                analytic solution to screen \\ \hline
				
action=plot\_wxt NAME          & Plot the results of the Spice validation model and 
                                analytic solution to wxt terminal  \\ \hline

action=plot\_jpg NAME          & Plot the results of the Spice validation model and 
                                analytic solution to .jpg file \\ \hline

action=plot\_ref NAME          & Plot the Spice validation model results against  
                                reference results to x11 terminal \\ \hline

action=plot\_ref\_wxt NAME      & Plot the Spice validation model results against  
                                reference results to wxt terminal \\ \hline

action=plot\_ref\_jpg NAME      & Plot the Spice validation model results against  
                                reference results to jpg file \\ \hline

action=plot\_bundle NAME       & Plot the bundle cross section to the screen \\ \hline

action=plot\_bundle\_wxt NAME   & Plot the bundle cross section to wxt terminal \\ \hline

action=plot\_bundle\_jpg NAME   & Plot the bundle cross section to jpg file  \\ \hline

action=plot\_bundle\_png NAME   & Plot the bundle cross section to png file  \\ \hline

action=plot\_bundle\_svg NAME   & Plot the bundle cross section to svg file  \\ \hline
								
action=reference  NAME        &  Update the reference results and the difference
                                 between the Spice model and validation model  
                                 with the current set of results i.e. the results of the latest run. \\ \hline
				
action=check\_error  NAME     &  Quick check that the difference between the 
                                Spice model and validation model is the same as 
				for the reference data set \\ \hline
				
action=clean  NAME            &  Remove all files except those required to set up
                                the problem and the reference results.  \\ \hline
				
action=clean\_all  NAME        &  Remove all files including the reference results.  \\ \hline

    \end{tabular}
\end{center}


NAME can be one of the existing test cases or left blank to process all of the test cases

The test case directory should contain the following:

 \textbf{*.cable\_spec} files as required to specify cables (though cables specified elsewhere 
could be used to form bundles)
 
a \textbf{*.bundle\_spec } file if required to specify the cable bundle (though cable bundles 
specified elsewhere could be used in the specification of Spice cable models)

a \textbf{*.spice\_model\_spec} file to specify the Spice cable bundle model if a Spice model is to be generated for this test case.

The action `run' does the following:

\begin{enumerate}
\item  copy the input files which describe the required simulation to the \textbf{RUN\_DIRECTORY} directory. The input files are as follows: \textbf{*.cable\_spec} file(s) which describe individual cable types, a \textbf{*.bundle\_spec} file which describes the cable bundle cross section and a \textbf{*.spice\_model\_spec} file which describes the simulation scenario and a validation test configuration.

\item   run the code \textbf{cable\_model\_builder} as required to create the cable models. the output of this process is a cable model in a file (\textbf{*.cable}) corresponding to each of the cable specification files (\textbf{*.cable\_spec}).

\item   run the code \textbf{cable\_bundle\_model\_builder} as required to create the cable bundle models. The output of this process is a  cable bundle model in a file (\textbf{*.bundle}).

\item   run the code \textbf{spice\_cable\_bundle\_model\_builder} as required to create 

    a. Spice subcircuit models of the bundle for each of the target Spice versions (\textbf{*\_Ngspice.lib}, \textbf{*\_LTspice.lib}, \textbf{*\_PSpice.lib} ).
    
    b. the schematic symbol for the Spice subcircuit model (\textbf{*.sym})
    
    c. Spice validation models for each of the target Spice versions  (\textbf{*\_Ngspice.cir}, \textbf{*\_LTspice.cir}, \textbf{*\_PSpice.cir} ).
    
    d. the analytic solution of the validation configuration (\textbf{analytic\_solution.dat})
  
\item   run \textbf{Ngspice} on the Spice validation model to produce the Spice solution output (\textbf{spice\_solution.dat})

\item   run the code \textbf{compare\_results} which provides a numerical measure of the difference between the
   results of the analytic solution and the Spice solution (\textbf{result\_comparison.dat}). 
   
For frequency domain simulations the difference measure is calculated as 
%
\begin{equation} \label{eq:freq_error}
err=\frac{\int_{fmin}^{fmax} \left|V_{analytic}(f)-V_{spice}(f)\right| df}{fmax-fmin}
\end{equation}
%
For time domain simulations the difference measure is calculated as 
%
\begin{equation} \label{eq:time_error}
err=\frac{\int_{tmin}^{tmax} \left|V_{analytic}(t)-V_{spice}(t)\right| dt}{tmax-tmin}
\end{equation}
%


\end{enumerate}



\cleardoublepage