ngspice/src/tcl

Spice Tcl module
$Id$
DESCRIPTION

Contained in this package is the source code for a spice tcl module and ng-spice-rework-14. 
It allows you run spice commands in tcl and run the spice simulator in the background 
so you can manipulate the results while spice is running.

THANKS:

Ng-Spice at http://ngspice.sourceforge.net for the spice simulator

ScriptEDA ( http://www-cad.eecs.berkeley.edu/~pinhong/scriptEDA ) for the idea and examples.

INSTALLATION

Requirements:
	ngspice, included (only tested with ng-spice-rework-13 and 14, should work with all rework versions)
	tcl WITH thread support compiled in (tested with tcl-8.3.3-65 and tcl8.3.4)
	BTL for tcl (tested with blt2.4y)
	pthreads (most modern OS's have this)

Installation:
	This package contains the ng-spice-rework-14 source code, which has been slightly modifed, and the tcl module source.
	The spice source is contained in the ng-spice-rework directory.
	Tcl modules's documentation is in the ng-spice-rework/src/tcl directory

	Please hide libgc.so (the garbage collector library), if you have it. You can put it back afterwards!
	This is because you don't want tclspice to compile with it included!

	Also if you want to run spice in the background you need to recompile
	tcl and tk to enable thread support if they haven't got it enabled already (redhat packages haven't).
	If you don't then tclspice will crash frequently!!!!
			
	The install commands are:
		From the root directory of the source:
		./configure --enable-tcl --enable-experimental --disable-shared
		make tcl
	    And as root:
		make install-tcl

USAGE

example:

$tclsh

%package require spice
	(to load the module)

Then you can run commands either by typing spice command directly or by typing spice <spice command>
For example:
	%spice::version
	%spice::source ./example.cir
	%spice::bg run 
	%spice::halt
	%spice::show
	%spice::plot_nvars 0
	%spice::plot_variables 0
	%spice::plot_datapoints 0
	%spice::bg resume
	%spice::halt
	%exit

Commands availiabe:

	spice has it's own namespace (spice::) which can be imported. 
	Although there are a few conflicts, so not all commands are imported.


	spice::spice <command>
		runs the spicified spice command in the foreground
	spice::bg <command>
		runs the spice command in the background
		All spice commands should be recognised
	spice::halt
		Stops(or attempts to) a spice background command (like run) (it simulates a ^C)

	spice::running 
      		returns 1 if a background process is running, 0 otherwise

	spice::get_output script ?stderr?
		runs the tcl script "script", catching std_out and maping it to the return value. 
		It can also catch the std_err and put it into the stderr variable.

	spice::get_param device param
		Returns the parameter of the device

	spice::spice_data
		Returns the names and types of avaliable spice
		 variables
		{name type} {name type} ... {name type}

	spice::spice_header
		Returns the current run's title, analysis name, date, and the number of signals as follows:
		{title ??} {name ???} {date ????} {variables ???}

	spice::delta ?value?
		Sets the value of delta to the given value, if given. 
		It returns the current setting of delta

	spice::maxstep ?value?
		Same as spice::delta but for the maximum stepsize allowed		

  variables:

	spice::steps_completed
		The number of simulation steps done so far.

The following concern the BLT vectors generated;

  functions:
	spice::spicetoblt vecName signal ?start? ?end?
		Sets the blt vector vecName with the contents of the spice signal, signal, 
		using the optional start and end index.
		
	spice::lastVector vecName
		Sets the blt vector vecName to contain the last spice state vector

  variables:
	spice::blt_vnum
		The number of signals avalible
	
The following only work if there is a plot stored;

	spice::plot_variables plot
        	returns a list of variables in plot "plot"
		plot is from 0-numofplots, newest plot being 0. 

	spice::plot_get_value name plot index 
       		returns value of varable "name" in plot "plot", at position "index"

	spice::plot_datapoints plot 
		returns number of time steps saved so far

	spice::plot_title plot 
		returns plot title

	spice::plot_date plot
		returns date string

	spice::plot_name plot 
        	returns plot name

	spice::plot_nvars plot 
		returns number of variables in the plot

Plotting functions;

	spice::plot
		The standard plot function has been wrapped to a Tk canvas ".c" See Tcl source in
		pkgIndex.tcl The callback functions are named gr_*, modify/override at will.
	spice::bltplot
		Instead of plotting: For each pair of vectors to plot spice::gr_Plot is called,
			"proc spice_gr_Plot { Xname Xtype Xunits Yname Ytype Yunits }" which you can override
		With the static Blt vectors "spice::X_Data" and "spice::Y_Data" containing the plot data.
	WARNING:
		If any of the Tcl callback functions cause an error then a crash may occour as tcl
		overwrites random data in the spice code. Not sure why.

SpiceWish:

This is a wish GUI to spice, it contains among other things graphical plotting.
To use it you need to have Tclx installed.
To initilise the GUI type:
% spice_init_gui <file>
	where file is your spice circuit file.

This will pop up a GUI for spice.

Commands available in spicewish:

spicewish::plot spice_vars ...
	Plots the given spice variables on a BLT graph.

Try "namespace import spicewish::plot" to make this your default plot command ( highly recommended ).

TODO & BUGS

1) plot and iplot don't work: window opens then tclsh stops, Xserver doesn't respond to spice requests
	They aren't really needed anymore, as you now have the blt vectors to play with,
	 and the Tk plot output and bltplot output.
2) Spice prints to stdout, unavoidable, sorry if it mucks up your commandline
3) tclreadline doesn't like this module very much

Stefan Jones
<stefan.jones@multigig.com>