Schematic capture is the process by which one uses a special-purpose drawing program to draw a schematic diagram of the circuit under design. In the gEDA environment, the schematic capture program is called "gschem". I assume you already know how to use gschem. For the purposes of creating SPICE netlists, you must use gschem to attach attributes to components, and possibly also incorporate other SPICE directives into your netlist. After you are done with schematic capture, you create the SPICE netlist by running gEDA's netlister "gnetlist" on your design.

There are several ways that spice attributes may be associated with a component using gschem. The way you choose to do this depends upon many factors, including the type of component, and the size and format of the SPICE model.

The following attributes are meaningful for SPICE netlisting, and may be attached from within gschem:

• refdes: The reference designator of the component. Valid values depend upon the component type and are given in the appendix.
• value: For passives, this is the component value. For actives, this is the type (model no) of the component (e.g. 2N3904, uA741). When a model for an active is instantiated separately from the component itself, the "value" attribute holds the name of the spice model.
• model: This holds a one line spice model for the component.
• file: This holds the name of a file. Typically, this is a file holding e.g. a SPICE .MODEL, .SUBCKT, or other SPICE code.
• model-name: This holds the name of the spice model referred to in a .MODEL or .SUBCKT statement. "model-name" is mainly used to identify the spice model name in the symbol "spice-model-1.sym". Active components should call out this name in the "device" attribute to associate the component with its particular spice model or subcircuit.
• type: This specifies the type of component and is used by spice when interpreting the model parameters. Valid values depend upon the device being modeled.

As a prerequisite to handling SPICE-related attributes, the SPICE netlister requires that all components must have a refdes attached to them. The refdes may be attached either by hand (which is laborious), or using the program refdes_renum included in the gEDA distribution.

Note that the first letter of the refdes must correspond to the appropriate letter for spice simulation. The refdes convention is given in the appendix

Basic passives

The most basic components which one encounters in spice are passive components like resistors and capacitors which have numeric values, but no other modeling attributes. In this case the following attributes must be filled in:

• refdes: The correct refdes for the component.
• value: For passives, this is the numeric value of the component (e.g. 100pF). For actives, this attribute may be filled in, but if no model attribute is available elsewhere in the schematic, the value is not used (in SPICE netlisting, anyway).

If only a refdes and value attribute are encountered, the netlister will write a single line into the output file.

Example resistor:
refdes = R2
value = 220
SPICE line generated: R2 0 4 220

(note that "0" and "4" correspond to the net nodes connected to the component, and are generated automatically by gnetlist.)

Example capacitor:
refdes = C22
value = 1UF
SPICE line generated: C22 4 23 1UF

Passives with additional attributes

Oftentimes, passive components have additional attributes attached to them for spice simulation. Examples of such attributes are temperature coefficients (for resistors) and initial conditions (for reactive components). These additional components may be incorporated into the SPICE file by simply attaching them to the component's "model" attribute. Specifically, the required attributes are:

• refdes: Correct component refdes.
• value: Numerical component value, as always.
• model: One line string holding additional parameters, formatted as a valid SPICE string.

This string is placed after the component value in the line generated by gnetlist. Therefore, it is important to format the string placed in the "model" line to be valid SPICE code. Otherwise, you will risk causing the SPICE simulator to barf.

Example resistor:
refdes = R5
value = 1MEG
model = TC=0.001,0.015
SPICE line generated: R2 0 4 220 TC=0.001,0.015

Transistors and diodes are generally accompanied by a device-specific model -- otherwise, SPICE simulation is pointless. The SPICE model may be either a short, one-line string of parameters, or a multi-line set of SPICE parameters. A typical one-line parameter string is a short list of parameters describing a small-signal diode. Typical multi-line models come from component vendors, who often provide models for their components in a text file. Since there are two broad formats of SPICE information, there are two approaches to incorporating these parameters into the schematic:

One line string of SPICE parameters

To incorporate a one line string of SPICE parameters into the netlist, the following attributes must be attached to the component:

• refdes: Correct component refdes.
• value: The model number or part number of the component.
• model-name: The name you wish to give the SPICE model. This is usually the model number or part number of the component. If you have already attached a "value" attribute to the component, this parameter is optional.
• model: One line string holding additional parameters. Do not place the model parameters in parentheses -- gnetlist will do this for you.

Example diode:
refdes = D5
model-name = 1N1004
model = IS=0.5UA RS=6 BV=5.20
SPICE lines generated:
D5 2 6 1N1004
MODEL 1N1004 D (IS=0.5UA RS=6 BV=5.20)

SPICE model file

To incorporate a file-full of SPICE parameters into the netlist, the following attributes must be attached to the component:

• refdes: Correct component refdes.
• value: The model number or part number of the component.
• model-name: the name you wish to give the SPICE model. This is usually the model number or part number of the component. If you have already attached a "value" attribute to the component, this parameter is optional.
• file: The file name of the SPICE model which you wish to incorporate into the netlist. This file name may specify either a relative or an absolute path, but it is probably better to use an absolute path to avoid problems if you ever move your schematic directory.

