Copyright © 2003 Richard P. Andresen

       

      CREATING A SPICE SUBCIRCUIT

      Want to automatically create subcircuits?
      The Professional edition of 5Spice 2.0 includes a tool to make a schematic into a Spice subcircuit.

      Creating a subcircuit manually is described here.

      A subcircuit definition contains Spice circuit elements, has a name and specifies the circuit nodes that connect it to the main circuit. Creating a subcircuit allows you to reuse the circuit multiple times in a design and in future designs. Subcircuits are similar to subroutines in software programming.

      Subcircuits may contain basic circuit elements, other subcircuit definitions, device models, and calls to subcircuits defined internally or externally. Spice program control lines may not appear within a subcircuit definition.

      In 5Spice, subcircuits are stored in the program’s library. You may add any subcircuit to the library and link it to the schematic’s subcircuit symbol.

      Caution

      As useful as subcircuits are, there is little help in finding errors except to run Spice and see it fail. The syntax must be perfect as well as the circuit.

      My experience is that developing very simple subcircuits is easy but developing more advanced subcircuits is slow and sometimes extremely frustrating. This is because there are no specialized tools to help find the syntax errors and bugs in a new subcircuit. It can be hard work, cryptic error messages and guessing.

    Basics
      • Subcircuit definitions are stored in text files. The file name may not contain the space character. In 5Spice's Library, file extensions .DOC, .BAK, .SAV, .TXT and .HTM are not recognized as subcircuit files.
         
      • All file lines must start in the first (left-most) column. When a line is too long to fit, break the line and use the + symbol as the first character of the extension line.
         
      • Spice sees "SPICE" and "spice" as the same.
         
      • Any device models or subcircuit definitions included in a subcircuit definition are strictly local (these models and definitions are not known/visible outside the subcircuit definition).
         
      • Any circuit nodes not included on the .SUBCKT line are strictly local with one exception: Spice defines node 0 (zero) as circuit ground in both circuits and subcircuits. node 0 always connects everywhere.
         
      • circuit nodes may be identified with either numbers or letters. examples: 1 2 In Out3
         
      • non-English speaking countries: numbers in Spice must be written as 1.23 (not as 1,23)

    • General form:
      • .SUBCKT  SubName Node1 Node2 Node3 ...

        circuit element lines

        .ENDS

      A subcircuit definition begins with the .SUBCKT line.

      SubName is the subcircuit's name. The name consists of letters and numbers from the English alphabet. The space character is not allowed. In 5Spice the maximum length for the name is 32 characters and the following characters may not be used in the name: ~ @ # ? . :

      Node1, Node2, etc. are the external nodes. Only these nodes connect outside the subcircuit. It is their order on the .subckt line that determines their external connection, NOT their name or number! 0 (zero) is not allowed as an external node.

      The circuit element lines which immediately follow the .SUBCKT line define the subcircuit. The last line in a subcircuit definition is the .ENDS line.

      Example

      a simple AC coupled amplifier

      Circuit1

      Draw the circuit. Number the circuit nodes 1 to 5 in any order. Ground is always node 0. Nodes 1,2,3 need to connect externally to provide power and get a signal in and out of the subcircuit.

      Choose a name for the subcircuit: ACamplifier

      consult Spice manual for syntax details for each type of part

      comment lines start with *

        * external nodes:  in power out

        .SUBCKT  ACamplifier 2 1 3

        R1 1 4 2K

        R2 4 0 500

        C1 2 4 10n

        * transistor node  order C B E. calls model named 2N2222

        Q1 3 4 5 2N2222

        Rc 1 3 2K

        Re 5 0 1e3

        .model 2N2222 NPN  (BF=50 IS=1E-13 VBF=50 and so on)

        .ENDS

      Note: If you  have a file with two subcircuits (Sub1,Sub2) that both call a third (Sub3), you can write Sub3 as a separate subcircuit in the same file.

      Example - Passing Parameters to the subcircuit

      5Spice and high end Spice simulators allow a subcircuit to accept parameter values passed from the schematic or from the subcircuit call line. The following shows the previous subcircuit but with the values of R1 and C1 as parameters. The parameter syntax shown for the .SUBCKT line works with 5Spice and PSpice. 5Spice also works with IsSpice parameter syntax.

        .SUBCKT  ACamplifier 2 1 3 PARAMS: Cin=10n Rbias=2K

        R1 1 4 {Rbias  * 1.12}

        R2 4 0 500

        C1 2 4 {Cin}

        .ENDS ACamplifier

      5Spice requires that all parameters be listed on the .SUBCKT line and given a default value. The order is not important. The parameter must be enclosed with braces {} where it is used in the subcircuit. This includes the formula for Spice's B source. Program registration is required to enter values for these parameter from the schematic, otherwise the default values are used.

      5Spice also allows defining parameters inside a subcircuit using .PARAM lines. See the program's Help for this and for information on using parameters in equations for component values, .PARAM lines or the B source.

      Important for 5Spice

      When writing more complex subcircuits, see subcircuits, 5Spice compatibility with in the program's Help index for details on the program’s Spice3 syntax extensions and PSpice syntax compatibility. This includes passing parameter values to subcircuits.

      Good Practice

      • start simply, get the subcircuit working, add complexity later
         
      • add a comment line identifying the circuit function of the external nodes listed on the .SUBCKT line
         
      • place any models and subcircuits defined within the subcircuit at the end
         
      • add the subcircuit name to the .ends line: .ENDS MySub1
         
      • avoid PSpice specific syntax if you want your subcircuit to work with all simulators
      •  

      Calling  your Subcircuit

      In schematic based simulators like 5Spice, the schematic symbol automatically calls the subcircuit linked to the symbol. If you are using traditional Spice or calling a subcircuit from another subcircuit, write the call as follows:

        X Node1 Node2 Node3 ... SubName

        example: Xamp  5 4 2  ACamplifier

      The identifier must start with the letter X. SubName is the subcircuit's name. Node identifiers Node1, Node2, etc. are the node numbers/names in the calling circuit that connect to the subcircuit. The number of nodes on the call line must match the number listed in the .subckt line of SubName. Spice connects the nodes from the call line to the subcircuit in the order they are listed.

      Note: In 5Spice, if one subcircuit calls another subcircuit, both subcircuits must be in the same file.

      Calling with parameters

      If the subcircuit has parameters defined, they are shown when editing the schematic symbol and new values can be assigned. When writing a call  by hand, parameter values placed in the call line override the  default values defined in the subcircuit. The parameter syntax shown works with 5Spice and PSpice. 5Spice also works with IsSpice parameter syntax.

        Xamp 5 4 2  ACamplifier PARAMS: Cin=20n Rbias=2.7K

       

      <---------  end of creating spice subcircuit --------->

       

      Testing your Subcircuit in 5Spice

      You may want to create a separate Library subdirectory ...\Library\Subcircuits\Testing for debugging your subcircuits. Place the file containing the subcircuit there. (To find where the Library is located, go to main menu>TOOLS>Rebuild Spice model Library)

      In 5Spice, go to the Tools menu and Rebuild the Library.

      Place a subcircuit symbol in the schematic and double click it to edit it. In the edit window that opens, use the Search box to search for the name of your subcircuit (not the name of its file). Click the subcircuit name in the listing.

      Problem on selecting

      If there is a graphic image next to its name in the listing then 5Spice has found a problem in the subcircuit. If the error message is PSpice compatibility problem, see the section Important for 5Spice above. Review the subcircuit carefully for syntax problems. You can find which line the problem is on by opening the report file generated when the library is rebuilt.

           report file: ...\Library\IndexSub.ndx.rpt

      5Spice only checks to be sure it can find models and subcircuits and for unsupported syntax and PSpice syntax compatibility. It does not syntax check every line.

      Note that users make frequent syntax errors in the formulas used with the B source.

      If you can’t find a problem, open the subcircuit file in a text editor (Notepad) and copy the .subckt and .ends line to make a new, empty subcircuit definition with the same name. Then rename the original subcircuit (add "x" on end of name) and save the file. Rebuild the Library again (will be no errors in the empty definition). Finally restore the name of your original subcircuit, comment out the empty one and save the file. The program will now let you select and load the subcircuit so you can see what error messages WinSpice (the Spice simulation engine) produces.

      selection OK

      When the subcircuit has been selected, draw the test schematic - something very simple for DC Bias. Run the DC Bias analysis. If things work, great. Do some checking that the subcircuit functions as you expect. Remember that a 1M resistance in a Spice subcircuit is defined as 1e-3 ohms!

      Error found by WinSpice

      If the simulation failure window appears with an error message, it may suggest a line in 5Spice's circuit transfer file that has an error. Find the file (Xfer1.cir or Xfer2.cir) in 5Spice/WinSpice and find the indicated line number in the file. The subcircuit lines you see are copied from the subcircuit file, sometimes with the syntax translated. Now open the subcircuit file, find the matching line there and fix the error in the subcircuit file.

      Also open the WinSpice program by clicking on its button on Windows' bottom toolbar and check if there were multiple error messages. There are so many possibilities with untested subcircuits that 5Spice may not report them all.

      IMPORTANT:  Modifying the subcircuit file and reloading

      As you modify and save the subcircuit file, you do not need to rebuild the Library unless you modify the .subckt line. You do need to double click the subcircuit symbol in the schematic and then click the OK button. This loads the modified version of the file into the program.