Creating a SPICE Subcircuit (.Subckt) manually

CREATING A SPICE SUBCIRCUIT

Want to automatically create SPICE subcircuits?
The Professional edition of 5Spice 2.0 includes a sophisticated tool to make a schematic into a Spice subcircuit (.Subckt). Later you can modify the schematic and then update the subcircuit with the tool.

Creating a SPICE subcircuit manually

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)

.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.

Let’s see an example.

a simple AC coupled amplifier

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 *

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 SPICE 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, PSpice, IsSpice and possibly others.

.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 mandates that you list all parameters on the .SUBCKT line and assign them a default value. You should enclose the parameter within braces {} wherever it’s utilized in the subcircuit. This also applies to the formula for Spice’s B source. You must register the program to input values for these parameters from the schematic; otherwise, the default values come into play.

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, PSpice, IsSpice and possibly others.

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.