\chapter{Creating a Spice Cable Bundle Model} \label{creating_a_spice_cable_bundle_model}

This chapter describes the creation of a Spice cable bundle model from a previously defined cable bundle and additional specifications which are required to define the Spice model. This section also describes how a validation test case is defined which enables the performance of the model to be assessed in either an a.c. or transient analysis.

The format of the files relating to the Spice cable bundle model building process are described in 
section \ref{Spice_cable_bundle_spec_file_formats}.

\section{Incident field excitation}

The transmission line model may  incorporate an incident field excitation which takes the form of a plane wave. The plane wave incident field may be a continuous wave for a.c. analysis or a pulse for transient analysis. When a plane wave excitation is required the Spice sub-circuit model has an additional two nodes defined, the voltage between these nodes specifies the Electric field of the plane wave.

For the purposes of incident field excitaton analysis the axis of the cable bundle is assumed to be in the z direction. The direction of the incident field plane wave is specified by its wave vector in polar coordinates (figure \ref{fig:Incident_field_1})
%
\begin{figure}[h]
\centering
\includegraphics[scale=0.75]{./Imgs/Incident_field_specificaton.eps}
\caption{Plane wave incident field excitation of a cable bundle}
\label{fig:Incident_field_1}
\end{figure}
%
\begin{equation}
\begin{array}{c}
k_{x}=\sin(k_{\theta})\cos(k_{\phi}) \\
k_{y}=\sin(k_{\theta})\sin(k_{\phi}) \\
k_{z}=\cos(k_{\phi}) \\
\end{array}
\end{equation}
%
where $k_{\theta}$ is the angle of the wave vector from the z axis and $k_{\phi}$ is the angle from the x axis as shown in figure \ref{fig:Incident_field_2}.

Given this k vector, unit vectors in the $\theta$ and $\phi$ directions can be identified. 
The Electric field polarisation direction is specified in terms of these vectors ($E_{\theta}$ and  $E_{\phi}$) as shown 
in figure \ref{fig:Incident_field_2}.
%
\begin{figure}[h]
\centering
\includegraphics[scale=1.5]{./Imgs/k_incident.eps}
\caption{Specification of the incident field polarisation}
\label{fig:Incident_field_2}
\end{figure}
% 
It is important to note that the angles $E_{\theta}$ and  $E_{\phi}$ specify the polarisation direction only, the amplitude of the Electric field is specified separately i.e. the polarisation vector is normalised to unit length and only the relative amplitudes of $E_{\theta}$ and  $E_{\phi}$ is significant in determining the polarisation direction so setting $E_{\theta}=1$ and  $E_{\phi}=1$ will give the polarisation vector as specifying $E_{\theta}=\frac{1}{\sqrt 2 }$ and  $E_{\phi}=\frac{1}{\sqrt 2 }$.
%

A wave in the +z direction with the Electric field polarised in the +x direction is therefore specified by
$k_{\theta}=0^{\circ}$  $k_{\phi}=0^{\circ}$  $E_{\theta}=1$  $E_{\phi}=0$  

A wave in the +z direction with the Electric field polarised in the +y direction is therefore specified by
$k_{\theta}=0^{\circ}$  $k_{\phi}=90^{\circ}$  $E_{\theta}=1$  $E_{\phi}=0$  

A wave in the +x direction with the Electric field polarised in the +z direction is therefore specified by
$k_{\theta}=90^{\circ}$  $k_{\phi}=0^{\circ}$  $E_{\theta}=-1$  $E_{\phi}=0$  

A wave in the -y direction with the Electric field polarised in the +z direction is therefore specified by
$k_{\theta}=90^{\circ}$  $k_{\phi}=-90^{\circ}$  $E_{\theta}=-1$  $E_{\phi}=0$  

A wave in the -y direction with the Electric field polarised in the +x direction is therefore specified by
$k_{\theta}=90^{\circ}$  $k_{\phi}=-90^{\circ}$  $E_{\theta}=0$  $E_{\phi}=1$  

The derivation of the Spice cable bundle model for incident field excitation requires that $0^{\circ} \leq k_{\theta} \leq 90^{\circ}$ . If $k_{\theta}$  is out of this range then an error will occur. It should be noted that models for the situation $k_{\theta}>90^{\circ}$ can be simulated by swapping the ends to which the termination circuits are connnected.

\section{Transfer impedance model}

The Spice cable bundle model is based on a domain decomposition method where a domain is formed by the set of conductors within a shield separating them from a possible external domain (if it exists). 

