

***************************************************************
*                            HP-SPICE                         *
***************************************************************


HP-SPICE (c) 1993
All rights reserved
Blair Mac Donald
28 Laurentide Drive,
Halifax, Nova Scotia, 
Canada
B3M 2N1

Home (902)-445-5672



DESCRIPTION:

HP-SPICE is an AC spice type circuit simulator.  The program is limited 
to AC analysis, but by selecting a very low frequency (not 0) it can give
a reasonable DC approximation.


DISTRIBUTION:

The program is available as a shareware version with some limitations on 
its capability and may be freely distributed with the following conditions:

1. This document file must be distributed with the program
2. The program must be distributed unaltered
3. The shareware version must be distributed with out charge

The limitations of the shareware version are:

1. No sub-circuit capability
2. No circuit file storage or loading capability
3. No plotting or graphical function plotting 

The registered version of the program allows :          

1. Sub-circuits.  These may be stored in a directory called SUBC and 
   used in any number of circuit files.  Devices such as transistors and
   op-amps may be modeled with sub-circuits.

2. Circuit file storage and loading.  Files may be stored easily for 
   later analysis.  Files are stored in a directory named SAVE

3. Plotting and graphical analysis.  This allows plotting of such things 
   as gain, phase, input impedance and other mathematical relationships
   between circuit elements.  The plots can then be read using the built
   in graphics functions of the calculator.

The registered version is available from the author for $30.00 Canadian.





SYNTAX:		[]        - Any capitalized word in brackets is an HP48 key.
		" "       - Any text between quotes is to entered literally
		            but do not enter the quotes.
		CAPITALS  - Any capitalized word is a HP48 variable.
		<>	  - Parameters for commands or devices appear between
			    these.


INSTALLATION:

                Both versions install as libraries in port 0 and the 
                following procedure works for both.

NOTE:           The registered version of the program will leave two
                small programs in the HOME directory.  These programs 
                called STP and RET are used by HP-SPICE so if you
                have any variables in the HOME directory with the same 
                names they will be over written.


Shareware &     1. Load the file SPICE.LIB or SPICE.SHR, via the serial
Registered         port, into the HOME directory.
versions	2. Store in port 0 - enter ":0:777" [ENTER] [STO]

	        3. Turn the calculator off then on to install

                4. Purge the variable SPICE.LIB or SPICE.SHR in the HOME 
		   directory.  If you are installing the shareware version
		   of the program it is now ready to use.


Registered      5. Create the sub-directory SAVE in the HOME directory.
version            This is where all circuit files will be stored.
only            
		6. Load the file SUBCIR into the HOME directory.  Recall
                   this file to the stack - type "'SUBCIR'" [RCL].  Now 
                   store this file in the SUBC directory - type
                   "'SUBC'" [STO].  This will create the sub-directory
                   SUBC and store the sub-circuit examples in it.
                   Now purge the variable SUBCIR.

                7. The registered version will also install two small
                   programs in the HOME directory.  These are called 
                   STP and RET and are used by HP-SPICE to keep track
                   of the directory path, they may be of use for other 
                   programs as well.  STP takes  a list of the present
                   path as an parameter and stores it in a variable P.
                   RET will return to the path stored in P.
                   
                   EXAMPLE << [PATH] [HOME] STP <place the name of what ever
			      program in the HOME directory you wish to run
			      here> RET>>
                   The above program uses the PATH command to get a list 
                   of the current path, then the program moves to the HOME
		   directory. STP then stores the path in P and a program in
		   HOME is then executed.  RET then allows a return to the
		   original directory and purges P.


OPERATING MANUAL:

                
KEYS:
                
[START] - Starts program, prompts for the number of nodes and
          in the registered version allows for file loading.
	  Loading is done by pressing the menu key under the 
	  name of the file to load then press [ENTER]. P will
	  appear in the program list, this is the return address
	  for RET not a circuit file.If you do not want to load a
	  file just press [ENTER] and INPUT will automatically
	  be started.  

[INPUT] - Allows the circuit file to be keyed in.  If 
          [INPUT] is used later it adds to the circuit file.
          This command is called up automatically after [START]
          in the shareware version.  In the registered version 
          if a file is not loaded from the START command, INPUT
          will start automatically.  To exit input press "0" as
          the input then press [ENTER].

                        The allowable devices are:
                        R = resistor
                        C = capacitors
                        L = inductors
                        I = current source
                        V = voltage source
                        G = voltage controlled current source
                        F = current controlled current source
