\chapter{Running the software without the GUI} \label{running_without_GUI}

There are three processes in the creation of a 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}

In this chapter the inputs and outputs to these processes are outlined. The datail of the input file formats may be found in chapters \ref{creating_a_cable_model}, \ref{creating_a_cable_bundle_model} and \ref{creating_a_spice_cable_bundle_model}.

\section{Cable model building process}

The inputs to the Cable model building process enable the characterisation of individual cables. For a particular cable type all the information required to model the cable within a bundle must be supplied. A cable will be characterised by its cross section geometry and material parameters. The extension for cable specification information files is \textbf{*.cable\_spec}. The cable types available are:

\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 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}

The inputs to the cable model building process are as follows:

\begin{enumerate}
\item Geometric and (constant with frequency) material parameters for the cable as requred for each cable type
\item Any frequency dependent dielectric models required for the cable type
\item Any frequency dependent transfer impedance models required for the cable type                                          
\item Flags to control the operation of the software. These flags consist of text commands. The available flags and their effect is as follows:\\

'verbose'    output detailed summary of the software operation and calculation results.\\

'use\_laplace'    use the numerical Laplace solver to calculate inductance and capacitance matrices where 
appropriate (i.e. where an exact analytic solution is not available.) By default, approximate analytic formulae are used. \\

'plot\_mesh'    output a vtk file which shows the mesh used in Finite Element Laplace calculations.\\

\item Mesh parameters for Laplace solution (if required): \\

'Laplace\_surface\_mesh\_constant'  This parameter determines the number of finite element edges on a conductor surface.
                                       The number of elements on a cylindrical conductor of radius r is
                                       $\frac{r}{Laplace_surface_mesh_constant}$. The default value is 3. \\


\end{enumerate}

The detail of the ways in which a cable is specified are detailed in section \ref{creating_a_cable_model} along with the format of the information in the \textbf{*.cable\_spec} file.

To run the cable model building process use the command:

\textbf{cable\_model\_builder}

The user is prompted to enter the name of the cable specification data file (without \textbf{.cable\_spec} extension) i.e. there must be an existing file \textbf{name.cable\_spec} containing the cable specification. Alternatively the user can supply the name of the cable as a command line argument i.e.

\textbf{cable\_model\_builder cable\_name}

This is the only action required by the user.

The output of the cable model building process is a fully specified cable model in a file (\textbf{name.cable}).

The cable models include internal propagation characterization (L, C matrices), shield characterization and loss model parameters also the domain decomposition matrices for shielded cables.

These outputs can be used to populate the library of cable models (MOD) with cable models by specifying an appropriate MOD directory in the \textbf{*.cable\_spec} file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Cable bundle model building process}

The cable bundle model consists of the propagation models of the shielded domains which have already been characterised on a cable basis. In addition to this the propagation on the bundle requires us to model the external domain and any domains defined by the presence of over-shields. The extension for cable bundle specification information files is \textbf{*.bundle\_spec}.

The configuration of the external domain is characterised by the geometry of the external conductors and dielectrics for each cable in the bundle, the geometric configuration of the cables within the bundle and its relation to the ground plane (if it exists). Similarly, domains within over-shields are characterised by the geometry of the external conductors and dielectrics for each cable within the shielded domain. Thus the cross section geometry of the cable bundle must be completely specified at this stage, including ground plane and/or overshields.

The inductance and capacitance matrices for the external and over-shielded domains may be determined from a numerical Laplace equation solution applied to the appropriate domain geometry ***** REFERENCE REQUIRED ***** or an approximate analytic solution ***** REFERENCE REQUIRED ***** according to flags set by the user. Losses will be based on models of skin effect appropriate for the conductor geometry. 

The inputs to the cable bundle model building process are as follows:

\begin{enumerate}
\item Cable models output from the cable model building process which may be obtained from the library of cable models (MOD) or elsewhere.
\item Bundle cross section geometry i.e. the placement of the individual cables in relation to each other in the bundle cross section.
      the bundle geometry can include overshields.
\item Ground plane specification (if required). The ground plane is assumed to be situated along the x axis in the x-y cross section of the cable bundle.                                           
\item Flags to control the operation of the software. These flags consist of text commands. The available flags and their effect is as follows:\\

'verbose'    output detailed summary of the software operation and calculation results.\\

'use\_laplace'    use the numerical Laplace solver to calculate inductance and capacitance matrices where 
appropriate (i.e. where an exact analytic solution is not available.) By default, approximate analytic formulae are used ***** REFERENCE REQUIRED *****. \\

'plot\_mesh'    output a vtk file which shows the mesh used in Finite Element Laplace calculations.\\