The domains are modelled independently i.e. signals propagate within domains and do not couple between domains through cable shields unless specifically requested. The Spice cable bundle model uses a weak form of transfer impedance coupling thus a source and a victim domain must be specified for the inclusion of a transfer impedance model.

The transfer impedance of cable shields and overshields will have been specified in the individual cable models as a conductor impedance model for a shield (section \ref{FD_transfer_impedance_model}  ). This will automatically be included as a loss in the propagation algorithm for signals propagating on the inside and outside of the shield.
The model extracts the d.c. resistance of conductors and includes this directly on each conductor therefore coupling between domains does exist in the model due to the d.c. transfer impedance.
 However as a default no coupling between the internal and external domains is included apart from that which results from the d.c. component of the transfer impedance. 

In order to include a transfer impedance model the conductor number of the shield of interest must be specified along with the direction of the coupling. The coupling direction is specified in the 
\textbf{name.spice\_model\_spec} file 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. 

An example of the specification of transfer impedance coupling within a Spice cable bundle model is seen in section\ref{Spice_cable_bundle_spec_file_formats}

\section{Spice cable bundle subcircuit node numbering}

The subcircuit node numbering is as follows:

\begin{enumerate}
\item End 1 (- z end) conductors in order of the conductors in the bundle specification
\item End 2 (+ z end) conductors in order of the conductors in the bundle specification
\item If an incident field excitation is required, there are two additional nodes to specify the incident (Electric) field excitation function. The incident electric field is equal to the voltage between these two nodes.
\end{enumerate}


\section{Spice Cable Bundle Specification File Formats} \label{Spice_cable_bundle_spec_file_formats}

This section describes the Spice cable bundle specification file formats used as the input to the Spice cable bundle model building process.
Spice cable bundle specification files have the extension \textbf{.spice\_model\_spec}.

The first lines of the \textbf{.spice\_model\_spec} file specifies the path to the cable models used in the cable bundle specification (i.e. the path to the cable models within MOD), then the path to the cable bundle models used in the Spice model  (i.e. the path to the cable bundle models within MOD) then the path and to the Spice model to be produced  (i.e. the path to the Spice cable bundle models within MOD) and finally the path to the Spice model circuit symbols.

The input file to the Spice cable bundle building processs then includes the bundle name, bundle length, incident field specification (if required) and the specification of the validation test configuration (if required).

In addition information regarding the transfer impedance models to be included and also
information to control the transfer function fitting process can be specified. 

The validation test configuration is shown in figure \ref{fig_validation_test_case_config}

\begin{figure}[h]
\centering
\includegraphics[scale=0.8]{./Imgs/V2_validation_test_case_configuration_portrait.eps}
\caption{Validation test case configuration}
\label{fig_validation_test_case_config}
\end{figure}

In addition to the data required to specify a Spice cable bundle model, additional flags may be specified to influence the operation of the software. These flags are as follows:

\begin{enumerate}
\item `verbose'    output detailed summary of the software operation and calculation results.\\
\item `use\_xie'    Include direct incident field to shielded domain coupling terms (Xie's model). This is the default.\\
\item `no\_xie'     Do not include direct incident field to shielded domain coupling terms\\
\item `use\_high\_freq\_zt\_model' Use a distributed model for the transfer resistance - this may give improved transfer 
                               impedance coupling results at high frequency for cases when the shield termination impedance 
                               is very small at the expense of low frequency accuracy. This is the default.\\
\item `no\_high\_freq\_zt\_model'  Use a lumped model for the transfer resistance - this may give poor transfer 
                               impedance coupling results at high frequency for cases when the shield termination impedance 
                               is very small however it will give good results at low frequency. 
                               This is the default state as it is expected
                               that once realistic bonding impedances are taken into account, the termination impedance will not be
                               small enough to cause a problem.\\
\item `use\_s\_xfer'           Use the s-domain transfer function to implement the frequency dependent transfer function
                               used in the propagation correction and transfer impedance implementation.\\
\item `no\_s\_xfer'            Use a lumped component model to implement the frequency dependent transfer function
                               used in the propagation correction and transfer impedance implementation. This is now
                               the default state of this flag following the development of the equivalent circuit model
                               for rational s-domain transfer functions of arbitrary order. This is the default.\\
\item `use\_LTRA'              Implement delay lines in the Spice models as LTRA transmission lines rather than 
                               simple delay lines (T elements). This is found to improve the robustness of the Spice
                               transmission line models, esepcially for transient analysis in Ngspice. This is the 
                               default state for this flag.\\
