Work with models — SLiCAP 4.0.7 documentation

# Work with models

SLiCAP circuit elements have associated network models. Some of these are `stamp` models and others are `expansion models`; see Devices and built-in models. Stamp models have a built-in MNA matrix stamp. Expansion models are described as subcircuits, ultimately using devices with stamp models as building blocks. Model expansion takes place during the execution of `makeCircuit()`.

## SLiCAP stamp models

The table below lists the built-in stamp models. For SPICE compatibility, the Device ID is the first letter of the device’s reference designator. But devices with the same device ID can have different nodels:

Device ID | Model | Description
--- | --- | ---
C | C | Linear capacitor
E | E | VCVS (voltage-controlled voltage source)
E | EZ | VCVS with output impedance
F | F | CCCS (current-controlled current source)
G | G | VCCS (voltage-controlled current source)
G | g | VCCS only instantaneous
H | H | CCVS (current-controlled voltage source)
H | HZ | CCVS with series impedance
I | I | Independent current source
K | K | Coupling factor
L | L | Linear inductor
N | N | Nullor
R | R | Linear resistor cannot have zero value
R | r | Linear resistor can have zero value
T | T | Ideal transformer
V | V | Independent voltage source
W | W | Gyrator

## SLiCAP expansion models

The table below lists the built-in expansion models. The Device ID is the first letter of the device’s reference designator. But devices with the same device ID can have different nodels:

Device ID | Model | Description
--- | --- | ---
D | D | Small-signal model PN diode
J | J | Small-signal model JFET
M | M | Small-signal model 4-terminal MOS
M | MD | Small-signal model MOS differential-pair
O | OV | Small-signal model voltage-feedback operational amplifier
O | OC | Small-signal model current-feedback operational amplifier
Q | QV | Small-signal model vertical BJT
Q | QL | Small-signal model lateral BJT
Q | QD | Small-signal model BJT differential-pair

## Model parameters

All models, except the nullor have model parameters (see Devices and built-in models). Model parameters can be passed to the model in three different ways:

1. In the netlist element definition line, after the declaration of the model type:

       O1 out 0 inP inN OV av={1e6/(1+s/(2*pi))} zo=100

2. In a netlist model statement

       O1 out 0 inP inN myOpAmp

       .model myOpAmp OV av={1e6/(1+s/(2*pi))} zo=100

3. In a library file and a call to it in the netlist:

       O1 out 0 inP inN myOpAmp
       .lib myLib.lib

   The library file must be stored in the `lib/` folder in the project directory. The format of a SLiCAP library file is identical to that of a circuit file:

   - The first line will be interpreted as the `Title`. So don’t start it with the line comment symbol: `*`!

   - The library ends with a `.end` command.

   - It comprises definitions of subcircuits, parameters and models.

   An example of the syntax of myLib.lib, referred to above:

       "My own SLiCAP model Library"
       *****************************
       * File: myLib.lib
       *
       .model myOpAmp OV av={1e6/(1+s/(2*pi))} zo=100
       *
       .end

### The scope of model parameters

Model parameters on the element definition line override those given model definition line (a netlist line starting with `.model`).

The operational amplifier in the netlist device definition line below, obtains all its parameter values from the library definition, except for `av`. This parameter will be set to \(10^6\).

    O1 inP inN out 0 myOpAmp av=1e6
    .lib myLib.lib

## SLiCAP model expansion

Expansion models are described as subcircuits. These subcircuits are recusrively expanded or “flattened” until all elements have stamp models. The expanded subcircuit is then included in the parent circuit. This is illustrated below.

SLiCAP output displayed on this manual page, is generated with the script: `models.py`, imported by `Manual.py`.

     1#!/usr/bin/env python3
     2# -*- coding: utf-8 -*-
     3
     4"""
     5models.py: SLiCAP scripts for the HTML help file
     6"""
     7import SLiCAP as sl
     8
     9###############################################################################
    10# work with models
    11###############################################################################

### Expanded circuit element data

The script below creates the circuit object from the kicad schematic file:

    13# Create a circuit object
    14cir = sl.makeCircuit("kicad/ZtoV/ZtoV.kicad_sch")

The figure below shows the KiCAD circuit diagram.

The netlist of the circuit:

    "Low-noise voltage amplifier"
    .param R_s = 50
    .model myOpAmp OV av={A_0/(1+s/(2*pi*p_1))} zo={R_o}
    O1 in 1 2 0 myOpAmp
    O2 0 3 out 0 myOpAmp
    R1 4 in R value={R_s} noisetemp=0 noiseflow=0 dcvar=0 dcvarlot=0
    R2 1 0 R value={R_a} noisetemp=0 noiseflow=0 dcvar=0 dcvarlot=0
    R3 2 1 R value={(A_1-1)*R_a} noisetemp=0 noiseflow=0 dcvar=0 dcvarlot=0
    R4 in out R value={R_f} noisetemp=0 noiseflow=0 dcvar=0 dcvarlot=0
    R5 2 3 R value={R_b} noisetemp=0 noiseflow=0 dcvar=0 dcvarlot=0
    R6 3 out R value={A_2*R_b} noisetemp=0 noiseflow=0 dcvar=0 dcvarlot=0
    V1 4 0 V value=0 noise=0 dc=0 dcvar=0
    .end

