The XCircuit Schematic Capture Tutorial

Getting Started
Task1 Acquaint yourself with XCircuit
Task2 Run the program
Task3 Drawing a circuit for SPICE simulation
Task4 Introduction to parameters
Task5 Drawing a circuit with parameters
Task6 Making a new "fundamental" object
Task7 A schematic with symbol-less schematics in the hierarchy
Task8 Identifying electrical connections
Task9 A symbol on its own schematic
Task10 "sim" format and flattened
Task11 "pcb" type netlists
Task12 Multiple-gate chips in PCB netlists
Task13 Modifying netlist formats
Task14 Example: A bridge rectifier for a PCB

Getting started

This tutorial is provided to help users get up and running with the schematic capture capabilities of xcircuit. In order to get the most out of this page, you should have already downloaded, compiled, and installed the xcircuit program and its libraries, and xcircuit should be compiled with schematic capture capability (on by default; see the Imakefile for details).

IMPORTANT NOTICE: It is necessary for you to have the new (version 2.3.3) distribution of xcircuit compiled and installed to get the correct behavior in the tutorial. In particular, the PostScript prolog has changed and if the old one is prepended to the new xcircuit files, the files will not be printable or viewable from a PostScript previewer.
There are additional differences between versions 2.1(beta) to version 2.3.3, mainly in the way symbols and schematics are associated with each other. The new methods are incorporated into this tutorial. Version 2.3.3 also corrects some errors in netlist generation, and is generally more stable. Versions before 2.3.3 will not produce pcb-style netlists as featured in this tutorial.

Task 1: Acquaint yourself with XCircuit

If you are not yet familiar with the basic features of xcircuit, I recommend you to peruse the basic XCircuit tutorial for essential features of the program which will not be reiterated here.

Task 2: Run the program

XCircuit now starts in schematic capture mode unless explicitly compiled without the feature. So just start xcircuit as you normally would:

xcircuit

Xcircuit in schematic capture mode will start with a window which has a menu button for ``Netlist'' and two buttons at the bottom left-hand corner, one of which is blank and the other which is colored red and labeled ``Schematic.'' The bottom buttons can be interpreted to mean that the current page is a schematic drawing, and this schematic has no corresponding symbol (more about this later).

There is a menu button, "Options->Disable (Enable) XSchema", which toggles the visibility of the ``Netlist'' menu button and the two status buttons at the bottom. In case you're working on a drawing which has nothing to do with schematic capture, you might prefer to have the option disabled. This does not affect the program in any way other than to make the buttons disappear so that xcircuit looks like the original version without the schematic capture features.

Task 3: Drawing a circuit for SPICE simulation

This task outlines some of the features of xcircuit used to make a simple circuit. In this and the following tasks, you will create an analog circuit, an operational amplifier, and make it into a symbol to be used as a subcircuit of a more general circuit (an integrator). First you will draw a circuit using simple (default) devices, and later I will show how to pass parameters to devices, such as width and length of individual MOSFETs.

Drag the elements which you need from the built-in library to (a clean) Page 1. Namely, the nMOS, pMOS, Vdd, and GND symbols.
Duplicate elements (copy (c), flip (f)) as necessary and connect with lines to produce the following transconductance amplifier schematic:

A transconductance amplifier, schematic drawing.
Either drag the "dot" object from the library page or use the period key (".") to place connections between the wires at junctions. This is not strictly necessary, as xcircuit will deduce connectivity from the T-connections of wires, not from the "dot" symbols; it is merely a matter of preference depending on the style with which you like to draw circuits. In the case of wires crossing at a junction, the dot is necessary since crossing wires generally do not indicate a connection in schematic diagrams. You may also use a "jumper" object to indicate that two crossing wires do not connect although this, like the use of dots at T-junctions, is a matter of style and personal preference.
Add "circle" connections at the inputs and outputs. Once again, this is a matter of style; the actual inputs and outputs from the netlist's point of view will be indicated by pin labels (see next step). The resulting diagram looks like the following:

Same transconductance amplifier, a little fancier style.
Because the amplifier will be a SPICE subcircuit, it is necessary to tell the netlist generator where the input and output ports are. For this, you need pin labels. Pin labels differ from ordinary labels in several ways: By default, they are colored red (though this can be changed), and are placed with a slight offset from their marked positions, so the position marker can be used as a tag to indicate what wire the label is attached to. Additionally, the marked position is visible on the drawing, since its exact location with respect to wires is critical to the resultant netlist. Finally, pin labels only appear on the top level of the hierarchy.
To generate the pin label, type key macro (capital) T, or choose menu item "Netlist->Make Pin". Set justification as desired and place the "x" marking the pin position over the "o" of the circle objects, or on top of a wire. The pins in this amplifier will be labeled "in.m", "in.p", "out", and "bias".