\item `no\_LTRA'               Implement delay lines in the Spice models as T elements rather than 
                               LTRA transmission lines. \\
\end{enumerate}

There are also a number of constants used in the development of the models which may be changed from their default values from within the \textbf{.spice\_model\_spec} file.
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:

\begin{enumerate}
\item `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. \\

\item `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 file format with no transfer impdance models or transfer function fitting information is as follows:

\clearpage

\begin{center}
    \begin{tabular}{ | p{1.25cm} | p{4.5cm} | p{1.75cm} | p{5.5cm} |}
    \hline
    Line number & Typical value & Unit  & Description \\ \hline
1       & \#MOD\_cable\_lib\_dir & -    & Comment line \\ \hline
2       & .             & -             & Directory to read the cable model file from \\ \hline
3       & \#MOD\_bundle\_lib\_dir & -    & Comment line \\ \hline
4       & .             & -             & Directory to read the cable bundle model file from \\ \hline
5       & \#MOD\_spice\_bundle\_lib\_dir & -    & Comment line \\ \hline
6       & .             & -             & Directory to write the Spice cable bundle model file to \\ \hline
7       & \# two wires over ground plane, crosstalk model  & -    & Comment line \\ \hline
8       & two\_wires\_over\_ground    & -              & Cable bundle name Note there should be nothing else on this line \\ \hline
9       & \# bundle length  & -    & Comment line \\ \hline
10       & 2.0    & metres              & Cable bundle length \\ \hline
11       & \# incident field specification  & -    & Comment line \\ \hline
12       & 0.0    & V/m          & Amplitude \\ \hline
13       & 90.0  0.0  & degrees          & Wave vector angle k$\theta$ k$\phi$ \\ \hline
14       & 1.0  0.0  & degrees          & Polarisation E$\theta$ E$\phi$ \\ \hline
15       & \# End 1 termination model  & -    & Number of sources and resistances = number of conductors \\ \hline
16       & 1.0    & V          & End 1, conductor 1 voltage source amplitude \\ \hline
-       & 0.0    & V          & End 1, conductor 2 voltage source amplitude \\ \hline
-       & 0.0    & V          & End 1, reference conductor  voltage source amplitude \\ \hline
-       & 50.0    & $\Omega$          & End 1, conductor 1 resistance \\ \hline
-       & 25.0    & $\Omega$          & End 1, conductor 2 resistance \\ \hline
-       & 0.0    & $\Omega$          & End 1, reference conductor resistance \\ \hline
-       & \# End 2 termination model  & -    & Number of sources and resistances = number of conductors \\ \hline
-       & 1.0    & V          & End 2, conductor 1 voltage source amplitude \\ \hline
-       & 0.0    & V          & End 2, conductor 2 voltage source amplitude \\ \hline
-       & 0.0    & V          & End 2, reference conductor  voltage source amplitude \\ \hline
-       & 50.0    & $\Omega$          & End 2, conductor 1 resistance \\ \hline
-       & 25.0    & $\Omega$          & End 2, conductor 2 resistance \\ \hline
-       & 0.0    & $\Omega$          & End 2, reference conductor resistance \\ \hline
    \end{tabular}
\end{center}

% continue table on the next page

\begin{center}
    \begin{tabular}{ | p{1.5cm} | p{4.5cm} | p{1.25cm} | p{5.5cm} |}
    \hline
    Line number & Typical value & Unit  & Description \\ \hline
-       & \# Type of analysis  & -    & Comment line \\ \hline
-       & AC    & -          & AC or TRANS \\ \hline
 \hline
 & For AC analysis  & & \\ \hline
-       & lin    & -          & logarithmic (log) or linear (lin) frequency scale \\ \hline
-       & 1e3 1e8 1000 & Hz Hz integer & min frequency, max frequency  number of frequencies \\ \hline
\hline
 & For TRANSIENT analysis & & \\ \hline
-       & 0.01E-9 100E-9  & seconds seconds & \# timestep runtime \\ \hline
-       & 1e-9 50e-9	  & seconds seconds & \# pulse risetime pulse width \\ \hline
\hline
-       & \# Output\_conductor1 output\_conductor2 and end number  & -    & Conductor\_2 can be left out in which case the voltage is relative to the reference conductor \\ \hline
-       & 1   1    & integer integer  & Output conductor number and end number \\ \hline
-       & lin    & -          &  For AC only: Output voltage scaling, linear or dB \\ \hline
    \end{tabular}
\end{center}

\clearpage

\vspace{5mm}
\textbf{\underline{AC example}}

An example file for the AC analysis of two wires over a ground plane is shown below:

\begin{verbatim}
#MOD_cable_lib_dir
LIBRARY_OF_CABLE_MODELS
#MOD_bundle_lib_dir
LIBRARY_OF_BUNDLE_MODELS
#MOD_spice_bundle_lib_dir
./
#spice_symbol_dir
SYMBOL_DIR
# Specification for Spice model of two wires over ground
two_wires_over_ground
# cable bundle length (m)
2.0
#Incident field specification
0.0	amplitude (V/m)
90.0 0.0	ktheta kphi (degrees)
-1.0  0.0	Etheta Ephi
# End 1 termination model 
1.0      End 1 voltage source list
0.0
0.0
100.0    End 1 impedance list
25.0
0.0
# End 2 termination model
0.0      End 2 voltage source list
0.0
0.0 
75.0  	 End 2 impedance list
50.0
0.0
# Type of analysis
AC
log          # frequency scale (log or lin)
1e3 1e8 1000 # fmin fmax number_of_frequencies
# Output conductor number and end number
1    1   
lin   # output type (lin or dB)
\end{verbatim}


\clearpage


\vspace{5mm}
\textbf{\underline{Transient example}}

An example file for the trasnsient analysis of two wires over a ground plane is shown below:

\begin{verbatim}
#MOD_cable_lib_dir
.
#MOD_bundle_lib_dir
.
MOD_spice_bundle_lib_dir
.
#spice_symbol_dir
SYMBOL_DIR
2   # number of conductors, n.
2_wire
# cable bundle length (m)
2.0
#Incident field specification
0.0	amplitude (V/m)
90.0 0.0	ktheta kphi (degrees)
-1.0  0.0	Etheta Ephi
# End 1 termination model
1.0      End 1 voltage source list
0.0
50.0  	End 1 impedance list
0.0
# End 2 termination model
0.0        End 2 voltage source list
0.0
50.0  	 End 2 impedance list
0.0
# Type of analysis
TRANS
0.01E-9 100E-9   # timestep runtime
1e-9 50e-9	# pulse_risetime pulse_width
# Output conductor number and end number
1  1     
\end{verbatim}

\clearpage

In the case of frequency dependent models and transfer impedance coupling models then the above file format can be
adapted to include additional information required to drive these models.

A weak form of the transfer impedance is implemented in this work hence the direction of coupling must be specified. 
In order to include a transfer impedance model the conductor number for the shield whose transfer impedance is required. In addition to
this the direction of the transfer impedance coupling must be specified. The direction is specified as an integer where +1 indicates 
coupling from inside the shield to outside and -1 indicates coupling from the outside to the inside.

The frequency dependent propagation correction takes the form of a s-domain transfer function in the Spice model. These propagation
correction transfer functions are derived using a rational function fitting process. This process provides a best fit model of
specified order over a specified frequency range. As a default the model order is 0 i.e. no frequency dependent propagation correction.
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 may also be specified as can the use of a log or linear frequency scale. If
the frequency range is not specified then it is derived from the definition of the validation test case. 

The format is descibed below followed by an example.

\clearpage

\begin{center}
    \begin{tabular}{ | p{1.5cm} | p{4.5cm} | p{2.5cm} | p{5cm} |}
    \hline
    Line number & Typical value & Unit  & Description \\ \hline
1       & \#MOD\_cable\_lib\_dir & -    & Comment line \\ \hline
2       & .             & -             & Directory to read the cable model file to \\ \hline
3       & \#MOD\_bundle\_lib\_dir & -    & Comment line \\ \hline
4       & .             & -             & Directory to read the cable bundle model file from \\ \hline
5       & \#MOD\_spice\_bundle\_lib\_dir & -    & Comment line \\ \hline
6       & .             & -             & Directory to write the Spice cable bundle model file to \\ \hline
7       & \# two wires over ground plane, crosstalk model  & -    & Comment line \\ \hline
8       & two\_wires\_over\_ground    & -              & Cable bundle name Note there should be nothing else on this line \\ \hline
9       & \# bundle length  & -    & Comment line \\ \hline
10      & 2.0    & metres              & Cable bundle length \\ \hline
11      & \# incident field specification  & -    & Comment line \\ \hline
12      & 0.0    & V/m          & Amplitude \\ \hline
13      & 90.0  0.0  & degrees          & Wave vector angle k$\theta$ k$\phi$ \\ \hline
14      & 1.0  0.0  & relative amplitudes & Polarisation E$\theta$ E$\phi$ \\ \hline
15      & \#Transfer impedance terms  & - & this line must inlcude the words `transfer impedance' 
                                           to indicate that transfer impedance information follows \\ \hline