Note that you need to make sure that the model name held in your SPICE model file is the same as the "value" or "model-name" attributes you attached to the component.It is also a good idea to verify that the pin assignments in the model file correspond to the pin assignments made by the component symbol.

Integrated circuits are incorporated into the netlist similarly to transistors and diodes. As such, you may incorporate the spice information either as a one-line parameter string, or as a model file.

One line string of SPICE parameters

To incorporate a one line string of SPICE parameters into the netlist, the following attributes must be attached to the component:

• refdes: Correct component refdes.
• value: The model number or part number of the component.
• model-name: the name you wish to give the SPICE model. This is usually the model number or part number of the component. If you have already attached a "value" attribute to the component, this parameter is optional.
• model: One line string holding additional parameters. Do not place the model parameters in parentheses -- gnetlist will do this for you.

SPICE .MODEL or .SUBCKT file

To incorporate a file-full of SPICE parameters into the netlist, the following attributes must be attached to the component:

• refdes: Correct component refdes. Note that if the file holds a .MODEL, the refdes should start with U; if the file holds a .SUBCKT, the refdes should start with X. The netlister checks for the file type and tries to "do the right thing", but problems can arise if you don't follow this rule.
• value: The model number or part number of the component.
• model-name: The name you wish to give the SPICE model. This is usually the model number or part number of the component. If you have already attached a "value" attribute to the component, this parameter is optional.
• file: The name of the file holding the SPICE .MODEL or .SUBCKT which you wish to incorporate into the netlist. This file name may specify either a relative or an absolute path, but it is probably better to use an absolute path to avoid problems if you ever move your schematic directory.

Note that you need to make sure that the model name held in your SPICE model file is the same as the "value" or "model-name" attributes you attached to the component. It is also a good idea to verify that the pin assignments in the model file correspond to the pin assignments made by the component symbol.

There are two independent sources: voltage sources and current sources. For incorporation into a SPICE netlist, they both work the same way. To incorporate an independent source into your SPICE netlist, do the following:

1. Place the independent source on your schematic. (Do "Add" -> "Component" -> "spice" -> "<independent source name>.sym")
2. Double click on the block and add/edit the following attributes:
   • refdes: V? or I?
   • value: A one line string in SPICE format describing the source.

There are four dependent sources:

This section remains TBD.

Spice model block

In certain situations, you may wish to embed a spice model block directly into your schematic. This is done when you have several devices with a "value" attribute calling out for a spice model. Depending upon whether the spice block is one line or multi-line, you may embed the code in one of two ways:

One line SPICE model:

1. Place a spice model block on your schematic. (Do "Add" -> "Component" -> "spice" -> "spice-model-1.sym")
2. Double click on the block and add/edit the following attributes:
   • refdes: a?
   • model: model name (i.e. the model name used in the components being modeled.)
   • type: One of the valid spice component types defined in the spice spec.
   • value: The corresponding one-line spice model

Multi-line SPICE model:

1. Place a spice model block on your schematic.(Do "Add" -> "Component" -> "spice" -> "spice-model-1.sym")
2. Double click on the block and add/edit the following attributes:
   • refdes: a?
   • model-name: model name
   • file: Name of file holding SPICE model code (i.e. .MODEL or .SUBCKT).

Include block

The include block places a .INCLUDE directive into your netlist.

1. Place a spice model block on your schematic. (Do "Add" -> "Component" -> "spice" -> "spice-include-1.sym")
2. Double click on the block and add/edit the following attributes:
   • refdes: a?
   • file: The name of the file to include.

SPICE directive block

Placing a SPICE directive block into your schematic creates an arbitrary block of SPICE code in the netlist. The directive may be either statements held in a file, or a one-line string held in the "model" attribute. Examples of situations where this is useful include:

• .TEMP statement
• .IC statement
• Other SPICE statements for which gschem has no symbol.

To place a SPICE directive on your schematic, do:

1. Place a SPICE directive block on your schematic. (Do "Add" -> "Component" -> "spice" -> "spice-directive-1.sym")
2. Double click on the block and add/edit the following attributes:
   • refdes: a?
   • file: The name of the file to include.

In SPICE modeling, there are often situations where you wish to create a schematic representation of some particular component as a .SUBCKT, and then embed that component's model in a higher level schematic. A common example might be as follows: You are doing a microwave simulation, and want to use a capacitor model which includes parasitic inductances and resistances, as well as the capacitance. Capacitor manufacturers often supply a printed schematic showing a circuit topology incorporating parasitics, and specify values for the parasitics. You would like to draw the capacitor model using gschem, netlist it to create a .SUBCKT, and then use the .SUBCKT to model capacitors in a higher lever schematic.

Since this kind of task is very common in SPICE simulation, gnet-spice-sdb now supports it (starting with rev 20030331). To create a lower level .SUBCKT and use it in a higher level schematic, do the following:

1. Draw the schematic of the lower level component (e.g. the capacitor + parasitics) using gschem.
2. On the lower level schematic, place a spice-subcircuit-LL block (spice-subcircuit-LL-1.sym). This alerts the netlister that the schematic is a Lower Level .SUBCKT. Attach the following attributes to the symbol:
   • model-name = cap_with_parasitics
   (Of course, "cap_with_parasitics" is the example we use here. Use your own model name in your schematic.) Upon netlisting, this schematic symbol will cause the netlist to insert ".SUBCKT cap_with_parasitics " into the first line of the netlist file.
3. On the lower level schematic, attach a spice-subcircuit-IO symbol (spice-subcircuit-IO-1.sym) to each IO net (i.e. connection to the upper level). Number the refdeses of the IO symbols in the same order as you would like the IO nets to be listed in the .SUBCKT line in the output file. (i.e. P1 = first, P2 = second, etc.)
4. When you are done with the lower level schematic, netlist it in the usual way. For example, if your schematic is called cap_with_parasitics.sch, netlist it by saying:
   gnetlist -g spice-sdb -o cap_with_parasitics.cir cap_with_parasitics.sch
   This will dump the SPICE netlist into the file called "cap_with_parasitics.cir". Visually inspect the .cir file to make sure that netlisting worked correctly.
5. Next, create a symbol for the upper level schematic which will point to the .SUBCKT. Note that the symbol must have a refdes starting with the letter "X". To ensure that this happens, do the following:
   1. Use gschem to draw the symbol. I usually draw a box around a model symbol to distinguish it from a normal component. Make any other annotations desired.
   2. In the symbol, make sure that the pins are ordered identically to the order in which you have placed the pins in the .SUBCKT. This is done by editing the symbol with a text editor and setting the "PINSEQ" attribute. The netlister will output the pins in the order determined by the "PINSEQ" attribute.
   3. Using a text editor, give the symbol a "DEVICE" attribute like "capacitor-model". Do not assign the symbol one of the native device types listed in the appendix! The goal is to create a symbol whose refdes starts with "X", and if the "DEVICE" is a recognized type, this will not happen.
   4. Using a text editor, give the symbol the "REFDES" attribute "X?"
6. Create the upper level schematic. Place your newly created symbol on the schematic as many times as required & wire up the schematic in the usual way.
7. To point your symbol to the lower level .SUBCKT, double click on the symbol and set the following attributes:
   • file = cap_with_parasitics.cir
   • model-name = cap_with_parasitics
   as well as any other attributes required (e.g. refdes).
8. Now netlist your upper level schematic the usual way. The contents of each .SUBCKT file is dumped into the main netlist. Inspect your netlist visually using a text editor to ensure that it is correct. It is a good idea to pay particular attention to the following:
   • Verify that the ordering of the nets connecting the upper level netlist to the lower level .SUBCKT is correct.
   • Make sure that the upper level model-name and the lower level model name (on the .SUBCKT declaration line) are the same.

Once the netlist is created, you may simulate your design using any SPICE simulator desired.

One final note: The netlister writes the contents of the lower level .SUBCKT file into the main netlist every time it encounters a component with "FILE" attribute pointing to that file. Therefore, if you use the same component with the same model more than once in a design you should instantiate the model file using a "spice-model" symbol and point to it with each component. This is described in the "multi-line SPICE model block" section above.

Once the schematic is captured, a SPICE netlist can be generated running the gEDA utility "gnetlist" on the schematic files. Gnetlist is built to be customizable, and is able to generate a netlist of any desired format using a Scheme back-end, which does the real heavy-lifting of creating the netlist. The back-end Scheme file which implements SPICE netlisting is called gnet-spice-sdb.scm, and it lives in the ${PREFIX}/geda/share/gEDA/scheme directory.

Creating a netlist from a schematic is easy. To generate a SPICE netlist, just do the following:

• Save your schematic to <filename.sch>
• Create the SPICE netlist by doing "gnetlist –g spice-sdb <filename.sch>". The output is a netlist held in the file output.net. Alternatively, if you wish to give your output file a different name, set the output name using the -o switch. For example:
  gnetlist -g spice-sdb -o amplifier.cir amplifier.sch
  takes the design schematic called "amplifier.sch" and outputs a SPICE netlist named "amplifier.cir".
• Inspect your SPICE netlist using a text editor. Verify that there are no missing attributes or other netlist problems.

It is important to manually inspect your SPICE netlist prior to using it in simulation. Please remember that the netlister is still "alpha" quality, and some problems may still exist in netlist generation. The following list attempts to catalog common problems with the netlist and the associated fixes.

• ERROR_INVALID_PIN: This can happen if the symbol’s PINSEQ attributes don’t start at 1, or have gaps in the numbering. This must be fixed by editing the symbol itself in a text editor.

Please send comments or questions about this HOWTO to Stuart Brorson at sdb@cloud9.net.