Registered   ------->   S = sub-circuit
version only                



        The input format is as follows:

        Resistors           R# <+node> <-node> <value>
                        
        Capacitors          C# <+node> <-node> <value>
                        
        Inductors           L# <+node> <-node> <value>
                        
        Current source      I# <+node> <-node> <value>
                        
        Voltage source      V# <+node> <-node> <value>
                        
        Voltage controlled  G# <+node> <-node> <+control> <-control> <gm> (gain)
        current source    

        Current controlled  F# <+node> <-node> <+control> <-control> <gain>
        current source

        Sub-circuit	    S# <nodes or parameters in any order> <sub-name>

                        
        For resistors, capacitors and inductors the +node and -nodes
        may be reversed.  In sub-circuits, nodes and values may
        be expressions in stack syntax.
                        
        The controlled sources are three terminal sources of the following
	form:

		  +control-------	-------- +node
				|	|
				\       |
				/      / \
		             (R)\      \ /(I)
				/       |
				|       |
		  -control---------------------- -node

	            

	  The + and - nodes may be reversed to make the source invert.
	  The main difference between current and voltage control is the value 
	  of R.  R = 10E20 for voltage control and 10E-20 for current control.

	  This should be kept in mind when modeling transistors.
          The voltage controlled current source produces
          better results when modeling transistors FETs and op-amps.  To make
          a voltage controlled voltage source, use the voltage controlled current
          source with a resistor in parallel with its output (handy for op-amps).
                
[SOLV]  - Solves for all node voltages and displays the results as complex
	  numbers on the stack.  The interactive stack may be used to view 
	  the results.
          SOLV will ask for the frequency as an input and the displayed 
          voltages will be calculated for this frequency.

[CIR]   - This is a typing aid as it is the name of the variable in which
          the circuit file is kept.  To edit this file press
	  "'[CIR]'" [VISIT]. The circuit file is stored as a list of strings
	  and may be edited at any time.

[PLOT]  - PLOT is a very useful plotting utility (not available in the
	  shareware version).  It may be used to plot the response of a 
	  circuit vrs. frequency (the X axis is always frequency).  PLOT will
	  ask for a function to be plotted.  This may be any mathematical
	  function (in algebraic form) to be performed on the output voltage
	  matrix.  This matrix is a one dimensional array of voltages with
	  the node number as the index to the array.  Please note that all 
	  voltages are complex and the HP plot functions do not plot complex
	  numbers so the expression to be plotted must select the real, 
	  imaginary, magnitude or phase to be plotted.  PLOT will then ask 
	  for a frequency range to plot.  Key this in as follows:
	  <minimum frequency> [SPC] <maximum frequency> [ENTER].  Using the built
	  in HP plot functions a Y range should be specified ([AUTO] may be
	  used but it is very slow).

	  The X axis of the plot is the log of the frequency (this produces
	  semi-log plots).  If coordinates are read from the plot 
	  (in rectangular form) the X value should be anti-logged to get
	  frequency.  The default X axis resolution is .3 (3 points per decade)
	  and may be changed but plot time will increase.  When all of the above
	  steps have been done press [DRAW] to see the plot.

	  After all plot functions are complete perss [ATTN] to exit graphics
	  mode and [CST] to return to the main menu.

          EXAMPLE OF FUNCTION TO BE PLOTTED:
                        
          To plot the dB difference between node 1 and node 2 use 
	  20*LOG(ABS(V(1)/V(2))).
          The ABS function returns just the magnitude of the voltages.

          To plot the phase difference between node 1 and node 2 use
	  ARG(V(1))-ARG(V(2)).
          The ARG function returns the angle of the voltages.
                 
                NOTE:  the plot takes a while even on small circuits

[EXIT]  - Exits HP-SPICE and purges all variables.  The SAVE option allows
	  saving of the circuit file in the SAVE directory.  Just key in a 
	  file name with the ".CIR" extension or select a file from the menu
	  and  press [ENTER].  
                
		NOTE: - Save is not available on the shareware version.
		      - The main menu is stored in CST and may be recalled 
			at any time by pressing [CST]