Transconductance amplifier with I/O pins marked.
Now it's time to turn this schematic into a symbol, that is, to make a symbol which will be used on the top-level drawing to designate the transconductance amplifier. What we really want to do is to use the symbol "wramp" (stands for "wide range (transconductance) amplifier", which is what this is), from library "avlsi.lps" (part of the distribution), as the symbol for the schematic you just drew. Go to the built-in library, then edit the "wramp" symbol from there by placing the cursor over the "wramp" symbol and typing key macro ">". The result looks like this:

Transconductance amplifier symbol from the "avlsi.lps" library.
Note that in this picture, the bottom left-hand corner of the screen says "Symbol" in the button that was, on Page 1, blank, and the button that used to say "Schematic" is now blank. This means that this object is a symbol, not a schematic, and it currently does not have a schematic attached to it.
Also note that the pin labels marking input/output positions for in.m, in.p, out, and bias are invisible on the library page, but become visible when editing the object, that is, when the library object has been placed on the top-level page. When the library object is used in a circuit, the pin labels are again invisible. This way, the drawing doesn't get cluttered up with nested labels.
The procedure to attach the schematic to this symbol is quite simple. Choose menu item Netlist->Associate With Schematic. Immediately, you will be taken to the page directory, with the message "Click on schematic page to associate." With the first mouse button, click on Page 1 (assuming that's the amplifier schematic). Instead of the usual behavior on the page directory (go immediately to the page under the cursor), you will be returned back to the amplifier symbol edit page. Now both buttons appear at the same time, one named "Symbol" and one named "Schematic". The one named "Schematic" is colored white, indicated that the current page is the symbol, and that a schematic exists which is the circuit represented by this symbol. Press either button, and you will go to the schematic drawing (back to Page 1). Press either button again, and you will return to the symbol. The library object "wramp" is now a symbol for the schematic of Page 1.
A symbol can be disassociated from its schematic, and vice versa, by choosing menu item "Netlist->Disassociate Symbol" or "Netlist->Disassociate Schematic". This menu option will appear only for the appropriate case. Choose this action from the menu now. Note that the white button in the lower left-hand corner goes back to being blank. The library object "wramp" is no longer a symbol for the schematic of Page 1.
Association can be initiated both ways. The alternate method is as follows: Go back to Page 1 (the amplifier schematic). Choose menu item "Netlist->Associate with Symbol" (note that this is the same button that used to be "Disassociate"). You are transported to the library directory, with the instructions in the message window to "click on the library page, then the object to associate".
Click on the first library page (the one containing the wide-range amplifier symbol "wramp"). Now click on the symbol "wramp". Now, you will be returned to the original schematic page, and once again, the buttons in the window's lower-left-hand corner are red and white, indicating that you are on the schematic page (red) but can move to the symbol page (white). Alternately to clicking buttons to move between pages, you can choose menu item "Netlist->Go To Symbol" (or "Go To Schematic", as appropriate), or use the "/" key macro. Note that the key macro only works if an association exists (i.e., it will never create a new schematic or symbol, as described in the next paragraph, although this was formerly the behavior in xcircuit version 2.1(beta)).
The schematic and symbol both do not need to exist before association. You can associate an existing schematic to a non-existing symbol or associate an existing symbol to a non-existing schematic by using the "Netlist->Make Matching Symbol" or "Netlist->Make Matching Schematic" selection, respectively. If you are editing a symbol, then you will be transported to the first blank top-level page. If you are editing a schematic (top-level page), a new User Library symbol will be generated and you will be transported there. In either case, the new object will take the name of its associated object, and all pin labels from the original will be copied to the new, so that's one less step you have to do yourself.
Now it's time to use the symbol as a subcircuit in a top-level circuit schematic. Go to Page 2, which will be the top-level circuit. Draw an integrator as shown below:

Simple continuous-time integrator using a transconductance amplifier.
Note that there is a "regular" text label titling the page; this is made in the usual fashion, using key macro (lowercase) "t", and therefore is not a pin label.
There is a one-to-one correspondence between the pin labels on the schematic and the pin labels on the corresponding symbol. This is important to make sure that the wires attaching to the symbol on the top-level schematic go to the correct destinations in the amplifier's schematic. It is not an error to have unassigned pins: A pin inside the schematic may be labeling a net for reference purposes only. A pin on the symbol which is not used in the schematic is much less likely, but may, for instance, be representing an unconnected pin on an IC.
Save this page. Call it "integrator". At this point, several points should be noted:
- Two pages were saved instead of one. XCircuit followed the path of the symbol to its schematic, and saved the schematic for the amplifier. This becomes a separate page in the PostScript output. Running "ghostview" or your favorite PostScript previewer shows the two-page output.
- Page 1, the page containing the schematic of the amplifier, regardless of what you called it in the first place (if anything), was renamed "wramp". By convention, the schematic and symbol have the same name, although this does not have to be the case.
- All the pages got saved as "Full Page" and not as "Encapsulated". For multi-page files, "Encapsulated" PostScript is not meaningful. Options for positioning the schematic on the page will probably appear in the future.
Go to the top-level schematic page (Page 2, or "integrator"). From the menu, select "Netlist->Write Spice". The message label will read "spice netlist saved as integrator.spc". You can view the file integrator.spc here. Note in particular that xcircuit has generated a hierarchical netlist, using the amplifier "wramp" as a subcircuit. The subcircuit contains parameters which are its pin labels; the call to the subcircuit has parameters which are the pin labels given on the top level page.

For reference, the resulting PostScript file can be found here: integrator.ps

SPICE simulation: Xcircuit provides only the netlist. It can also provide voltage sources and so forth, which will be described in the next task. However, it has no concept of "models" and provides no commands for running analyses. In the example above, the spice file will need to be edited to insert models for devices "nmos" and "pmos", Declare a voltage source and value for Vdd, and add commands for DC operating point determination and transient analysis.

Task 4: Introduction to parameters

One thing you may have noticed about the previous circuit is that you did not, in fact could not specify a value for the capacitor, which defaulted in the spice netlist to 1.0pF. And there was no way to specify a width and length of each nMOS and pMOS device. You might have guessed: There does exist a way to pass values such as capacitance to the capacitor object, and width and length to the MOS device objects.

Here's a brief description of how parameters work:
Each object contains a list of its parameters, NULL if there are no parameters. Each item in this list declares what is the type of parameter (so far, "string" or "integer", with only string types fully supported at present), a default value for the parameter, and another list which points to all the locations where the parameter gets substituted.

It is important to keep in mind the distinction between an object and its instantiations. If you are on Page 1 looking at an object you just dragged back from the library, you are looking at a single instance of that object. If you use the > key to edit the object, then you are editing the object itself. Normally, there is no particular need to make the distinction. However, when using parameters, the object itself will declare the default parameter, but each instance of the object may contain its own unique value for that parameter.

Xcircuit adopts a method for editing parameters in which either the default value or the instance value may be altered, and which one is altered depends on what top-level page you came from. The most obvious way to implement this is that if you edit an object from one of the library pages, you are assumed to be altering the default (the object on the library page always displays the default value of all its parameters). If, instead, you edit the object by getting there from a top-level page or another object, you are editing the instance, and changes you make to the parameters will only affect the value of that instance only. This should be made clear by the tutorial below.

Run xcircuit, which should automatically load "analoglib2.lps" onto library page 2 (since xcircuit version 2.2.0. Otherwise, load it from the subdirectory "examples" of the source distribution).
Go to library page 2 (macro L, click on second page). You will see a set of replacement objects for the basic circuit structures "capacitor", "resistor", "nmos", etc. The main difference between these and the original objects is that they contain labels indicating values.

The parameterized analog component library.
Select, say, the "Resistor" object and drag it back to Page 1.
Copy the resistor so you have two resistors on Page 1.
Edit one of the resistors (> key). You will note that, in addition to pin labels, there are some other strings (called "info labels") which will be described in detail later.
Edit the string which reads "1.0 k(Ohm)" (e key macro, or menu selection Edit->Edit). As you move the cursor around the string, look at the message window. You will note that in addition to the usual ASCII characters and string commands such as font changes, half-space, etc., there is now an additional embedded command label "Parameter(n)< text>", where n is the parameter number, and text is a substring (may be empty) which is the parameter text. For the resistor, "1.0" is a parameter describing the value, and "k" is a parameter for the metric scale prefix. Unlike all other parts of the string, you cannot delete the parameter delimiter marks (parameters must be removed from a string with the "Unparameterize" function).
Replace the substring "1.0" with "20" and replace "k" by "M" or whatever your favorite resistor value is. Be sure that you are inside the parameter delimiters when you make the change, or you will get unexpected results.
Pop back up to the originating page (< key). You will see that only the resistor which you edited has its values changed; the other one still has the original (default) values of "1.0" and "k".
Go to the library again (L key, then click on the second page), and from there, edit the resistor (> key). From here, change the value to, say, "2.0 k". Note that now you are changing the default value, not an instance value.
Return to the library page (< key). Now the library object shows the new resistance value, indicating that the default value was new object will take the name of its associated object, and all pin labels from the original will be copied to the new, so that's one less step you have to do yourself.
Now it's time to use the symbol as a subcircuit in a top-level circuit schematic. Go to Page 2, which will be the top-level circuit. Draw an integrator as shown below:

Simple continuous-time integrator using a transconductance amplifier.
Note that there is a "regular" text label titling the page; this is made in the usual fashion, using key macro (lowercase) "t", and therefore is not a pin label.
There is a one-to-one correspondence between the pin labels on the schematic and the pin labels on the corresponding symbol. This is important to make sure that the wires attaching to the symbol on the top-level schematic go to the correct destinations in the amplifier's schematic. It is not an error to have unassigned pins: A pin inside the schematic may be labeling a net for reference purposes only. A pin on the symbol which is not used in the schematic is much less likely, but may, for instance, be representing an unconnected pin on an IC.
Save this page. Call it "integrator". At this point, several points should be noted:
- Two pages were saved instead of one. XCircuit followed the path of the symbol to its schematic, and saved the schematic for the amplifier. This becomes a separate page in the PostScript output. Running "ghostview" or your favorite PostScript previewer shows the two-page output.
- Page 1, the page containing the schematic of the amplifier, regardless of what you called it in the first place (if anything), was renamed "wramp". By convention, the schematic and symbol have the same name, although this does not have to be the case.
- All the pages got saved as "Full Page" and not as "Encapsulated". For multi-page files, "Encapsulated" PostScript is not meaningful. Options for positioning the schematic on the page will probably appear in the future.
Go to the top-level schematic page (Page 2, or "integrator"). From the menu, select "Netlist->Write Spice". The message label will read "spice netlist saved as integrator.spc". You can view the file integrator.spc here. Note in particular that xcircuit has generated a hierarchical netlist, using the amplifier "wramp" as a subcircuit. The subcircuit contains parameters which are its pin labels; the call to the subcircuit has parameters which are the pin labels given on the top level page.

For reference, the resulting PostScript file can be found here: integrator.ps

Task 4: Introduction to parameters

Run xcircuit, which should automatically load "analoglib2.lps" onto library page 2 (since xcircuit version 2.2.0. Otherwise, load it from the subdirectory "examples" of the source distribution).
Go to library page 2 (macro L, click on second page). You will see a set of replacement objects for the basic circuit structures "capacitor", "resistor", "nmos", etc. The main difference between these and the original objects is that they contain labels indicating values.

The parameterized analog component library.
Select, say, the "Resistor" object and drag it back to Page 1.
Copy the resistor so you have two resistors on Page 1.
Edit one of the resistors (> key). You will note that, in addition to pin labels, there are some other strings (called "info labels") which will be described in detail later.
Edit the string which reads "1.0 k(Ohm)" (e key macro, or menu selection Edit->Edit). As you move the cursor around the string, look at the message window. You will note that in addition to the usual ASCII characters and string commands such as font changes, half-space, etc., there is now an additional embedded command label "Parameter(n)< text>", where n is the parameter number, and text is a substring (may be empty) which is the parameter text. For the resistor, "1.0" is a parameter describing the value, and "k" is a parameter for the metric scale prefix. Unlike all other parts of the string, you cannot delete the parameter delimiter marks (parameters must be removed from a string with the "Unparameterize" function).
Replace the substring "1.0" with "20" and replace "k" by "M" or whatever your favorite resistor value is. Be sure that you are inside the parameter delimiters when you make the change, or you will get unexpected results.
Pop back up to the originating page (< key). You will see that only the resistor which you edited has its values changed; the other one still has the original (default) values of "1.0" and "k".
Go to the library again (L key, then click on the second page), and from there, edit the resistor (> key). From here, change the value to, say, "2.0 k". Note that now you are changing the default value, not an instance value.
Return to the library page (< key). Now the library object shows the new resistance value, indicating that the default value was new object will take the name of its associated object, and all pin labels from the original will be copied to the new, so that's one less step you have to do yourself.
Now it's time to use the symbol as a subcircuit in a top-level circuit schematic. Go to Page 2, which will be the top-level circuit. Draw an integrator as shown below:

Simple continuous-time integrator using a transconductance amplifier.
Note that there is a "regular" text label titling the page; this is made in the usual fashion, using key macro (lowercase) "t", and therefore is not a pin label.
There is a one-to-one correspondence between the pin labels on the schematic and the pin labels on the corresponding symbol. This is important to make sure that the wires attaching to the symbol on the top-level schematic go to the correct destinations in the amplifier's schematic. It is not an error to have unassigned pins: A pin inside the schematic may be labeling a net for reference purposes only. A pin on the symbol which is not used in the schematic is much less likely, but may, for instance, be representing an unconnected pin on an IC.
Save this page. Call it "integrator". At this point, several points should be noted:
- Two pages were saved instead of one. XCircuit followed the path of the symbol to its schematic, and saved the schematic for the amplifier. This becomes a separate page in the PostScript output. Running "ghostview" or your favorite PostScript previewer shows the two-page output.
- Page 1, the page containing the schematic of the amplifier, regardless of what you called it in the first place (if anything), was renamed "wramp". By convention, the schematic and symbol have the same name, although this does not have to be the case.
- All the pages got saved as "Full Page" and not as "Encapsulated". For multi-page files, "Encapsulated" PostScript is not meaningful. Options for positioning the schematic on the page will probably appear in the future.
Go to the top-level schematic page (Page 2, or "integrator"). From the menu, select "Netlist->Write Spice". The message label will read "spice netlist saved as integrator.spc". You can view the file integrator.spc here. Note in particular that xcircuit has generated a hierarchical netlist, using the amplifier "wramp" as a subcircuit. The subcircuit contains parameters which are its pin labels; the call to the subcircuit has parameters which are the pin labels given on the top level page.

For reference, the resulting PostScript file can be found here: integrator.ps

Task 4: Introduction to parameters

Run xcircuit, which should automatically load "analoglib2.lps" onto library page 2 (since xcircuit version 2.2.0. Otherwise, load it from the subdirectory "examples" of the source distribution).
Go to library page 2 (macro L, click on second page). You will see a set of replacement objects for the basic circuit structures "capacitor", "resistor", "nmos", etc. The main difference between these and the original objects is that they contain labels indicating values.

The parameterized analog component library.
Select, say, the "Resistor" object and drag it back to Page 1.
Copy the resistor so you have two resistors on Page 1.
Edit one of the resistors (> key). You will note that, in addition to pin labels, there are some other strings (called "info labels") which will be described in detail later.
Edit the string which reads "1.0 k(Ohm)" (e key macro, or menu selection Edit->Edit). As you move the cursor around the string, look at the message window. You will note that in addition to the usual ASCII characters and string commands such as font changes, half-space, etc., there is now an additional embedded command label "Parameter(n)< text>", where n is the parameter number, and text is a substring (may be empty) which is the parameter text. For the resistor, "1.0" is a parameter describing the value, and "k" is a parameter for the metric scale prefix. Unlike all other parts of the string, you cannot delete the parameter delimiter marks (parameters must be removed from a string with the "Unparameterize" function).
Replace the substring "1.0" with "20" and replace "k" by "M" or whatever your favorite resistor value is. Be sure that you are inside the parameter delimiters when you make the change, or you will get unexpected results.
Pop back up to the originating page (< key). You will see that only the resistor which you edited has its values changed; the other one still has the original (default) values of "1.0" and "k".
Go to the library again (L key, then click on the second page), and from there, edit the resistor (> key). From here, change the value to, say, "2.0 k". Note that now you are changing the default value, not an instance value.
Return to the library page (< key). Now the library object shows the new resistance value, indicating that the default value was new object will take the name of its associated object, and all pin labels from the original will be copied to the new, so that's one less step you have to do yourself.
Now it's time to use the symbol as a subcircuit in a top-level circuit schematic. Go to Page 2, which will be the top-level circuit. Draw an integrator as shown below:

Simple continuous-time integrator using a transconductance amplifier.
Note that there is a "regular" text label titling the page; this is made in the usual fashion, using key macro (lowercase) "t", and therefore is not a pin label.
There is a one-to-one correspondence between the pin labels on the schematic and the pin labels on the corresponding symbol. This is important to make sure that the wires attaching to the symbol on the top-level schematic go to the correct destinations in the amplifier's schematic. It is not an error to have unassigned pins: A pin inside the schematic may be labeling a net for reference purposes only. A pin on the symbol which is not used in the schematic is much less likely, but may, for instance, be representing an unconnected pin on an IC.
Save this page. Call it "integrator". At this point, several points should be noted:
- Two pages were saved instead of one. XCircuit followed the path of the symbol to its schematic, and saved the schematic for the amplifier. This becomes a separate page in the PostScript output. Running "ghostview" or your favorite PostScript previewer shows the two-page output.
- Page 1, the page containing the schematic of the amplifier, regardless of what you called it in the first place (if anything), was renamed "wramp". By convention, the schematic and symbol have the same name, although this does not have to be the case.
- All the pages got saved as "Full Page" and not as "Encapsulated". For multi-page files, "Encapsulated" PostScript is not meaningful. Options for positioning the schematic on the page will probably appear in the future.
Go to the top-level schematic page (Page 2, or "integrator"). From the menu, select "Netlist->Write Spice". The message label will read "spice netlist saved as integrator.spc". You can view the file integrator.spc here. Note in particular that xcircuit has generated a hierarchical netlist, using the amplifier "wramp" as a subcircuit. The subcircuit contains parameters which are its pin labels; the call to the subcircuit has parameters which are the pin labels given on the top level page.

For reference, the resulting PostScript file can be found here: integrator.ps

Task 4: Introduction to parameters

Run xcircuit, which should automatically load "analoglib2.lps" onto library page 2 (since xcircuit version 2.2.0. Otherwise, load it from the subdirectory "examples" of the source distribution).
Go to library page 2 (macro L, click on second page). You will see a set of replacement objects for the basic circuit structures "capacitor", "resistor", "nmos", etc. The main difference between these and the original objects is that they contain labels indicating values.

The parameterized analog component library.
Select, say, the "Resistor" object and drag it back to Page 1.
Copy the resistor so you have two resistors on Page 1.
Edit one of the resistors (> key). You will note that, in addition to pin labels, there are some other strings (called "info labels") which will be described in detail later.
Edit the string which reads "1.0 k(Ohm)" (e key macro, or menu selection Edit->Edit). As you move the cursor around the string, look at the message window. You will note that in addition to the usual ASCII characters and string commands such as font changes, half-space, etc., there is now an additional embedded command label "Parameter(n)< text>", where n is the parameter number, and text is a substring (may be empty) which is the parameter text. For the resistor, "1.0" is a parameter describing the value, and "k" is a parameter for the metric scale prefix. Unlike all other parts of the string, you cannot delete the parameter delimiter marks (parameters must be removed from a string with the "Unparameterize" function).
Replace the substring "1.0" with "20" and replace "k" by "M" or whatever your favorite resistor value is. Be sure that you are inside the parameter delimiters when you make the change, or you will get unexpected results.
Pop back up to the originating page (< key). You will see that only the resistor which you edited has its values changed; the other one still has the original (default) values of "1.0" and "k".
Go to the library again (L key, then click on the second page), and from there, edit the resistor (> key). From here, change the value to, say, "2.0 k". Note that now you are changing the default value, not an instance value.
Return to the library page (< key). Now the library object shows the new resistance value, indicating that the default value was new object will take the name of its associated object, and all pin labels from the original will be copied to the new, so that's one less step you have to do yourself.
Now it's time to use the symbol as a subcircuit in a top-level circuit schematic. Go to Page 2, which will be the top-level circuit. Draw an integrator as shown below:

Simple continuous-time integrator using a transconductance amplifier.
Note that there is a "regular" text label titling the page; this is made in the usual fashion, using key macro (lowercase) "t", and therefore is not a pin label.
There is a one-to-one correspondence between the pin labels on the schematic and the pin labels on the corresponding symbol. This is important to make sure that the wires attaching to the symbol on the top-level schematic go to the correct destinations in the amplifier's schematic. It is not an error to have unassigned pins: A pin inside the schematic may be labeling a net for reference purposes only. A pin on the symbol which is not used in the schematic is much less likely, but may, for instance, be representing an unconnected pin on an IC.
Save this page. Call it "integrator". At this point, several points should be noted:
- Two pages were saved instead of one. XCircuit followed the path of the symbol to its schematic, and saved the schematic for the amplifier. This becomes a separate page in the PostScript output. Running "ghostview" or your favorite PostScript previewer shows the two-page output.
- Page 1, the page containing the schematic of the amplifier, regardless of what you called it in the first place (if anything), was renamed "wramp". By convention, the schematic and symbol have the same name, although this does not have to be the case.
- All the pages got saved as "Full Page" and not as "Encapsulated". For multi-page files, "Encapsulated" PostScript is not meaningful. Options for positioning the schematic on the page will probably appear in the future.
Go to the top-level schematic page (Page 2, or "integrator"). From the menu, select "Netlist->Write Spice". The message label will read "spice netlist saved as integrator.spc". You can view the file integrator.spc here. Note in particular that xcircuit has generated a hierarchical netlist, using the amplifier "wramp" as a subcircuit. The subcircuit contains parameters which are its pin labels; the call to the subcircuit has parameters which are the pin labels given on the top level page.

For reference, the resulting PostScript file can be found here: integrator.ps

Task 4: Introduction to parameters

Run xcircuit, which should automatically load "analoglib2.lps" onto library page 2 (since xcircuit version 2.2.0. Otherwise, load it from the subdirectory "examples" of the source distribution).
Go to library page 2 (macro L, click on second page). You will see a set of replacement objects for the basic circuit structures "capacitor", "resistor", "nmos", etc. The main difference between these and the original objects is that they contain labels indicating values.

The parameterized analog component library.
Select, say, the "Resistor" object and drag it back to Page 1.
Copy the resistor so you have two resistors on Page 1.
Edit one of the resistors (> key). You will note that, in addition to pin labels, there are some other strings (called "info labels") which will be described in detail later.
Edit the string which reads "1.0 k(Ohm)" (e key macro, or menu selection Edit->Edit). As you move the cursor around the string, look at the message window. You will note that in addition to the usual ASCII characters and string commands such as font changes, half-space, etc., there is now an additional embedded command label "Parameter(n)< text>", where n is the parameter number, and text is a substring (may be empty) which is the parameter text. For the resistor, "1.0" is a parameter describing the value, and "k" is a parameter for the metric scale prefix. Unlike all other parts of the string, you cannot delete the parameter delimiter marks (parameters must be removed from a string with the "Unparameterize" function).
Replace the substring "1.0" with "20" and replace "k" by "M" or whatever your favorite resistor value is. Be sure that you are inside the parameter delimiters when you make the change, or you will get unexpected results.
Pop back up to the originating page (< key). You will see that only the resistor which you edited has its values changed; the other one still has the original (default) values of "1.0" and "k".
Go to the library again (L key, then click on the second page), and from there, edit the resistor (> key). From here, change the value to, say, "2.0 k". Note that now you are changing the default value, not an instance value.
Return to the library page (< key). Now the library object shows the new resistance value, indicating that the default value was new object will take the name of its associated object, and all pin labels from the original will be copied to the new, so that's one less step you have to do yourself.
Now it's time to use the symbol as a subcircuit in a top-level circuit schematic. Go to Page 2, which will be the top-level circuit. Draw an integrator as shown below:

Simple continuous-time integrator using a transconductance amplifier.
Note that there is a "regular" text label titling the page; this is made in the usual fashion, using key macro (lowercase) "t", and therefore is not a pin label.
There is a one-to-one correspondence between the pin labels on the schematic and the pin labels on the corresponding symbol. This is important to make sure that the wires attaching to the symbol on the top-level schematic go to the correct destinations in the amplifier's schematic. It is not an error to have unassigned pins: A pin inside the schematic may be labeling a net for reference purposes only. A pin on the symbol which is not used in the schematic is much less likely, but may, for instance, be representing an unconnected pin on an IC.
Save this page. Call it "integrator". At this point, several points should be noted:
- Two pages were saved instead of one. XCircuit followed the path of the symbol to its schematic, and saved the schematic for the amplifier. This becomes a separate page in the PostScript output. Running "ghostview" or your favorite PostScript previewer shows the two-page output.
- Page 1, the page containing the schematic of the amplifier, regardless of what you called it in the first place (if anything), was renamed "wramp". By convention, the schematic and symbol have the same name, although this does not have to be the case.
- All the pages got saved as "Full Page" and not as "Encapsulated". For multi-page files, "Encapsulated" PostScript is not meaningful. Options for positioning the schematic on the page will probably appear in the future.
Go to the top-level schematic page (Page 2, or "integrator"). From the menu, select "Netlist->Write Spice". The message label will read "spice netlist saved as integrator.spc". You can view the file integrator.spc here. Note in particular that xcircuit has generated a hierarchical netlist, using the amplifier "wramp" as a subcircuit. The subcircuit contains parameters which are its pin labels; the call to the subcircuit has parameters which are the pin labels given on the top level page.

For reference, the resulting PostScript file can be found here: integrator.ps

Task 4: Introduction to parameters

Run xcircuit, which should automatically load "analoglib2.lps" onto library page 2 (since xcircuit version 2.2.0. Otherwise, load it from the subdirectory "examples" of the source distribution).
Go to library page 2 (macro L, click on second page). You will see a set of replacement objects for the basic circuit structures "capacitor", "resistor", "nmos", etc. The main difference between these and the original objects is that they contain labels indicating values.

The parameterized analog component library.
Select, say, the "Resistor" object and drag it back to Page 1.
Copy the resistor so you have two resistors on Page 1.
Edit one of the resistors (> key). You will note that, in addition to pin labels, there are some other strings (called "info labels") which will be described in detail later.
Edit the string which reads "1.0 k(Ohm)" (e key macro, or menu selection Edit->Edit). As you move the cursor around the string, look at the message window. You will note that in addition to the usual ASCII characters and string commands such as font changes, half-space, etc., there is now an additional embedded command label "Parameter(n)< text>", where n is the parameter number, and text is a substring (may be empty) which is the parameter text. For the resistor, "1.0" is a parameter describing the value, and "k" is a parameter for the metric scale prefix. Unlike all other parts of the string, you cannot delete the parameter delimiter marks (parameters must be removed from a string with the "Unparameterize" function).
Replace the substring "1.0" with "20" and replace "k" by "M" or whatever your favorite resistor value is. Be sure that you are inside the parameter delimiters when you make the change, or you will get unexpected results.
Pop back up to the originating page (< key). You will see that only the resistor which you edited has its values changed; the other one still has the original (default) values of "1.0" and "k".
Go to the library again (L key, then click on the second page), and from there, edit the resistor (> key). From here, change the value to, say, "2.0 k". Note that now you are changing the default value, not an instance value.
Return to the library page (< key). Now the library object shows the new resistance value, indicating that the default value was new object will take the name of its associated object, and all pin labels from the original will be copied to the new, so that's one less step you have to do yourself.
Now it's time to use the symbol as a subcircuit in a top-level circuit schematic. Go to Page 2, which will be the top-level circuit. Draw an integrator as shown below:

Simple continuous-time integrator using a transconductance amplifier.
Note that there is a "regular" text label titling the page; this is made in the usual fashion, using key macro (lowercase) "t", and therefore is not a pin label.
There is a one-to-one correspondence between the pin labels on the schematic and the pin labels on the corresponding symbol. This is important to make sure that the wires attaching to the symbol on the top-level schematic go to the correct destinations in the amplifier's schematic. It is not an error to have unassigned pins: A pin inside the schematic may be labeling a net for reference purposes only. A pin on the symbol which is not used in the schematic is much less likely, but may, for instance, be representing an unconnected pin on an IC.
Save this page. Call it "integrator". At this point, several points should be noted:
- Two pages were saved instead of one. XCircuit followed the path of the symbol to its schematic, and saved the schematic for the amplifier. This becomes a separate page in the PostScript output. Running "ghostview" or your favorite PostScript previewer shows the two-page output.
- Page 1, the page containing the schematic of the amplifier, regardless of what you called it in the first place (if anything), was renamed "wramp". By convention, the schematic and symbol have the same name, although this does not have to be the case.
- All the pages got saved as "Full Page" and not as "Encapsulated". For multi-page files, "Encapsulated" PostScript is not meaningful. Options for positioning the schematic on the page will probably appear in the future.
Go to the top-level schematic page (Page 2, or "integrator"). From the menu, select "Netlist->Write Spice". The message label will read "spice netlist saved as integrator.spc". You can view the file integrator.spc here. Note in particular that xcircuit has generated a hierarchical netlist, using the amplifier "wramp" as a subcircuit. The subcircuit contains parameters which are its pin labels; the call to the subcircuit has parameters which are the pin labels given on the top level page.

For reference, the resulting PostScript file can be found here: integrator.ps

The XCircuit Schematic Capture Tutorial

Table of Contents