# Open source Spice cable bundle modelling project

The software allows the generation of multi-conductor cable bundle models
for inclusion in Spice circuit simulations for the purposes of EMC/ EMI studies.
The models include the following features:

Multi-conductor cables

Shielded cables

Frequency dependent cable properties

Incident field excitation

Transfer impedance coupling through imperfect shields


A set of test cases is included in the project. These may be run automatically
to provide a test of the installation and they also provide examples to aid the 
generation of new cable bundle models.


## The project files and directory structure is summarised below:

license.txt,  COPYING.txt, COPYING.LESSER.txt  : License information
version_information.inc: Current version tag 
clean_project:	A script to remove all executable files, object files, module files and test case files 
		to provide a clean structure before updating the project repository

SRC            : source code

DOCUMENTATION  : theory document and user guide

TEST_CASES     : directory of test cases and a script to run these automatically

SOFTWARE_NOTES : Notes regarding the software developments, work log, knoown problems etc

bin            : binary executable files

obj_mod        : Object files and fortran module files

## Compiling and runnning the code

### Unix installation for ngspice

Prerequisites: 
1. ESA_SPICE_CABLE_MODELLING project obtained from the git repository
2. fortran complier
3. ngspice
4. gmsh    (mesh generator)
5. gnuplot
6. text editor (nedit, gedit or similar)

If the transmission line models are to be included in other circuits 
then you will need the following:
7. gschem (schematic capture tool)
8. gnetlist (tool to create a spice circuit file from the output of gschem)
9. gspiceui (tool to create and run a spice simulation)

Compilation Process:

from the top level go into the SRC directory

cd SRC

edit the Makefile as required to set the fortran compiler name and flags as required 
(the system is set up for gfortran by default, some notes are included in the Makefile)

compile the code with the command

make

(Note that has been observered to fail when the software is installed in a path which 
contains spaces so please ensure that there are no spaces in the path...) 

The executables will be put in the /bin directory in the top level of the project

### Running the test cases

from the top level go into the TEST_CASES directory
cd TEST_CASES

Edit the file generate_spice_cable_model if required to set the directory for the
schematic circuit symbols created for the spice transmission line subcircuits, SYMBOL_DIR.

SYMBOL_DIR can be set to the local directory 
SYMBOL_DIR="./"
or to a directory which is used by gschem for example
SYMBOL_DIR="/usr/share/gEDA/sym/local/"

The script generate_spice_cable_model can be used to run one or all test cases, 
view the results, check the latest results against saved reference results etc.

Run using the following command:

generate_spice_cable_model action

action is the process to run:

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                              
				
action=plot NAME              : Plot the results of the spice validation model and
                                analytic solution to x11 terminal
				
action=plot_wxt NAME          : Plot the results of the spice validation model and 
                                analytic solution to wxt terminal 

action=plot_jpg NAME          : Plot the results of the spice validation model and 
                                analytic solution to .jpg file

action=plot_ref NAME          : Plot the spice validation model results against  
                                reference results to x11 terminal

action=plot_ref_wxt NAME      : Plot the spice validation model results against  
                                reference results to wxt terminal

action=plot_ref_jpg NAME      : Plot the spice validation model results against  
                                reference results to jpg file

action=plot_bundle NAME       : Plot the bundle cross section to x11 terminal

action=plot_bundle_wxt NAME   : Plot the bundle cross section to wxt terminal

action=plot_bundle_jpg NAME   : Plot the bundle cross section to jpg file 
				
action=reference  NAME        : Update the reference results and the difference
                                between the spice model and validation model  
                                with the current set of results
				
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
				
action=clean  NAME            : Remove all files except those required to set up
                                the problem and the reference results. 
				
action=clean_all  NAME        : Remove all files including the reference results. 

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

(note that if there are problems running the generate_spice_cable_model script this 
may be due to the file not being an 'executable' file. This can be fixed with
chmod +x generate_spice_cable_model
note also that it is useful if the local directory is included in the search path, 
if it is not then you will need to use 

./generate_spice_cable_model 

instead of 

generate_spice_cable_model

As an example, run all the test cases with

generate_spice_cable_model run

The result comparisons given in the STATUS at the end of the process give a
measure of the difference between the Spice model result and the analytic solution 
for each of the test cases run.

plot the comparison between the analytic and spice validation model results for all
test cases with

generate_spice_cable_model plot

(note: press RETURN to move from one plot to the next)

## Acknowledgement:
This work was funded by ESA under contract number
4000112765/14/NL/HK