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.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

"""
models.py: SLiCAP scripts for the HTML help file
"""
import SLiCAP as sl

###############################################################################
# work with models
###############################################################################

Expanded circuit element data

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

# Create a circuit object
cir = 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.

* Voltage feedback operational amplifier
.subckt OV inP inN out ref av=1M zo=0 gd=0 gc=0 cd=0 cc=0 ; default values
E out ref inP inN EZ value={av} zo={zo}
Gd inP inN inP inN g value={gd}
Gc1 inP ref inP ref g value={gc/2}
Gc2 inN ref inN ref g value={gc/2}
Cd inP inN {cd}
Cc1 inP ref {cc/2}
Cc2 inN ref {cc/2}
.ends

The script below prints the expanded netlist.

# Display the expanded netlist
print('"' + cir.title +'"')
for element in cir.elements.keys():
    refdes = cir.elements[element].refDes
    nodes = ""
    for node in cir.elements[element].nodes:
        nodes += node + " "
    refs = ""
    if len(cir.elements[element].refs):
        for ref in cir.elements[element].refs:
            refs += ref + " "
    model = cir.elements[element].model
    pardefs = ""
    for param in cir.elements[element].params.keys():
        pardefs += str(param) + "={" + str(cir.elements[element].params[param]) +"} "
    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.

# Generate an RST snippet of the table with expanded elements for the Help file
rst = sl.RSTformatter()

rst.elementData(cir, 
                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\)