# Switcap netlister README

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