\item Mesh parameters for Laplace solution (if required): \\

'Laplace\_boundary\_constant'  This parameter determines the distance to the outer boundary in open boundary domains.
                                   The distance to the outer boundary is calculated by first determining the largest dimension 
                                   of the conductor system (including the ground plane point), bundle\_size. The outer boundary is 
                                   defined as a circle of radius  $bundle_size*Laplace_boundary_constant$. The default value is 3. \\

'Laplace\_surface\_mesh\_constant'  This parameter determines the number of finite element edges on a conductor surface.
                                       The number of elements on a cylindrical conductor of radius r is
                                       $\frac{r}{Laplace_surface_mesh_constant}$. The default value is 3. \\


\end{enumerate}

To run the cable bundle model building process use the command:

\textbf{cable\_bundle\_model\_builder}

The user is prompted to enter the name of the cable specification data (without \textbf{.bundle\_spec} extension). Alternatively the user can supply the name of the bundle as a command line argument i.e.

\textbf{cable\_bundle\_model\_builder  bundle\_name}

This is the only action required by the user.

The output from the cable bundle model building process is a cable bundle model ( \textbf{*.cable\_bundle} ) file. This file incorporates a model of the cable bundle decomposed into domains. The model specifies the cables forming the bundle, the bundle cross section and decomposition of the cable bundle into domains i.e. which cables and conductors belong in which domain, which conductors (shields) separate which domains, transfer impedance models for shields.
Within each domain the following is specified:

\begin{enumerate}
\item Inductance and capacitance matrix 
\item Loss model
\item Domain decomposition matrices
\end{enumerate}

The output can be used to populate the library of cable models (MOD) with cable models by specifying an appropriate MOD directory in the \textbf{*.bundle\_spec} file.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Spice cable bundle model building process}

Once a cable bundle has been specified a spice cable model can be created for the bundle. The spice model will necessarily be dependent on the particular analysis required for a bundle for example different incident field excitations may be specified or transfer impedance coupling paths included in the model. We also note that the spice cable models are not portable between different versions of Spice. 

The spice cable bundle model building process inputs are as follows:

\begin{enumerate}
\item Bundle model which is characterised by the inductance and capacitance matrices in each domain and the conductor loss models, frequency dependent transfer impedances of shields, spatial configuration of conductors in the external domain and domain decomposition matrices. The bundle model can come from the library of cable models, MOD.\\
\item Bundle length.\\
\item Incident field excitation (angle, polarization).\\
\item Source and victim conductors for transfer impedance coupling.\\
\item Frequency range for model.\\
\item Spice version required.\\
\item Validation test case configuration.  \\
\item Flags to control the operation of the software. These flags consist of text commands. The available flags and their effect is as follows:\\

'verbose'    output detailed summary of the software operation and calculation results.\\

'use\_xie'   use Xie's model for incident field excitation of shielded cables.\\

'no\_s\_xfer' For first order frequency dependent models (transfer impedance, propagation correction) we may 
                    use a passive circuit implementation for frequency dependent transfer functions instead of s-domain
                    transfer functions. This may be of use in Ngspice models which fail to run.\\

\item Constants to be changed from their default values. The format is a line with the constant name and the following line has the new value. The constants which may be specified by the user are:\\

'min\_delay'    . Minimum delay allowed for transmission lines in the sub-circuit models.
Transmission lines with delays less than this value are dealt with in a different manner. The default value is $10^{-12}$ s. \\

'Rsmall'   Minimum resistance value in the sub-circuit model. Resistances less than this value are replaced by this value. The default value is $10^{-8}\Omega$. \\

\end{enumerate}

The spice cable bundle model building process output consists of the following:

\begin{enumerate}
\item The Spice Cable Model and an associated schematic symbol
\item Spice cable model with a test/validation configuration.
\item Validation data.
\item The Spice cable model and schematic symbol can form an input to the library of cable models (MOD).
\end{enumerate}

To run the cable bundle model building process use the command:

\textbf{spice\_cable\_bundle\_model\_builder}

The user is prompted to enter the name of the spice cable bundle model specification data (without \textbf{.spice\_model\_spec} extension). Alternatively the user can supply the name of the spice cable bundle model as a command line argument i.e.

\textbf{spice\_cable\_bundle\_model\_builder  spice\_cable\_bundle\_model\_name}
 
This is the only action required by the user.

\subsection{Transient validation test cases}

When setting up a transient validation test case it is extremely important that the runtime specified is sufficient for all the transients in the simulation to reduce to an insignificant level. If this is not the case then significant errors can arise in the analytic transient solution due to aliasing in the FFT implementation of the convolution process. 


\cleardoublepage