16      & 1 & integer  &    \# number of transfer impedances to include in the model \\ \hline
-       & 3 +1 & integer integer & \# shield conductor number and coupling direction for transfer impedance model 1 + is inside to out \\ \hline
-       & \# End 1 termination model  & -    & Number of sources and resistances = number of conductors \\ \hline
-       & 1.0    & V          & End 1, conductor 1 voltage source amplitude \\ \hline
-       & 0.0    & V          & End 1, conductor 2 voltage source amplitude \\ \hline
-       & 0.0    & V          & End 1, reference conductor  voltage source amplitude \\ \hline
-       & 50.0    & $\Omega$          & End 1, conductor 1 resistance \\ \hline
-       & 25.0    & $\Omega$          & End 1, conductor 2 resistance \\ \hline
-       & 0.0    & $\Omega$          & End 1, reference conductor resistance \\ \hline
    \end{tabular}
\end{center}

% continue on next page


\begin{center}
    \begin{tabular}{ | p{1.5cm} | p{4.5cm} | p{2.5cm} | p{5cm} |}
    \hline
    Line number & Typical value & Unit  & Description \\ \hline
-       & \# End 2 termination model  & -    & Number of sources and resistances = number of conductors \\ \hline
-       & 1.0    & V          & End 2, conductor 1 voltage source amplitude \\ \hline
-       & 0.0    & V          & End 2, conductor 2 voltage source amplitude \\ \hline
-       & 0.0    & V          & End 2, reference conductor  voltage source amplitude \\ \hline
-       & 50.0    & $\Omega$          & End 2, conductor 1 resistance \\ \hline
-       & 25.0    & $\Omega$          & End 2, conductor 2 resistance \\ \hline
-       & 0.0    & $\Omega$          & End 2, reference conductor resistance \\ \hline
-       & \# Type of analysis  & -    & Comment line \\ \hline
-       & AC    & -          & AC or TRANS \\ \hline
 \hline