The sub circuit definition of the model `OV` is found in `SLiCAPmodels.lib` in the folder given in `ini.main_lib_path`.

    110.subckt QD c1 c2 b1 b2 gm=20m gbb=5k gcc=0 gbc=0 rb=0 cbb=0 cbc=0 cbx=0 ; default values
    111Gm c1 c2 1 2 g value={gm}
    112Gbb 1 2 1 2 g value={gbb}
    113Gcc c1 c2 c1 c2 g value={gcc}
    114Gbc1 1 c1 1 c1 g value={gbc}
    115Gbc2 2 c2 2 c2 g value={gbc}
    116Rb1 b1 1 r value={rb}
    117Rb2 b2 2 r value={rb}
    118Cbb 1 2 {cbb}
    119Cbc1 1 c1 {cbc}

The script below prints the expanded netlist.

    16# Display the expanded netlist
    17print('"' + cir.title +'"')
    18for element in cir.elements.keys():
    19    refdes = cir.elements[element].refDes
    20    nodes = ""
    21    for node in cir.elements[element].nodes:
    22        nodes += node + " "
    23    refs = ""
    24    if len(cir.elements[element].refs):
    25        for ref in cir.elements[element].refs:
    26            refs += ref + " "
    27    model = cir.elements[element].model
    28    pardefs = ""
    29    for param in cir.elements[element].params.keys():
    30        pardefs += str(param) + "={" + str(cir.elements[element].params[param]) +"} "
    31    print(refdes, nodes, refs, model, pardefs)

The result below shows the way in which the operational amplifiers have been replaced with their expanded subcircuits. The expanded circuit only comprises stamp elements and can directly be converted into an MNA matrix.

Below a netlist constructed from element data of the top-level circuit.

    "Low-noise voltage amplifier"
    R1 4 in   R value={R_s} noisetemp={0} noiseflow={0} dcvar={0} dcvarlot={0}
    R2 1 0   R value={R_a} noisetemp={0} noiseflow={0} dcvar={0} dcvarlot={0}
    R3 2 1   R value={R_a*(A_1 - 1)} noisetemp={0} noiseflow={0} dcvar={0} dcvarlot={0}
    R4 in out   R value={R_f} noisetemp={0} noiseflow={0} dcvar={0} dcvarlot={0}
    R5 2 3   R value={R_b} noisetemp={0} noiseflow={0} dcvar={0} dcvarlot={0}
    R6 3 out   R value={A_2*R_b} noisetemp={0} noiseflow={0} dcvar={0} dcvarlot={0}
    V1 4 0   V value={0} noise={0} dc={0} dcvar={0}
    E_O1 2 0 in 1   EZ value={A_0/(1 + s/(2*pi*p_1))} zo={R_o}
    Gd_O1 in 1 in 1   g value={0}
    Gc1_O1 in 0 in 0   g value={0}
    Gc2_O1 1 0 1 0   g value={0}
    Cd_O1 in 1   C value={0} vinit={0}
    Cc1_O1 in 0   C value={0} vinit={0}
    Cc2_O1 1 0   C value={0} vinit={0}
    E_O2 out 0 0 3   EZ value={A_0/(1 + s/(2*pi*p_1))} zo={R_o}
    Gd_O2 0 3 0 3   g value={0}
    Gc1_O2 0 0 0 0   g value={0}
    Gc2_O2 3 0 3 0   g value={0}
    Cd_O2 0 3   C value={0} vinit={0}
    Cc1_O2 0 0   C value={0} vinit={0}
    Cc2_O2 3 0   C value={0} vinit={0}
    .param R_s ={50}
    .end

### Reference designators of expanded circuit elements

Important

The reference identifiers of the expanded netlist of subcircuits (or expansion models) are those of the parent element extended with `_<ref_EL>`, where `ref_EL` is the reference identifier of the parent element.

Hence, the reference designator of element “Gc1” of operational amplifier “O1” is “Gc1_O1”.

## Displaying a table with element data in LaTeX documents and on HTML pages

With the aid of the report module Create reports, a table with expanded netlist data can be displayed on HTML pages or in LaTeX documents.

