-----------------------------------------------------------------
I.   What is this?
-----------------------------------------------------------------

This archive contains a set of symbols and a netlister backend for the
gEDA to drive SWITCAP simulations.  gEDA is the GNU EDA project and
includes a schematic capture tool and a highly flexible netlister.
The SWITCAP program is a switched capacitor circuit simulator.

-----------------------------------------------------------------
II.  Overview
-----------------------------------------------------------------

The basic steps involved with using gEDA as the frontend for SWITCAP
simulations are:

- configure the gEDA symbol search path
- set the gEDA netlister backend search path
- create schematics of the circuit
- create an analysis file
- extract the netlist
- run the SWITCAP simulation


-----------------------------------------------------------------
III.  Initial Setup
-----------------------------------------------------------------
  1)  Set your symbol search path for gschem and gnetlist by adding
      the following line to the 'gschemrc' and 'gnetlistrc' files in
      your project directory.  

        (component-library "/path/to/sym/switcap")

      If those files do not exist, then create them.  You will need to
      replace /path/to/sym/switcap with the directory name where you
      have installed the .sym files.

  2)  Set the search path for scheme files for gnetlist by adding the
      following line to your 'gnetlistrc' file.

        (scheme-directory "/path/to/scheme")

      You will need to replace /path/to/scheme with the path to where
      you have installed the gnet-switcap.scm file.

  3)  

-----------------------------------------------------------------
IV.  Creating Schematics
-----------------------------------------------------------------

--------------------
A.  Required Symbols
--------------------

This section assumes you are familiar with using gschem to create and
edit schematics.  SWITCAP netlisting is only supported for the
components contained in the SWITCAP symbol library as well as the
ground symbol found in the 'power' library which comes with gEDA.  All
allowed SWITCAP elements except for subcircuits are supported.  You
_must_ include the following elements on your schematic:

- one instance of the switcap-timing symbol.  This symbol will set the
  master clock period for your simulations.

- one or more instances of the switcap-clock symbol.  This symbol
  defines a clock with a particular phase and period.  The reference
  designator of the clock symbol is used by the switches to set what
  phase they switch on.

- one or more instances of the switcap-analysis symbol.  This symbol
  defines an analysis by specifying a file to include in the SWITCAP
  netlist.

--------------------
B.  Optional Symbols
--------------------

You can also optionally add the following SWITCAP special symbols to
your schematic:

- zero or one instance of the switcap-title symbol.  This will add a
  TITLE: line to the SWITCAP netlist and will appear in the output
  file.

- zero or one instance of the switcap-options symbol.  By editing the
  OPTIONS attribute on this symbol you can set the various options
  which can be passed to SWITCAP.

--------------------
C.  Net Names
--------------------

When creating schematics to drive SWITCAP, you should name all nets
that you wish to plot.  To avoid possible conflicts with unnamed nets,
you should avoid using purely numerical names for nets because
all unnamed nets will be assigned (somewhat randomly) numbers.
SWITCAP limits the length of node names to 7 characters.

--------------------
D.  Switches
--------------------

When placing switches on your schematic, you will need to define
which clock they are controlled with.  This is done by setting
the clock attribute on the switch to the reference designator 
of the clock which should control it.

-----------------------------------------------------------------
V.  Extracting the SWITCAP Netlist
-----------------------------------------------------------------

To extract the SWITCAP netlist, run

  gnetlist -g switcap -o test.scn file1.sch [file2.sch ...]

For the example file contained in this archive, you can run:

  gnetlist -g switcap -o example.scn ckt.sch clocks.sch analysis.sch

The netlist will be left in example.scn.

-----------------------------------------------------------------
VI.  Running SWITCAP
-----------------------------------------------------------------

I typically use something like:

  printf "example.scn\nexample.out" | sw

so I can use command history to rerun SWITCAP without having to
manually type the file names each time.

Refer to the SWITCAP manual for more details.