SUB-CIRCUITS:

	Sub-circuits offer increased flexibility in circuit modeling.  They
	allow devices to be entered that are not contained in the basic device
	list.  A sub-circuit must consist of only the basic HP-SPICE devices
	described above and may not call another sub-circuit (I'm working 
	on this one!).  Devices such as transistors, FET's and op-amps may
	be modeled, stored and used in any number of circuit files.
	The form of a sub-circuit call is flexible as the sub-circuit contains 
	the code to read all passed parameters.  Sub-circuits also may contain
	imbedded nodes that do not appear in the calling file.

	There are several variables used in sub-circuits that the user should
	know of: 
		1. PL - Purge list.  This is a list of global variables to 
			be purged when exit is executed.  Any variables used
			by the sub-circuit should be added to this list so
			HP-SPICE will be able to purge them at the exit command.
			All sub-circuit variables should start with the letter
			s (note case) so as not to conflict with HP-SPICE.  All nodes
			sub-circuit variables must be global.

		2. N  - Number of nodes.  The is a real number that contains
			the present number of nodes in the circuit file.  It
			must be updated each time a new internal sub-circuit
			node is used (the [INCR] command is handy for this).
			
	Sub-circuits take their parameters from the stack and the sub-circuit
	file builder will insert the sub-circuit into the circuit file.  Because
	of the structure used in HP-SPICE, sub-circuit calls must be the last
	entries in the circuit file.  Imbedded programs are allowed in sub-circuits 
	provided they are followed by the [EVAL] command.

	The structure used for sub-circuits is as follows:
		1. A small program to read parameters from the stack and
		   store them in global variables.  This program should
		   also add to variable names to the purge list (PL).

		2. A list of strings that contain the basic HP-SPICE
		   devices that make up the sub-circuit.

	EXAMPLE:

	An op-amp may be modeled as a voltage controlled current
	source with its output in parallel with a resistor and 
	capacitor.  In order to illustrate how to keep track of
	internal nodes this example will also use a series resistor
	connected to the output so one internal node will be used.

	Sub-circuit call:	S1 1 2 3 op amp
		
	The name of the sub-circuit is op amp and it has three external
	nodes 1, 2 and 3.

	Sub-circuit definition:

	The sub-circuit will define the first node as the non-inverting
	input, the second node as the inverting input and the last node 
	as the output.

		<< PL {inm inp out L1} + 'OUT' [STO] 'INM' [STO]
		   'INP' [STO]
		   {"G1 s1 0 INP INM 4000"
		    "R1 s1 0 1"
		    "C1 s1 1 637E-6"
		    "R2 'N' [INCR] [DUP] 's1' [STO] OUT 1"}>>

	The first portion of the sub-circuit adds the list to PL and stores all
	passed parameters.  The list that makes up the sub-circuit follows and 
	is evaluated from the bottom to the top so N will be incremented and 
	stored in L1 during the entry of the last line into the circuit file
	(this occurs first).  Internal nodes must be defined (L1 in the example above)
	in the lines following the line which first uses the node. 
		


EXAMPLE OF A HP-SPICE RUN:

	This example will deal with a simple RC low pass filter.  The resistor
	value will be 1000 ohms and the capacitor will be 159 nF.  The driving
	source will be 1 volt and the circuit will have 2 nodes.

	To start HP-SPICE press [LIBRARY] then press the menu key
        under SPICE in the menu display.

        The menu display will now display:
        [START] [INPUT] [SOLVE] [PLOT] [EXIT]

	Press [START] and after the copyright notice, HP-SPICE will ask for the number
	of nodes in the circuit (remember ground is always node 0).

	The menu will now display:
	[START] [INPUT] [SOLVE] [CIR] [PLOT] [EXIT]

	Enter "2" for the number of nodes and press [ENTER].

	If you have the shareware version INPUT will be automatically start.  If you have
	the registered version, HP-SPICE will ask if you want to load a file before continuing.
	Press [ENTER] in the registered version to go to input without loading a file.

	Now enter the circuit file as follows (check the section on syntax
	as quotes are not entered).

		"V1 1 0 1" [ENTER]
		"R1 1 2 1000" [ENTER]
		"C1 2 0 159E-9" [ENTER]
		"0" [ENTER]				This exits input.

	Now press [SOLV] and HP-SPICE will ask for a frequency.
	Enter 1000 Hz for the frequency as follows:  "1000" [ENTER]

	The node voltages will be displayed on the stack.  The stack level is the node number.
	
	Press [EXIT] to leave HP-SPICE.

			