Below the script for generating the rst snippet for this help file.

    36# Generate an RST snippet of the table with expanded elements for the Help file
    37rst = sl.RSTformatter()
    38
    39rst.elementData(cir,
    40                caption="Expanded netlist element data").save("table-ZtoV_elements")

Below the expanded netlist table generated with this script.

Table 6 Expanded netlist element data
ID | Nodes | Refs | Model | Param | Symbolic | Numeric
--- | --- | --- | --- | --- | --- | ---
R1 | 4 in |  | R | value | \(R_{s}\) | \(50\)
|  |  |  | noisetemp | \(0\) | \(0\)
|  |  |  | noiseflow | \(0\) | \(0\)
|  |  |  | dcvar | \(0\) | \(0\)
|  |  |  | dcvarlot | \(0\) | \(0\)
R2 | 1 0 |  | R | value | \(R_{a}\) | \(R_{a}\)
|  |  |  | noisetemp | \(0\) | \(0\)
|  |  |  | noiseflow | \(0\) | \(0\)
|  |  |  | dcvar | \(0\) | \(0\)
|  |  |  | dcvarlot | \(0\) | \(0\)
R3 | 2 1 |  | R | value | \(R_{a} \left(A_{1} - 1\right)\) | \(R_{a} \left(A_{1} - 1\right)\)
|  |  |  | noisetemp | \(0\) | \(0\)
|  |  |  | noiseflow | \(0\) | \(0\)
|  |  |  | dcvar | \(0\) | \(0\)
|  |  |  | dcvarlot | \(0\) | \(0\)
R4 | in out |  | R | value | \(R_{f}\) | \(R_{f}\)
|  |  |  | noisetemp | \(0\) | \(0\)
|  |  |  | noiseflow | \(0\) | \(0\)
|  |  |  | dcvar | \(0\) | \(0\)
|  |  |  | dcvarlot | \(0\) | \(0\)
R5 | 2 3 |  | R | value | \(R_{b}\) | \(R_{b}\)
|  |  |  | noisetemp | \(0\) | \(0\)
|  |  |  | noiseflow | \(0\) | \(0\)
|  |  |  | dcvar | \(0\) | \(0\)
|  |  |  | dcvarlot | \(0\) | \(0\)
R6 | 3 out |  | R | value | \(A_{2} R_{b}\) | \(A_{2} R_{b}\)
|  |  |  | noisetemp | \(0\) | \(0\)
|  |  |  | noiseflow | \(0\) | \(0\)
|  |  |  | dcvar | \(0\) | \(0\)
|  |  |  | dcvarlot | \(0\) | \(0\)
V1 | 4 0 |  | V | value | \(0\) | \(0\)
|  |  |  | noise | \(0\) | \(0\)
|  |  |  | dc | \(0\) | \(0\)
|  |  |  | dcvar | \(0\) | \(0\)
E_O1 | 2 0 in 1 |  | EZ | value | \(\frac{A_{0}}{1 + \frac{0.5 s}{\pi p_{1}}}\) | \(\frac{A_{0}}{1 + \frac{0.1592 s}{p_{1}}}\)
|  |  |  | zo | \(R_{o}\) | \(R_{o}\)
Gd_O1 | in 1 in 1 |  | g | value | \(0\) | \(0\)
Gc1_O1 | in 0 in 0 |  | g | value | \(0\) | \(0\)
Gc2_O1 | 1 0 1 0 |  | g | value | \(0\) | \(0\)
Cd_O1 | in 1 |  | C | value | \(0\) | \(0\)
|  |  |  | vinit | \(0\) | \(0\)
Cc1_O1 | in 0 |  | C | value | \(0\) | \(0\)
|  |  |  | vinit | \(0\) | \(0\)
Cc2_O1 | 1 0 |  | C | value | \(0\) | \(0\)
|  |  |  | vinit | \(0\) | \(0\)
E_O2 | out 0 0 3 |  | EZ | value | \(\frac{A_{0}}{1 + \frac{0.5 s}{\pi p_{1}}}\) | \(\frac{A_{0}}{1 + \frac{0.1592 s}{p_{1}}}\)
|  |  |  | zo | \(R_{o}\) | \(R_{o}\)
Gd_O2 | 0 3 0 3 |  | g | value | \(0\) | \(0\)
Gc1_O2 | 0 0 0 0 |  | g | value | \(0\) | \(0\)
Gc2_O2 | 3 0 3 0 |  | g | value | \(0\) | \(0\)
Cd_O2 | 0 3 |  | C | value | \(0\) | \(0\)
|  |  |  | vinit | \(0\) | \(0\)
Cc1_O2 | 0 0 |  | C | value | \(0\) | \(0\)
|  |  |  | vinit | \(0\) | \(0\)
Cc2_O2 | 3 0 |  | C | value | \(0\) | \(0\)
|  |  |  | vinit | \(0\) | \(0\)