bbsim(1)

NAME
bbsim.pl -Circuit simulation script.

SYNOPSIS
bbsim [-i] <input deck>

DESCRIPTION

bbsim is a perl script which links together freely available tools in the Linux operating system. The main purpose of this script is to generate graphic output of circuit simulations using the spice 2g6 circuit simulation program. Spice was distributed with RedHat version 5.2 and is freely available. ftp://linux-rep.fnal.gov/pub/mirrors/old-releases/redhat-5.2/i386/RedHat/RPMS is one such source. bbsim uses GNU Octave to generate graphical output for the user. GNU Octave is an excellent program available from many mirror sites. Note that throughout this document the terms deck, netlist and circuit are used interchangeably. I assume that there is at least some familiarity with at least one flavor of spice. If not, then it is advisable that you read the documentation that comes with spice 2g6. I also assume that there is some familiarity with gnuplot or GNU Octave. If not you should probably get familiar with those programs also.

The typical order of operations for this script would be to load a netlist either on the command line with the -i at startup or through the load command. Then using the setup command, setup the type of analysis that you would like to perform. If you have setup the analysis requests on your own in the netlist then it is of course not necessary to do this. Once the circuit is set up to be simulated use the simulate command to run spice on the circuit. If there are any errors from the spice output these will be printed out in red to the screen. Once the simulation has been successfully run, you can view the output by typing the appropriate command for the type of analysis performed. For example, if you did a transient analysis you would use the 'tran' command to see the output.

To get graphical output, use the plot command followed by the type of analysis that was performed. For example, for the same transient analysis as above you would type 'plot tran' This will start up Octave and display a graph of the output. At this point you can use the cursors by typing the command 'cursors' The numeric keypad keys control the movement of the cursors. There are several options available at this point. See the commands section below for the full listing. Enjoy...

OPTIONS
-i netlist/deck The script will load the netlist specified after -i The script operates in one of three modes. The first mode is when the script is initially started. This is the simulation/setup mode. There are several commands available in this mode:

COMMANDS
load 'input deck' This command will first verify that the specified deck does exist and then will open it up and read the contents into memory. activate 'deck' This command will set the specified deck active, which means that if you use the simulate command, then that is the deck which will be simulated. The currently active deck will be the one that is displayed on the command prompt. Using activate without any arguments will list the currently loaded decks that could be activated. edit This will start up an editor session with the currently active deck. By default this will be the vi editor because it has the highest probability of being on every machine. You can change this by changing the EDITOR environment variable at the top of the script. deck This command will display the contents of the currently active deck. decks This will display the currently loaded decks. help '<command>' Without any arguments this will give a list of the commands. If an argument is given then it will print out a brief info message about the command. quit|exit exit the script. setup This command will guide the user through an interactive setup of the analysis requests to be passed on to spice. Currently AC, Transient and Fourier analysis are implemented. simulate This causes the currently active deck to be simulated by spice. The output from the analysis requests that were set up will be parsed out of the spice output. This data will then be stored. ac This command will print out the results of an AC analysis that was performed on the currently active circuit. If no AC analysis has been performed, an error will be printed to notfy the user. tran This command will print out the results of a transient analysis that was performed on the currently active circuit. If no transient has been performed, the user will be notified with an error message. four This command will print out the results of a fourier analysis that has been performed on the currently active circuit. The fourier output from spice is in the form of a voltage component. This value is parsed out of the file and changed into decibels RMS. Future versions of this script will probably contain some flexibility in this output. Note that if you would like db peak, you should add 3db to these values. If no four analysis has been performed the user will be notified with an error message. node [1 2 3...] If called without any arguments this command will display all of the DC Bias voltages from the spice output. If called with node numbers of the form 1 2 3.... then only those values will be displayed. Note that if you do a transient analysis DC bias is not calculated by spice by default. You have to include a .OP statement for this to happen with transient analysis. Keep this in mind if you set up the netlist on your own. If you go through the interactive setup of this script, this is included by the script. cd 'dir' change directory. ls list the contents of the directory. pwd Print working directory. plot <tran|ac|four> This will plot the results of an ac, transient or fourier simulation. This works by starting up an interactive session with GNU Octave and reading the output values that were stored during the simulation into the octave program through a pipe. Once the plot is up, the user will be in the plot mode of the script in which there are a few unique commands which will be described below. Plot mode will be obvious by the presence of the plot and the command prompt will display plot in it.

  PLOT COMMANDS
These are the available commands once the script is in plot mode. cursors This command will turn on the cursors for tracing of the output data. The cursors movement can be controlled by the '8', '6', '2', '4' keys. The '5' key will place the cursors in the middle of the data. Use the 'q' key to exit the cursors. There are several keypress operations available inside of the cursors function. 'm' while the cursors are active, pressing the m key will mark the current location of the cursors with an arrow and a label. The following keys effect the arrow and label 'r' This will cause the arrow and label to be rotated around to adjust the placement. 'l' This will cause the length of the arrow to be increased. 's' This will cause the length of the arrow to be decreased. 'i' This will cause the spacing between the label and the end of the arrow to be increased. 'd' If used while in the marking mode this will cause the spacing between the label and the end of the arrow to be decreased. If used while the cursors are active, this will delete arrows from the last to the first marked. 'q' This will exit the mark mode and return the user to the cursors where they were left off. save This will save the graph to the current directory. The default format will be png. Future versions of this script will probably have some more flexibility with this. gset [arg1, arg2 ...] This passes the argument to octave. Octave has many gset functions most of which are documented. For the entire gset listing see the help pages for gnuplot. replot This will replot the plot. This is to be used with the gset command function. Changes will not visible until a replot has been done. deck As above this will print out the text of the currently active netlist. node As above this will show the dc values of the nodes in the circuit. Again, if you are doing a transient analysis you must put a .OP in the netlist to get the bias values. If you use the setup utility in this script it will be done for you. help [command] If called without any arguments this will print out a list of the commands available in the plot mode. If an argument is specified a brief description of the command will be printed. exit|quit This will exit the plot mode of the simulator. You will be placed back into the starting mode and the plot will be killed.

CONDITIONS
As always, there are no waranties with this free software. The only conditions for the use of this script are that if you make modifications please let me know so that I can add them if they are advantageous. Please make an effort to read the code and understand what is going on. if you don't know perl and are using Linux, you should probably learn it.

BUGS
At this stage probably several. I have exercised the script for my purposes and it seems to be working well but there are a few problem areas. If you do an AC DEC plot and use use the labels the spacing and length controls will not work totally correct. I am working on it. The log x axis makes this challenging.

SEE ALSO
spice, octave, gnuplot, perl

AUTHOR
Billy W. Bryant Jr. bbryant@cubsmvp.com