\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 addition there are the supporting processes to generate frequency dependent dielectric models from tabulated frequency domain relative permittivity data and togenerate frequency dependent transfer impedance models from a description of the braid geometry.

In this chapter the inputs and outputs to these processes are outlined. The detail of the input file formats for the Spice cable bundle creation process 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 Cylindrical conductor with dielectric
\item Coaxial cable with transfer impedance and shield surface impedance loss
\item Twinax cable with transfer impedance and shield surface impedance loss
\item Twisted pair
\item Shielded twisted pair with transfer impedance and shield surface impedance loss
\item Spacewire with transfer impedance and shield surface impedance loss
\item Overshield with transfer impedance and shield surface impedance loss
\item 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.
\item Mesh parameters for Laplace solution (if required):
\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 the external domain to be modelled, plus 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 or an approximate analytic solution according to flags set by the user. Loss models are based on models of skin effect appropriate for the conductor geometry. Details of the Laplace equation solution and loss models may be found in the Theory Manual \cite{Theory_manual}.

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. 
\item Mesh parameters for Laplace solution (if required): 
\end{enumerate}

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

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 bundle 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. 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. 
\item Constants to be changed from their default values.
\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}

The ways in which a Spice cable bundle is specified are detailed in section \ref{creating_a_spice_cable_bundle_model} along with the format of the information in the \textbf{*.spice\_model\_spec} file.

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. 


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

\section{Generation of frequency dependent rational function models}\label{FD_model_fit}

In order to take full advantage of the frequency dependent models available it may be necessary to generate a rational function representation of a frequency dependent parameter. This may be the relative permittivity of a dielectric material or a transfer impedance. A command line driven process,
\textbf{rational\_function\_fit}, is available which allows the calculation of rational function coefficients from tabulated complex frequency domain data. The process provides a best fit model of specified order over the specified frequency range. 
The model order can be specified in two ways:

\begin{enumerate}
\item The order is specified as a positive integer and this is the order used
\item A negative integer is specified. In this case the order is chosen using an automatic algorithm which
attempts to choose the best order from 0 up to $|$specified order$|$
\end{enumerate}

The frequency range for the model fit must be specified as must be the use of a log or linear frequency scale.

The complex frequency domain data should be in a file formatted with three columns for the frequency, real part and imaginary part of the function respectively.

To run the rational function fitting process use the command:

\textbf{rational\_function\_fit}

The user is prompted to enter the name of the complex frequency domain data file (\textbf{file\_name}). The file is then read before the user is prompted to provide the numerator order and the denominator order for the rational function. The best fit model is calculated and the stability of the resulting model is determined (i.e. whether the impulse response of the transfer function converges).

The output of the process is a file \textbf{name.function\_fit} which contains the rational function model fit to the input function. In addition a file 
\textbf{function\_fit.fout} is produced which contains tfive columns; frequency, Real part of the input function data, Imaginary part of the input function data, Real part of the function fit data, Imaginary part of the function fit data. This data set allows the original data and the model fit data to be visualised.


 
\clearpage

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

\section{Generation of frequency dependent transfer impedance models}\label{FD_transfer_impedance_models}
                                                                            
The program \textbf{shield\_conductor\_and\_transfer\_impedance\_model\_builder} calculates the frequency dependent transfer impedance and surface impedance of a braided shield from the shield specifications using the theory described by Vance <cite{vance} and Kley \cite{Kley} and summarised in appendix \ref{appendix_kley}. The braid specification is given in a file 
\textbf{name.braid\_spec}. The braid specification consists of the parameters given in table \ref{cable_braid_spec}.

\begin{table}[h]
\begin{center}
\begin{tabular}{| p{3cm} | p{3cm} | p{6cm} |}
\hline
example value  & unit    & Comment \\ \hline
0.00294        & m       & braid diameter, D (m)\\ \hline
8              & integer & Number of carriers, C\\ \hline
4              & integer & Number of wires in a carrier, N\\ \hline
0.25e-3        & m       & diameter of a single wire, d (m)\\ \hline
5E7            & S/m     & conductivity of wires (S/m) \\ \hline
60.0           & degrees & pitch angle of the braid ($\alpha$) \\ \hline
4              & integer & order of transfer impedance rational function model \\ \hline
log            & log/lin & frequency range type for rational function model fitting \\ \hline
1E5   1E8  100 & Hz Hz Integer     & fmin, fmax, number of frequencies for rational function model fitting\\ \hline
\end{tabular}
\end{center}
\caption{Cable braid parameters}
\label{cable_braid_spec}
\end{table}

