# Hierarchical SPICE model

Example of a hierarchical analog RF SPICE model in the:
`${prefix}/share/doc/geda-gaf/examples/RF_Amp`
directory, where `${prefix}` is the installation prefix for gEDA on your system (usually `/usr` or `/usr/local`).

    This README created 3.31.2003

    ---------------------  Contents of directories  -----------------------

    This directory holds the schematics and associated materials for a
    SPICE model of Agilent's MSA-2643 bipolar amp.  The model was obtained
    from Agilent's datasheet 5980-2396E.  The directory structure is as
    follows:

    RF_Amp (base directory)

    MSA-2643.sch -- schematic of stuff inside device package (as shown in
    p. 7 of datasheet.  Note that I have not included the transmission
    lines in this schematic because no value of Z was included in the data
    sheet.   (Yes, it's probably 50 ohms, but including them was a
    sideshow compared to my main intent: build a hierarchical model of an
    RF circuit.)
    MSA-2643.cir -- netlisted circuit ready for SPICE simulation.

    Q1.sch -- schematic model of Q1 MSA-26 transistor shown on p. 8 of datasheet.
    Q1.cir -- netlisted circuit holding .SUBCKT model of Q1.

    Q2.sch -- schematic model of Q2 MSA-26 transistor shown on p. 8 of datasheet.
    Q2.cir -- netlisted circuit holding .SUBCKT model of Q2.

    README -- this file.

    Simulation.cmd -- a file holding SPICE analysis commands which is read
    at simulation time by the SPICE simulator.

    5980-2396E.pdf -- Agilent datasheet about the MSA-2643.

    ./model/

    BJTM1_Q1.mod -- text-based SPICE model of BJT1 used in Q1 .SUBCKT
    DiodeM1_Q1.mod -- text-based SPICE model of diode M1 used in Q1 .SUBCKT
    DiodeM2_Q1.mod -- SPICE model of diode M2 used in Q1 .SUBCKT
    DiodeM3_Q1.mod -- SPICE model of diode M3 used in Q1 .SUBCKT
    (similar files for Q2 models. . . .)
    These models were obtained from parameters give in p. 8 of the datasheet.

    ./sym/

    BJT_Model.sym
    spice-subcircuit-IO-1.sym
    spice-subcircuit-LL-1.sym
    Q_Model.sym -- symbol pointing to lower level models placed on upper
    level schematic.

    ------------  Usage of hierarchical spice models ---------------------
    This project exemplifies construction of a hierarchical SPICE
    simulation using gEDA.  The project is built in the following way:

    1.  Use a text editor to create .mod files containing SPICE models of
    the transistors and diodes on p. 8 of the datasheet.

    2.  Create Q1 and Q2 transistor model schematics using gschem.  Place
    the .SUBCKT SPICE block on the schematic to alert the netlister that
    the schematic is a lower level .SUBCKT for incorporation into other
    schematics.  Place spice-IO pads on the schematic to instantiate the
    IOs.  Make sure to number the spice-IO pads in the same order as you
    wish them to appear in the .SUBCKT line in the .cir.

    3.  Generate the .SUBCKT netlist by saying:

    gnetlist -g spice-sdb -o Q1.cir Q1.sch
    gnetlist -g spice-sdb -o Q2.cir Q2.sch

    4.  Create a symbol for Q1.cir and Q2.cir which will be dropped onto
    the higher lever schematic.  Name the symbol Q_Model.sym.  Set the
    symbol "DEVICE" attribute = NPN_TRANSISTOR_subcircuit.  This causes
    the netlister to use "write-default-component" to write out the SPICE
    line for the component.  Make sure that the "REFDES" attribute is X?
    and not Q? -- this enables the .SUBCKT file to be attached to the
    device.

    5.  Create the higher layer schematic MSA-2643.sch.  Place
    two copies of Q_Model.sym onto the schematic, corresponding to Q1 and
    Q2.  Make Q1 point to its model by setting the following attributes:

    model-name: Q1_MSA26F
    file: Q1.cir

    Do the same for Q2.

    6.  Create the rest of the higher layer schematic the usual way.  Make
    sure to place a spice-include block on the schematic and point it to
    "Simulation.cmd".  Place any analysis commands (e.g. .DC, .AC, .TRAN,
    etc.) into the file "Simulation.cmd".

    7.  Netlist the higher layer design:

    gnetlist -g spice-sdb -o MSA-2643.cir MSA-2643.sch

    8.  The circuit may be simulated by any desired SPICE simulation
    and analysis package, e.g. LTSpice.

    --------------------  Contact  ----------------------------
    Documentation and other materials relevant to SPICE simulation under
    gEDA lives at http://www.brorson.com/gEDA/SPICE

    For inquiries or bug reports, please contact me:

    Stuart Brorson
    mailto:sdb@cloud9.net