& For AC analysis: & & \\ \hline
-       & lin    & -          & logarithmic (log) or linear (lin) frequency scale \\ \hline
-       & 1e3 1e8 1000 & Hz Hz integer & min frequency, max frequency  number of frequencies \\ \hline
 \hline
& For TRANSIENT analysis & & \\ \hline
-       & 0.01E-9 100E-9  & seconds seconds & \# timestep runtime \\ \hline
-       & 1e-9 50e-9	  & seconds seconds & \# pulse risetime pulse width \\ \hline
 \hline
-       & \# Output conductor number and end number  & -    & Comment line \\ \hline
-       & 1   1    & integer integer  & Output conductor number and end number \\ \hline
-       & lin    & -          &  For AC only: Output voltage scaling, linear or dB \\ \hline
-       & -10    & integer  &  \# order for transfer function fit model \\ \hline
-       & log   & -          & logarithmic (log) or linear (lin) frequency scale for transfer function fitting \\ \hline
-       & real real integer & 1e5 1e9 200 & \# fmin fmax number\_of\_frequencies for transfer function fitting \\ \hline
 \hline
    \end{tabular}
\end{center}

\clearpage

\vspace{5mm}
\textbf{\underline{AC example with a transfer impedance model }}

This example demonstrates a model of coupling from a single wire to a coaxial cable. The bundle is defined such that conductor 1 is the single wire,
conductor 2 is the inner coax conductor and conductor 3 is the coaxial cable shield.

\begin{verbatim}
#MOD_cable_lib_dir
./
#MOD_bundle_lib_dir
./
#MOD_spice_bundle_lib_dir
./
#spice_symbol_dir
./
# Specification for Spice model of two wire transmission line, no loss
zt_test
# cable bundle length (m)
1.0
#Incident field specification
0.0	amplitude (V/m)
90.0 0.0	ktheta kphi (degrees)
-1.0  0.0	Etheta Ephi
#Transfer impedance terms
1    # number of transfer impedances to include in the model
3 +1 # conductor number and coupling direction for transfer impedance model
# End 1 termination model
 0.02      End 1 voltage source list
 0.5
 0.0
300.0  	End 1 impedance list
20.0
0.0
# End 2 termination model
0.03        End 2 voltage source list
1.0
0.0
1000.0 	 End 2 impedance list
150.0
0.0
# Type of analysis
AC
log          # frequency scale (log or lin)
1e5 1e9 1000 # fmin fmax number_of_frequencies
# Output conductor number and end number
1    2
lin   # output type (lin or dB)
-10     # order for transfer function fit model 
log          # frequency scale for transfer function fit (log or lin)
1e5 1e9 200 # fmin fmax number_of_frequencies for transfer function fit
\end{verbatim}

\clearpage

\cleardoublepage