The braid parameters are illustrated in figure \ref{fig:braid}

\begin{figure}[h]
\centering
\includegraphics[scale=0.25]{./Imgs/braid.jpg}
\caption{Braid parameters}
\label{fig:braid}    
\end{figure}

The transfer impedance rational function representation is derived using the function function fitting process described in the theory manual, chapter 5.  This process provides a best fit model of specified order over the specified frequency range. The model order can be specified in two ways:

\begin{enumerate}
\item The order is specified as a positive integer and this is the order used
\item A negative integer is specified. In this case the order is chosen using an automatic algorithm which
attempts to choose the best order from 0 up to $|$specified order$|$
\end{enumerate}

The frequency range for the model fit must be specified as must be the use of a log or linear frequency scale.

An example \textbf{.braid\_spec} file is shown below

\begin{verbatim}
5E-3            ! braid diameter, D (m)
8               ! Number of carriers, C
5               ! Number of wires in a carrier, N
0.25e-3         ! diameter of a single wire, d (m)
5E7             ! conductivity of wires (S/m)
60.0            ! pitch angle of the braid (degrees)
4               ! order of transfer impedance model
log             ! frequency range type
1E5   1E8  100  ! fmin, fmax, number of frequencies
\end{verbatim}


To run the frequency dependent transfer impedance model generation process use the command:

\textbf{shield\_conductor\_and\_transfer\_impedance\_model\_builder}

The user is prompted to enter the name of the braid specification data (without \textbf{.braid\_spec} extension). This is the only action required by the user. 

The output of the process is a file \textbf{name.shield\_model} which contains the parameters required to specify the shield model in a \textbf{.cable\_spec} file i.e. the shield radius, the equivalent shield thickness, the shield conductivity and the rational function coefficients for the transfer impedance ratonal function model. In addition a rational function model for the shield surface resistance is given, plus some dervied values used in the calculation of the transfer impedance. 

An example \textbf{.shield\_model} file is shown below.


{\small
\begin{verbatim}
2.5000000000000001E-003  # Parameter Shield radius (m)
6.2500000000000015E-005  # Parameter Equivalent shield thickness (m)
50000000.000000000       # Parameter Shield conductivity (S/m)
  
# Transfer impedance model
 
628318530.71795857        # w normalisation constant
        6   # a order, a coefficients follow below:
2.0374795470322369E-002   2.4254670721262799        58.296168241008900        
360.12236267295452        895.52398521190491        1000.0529344339834        
485.68143255311600     
        5   # b order, b coefficients follow below:
1.0000000000000000        23.599449123864325        145.90222072648217        
362.78999275303266        405.14016972906620        196.75864271144215     
 
# Conductor surface impedance model
 
628318530.71795857        # w normalisation constant
        4   # a order, a coefficients follow below:
2.0425431606526812E-002   1.4239191601879064        10.701214713988804        
17.439082798989524        5.5415240356671571     
        4   # b order, b coefficients follow below:
1.0000000000000000        18.987055251519244        64.911367837365901   
9.386334031367127        4.7789439058672514     

# Shield parameters used in the shield model calculation
braid circummference, cb=   1.5707963267948967E-002
C=           8  Number of carriers
N=           5  Number of conductors in each carrier
W=   1.2500000000000000E-003  Width of each carrier
W=   2.4999999999999996E-003  Width of each carrier in circumferential direction
cb/(C/2)=   3.9269908169872417E-003  circumferential dimension for each carrier
P=   441.06311633743348     
v=   3528.5049306994679        Number of holes per unit length in braid
F=  0.63661977236758116        Fill factor
K=  0.86795481016581144        Optical coverage
l=   8.2387353231870868E-004   hole length
w=   1.4269908169872426E-003   hole width
S=   9.2336117727334644E-007   hole area
Th=   1.9846324228763292        hole attenuation factor
Ck=  0.12025223119877292        hole inductance factor
Ro   2.0371832715762598E-002   braid d.c. resistance
T    6.2500000000000015E-005   braid equivalent thickness
mean braid diameter, Dm=   5.4999999999999997E-003
Width between holes,  b=   7.1349540849362139E-004
Average height for braid inductance,  hh=   2.5000000000000001E-004
M12=(7.8743906839290131E-010,0.0000000000000000) Hole inductance
Mb =(3.1411609510809177E-009,0.0000000000000000) Braid inductance
Ms=(0.0000000000000000     ,0.0000000000000000) Skin inductance
M=(3.9286000194738192E-009,0.0000000000000000) Total transfer inductance
\end{verbatim}
}

\cleardoublepage