# Ngspice User Manual

User Manual: Pdf

Open the PDF directly: View PDF .

Page Count: 627

Download | |

Open PDF In Browser | View PDF |

Ngspice Users Manual Version 27plus (Describes ngspice master branch version) Holger Vogt, Marcel Hendrix, Paolo Nenzi December 28, 2017 2 Locations The project and download pages of ngspice may be found at Ngspice home page http://ngspice.sourceforge.net/ Project page at sourceforge http://sourceforge.net/projects/ngspice/ Download page at sourceforge http://sourceforge.net/projects/ngspice/files/ Git source download http://sourceforge.net/scm/?type=cvs&group_id=38962 Status This manual is a work in progress. Some to-dos are listed in Chapt. 24.3. More is surely needed. You are invited to report bugs, missing items, wrongly described items, bad English style etc. How to use this manual The manual is a ‘work in progress’. It may accompany a specific ngspice release, e.g. ngspice24 as manual version 24. If its name contains ‘Version xxplus’, it describes the actual code status, found at the date of issue in the Git Source Code Management (SCM) tool. The manual is intended to provide a complete description of the ngspice functionality, its features, commands, or procedures. It is not a book about learning SPICE usage, but the novice user may find some hints how to start using ngspice. Chapter 21.1 gives a short introduction how to set up and simulate a small circuit. Chapter 32 is about compiling and installing ngspice from a tarball or the actual Git source code, which you may find on the ngspice web pages. If you are running a specific Linux distribution, you may check if it provides ngspice as part of the package. Some are listed here. License This document is covered by the Creative Commons Attribution Share-Alike (CC-BY-SA) v4.0.. Part of chapters 12 and 25-27 are in the public domain. Chapter 30 is covered New BSD, but still under discussion, and therefore may not be available in all distributions. Part I Ngspice User Manual 3 Contents I Ngspice User Manual 1 Introduction 33 1.1 Simulation Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 1.1.1 Analog Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 1.1.2 Digital Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 1.1.3 Mixed-Signal Simulation . . . . . . . . . . . . . . . . . . . . . . . . . 35 1.1.4 Mixed-Level Simulation . . . . . . . . . . . . . . . . . . . . . . . . . 36 Supported Analyses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 1.2.1 DC Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 1.2.2 AC Small-Signal Analysis . . . . . . . . . . . . . . . . . . . . . . . . 38 1.2.3 Transient Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 1.2.4 Pole-Zero Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 1.2.5 Small-Signal Distortion Analysis . . . . . . . . . . . . . . . . . . . . 39 1.2.6 Sensitivity Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 1.2.7 Noise Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 1.2.8 Periodic Steady State Analysis . . . . . . . . . . . . . . . . . . . . . . 40 1.3 Analysis at Different Temperatures . . . . . . . . . . . . . . . . . . . . . . . . 40 1.4 Convergence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 1.4.1 Voltage convergence criterion . . . . . . . . . . . . . . . . . . . . . . 42 1.4.2 Current convergence criterion . . . . . . . . . . . . . . . . . . . . . . 42 1.4.3 Convergence failure . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 1.2 2 3 Circuit Description 45 2.1 General Structure and Conventions . . . . . . . . . . . . . . . . . . . . . . . . 45 2.1.1 Input file structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 2.1.2 Circuit elements (device instances) . . . . . . . . . . . . . . . . . . . 45 2.1.3 Some naming conventions . . . . . . . . . . . . . . . . . . . . . . . . 47 5 6 CONTENTS 2.2 Basic lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 2.2.1 .TITLE line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 2.2.2 .END Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 2.2.3 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 2.2.4 End-of-line comments . . . . . . . . . . . . . . . . . . . . . . . . . . 49 2.3 .MODEL Device Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 2.4 .SUBCKT Subcircuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 2.4.1 .SUBCKT Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 2.4.2 .ENDS Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 2.4.3 Subcircuit Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 2.5 .GLOBAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 2.6 .INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 2.7 .LIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 2.8 .PARAM Parametric netlists . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 2.8.1 .param line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 2.8.2 Brace expressions in circuit elements: . . . . . . . . . . . . . . . . . . 54 2.8.3 Subcircuit parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 2.8.4 Symbol scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 2.8.5 Syntax of expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 56 2.8.6 Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 2.8.7 A word of caution on the three ngspice expression parsers . . . . . . . 59 .FUNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 2.10 .CSPARAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 2.11 .TEMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 2.12 .IF Condition-Controlled Netlist . . . . . . . . . . . . . . . . . . . . . . . . . 61 2.13 Parameters, functions, expressions, and command scripts . . . . . . . . . . . . 62 2.13.1 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 2.13.2 Nonlinear sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 2.13.3 Control commands, Command scripts . . . . . . . . . . . . . . . . . . 62 2.9 3 Circuit Elements and Models 65 3.1 General options and information . . . . . . . . . . . . . . . . . . . . . . . . . 65 3.1.1 Paralleling devices with multiplier m . . . . . . . . . . . . . . . . . . 65 3.1.2 Technology scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 3.1.3 Model binning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 CONTENTS 3.1.4 3.2 4 7 Initial conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Elementary Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 3.2.1 Resistors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 3.2.2 Semiconductor Resistors . . . . . . . . . . . . . . . . . . . . . . . . . 69 3.2.3 Semiconductor Resistor Model (R) . . . . . . . . . . . . . . . . . . . 70 3.2.4 Resistors, dependent on expressions (behavioral resistor) . . . . . . . . 71 3.2.5 Capacitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 3.2.6 Semiconductor Capacitors . . . . . . . . . . . . . . . . . . . . . . . . 73 3.2.7 Semiconductor Capacitor Model (C) . . . . . . . . . . . . . . . . . . . 73 3.2.8 Capacitors, dependent on expressions (behavioral capacitor) . . . . . . 75 3.2.9 Inductors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 3.2.10 Inductor model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 3.2.11 Coupled (Mutual) Inductors . . . . . . . . . . . . . . . . . . . . . . . 78 3.2.12 Inductors, dependent on expressions (behavioral inductor) . . . . . . . 78 3.2.13 Capacitor or inductor with initial conditions . . . . . . . . . . . . . . . 79 3.2.14 Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 3.2.15 Switch Model (SW/CSW) . . . . . . . . . . . . . . . . . . . . . . . . 81 Voltage and Current Sources 83 4.1 Independent Sources for Voltage or Current . . . . . . . . . . . . . . . . . . . 83 4.1.1 Pulse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 4.1.2 Sinusoidal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 4.1.3 Exponential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 4.1.4 Piece-Wise Linear . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 4.1.5 Single-Frequency FM . . . . . . . . . . . . . . . . . . . . . . . . . . 86 4.1.6 Amplitude modulated source (AM) . . . . . . . . . . . . . . . . . . . 87 4.1.7 Transient noise source . . . . . . . . . . . . . . . . . . . . . . . . . . 88 4.1.8 Random voltage source . . . . . . . . . . . . . . . . . . . . . . . . . . 89 4.1.9 External voltage or current input . . . . . . . . . . . . . . . . . . . . . 89 4.1.10 Arbitrary Phase Sources . . . . . . . . . . . . . . . . . . . . . . . . . 90 Linear Dependent Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 4.2.1 Gxxxx: Linear Voltage-Controlled Current Sources (VCCS) . . . . . . 90 4.2.2 Exxxx: Linear Voltage-Controlled Voltage Sources (VCVS) . . . . . . 91 4.2.3 Fxxxx: Linear Current-Controlled Current Sources (CCCS) . . . . . . 91 4.2.4 Hxxxx: Linear Current-Controlled Voltage Sources (CCVS) . . . . . . 91 4.2.5 Polynomial Source Compatibility . . . . . . . . . . . . . . . . . . . . 92 4.2 8 5 CONTENTS Non-linear Dependent Sources (Behavioral Sources) 93 5.1 Bxxxx: Nonlinear dependent source (ASRC) . . . . . . . . . . . . . . . . . . 93 5.1.1 Syntax and usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 5.1.2 Special B-Source Variables time, temper, hertz . . . . . . . . . . . . . 96 5.1.3 par(’expression’) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 5.1.4 Piecewise Linear Function: pwl . . . . . . . . . . . . . . . . . . . . . 97 Exxxx: non-linear voltage source . . . . . . . . . . . . . . . . . . . . . . . . . 99 5.2.1 VOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 5.2.2 VALUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 5.2.3 TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 5.2.4 POLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 5.2.5 LAPLACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 5.2 5.3 5.4 6 Gxxxx: non-linear current source . . . . . . . . . . . . . . . . . . . . . . . . . 102 5.3.1 CUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 5.3.2 VALUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 5.3.3 TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 5.3.4 POLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 5.3.5 LAPLACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 5.3.6 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Debugging a behavioral source . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Transmission Lines 6.1 Lossless Transmission Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 6.2 Lossy Transmission Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 6.2.1 6.3 6.4 Lossy Transmission Line Model (LTRA) . . . . . . . . . . . . . . . . 108 Uniform Distributed RC Lines . . . . . . . . . . . . . . . . . . . . . . . . . . 110 6.3.1 7 107 Uniform Distributed RC Model (URC) . . . . . . . . . . . . . . . . . 110 KSPICE Lossy Transmission Lines . . . . . . . . . . . . . . . . . . . . . . . . 111 6.4.1 Single Lossy Transmission Line (TXL) . . . . . . . . . . . . . . . . . 111 6.4.2 Coupled Multiconductor Line (CPL) . . . . . . . . . . . . . . . . . . . 112 Diodes 115 7.1 Junction Diodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 7.2 Diode Model (D) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 7.3 Diode Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 CONTENTS 8 9 BJTs 9 123 8.1 Bipolar Junction Transistors (BJTs) . . . . . . . . . . . . . . . . . . . . . . . 123 8.2 BJT Models (NPN/PNP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 JFETs 129 9.1 Junction Field-Effect Transistors (JFETs) . . . . . . . . . . . . . . . . . . . . 129 9.2 JFET Models (NJF/PJF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 9.2.1 JFET level 1 model with Parker Skellern modification . . . . . . . . . 129 9.2.2 JFET level 2 Parker Skellern model . . . . . . . . . . . . . . . . . . . 131 10 MESFETs 133 10.1 MESFETs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 10.2 MESFET Models (NMF/PMF) . . . . . . . . . . . . . . . . . . . . . . . . . . 133 10.2.1 Model by Statz e.a. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 10.2.2 Model by Ytterdal e.a. . . . . . . . . . . . . . . . . . . . . . . . . . . 134 10.2.3 hfet1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 10.2.4 hfet2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 11 MOSFETs 135 11.1 MOSFET devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 11.2 MOSFET models (NMOS/PMOS) . . . . . . . . . . . . . . . . . . . . . . . . 136 11.2.1 MOS Level 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 11.2.2 MOS Level 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 11.2.3 MOS Level 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 11.2.4 MOS Level 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 11.2.5 Notes on Level 1-6 models . . . . . . . . . . . . . . . . . . . . . . . . 138 11.2.6 MOS Level 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 11.2.7 BSIM Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 11.2.8 BSIM1 model (level 4) . . . . . . . . . . . . . . . . . . . . . . . . . . 142 11.2.9 BSIM2 model (level 5) . . . . . . . . . . . . . . . . . . . . . . . . . . 143 11.2.10 BSIM3 model (levels 8, 49) . . . . . . . . . . . . . . . . . . . . . . . 143 11.2.11 BSIM4 model (levels 14, 54) . . . . . . . . . . . . . . . . . . . . . . . 144 11.2.12 EKV model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 11.2.13 BSIMSOI models (levels 10, 58, 55, 56, 57) . . . . . . . . . . . . . . . 145 11.2.14 SOI3 model (level 60) . . . . . . . . . . . . . . . . . . . . . . . . . . 145 11.2.15 HiSIM models of the University of Hiroshima . . . . . . . . . . . . . . 145 10 CONTENTS 12 Mixed-Mode and Behavioral Modeling with XSPICE 147 12.1 Code Model Element & .MODEL Cards . . . . . . . . . . . . . . . . . . . . . 147 12.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 12.1.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 12.1.3 Search path for file input . . . . . . . . . . . . . . . . . . . . . . . . . 152 12.2 Analog Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 12.2.1 Gain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 12.2.2 Summer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 12.2.3 Multiplier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 12.2.4 Divider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 12.2.5 Limiter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 12.2.6 Controlled Limiter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 12.2.7 PWL Controlled Source . . . . . . . . . . . . . . . . . . . . . . . . . 160 12.2.8 Filesource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 12.2.9 multi_input_pwl block . . . . . . . . . . . . . . . . . . . . . . . . . . 164 12.2.10 Analog Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 12.2.11 Zener Diode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 12.2.12 Current Limiter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 12.2.13 Hysteresis Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 12.2.14 Differentiator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 12.2.15 Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 12.2.16 S-Domain Transfer Function . . . . . . . . . . . . . . . . . . . . . . . 174 12.2.17 Slew Rate Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 12.2.18 Inductive Coupling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 12.2.19 Magnetic Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 12.2.20 Controlled Sine Wave Oscillator . . . . . . . . . . . . . . . . . . . . . 183 12.2.21 Controlled Triangle Wave Oscillator . . . . . . . . . . . . . . . . . . . 184 12.2.22 Controlled Square Wave Oscillator . . . . . . . . . . . . . . . . . . . . 185 12.2.23 Controlled One-Shot . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 12.2.24 Capacitance Meter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 12.2.25 Inductance Meter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 12.2.26 Memristor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 12.2.27 2D table model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 12.2.28 3D table model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 12.3 Hybrid Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 CONTENTS 11 12.3.1 Digital-to-Analog Node Bridge . . . . . . . . . . . . . . . . . . . . . 195 12.3.2 Analog-to-Digital Node Bridge . . . . . . . . . . . . . . . . . . . . . 197 12.3.3 Controlled Digital Oscillator . . . . . . . . . . . . . . . . . . . . . . . 198 12.3.4 Node bridge from digital to real with enable . . . . . . . . . . . . . . . 199 12.3.5 A Z**-1 block working on real data . . . . . . . . . . . . . . . . . . . 200 12.3.6 A gain block for event-driven real data . . . . . . . . . . . . . . . . . . 200 12.3.7 Node bridge from real to analog voltage . . . . . . . . . . . . . . . . . 201 12.4 Digital Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 12.4.1 Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 12.4.2 Inverter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 12.4.3 And . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 12.4.4 Nand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 12.4.5 Or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 12.4.6 Nor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 12.4.7 Xor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 12.4.8 Xnor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 12.4.9 Tristate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 12.4.10 Pullup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 12.4.11 Pulldown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 12.4.12 D Flip Flop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 12.4.13 JK Flip Flop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 12.4.14 Toggle Flip Flop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 12.4.15 Set-Reset Flip Flop . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 12.4.16 D Latch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 12.4.17 Set-Reset Latch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 12.4.18 State Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 12.4.19 Frequency Divider . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 12.4.20 RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 12.4.21 Digital Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 12.4.22 LUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 12.4.23 General LUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 12.5 Predefined Node Types for event driven simulation . . . . . . . . . . . . . . . 238 12.5.1 Digital Node Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 12.5.2 Real Node Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 12.5.3 Int Node Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 12.5.4 (Digital) Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . 238 12 CONTENTS 13 Verilog A Device models 241 13.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 13.2 adms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 13.3 How to integrate a Verilog-A model into ngspice . . . . . . . . . . . . . . . . 241 13.3.1 How to setup a *.va model for ngspice . . . . . . . . . . . . . . . . . . 241 13.3.2 Adding admsXml to your build environment . . . . . . . . . . . . . . 241 14 Mixed-Level Simulation (ngspice with TCAD) 243 14.1 Cider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 14.2 GSS, Genius . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 15 Analyses and Output Control (batch mode) 245 15.1 Simulator Variables (.options) . . . . . . . . . . . . . . . . . . . . . . . . . . 245 15.1.1 General Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 15.1.2 DC Solution Options . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 15.1.3 AC Solution Options . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 15.1.4 Transient Analysis Options . . . . . . . . . . . . . . . . . . . . . . . . 248 15.1.5 ELEMENT Specific options . . . . . . . . . . . . . . . . . . . . . . . 249 15.1.6 Transmission Lines Specific Options . . . . . . . . . . . . . . . . . . . 250 15.1.7 Precedence of option and .options commands . . . . . . . . . . . . . . 250 15.2 Initial Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 15.2.1 .NODESET: Specify Initial Node Voltage Guesses . . . . . . . . . . . 250 15.2.2 .IC: Set Initial Conditions . . . . . . . . . . . . . . . . . . . . . . . . 251 15.3 Analyses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 15.3.1 .AC: Small-Signal AC Analysis . . . . . . . . . . . . . . . . . . . . . 252 15.3.2 .DC: DC Transfer Function . . . . . . . . . . . . . . . . . . . . . . . . 253 15.3.3 .DISTO: Distortion Analysis . . . . . . . . . . . . . . . . . . . . . . . 253 15.3.4 .NOISE: Noise Analysis . . . . . . . . . . . . . . . . . . . . . . . . . 255 15.3.5 .OP: Operating Point Analysis . . . . . . . . . . . . . . . . . . . . . . 255 15.3.6 .PZ: Pole-Zero Analysis . . . . . . . . . . . . . . . . . . . . . . . . . 256 15.3.7 .SENS: DC or Small-Signal AC Sensitivity Analysis . . . . . . . . . . 257 15.3.8 .TF: Transfer Function Analysis . . . . . . . . . . . . . . . . . . . . . 257 15.3.9 .TRAN: Transient Analysis . . . . . . . . . . . . . . . . . . . . . . . . 258 15.3.10 Transient noise analysis (at low frequency) . . . . . . . . . . . . . . . 258 15.3.11 .PSS: Periodic Steady State Analysis . . . . . . . . . . . . . . . . . . 262 15.4 Measurements after AC, DC and Transient Analysis . . . . . . . . . . . . . . . 263 CONTENTS 13 15.4.1 .meas(ure) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 15.4.2 batch versus interactive mode . . . . . . . . . . . . . . . . . . . . . . 263 15.4.3 General remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 15.4.4 Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 15.4.5 Trig Targ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 15.4.6 Find ... When . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 15.4.7 AVG|MIN|MAX|PP|RMS|MIN_AT|MAX_AT . . . . . . . . . . . . . . . . 267 15.4.8 Integ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 15.4.9 param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 15.4.10 par(’expression’) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 15.4.11 Deriv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 15.4.12 More examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 15.5 Safe Operating Area (SOA) warning messages . . . . . . . . . . . . . . . . . . 270 15.5.1 Resistor and Capacitor SOA model parameters . . . . . . . . . . . . . 271 15.5.2 Diode SOA model parameter . . . . . . . . . . . . . . . . . . . . . . . 271 15.5.3 BJT SOA model parameter . . . . . . . . . . . . . . . . . . . . . . . . 271 15.5.4 MOS SOA model parameter . . . . . . . . . . . . . . . . . . . . . . . 271 15.6 Batch Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 15.6.1 .SAVE: Name vector(s) to be saved in raw file . . . . . . . . . . . . . . 272 15.6.2 .PRINT Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 15.6.3 .PLOT Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 15.6.4 .FOUR: Fourier Analysis of Transient Analysis Output . . . . . . . . . 274 15.6.5 .PROBE: Name vector(s) to be saved in raw file . . . . . . . . . . . . . 275 15.6.6 par(’expression’): Algebraic expressions for output . . . . . . . . . . . 275 15.6.7 .width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 15.7 Measuring current through device terminals . . . . . . . . . . . . . . . . . . . 276 15.7.1 Adding a voltage source in series . . . . . . . . . . . . . . . . . . . . 276 15.7.2 Using option ’savecurrents’ . . . . . . . . . . . . . . . . . . . . . . . 276 16 Starting ngspice 279 16.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 16.2 Where to obtain ngspice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 16.3 Command line options for starting ngspice and ngnutmeg . . . . . . . . . . . . 280 16.4 Starting options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 16.4.1 Batch mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 14 CONTENTS 16.4.2 Interactive mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 16.4.3 Control mode (Interactive mode with control file or control section) . . 283 16.5 Standard configuration file spinit . . . . . . . . . . . . . . . . . . . . . . . . . 284 16.6 User defined configuration file .spiceinit . . . . . . . . . . . . . . . . . . . . . 285 16.7 Environmental variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 16.7.1 Ngspice specific variables . . . . . . . . . . . . . . . . . . . . . . . . 285 16.7.2 Common environment variables . . . . . . . . . . . . . . . . . . . . . 286 16.8 Memory usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 16.9 Simulation time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 16.10Ngspice on multi-core processors using OpenMP . . . . . . . . . . . . . . . . 287 16.10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 16.10.2 Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 16.10.3 Some results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 16.10.4 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 16.10.5 Literature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 16.11Server mode option -s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 16.12Ngspice control via input, output fifos . . . . . . . . . . . . . . . . . . . . . . 291 16.13Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 16.13.1 Compatibility mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 16.13.2 Missing functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 16.13.3 Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 16.13.4 Controls and commands . . . . . . . . . . . . . . . . . . . . . . . . . 294 16.14Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 16.15Reporting bugs and errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 17 Interactive Interpreter 297 17.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 17.2 Expressions, Functions, and Constants . . . . . . . . . . . . . . . . . . . . . . 298 17.3 Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 17.4 Command Interpretation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 17.4.1 On the console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 17.4.2 Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 17.4.3 Add-on to circuit file . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 17.5 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 17.5.1 Ac*: Perform an AC, small-signal frequency response analysis . . . . . 304 CONTENTS 15 17.5.2 Alias: Create an alias for a command . . . . . . . . . . . . . . . . . . 305 17.5.3 Alter*: Change a device or model parameter . . . . . . . . . . . . . . 305 17.5.4 Altermod*: Change model parameter(s) . . . . . . . . . . . . . . . . 306 17.5.5 Asciiplot: Plot values using old-style character plots . . . . . . . . . . 308 17.5.6 Aspice*: Asynchronous ngspice run . . . . . . . . . . . . . . . . . . . 308 17.5.7 Bug: Mail a bug report . . . . . . . . . . . . . . . . . . . . . . . . . . 308 17.5.8 Cd: Change directory . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 17.5.9 Cdump: Dump the control flow to the screen . . . . . . . . . . . . . . 309 17.5.10 Circbyline*: Enter a circuit line by line . . . . . . . . . . . . . . . . . 309 17.5.11 Codemodel*: Load an XSPICE code model library . . . . . . . . . . . 310 17.5.12 Compose: Compose a vector . . . . . . . . . . . . . . . . . . . . . . . 310 17.5.13 Dc*: Perform a DC-sweep analysis . . . . . . . . . . . . . . . . . . . 311 17.5.14 Define: Define a function . . . . . . . . . . . . . . . . . . . . . . . . . 311 17.5.15 Deftype: Define a new type for a vector or plot . . . . . . . . . . . . . 311 17.5.16 Delete*: Remove a trace or breakpoint . . . . . . . . . . . . . . . . . . 312 17.5.17 Destroy: Delete an output data set . . . . . . . . . . . . . . . . . . . . 312 17.5.18 Devhelp: information on available devices . . . . . . . . . . . . . . . . 312 17.5.19 Diff: Compare vectors . . . . . . . . . . . . . . . . . . . . . . . . . . 313 17.5.20 Display: List known vectors and types . . . . . . . . . . . . . . . . . . 313 17.5.21 Echo: Print text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 17.5.22 Edit*: Edit the current circuit . . . . . . . . . . . . . . . . . . . . . . 313 17.5.23 Edisplay: Print a list of all the event nodes . . . . . . . . . . . . . . . 314 17.5.24 Eprint: Print an event driven node . . . . . . . . . . . . . . . . . . . . 314 17.5.25 Eprvcd: Dump event nodes in VCD format . . . . . . . . . . . . . . . 314 17.5.26 FFT: fast Fourier transform of vectors . . . . . . . . . . . . . . . . . . 314 17.5.27 Fourier: Perform a Fourier transform . . . . . . . . . . . . . . . . . . 316 17.5.28 Gnuplot: Graphics output via gnuplot . . . . . . . . . . . . . . . . . . 317 17.5.29 Hardcopy: Save a plot to a file for printing . . . . . . . . . . . . . . . 317 17.5.30 Help: Print summaries of Ngspice commands . . . . . . . . . . . . . . 318 17.5.31 History: Review previous commands . . . . . . . . . . . . . . . . . . 318 17.5.32 Inventory: Print circuit inventory . . . . . . . . . . . . . . . . . . . . . 321 17.5.33 Iplot*: Incremental plot . . . . . . . . . . . . . . . . . . . . . . . . . 321 17.5.34 Jobs*: List active asynchronous ngspice runs . . . . . . . . . . . . . . 321 17.5.35 Let: Assign a value to a vector . . . . . . . . . . . . . . . . . . . . . . 321 17.5.36 Linearize*: Interpolate to a linear scale . . . . . . . . . . . . . . . . . 322 16 CONTENTS 17.5.37 Listing*: Print a listing of the current circuit . . . . . . . . . . . . . . 323 17.5.38 Load: Load rawfile data . . . . . . . . . . . . . . . . . . . . . . . . . 323 17.5.39 Meas*: Measurements on simulation data . . . . . . . . . . . . . . . . 323 17.5.40 Mdump*: Dump the matrix values to a file (or to console) . . . . . . . 324 17.5.41 Mrdump*: Dump the matrix right hand side values to a file (or to console)324 17.5.42 Noise*: Noise analysis . . . . . . . . . . . . . . . . . . . . . . . . . . 324 17.5.43 Op*: Perform an operating point analysis . . . . . . . . . . . . . . . . 325 17.5.44 Option*: Set a ngspice option . . . . . . . . . . . . . . . . . . . . . . 325 17.5.45 Plot: Plot vectors on the display . . . . . . . . . . . . . . . . . . . . . 326 17.5.46 Pre_: execute commands prior to parsing the circuit . . . . 327 17.5.47 Print: Print values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 17.5.48 Psd: power spectral density of vectors . . . . . . . . . . . . . . . . . . 328 17.5.49 Quit: Leave Ngspice or Nutmeg . . . . . . . . . . . . . . . . . . . . . 329 17.5.50 Rehash: Reset internal hash tables . . . . . . . . . . . . . . . . . . . . 329 17.5.51 Remcirc*: Remove the current circuit . . . . . . . . . . . . . . . . . . 329 17.5.52 Reset*: Reset an analysis . . . . . . . . . . . . . . . . . . . . . . . . . 329 17.5.53 Reshape: Alter the dimensionality or dimensions of a vector . . . . . . 330 17.5.54 Resume*: Continue a simulation after a stop . . . . . . . . . . . . . . 330 17.5.55 Rspice*: Remote ngspice submission . . . . . . . . . . . . . . . . . . 330 17.5.56 Run*: Run analysis from the input file . . . . . . . . . . . . . . . . . . 331 17.5.57 Rusage: Resource usage . . . . . . . . . . . . . . . . . . . . . . . . . 331 17.5.58 Save*: Save a set of outputs . . . . . . . . . . . . . . . . . . . . . . . 332 17.5.59 Sens*: Run a sensitivity analysis . . . . . . . . . . . . . . . . . . . . . 333 17.5.60 Set: Set the value of a variable . . . . . . . . . . . . . . . . . . . . . . 334 17.5.61 Setcirc*: Change the current circuit . . . . . . . . . . . . . . . . . . . 334 17.5.62 Setplot: Switch the current set of vectors . . . . . . . . . . . . . . . . 334 17.5.63 Setscale: Set the scale vector for the current plot . . . . . . . . . . . . 335 17.5.64 Settype: Set the type of a vector . . . . . . . . . . . . . . . . . . . . . 335 17.5.65 Shell: Call the command interpreter . . . . . . . . . . . . . . . . . . . 335 17.5.66 Shift: Alter a list variable . . . . . . . . . . . . . . . . . . . . . . . . . 335 17.5.67 Show*: List device state . . . . . . . . . . . . . . . . . . . . . . . . . 336 17.5.68 Showmod*: List model parameter values . . . . . . . . . . . . . . . . 336 17.5.69 Snload*: Load the snapshot file . . . . . . . . . . . . . . . . . . . . . 336 17.5.70 Snsave*: Save a snapshot file . . . . . . . . . . . . . . . . . . . . . . 337 17.5.71 Source: Read a ngspice input file . . . . . . . . . . . . . . . . . . . . 338 CONTENTS 17 17.5.72 Spec: Create a frequency domain plot . . . . . . . . . . . . . . . . . . 339 17.5.73 Status*: Display breakpoint information . . . . . . . . . . . . . . . . . 339 17.5.74 Step*: Run a fixed number of time-points . . . . . . . . . . . . . . . . 339 17.5.75 Stop*: Set a breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . 340 17.5.76 Strcmp: Compare two strings . . . . . . . . . . . . . . . . . . . . . . 340 17.5.77 Sysinfo*: Print system information . . . . . . . . . . . . . . . . . . . 341 17.5.78 Tf*: Run a Transfer Function analysis . . . . . . . . . . . . . . . . . . 341 17.5.79 Trace*: Trace nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 17.5.80 Tran*: Perform a transient analysis . . . . . . . . . . . . . . . . . . . 342 17.5.81 Transpose: Swap the elements in a multi-dimensional data set . . . . . 343 17.5.82 Unalias: Retract an alias . . . . . . . . . . . . . . . . . . . . . . . . . 343 17.5.83 Undefine: Retract a definition . . . . . . . . . . . . . . . . . . . . . . 343 17.5.84 Unlet: Delete the specified vector(s) . . . . . . . . . . . . . . . . . . . 343 17.5.85 Unset: Clear a variable . . . . . . . . . . . . . . . . . . . . . . . . . . 344 17.5.86 Version: Print the version of ngspice . . . . . . . . . . . . . . . . . . . 344 17.5.87 Where*: Identify troublesome node or device . . . . . . . . . . . . . . 345 17.5.88 Wrdata: Write data to a file (simple table) . . . . . . . . . . . . . . . . 346 17.5.89 Write: Write data to a file (Spice3f5 format) . . . . . . . . . . . . . . . 346 17.5.90 Wrs2p: Write scattering parameters to file (Touchstone® format) . . . 347 17.5.91 Xgraph: use the xgraph(1) program for plotting. . . . . . . . . . . . . 347 17.6 Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 17.6.1 While - End . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 17.6.2 Repeat - End . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 17.6.3 Dowhile - End . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 17.6.4 Foreach - End . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 17.6.5 If - Then - Else . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 17.6.6 Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 17.6.7 Goto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 17.6.8 Continue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 17.6.9 Break . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 17.7 Internally predefined variables . . . . . . . . . . . . . . . . . . . . . . . . . . 350 17.8 Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 17.8.1 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 17.8.2 Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 17.8.3 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 18 CONTENTS 17.8.4 control structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 17.8.5 Example script ’spectrum’ . . . . . . . . . . . . . . . . . . . . . . . . 360 17.8.6 Example script for random numbers . . . . . . . . . . . . . . . . . . . 362 17.8.7 Parameter sweep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 17.8.8 Output redirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 17.9 Scattering parameters (s-parameters) . . . . . . . . . . . . . . . . . . . . . . . 365 17.9.1 Intro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 17.9.2 S-parameter measurement basics . . . . . . . . . . . . . . . . . . . . . 365 17.9.3 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 17.10MISCELLANEOUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 17.11Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 18 Ngspice User Interfaces 369 18.1 MS Windows Graphical User Interface . . . . . . . . . . . . . . . . . . . . . . 369 18.2 MS Windows Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 18.3 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 18.4 CygWin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 18.5 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 18.6 Postscript printing options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 18.7 Gnuplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 18.8 Integration with CAD software and ‘third party’ GUIs . . . . . . . . . . . . . . 374 18.8.1 KiCad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 18.8.2 GNU Spice GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 18.8.3 XCircuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 18.8.4 GEDA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 18.8.5 MSEspice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 18.8.6 GNU Octave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 19 ngspice as shared library or dynamic link library 377 19.1 Compile options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 19.1.1 How to get the sources . . . . . . . . . . . . . . . . . . . . . . . . . . 377 19.1.2 Linux, MINGW, CYGWIN . . . . . . . . . . . . . . . . . . . . . . . 377 19.1.3 MS Visual Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 19.2 Linking shared ngspice to a calling application . . . . . . . . . . . . . . . . . 378 19.2.1 Linking during creating the caller . . . . . . . . . . . . . . . . . . . . 378 19.2.2 Loading at runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 CONTENTS 19 19.3 Shared ngspice API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 19.3.1 structs and types defined for transporting data . . . . . . . . . . . . . . 378 19.3.2 Exported functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 19.3.3 Callback functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 19.4 General remarks on using the API . . . . . . . . . . . . . . . . . . . . . . . . 384 19.4.1 Loading a netlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 19.4.2 Running the simulation . . . . . . . . . . . . . . . . . . . . . . . . . . 385 19.4.3 Accessing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 19.4.4 Altering model or device parameters . . . . . . . . . . . . . . . . . . . 387 19.4.5 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 19.4.6 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 19.5 Example applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 19.6 ngspice parallel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 19.6.1 Go parallel! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 19.6.2 Additional exported functions . . . . . . . . . . . . . . . . . . . . . . 389 19.6.3 Additional callback functions . . . . . . . . . . . . . . . . . . . . . . 390 19.6.4 Parallel ngspice example . . . . . . . . . . . . . . . . . . . . . . . . . 391 20 TCLspice 393 20.1 tclspice framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 20.2 tclspice documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 20.3 spicetoblt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 20.4 Running TCLspice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 20.5 examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 20.5.1 Active capacitor measurement . . . . . . . . . . . . . . . . . . . . . . 394 20.5.2 Optimization of a linearization circuit for a Thermistor . . . . . . . . . 397 20.5.3 Progressive display . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 20.6 Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 20.6.1 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 20.6.2 MS Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 20.7 MS Windows 32 Bit binaries . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 20 CONTENTS 21 Example Circuits 405 21.1 AC coupled transistor amplifier . . . . . . . . . . . . . . . . . . . . . . . . . . 405 21.2 Differential Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 21.3 MOSFET Characterization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 21.4 RTL Inverter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 21.5 Four-Bit Binary Adder (Bipolar) . . . . . . . . . . . . . . . . . . . . . . . . . 412 21.6 Four-Bit Binary Adder (MOS) . . . . . . . . . . . . . . . . . . . . . . . . . . 414 21.7 Transmission-Line Inverter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 22 Statistical circuit analysis 417 22.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 22.2 Using random param(eters) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 22.3 Behavioral sources (B, E, G, R, L, C) with random control . . . . . . . . . . . 419 22.4 ngspice scripting language . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 22.5 Monte-Carlo Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 22.5.1 Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 22.5.2 Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 22.5.3 Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 22.6 Data evaluation with Gnuplot . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 23 Circuit optimization with ngspice 427 23.1 Optimization of a circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 23.2 ngspice optimizer using ngspice scripts . . . . . . . . . . . . . . . . . . . . . 428 23.3 ngspice optimizer using tclspice . . . . . . . . . . . . . . . . . . . . . . . . . 428 23.4 ngspice optimizer using a Python script . . . . . . . . . . . . . . . . . . . . . 428 23.5 ngspice optimizer using ASCO . . . . . . . . . . . . . . . . . . . . . . . . . . 428 23.5.1 Three stage operational amplifier . . . . . . . . . . . . . . . . . . . . . 429 23.5.2 Digital inverter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 23.5.3 Bandpass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 23.5.4 Class-E power amplifier . . . . . . . . . . . . . . . . . . . . . . . . . 433 24 Notes 435 24.1 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 24.2 Acronyms and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 24.3 To Do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 CONTENTS II 21 XSPICE Software User’s Manual 25 XSPICE Basics 441 443 25.1 ngspice with the XSPICE option . . . . . . . . . . . . . . . . . . . . . . . . . 443 25.2 The XSPICE Code Model Subsystem . . . . . . . . . . . . . . . . . . . . . . 443 25.3 XSPICE Top-Level Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 26 Execution Procedures 445 26.1 Simulation and Modeling Overview . . . . . . . . . . . . . . . . . . . . . . . 445 26.1.1 Describing the Circuit . . . . . . . . . . . . . . . . . . . . . . . . . . 445 26.2 Circuit Description Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 26.2.1 XSPICE Syntax Extensions . . . . . . . . . . . . . . . . . . . . . . . 451 26.3 How to create code models . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 27 Example circuits 457 27.1 Amplifier with XSPICE model ‘gain’ . . . . . . . . . . . . . . . . . . . . . . 457 27.2 XSPICE advanced usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459 27.2.1 Circuit example C3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459 27.2.2 Running example C3 . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 28 Code Models and User-Defined Nodes 467 28.1 Code Model Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . 468 28.2 Creating Code Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 28.3 Creating User-Defined Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 28.4 Adding a new code model library . . . . . . . . . . . . . . . . . . . . . . . . . 470 28.5 Compiling and loading the new code model (library) . . . . . . . . . . . . . . 470 28.6 Interface Specification File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 28.6.1 The Name Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473 28.6.2 The Port Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473 28.6.3 The Parameter Table . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 28.6.4 Static Variable Table . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 28.7 Model Definition File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478 28.7.1 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478 28.7.2 Function Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 28.8 User-Defined Node Definition File . . . . . . . . . . . . . . . . . . . . . . . . 494 28.8.1 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 28.8.2 Function Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 28.8.3 Example UDN Definition File . . . . . . . . . . . . . . . . . . . . . . 498 22 CONTENTS 29 Error Messages 503 29.1 Preprocessor Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 29.2 Simulator Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 29.3 Code Model Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 29.3.1 Code Model aswitch . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 29.3.2 Code Model climit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 29.3.3 Code Model core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 29.3.4 Code Model d_osc . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 29.3.5 Code Model d_source . . . . . . . . . . . . . . . . . . . . . . . . . . 511 29.3.6 Code Model d_state . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 29.3.7 Code Model oneshot . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 29.3.8 Code Model pwl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 29.3.9 Code Model s_xfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 29.3.10 Code Model sine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 29.3.11 Code Model square . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 29.3.12 Code Model triangle . . . . . . . . . . . . . . . . . . . . . . . . . . . 514 III CIDER 30 CIDER User’s Manual 515 517 30.1 SPECIFICATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 30.1.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 30.2 BOUNDARY, INTERFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 30.2.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 30.2.2 PARAMETERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 30.2.3 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 30.3 COMMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 30.3.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 30.3.2 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 30.4 CONTACT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 30.4.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 30.4.2 PARAMETERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 30.4.3 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 30.4.4 SEE ALSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 30.5 DOMAIN, REGION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 CONTENTS 30.5.1 DESCRIPTION 23 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 30.5.2 PARAMETERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 30.5.3 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 30.5.4 SEE ALSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 30.6 DOPING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 30.6.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 30.6.2 PARAMETERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 30.6.3 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 30.6.4 SEE ALSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 30.7 ELECTRODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 30.7.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 30.7.2 PARAMETERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 30.7.3 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 30.7.4 SEE ALSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 30.8 END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 30.8.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 30.9 MATERIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 30.9.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 30.9.2 PARAMETERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 30.9.3 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 30.9.4 SEE ALSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 30.10METHOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 30.10.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 30.10.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 30.10.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 30.11Mobility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 30.11.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 30.11.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 30.11.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 30.11.4 SEE ALSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 30.11.5 BUGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 30.12MODELS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 30.12.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 30.12.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 30.12.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 24 CONTENTS 30.12.4 See also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 30.12.5 Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 30.13OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 30.13.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 30.13.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 30.13.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 30.13.4 See also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 30.14OUTPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 30.14.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 30.14.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 30.14.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 30.14.4 SEE ALSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 30.15TITLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 30.15.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 30.15.2 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 30.15.3 BUGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 30.16X.MESH, Y.MESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 30.16.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 30.16.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 30.16.3 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 30.16.4 SEE ALSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 30.17NUMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 30.17.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 30.17.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 30.17.3 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 30.17.4 SEE ALSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 30.17.5 BUGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 30.18NBJT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 30.18.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 30.18.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 30.18.3 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 30.18.4 SEE ALSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 30.18.5 BUGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 30.19NUMOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 30.19.1 DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 CONTENTS 25 30.19.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 30.19.3 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 30.19.4 SEE ALSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 30.20Cider examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 IV Appendices 31 Model and Device Parameters 549 551 31.1 Accessing internal device parameters . . . . . . . . . . . . . . . . . . . . . . . 551 31.2 Elementary Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 31.2.1 Resistor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 31.2.2 Capacitor - Fixed capacitor . . . . . . . . . . . . . . . . . . . . . . . . 555 31.2.3 Inductor - Fixed inductor . . . . . . . . . . . . . . . . . . . . . . . . . 556 31.2.4 Mutual - Mutual Inductor . . . . . . . . . . . . . . . . . . . . . . . . . 557 31.3 Voltage and current sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 31.3.1 ASRC - Arbitrary source . . . . . . . . . . . . . . . . . . . . . . . . . 558 31.3.2 Isource - Independent current source . . . . . . . . . . . . . . . . . . . 559 31.3.3 Vsource - Independent voltage source . . . . . . . . . . . . . . . . . . 560 31.3.4 CCCS - Current controlled current source . . . . . . . . . . . . . . . . 561 31.3.5 CCVS - Current controlled voltage source . . . . . . . . . . . . . . . . 561 31.3.6 VCCS - Voltage controlled current source . . . . . . . . . . . . . . . . 562 31.3.7 VCVS - Voltage controlled voltage source . . . . . . . . . . . . . . . . 562 31.4 Transmission Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 31.4.1 CplLines - Simple Coupled Multiconductor Lines . . . . . . . . . . . . 563 31.4.2 LTRA - Lossy transmission line . . . . . . . . . . . . . . . . . . . . . 564 31.4.3 Tranline - Lossless transmission line . . . . . . . . . . . . . . . . . . . 565 31.4.4 TransLine - Simple Lossy Transmission Line . . . . . . . . . . . . . . 566 31.4.5 URC - Uniform R. C. line . . . . . . . . . . . . . . . . . . . . . . . . 567 31.5 BJTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 31.5.1 BJT - Bipolar Junction Transistor . . . . . . . . . . . . . . . . . . . . 568 31.5.2 BJT - Bipolar Junction Transistor Level 2 . . . . . . . . . . . . . . . . 571 31.5.3 VBIC - Vertical Bipolar Inter-Company Model . . . . . . . . . . . . . 574 31.6 MOSFETs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 31.6.1 MOS1 - Level 1 MOSFET model with Meyer capacitance model . . . . 578 31.6.2 MOS2 - Level 2 MOSFET model with Meyer capacitance model . . . . 581 26 CONTENTS 31.6.3 MOS3 - Level 3 MOSFET model with Meyer capacitance model . . . . 585 31.6.4 MOS6 - Level 6 MOSFET model with Meyer capacitance model . . . . 589 31.6.5 MOS9 - Modified Level 3 MOSFET model . . . . . . . . . . . . . . . 592 31.6.6 BSIM1 - Berkeley Short Channel IGFET Model . . . . . . . . . . . . 596 31.6.7 BSIM2 - Berkeley Short Channel IGFET Model . . . . . . . . . . . . 599 31.6.8 BSIM3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 31.6.9 BSIM4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 32 Compilation notes 607 32.1 Ngspice Installation under Linux (and other ’UNIXes’) . . . . . . . . . . . . . 607 32.1.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 32.1.2 Install from Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 32.1.3 Install from a tarball, e.g. ngspice-rework-27.tgz . . . . . . . . . . . . 609 32.1.4 Compilation using an user defined directory tree for object files . . . . 609 32.1.5 Advanced Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 32.1.6 Compilers and Options . . . . . . . . . . . . . . . . . . . . . . . . . . 612 32.1.7 Compiling For Multiple Architectures . . . . . . . . . . . . . . . . . . 612 32.1.8 Installation Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612 32.1.9 Optional Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 32.1.10 Specifying the System Type . . . . . . . . . . . . . . . . . . . . . . . 613 32.1.11 Sharing Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 32.1.12 Operation Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 32.2 Ngspice Compilation under Windows OS . . . . . . . . . . . . . . . . . . . . 614 32.2.1 Compile ngspice with MS Visual Studio 2015 or 2017 . . . . . . . . . 614 32.2.2 How to make ngspice with MINGW and MSYS . . . . . . . . . . . . 616 32.2.3 64 Bit executables with MINGW-w64 . . . . . . . . . . . . . . . . . . 618 32.2.4 make ngspice with pure CYGWIN . . . . . . . . . . . . . . . . . . . . 620 32.2.5 ngspice mingw or cygwin console executable w/o graphics . . . . . . . 620 32.2.6 ngspice for MS Windows, cross compiled from Linux . . . . . . . . . 620 32.3 Reporting errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 33 Copyrights and licenses 623 33.1 Documentation license . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 33.2 ngspice license . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 33.3 Some license details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 33.3.1 CC-BY-SA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 CONTENTS 27 33.3.2 ‘Modified’ BSD license . . . . . . . . . . . . . . . . . . . . . . . . . 624 33.4 Some notes on the historical evolvement of the ngspice licenses . . . . . . . . 625 33.4.1 Original spice documentation copyright . . . . . . . . . . . . . . . . . 625 33.4.2 XSPICE SOFTWARE (documentation) copyright . . . . . . . . . . . . 625 33.4.3 CIDER RESEARCH SOFTWARE AGREEMENT (superseded by 33.4.4)626 33.4.4 ‘Modified’ BSD license . . . . . . . . . . . . . . . . . . . . . . . . . 626 33.4.5 XSPICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627 33.4.6 tclspice, numparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627 33.4.7 Linking to GPLd libraries (e.g. readline, fftw, table.cm): . . . . . . . . 627 28 CONTENTS Prefaces Preface to the first edition This manual has been assembled from different sources: 1. The spice3f5 manual, 2. the XSPICE user’s manual, 3. the CIDER user’s manual and some original material needed to describe the new features and the newly implemented models. This cut and paste approach, while not being orthodox, allowed ngspice to have a full manual in a fraction of the time that writing a completely new text would have required. The use of LaTex and LYX instead of TeXinfo, which was the original encoding for the manual, further helped to reduce the writing effort and improved the quality of the result, at the expense of an on-line version of the manual but, due to the complexity of the software I hardly think that users will ever want to read an on-line text version. In writing this text I followed the spice3f5 manual, both in the chapter sequence and presentation of material, mostly because that was already the user manual of SPICE. Ngspice is an open source software, users can download the source code, compile, and run it. This manual has an entire chapter describing program compilation and available options to help users in building ngspice (see Chapt. 32). The source package already comes with all ‘safe’ options enabled by default, and activating the others can produce unpredictable results and thus is recommended to expert users only. This is the first ngspice manual and I have removed all the historical material that described the differences between ngspice and spice3, since it was of no use for the user and not so useful for the developer who can look for it in the Changelogs of in the revision control system. I want to acknowledge the work done by Emmanuel Rouat and Arno W. Peters for converting the original spice3f documentation to TEXinfo. Their effort gave ngspice users the only available documentation that described the changes for many years. A good source of ideas for this manual came from the on-line spice3f manual written by Charles D.H. Williams (Spice3f5 User Guide), constantly updated and useful for its many insights. As always, errors, omissions and unreadable phrases are only my fault. Paolo Nenzi Roma, March 24th 2001 29 30 CONTENTS Indeed. At the end of the day, this is engineering, and one learns to live within the limitations of the tools. Kevin Aylward, Warden of the King’s Ale Preface to the actual edition (as of September 2017) Due to the wealth of new material and options in ngspice the actual order of chapters has been revised. Several new chapters have been added. The LYX text processor has allowed adding internal cross references. The PDF format has become the standard format for distribution of the manual. Within each new ngspice distribution (starting with ngspice-21) a manual edition is provided reflecting the ngspice status at the time of distribution. At the same time, located at ngspice manuals, the manual is constantly updated. Every new ngspice feature should enter this manual as soon as it has been made available in the Git source code master branch. Holger Vogt Mülheim, 2017 Acknowledgments ngspice contributors Spice3 and CIDER were originally written at The University of California at Berkeley (USA). XSPICE has been provided by Georgia Institute of Technology, Atlanta (USA). Since then, there have been many people working on the software, most of them releasing patches to the original code through the Internet. The following people have contributed in some way: Vera Albrecht, Cecil Aswell, Giles C. Billingsley, Phil Barker, Steven Borley, Stuart Brorson, Mansun Chan, Wayne A. Christopher, Al Davis, Glao S. Dezai, Jon Engelbert, Daniele Foci, Noah Friedman, David A. Gates, Alan Gillespie, John Heidemann, Marcel Hendrix, Jeffrey M. Hsu, JianHui Huang, S. Hwang, Chris Inbody, Gordon M. Jacobs, Min-Chie Jeng, Beorn Johnson, Stefan Jones, Kenneth H. Keller, Francesco Lannutti, Robert Larice, 31 32 CONTENTS Mathew Lew, Robert Lindsell, Weidong Liu, Kartikeya Mayaram, Richard D. McRoberts, Manfred Metzger, Wolfgang Muees, Paolo Nenzi, Gary W. Ng, Hong June Park, Stefano Perticaroli, Arno Peters, Serban-Mihai Popescu, Georg Post, Thomas L. Quarles, Emmanuel Rouat, Jean-Marc Routure, Jaijeet S. Roychowdhury, Lionel Sainte Cluque, Takayasu Sakurai, Amakawa Shuhei, Kanwar Jit Singh, Bill Swartz, Hitoshi Tanaka, Steve Tell, Andrew Tuckey, Andreas Unger, Holger Vogt, Dietmar Warning, Michael Widlok, Charles D.H. Williams, Antony Wilson, and many others... If someone helped in the development and has not been inserted in this list then this omission was unintentional. If you feel you should be on this list then please write to . Do not be shy, we would like to make a list as complete as possible. Chapter 1 Introduction Ngspice is a general-purpose circuit simulation program for nonlinear and linear analyses. Circuits may contain resistors, capacitors, inductors, mutual inductors, independent or dependent voltage and current sources, loss-less and lossy transmission lines, switches, uniform distributed RC lines, and the five most common semiconductor devices: diodes, BJTs, JFETs, MESFETs, and MOSFETs. Some introductory remarks on how to use ngspice may be found in Chapt. 21. Ngspice is an update of Spice3f5, the last Berkeley’s release of Spice3 simulator family. Ngspice is being developed to include new features to existing Spice3f5 and to fix its bugs. Improving a complex software like a circuit simulator is a very hard task and, while some improvements have been made, most of the work has been done on bug fixing and code refactoring. Ngspice has built-in models for the semiconductor devices, and the user need specify only the pertinent model parameter values. There are three models for bipolar junction transistors, all based on the integral-charge model of Gummel and Poon; however, if the Gummel-Poon parameters are not specified, the basic model (BJT) reduces to the simpler Ebers-Moll model. In either case and in either models, charge storage effects, ohmic resistances, and a currentdependent output conductance may be included. The second bipolar model BJT2 adds dc current computation in the substrate diode. The third model (VBIC) contains further enhancements for advanced bipolar devices. The semiconductor diode model can be used for either junction diodes or Schottky barrier diodes. There are two models for JFET: the first (JFET) is based on the model of Shichman and Hodges, the second (JFET2) is based on the Parker-Skellern model. All the original six MOSFET models are implemented: MOS1 is described by a square-law I-V characteristic, MOS2 [1] is an analytical model, while MOS3 [1] is a semi-empirical model; MOS6 [2] is a simple analytic model accurate in the short channel region; MOS9, is a slightly modified Level 3 MOSFET model - not to confuse with Philips level 9; BSIM 1 [3, 4]; BSIM2 [5] are the old BSIM (Berkeley Short-channel IGFET Model) models. MOS2, MOS3, and BSIM include second-order effects such as channel-length modulation, subthreshold conduction, scattering-limited velocity saturation, small-size effects, and charge controlled capacitances. The recent MOS models for submicron devices are the BSIM3 (Berkeley BSIM3 web page) and BSIM4 (Berkeley BSIM4 web page) models. Silicon-on-insulator MOS transistors are described by the SOI models from the BSIMSOI family (Berkeley BSIMSOI web page) and the STAG [18] one. There is partial support for a couple of HFET models and one model for MESA devices. 33 34 CHAPTER 1. INTRODUCTION Ngspice supports mixed-level simulation and provides a direct link between technology parameters and circuit performance. A mixed-level circuit and device simulator can provide greater simulation accuracy than a stand-alone circuit or device simulator by numerically modeling the critical devices in a circuit. Compact models can be used for all other devices. The mixedlevel extensions to ngspice is CIDER, a mixed-level circuit and device simulator integrated into ngspice code. Ngspice supports mixed-signal simulation through the integration of XSPICE code. XSPICE software, developed as an extension to Spice3C1 by GeorgiaTech, has been enhanced and ported to ngspice to provide ‘board’ level and mixed-signal simulation. The XSPICE extension enables pure digital simulation as well. New devices can be added to ngspice by several means: behavioral B-, E- or G-sources, the XSPICE code-model interface for C-like device coding, and the ADMS interface based on Verilog-A and XML. Finally, numerous small bugs have been discovered and fixed, and the program has been ported to a wider variety of computing platforms. 1.1 Simulation Algorithms Computer-based circuit simulation is often used as a tool by designers, test engineers, and others who want to analyze the operation of a design without examining the physical circuit. Simulation allows you to change quickly the parameters of many of the circuit elements to determine how they affect the circuit response. Often it is difficult or impossible to change these parameters in a physical circuit. However, to be practical, a simulator must execute in a reasonable amount of time. The key to efficient execution is choosing the proper level of modeling abstraction for a given problem. To support a given modeling abstraction, the simulator must provide appropriate algorithms. Historically, circuit simulators have supported either an analog simulation algorithm or a digital simulation algorithm. Ngspice inherits the XSPICE framework and supports both analog and digital algorithms and is a ‘mixed-mode’ simulator. 1.1.1 Analog Simulation Analog simulation focuses on the linear and non-linear behavior of a circuit over a continuous time or frequency interval. The circuit response is obtained by iteratively solving Kirchhoff’s Laws for the circuit at time steps selected to ensure the solution has converged to a stable value and that numerical approximations of integrations are sufficiently accurate. Since Kirchhoff’s laws form a set of simultaneous equations, the simulator operates by solving a matrix of equations at each time point. This matrix processing generally results in slower simulation times when compared to digital circuit simulators. The response of a circuit is a function of the applied sources. Ngspice offers a variety of source types including DC, sine-wave, and pulse. In addition to specifying sources, the user must define the type of simulation to be run. This is termed the ‘mode of analysis’. Analysis modes include DC analysis, AC analysis, and transient analysis. For DC analysis, the timevarying behavior of reactive elements is neglected and the simulator calculates the DC solution 1.1. SIMULATION ALGORITHMS 35 of the circuit. Swept DC analysis may also be accomplished with ngspice. This is simply the repeated application of DC analysis over a range of DC levels for the input sources. For AC analysis, the simulator determines the response of the circuit, including reactive elements to small-signal sinusoidal inputs over a range of frequencies. The simulator output in this case includes amplitudes and phases as a function of frequency. For transient analysis, the circuit response, including reactive elements, is analyzed to calculate the behavior of the circuit as a function of time. 1.1.2 Digital Simulation Digital circuit simulation differs from analog circuit simulation in several respects. A primary difference is that a solution of Kirchhoff’s laws is not required. Instead, the simulator must only determine whether a change in the logic state of a node has occurred and propagate this change to connected elements. Such a change is called an ‘event’. When an event occurs, the simulator examines only those circuit elements that are affected by the event. As a result, matrix analysis is not required in digital simulators. By comparison, analog simulators must iteratively solve for the behavior of the entire circuit because of the forward and reverse transmission properties of analog components. This difference results in a considerable computational advantage for digital circuit simulators, which is reflected in the significantly greater speed of digital simulations. 1.1.3 Mixed-Signal Simulation Modern circuits often contain a mix of analog and digital circuits. To simulate such circuits efficiently and accurately a mix of analog and digital simulation techniques is required. When analog simulation algorithms are combined with digital simulation algorithms, the result is termed ‘mixed-mode simulation’. Two basic methods of implementing mixed-mode simulation used in practice are the ‘native mode’ and ‘glued mode’ approaches. Native mode simulators implement both an analog algorithm and a digital algorithm in the same executable. Glued mode simulators actually use two simulators, one of which is analog and the other digital. This type of simulator must define an input/output protocol so that the two executables can communicate with each other effectively. The communication constraints tend to reduce the speed, and sometimes the accuracy, of the complete simulator. On the other hand, the use of a glued mode simulator allows the component models developed for the separate executables to be used without modification. Ngspice is a native mode simulator providing both analog and event-based simulation in the same executable. The underlying algorithms of ngspice (coming from XSPICE and its Code Model Subsystem) allow use of all the standard SPICE models, provide a pre-defined collection of the most common analog and digital functions, and provide an extensible base on which to build additional models. 1.1.3.1 User-Defined Nodes Ngspice supports creation of ‘User-Defined Node’ types. User-Defined Node types allow you to specify nodes that propagate data other than voltages, currents, and digital states. Like digital 36 CHAPTER 1. INTRODUCTION nodes, User-Defined Nodes use event-driven simulation, but the state value may be an arbitrary data type. A simple example application of User-Defined Nodes is the simulation of a digital signal processing filter algorithm. In this application, each node could assume a real or integer value. More complex applications may define types that involve complex data such as digital data vectors or even non-electronic data. Ngspice digital simulation is actually implemented as a special case of this User-Defined Node capability where the digital state is defined by a data structure that holds a Boolean logic state and a strength value. 1.1.4 Mixed-Level Simulation Ngspice can simulate numerical device models for diodes and transistors in two different ways, either through the integrated DSIM simulator or interfacing to GSS TCAD system. DSIM is an internal C-based device simulator that is part of the CIDER simulator, the mixed-level simulator based on SPICE3f5. CIDER within ngspice provides circuit analyses, compact models for semiconductor devices, and one- or two-dimensional numerical device models. 1.1.4.1 CIDER (DSIM) CIDER integrates the DSIM simulator with Spice3. It provides accurate, one- and two-dimensional numerical device models based on the solution of Poisson’s equation, and the electron and hole current-continuity equations. DSIM incorporates many of the same basic physical models found in the Stanford two-dimensional device simulator PISCES. Input to CIDER consists of a SPICE-like description of the circuit and its compact models, and PISCES-like descriptions of the structures of numerically modeled devices. As a result, CIDER should seem familiar to designers already accustomed to these two tools. The CIDER input format has great flexibility and allows access to physical model parameters. New physical models have been added to allow simulation of state-of-the-art devices. These include transverse field mobility degradation important in scaled-down MOSFETs and a polysilicon model for poly-emitter bipolar transistors. Temperature dependence has been included over the range from -50C to 150C. The numerical models can be used to simulate all the basic types of semiconductor devices: resistors, MOS capacitors, diodes, BJTs, JFETs and MOSFETs. BJTs and JFETs can be modeled with or without a substrate contact. Support has been added for the management of device internal states. Post-processing of device states can be performed using the ngnutmeg user interface. 1.1.4.2 GSS TCAD GSS is a TCAD software that enables two-dimensional numerical simulation of semiconductor device with well-known drift-diffusion and hydrodynamic method. GSS has Basic DDM (driftdiffusion method) solver, Lattice Temperature Corrected DDM solver, EBM (energy balance method) solver and Quantum corrected DDM solver based on density-gradient theory. The GSS program is directed via input statements by a user specified disk file. Supports triangle mesh generation and adaptive mesh refinement. Employs PMI (physical model interface) to support various materials, including compound semiconductor materials such as SiGe and AlGaAs. Supports DC sweep, transient and AC sweep calculations. The device can be stimulated by voltage or current source(s). 1.2. SUPPORTED ANALYSES 37 GSS is no longer updated, but is still available as open source as a limited edition of the commercial GENIUS TCAD tool. This interface has not been tested with actual ngspice versions and may need some maintainance efforts. 1.2 Supported Analyses The ngspice simulator supports the following different types of analysis: 1. DC Analysis (Operating Point and DC Sweep) 2. AC Small-Signal Analysis 3. Transient Analysis 4. Pole-Zero Analysis 5. Small-Signal Distortion Analysis 6. Sensitivity Analysis 7. Noise Analysis Applications that are exclusively analog can make use of all analysis modes with the exception of Code Model subsystem that do not implements Pole-Zero, Distortion, Sensitivity and Noise analyses. Event-driven applications that include digital and User-Defined Node types may make use of DC (operating point and DC sweep) and Transient only. In order to understand the relationship between the different analyses and the two underlying simulation algorithms of ngspice, it is important to understand what is meant by each analysis type. This is detailed below. 1.2.1 DC Analysis The dc analysis portion of ngspice determines the dc operating point of the circuit with inductors shorted and capacitors opened. The dc analysis options are specified on the .DC, .TF, and .OP control lines. There is assumed to be no time dependence on any of the sources within the system description. The simulator algorithm subdivides the circuit into those portions that require the analog simulator algorithm and such that require the event-driven algorithm. Each subsystem block is then iterated to solution, with the interfaces between analog nodes and event-driven nodes iterated for consistency across the entire system. Once stable values are obtained for all nodes in the system, the analysis halts and the results may be displayed or printed out as you request them. A dc analysis is automatically performed prior to a transient analysis to determine the transient initial conditions, and prior to an ac small-signal analysis to determine the linearized, smallsignal models for nonlinear devices. If requested, the dc small-signal value of a transfer function (ratio of output variable to input source), input resistance, and output resistance is also computed as a part of the dc solution. The dc analysis can also be used to generate dc transfer curves: a specified independent voltage, current source, resistor or temperature is stepped over a userspecified range and the dc output variables are stored for each sequential source value. 38 1.2.2 CHAPTER 1. INTRODUCTION AC Small-Signal Analysis AC analysis is limited to analog nodes and represents the small signal, sinusoidal solution of the analog system described at a particular frequency or set of frequencies. This analysis is similar to the DC analysis in that it represents the steady-state behavior of the described system with a single input node at a given set of stimulus frequencies. The program first computes the dc operating point of the circuit and determines linearized, small-signal models for all of the nonlinear devices in the circuit. The resultant linear circuit is then analyzed over a user-specified range of frequencies. The desired output of an ac smallsignal analysis is usually a transfer function (voltage gain, transimpedance, etc). If the circuit has only one ac input, it is convenient to set that input to unity and zero phase, so that output variables have the same value as the transfer function of the output variable with respect to the input. 1.2.3 Transient Analysis Transient analysis is an extension of DC analysis to the time domain. A transient analysis begins by obtaining a DC solution to provide a point of departure for simulating time-varying behavior. Once the DC solution is obtained, the time-dependent aspects of the system are reintroduced, and the two simulator algorithms incrementally solve for the time varying behavior of the entire system. Inconsistencies in node values are resolved by the two simulation algorithms such that the time-dependent waveforms created by the analysis are consistent across the entire simulated time interval. Resulting time-varying descriptions of node behavior for the specified time interval are accessible to you. All sources that are not time dependent (for example, power supplies) are set to their dc value. The transient time interval is specified on a .TRAN control line. 1.2.4 Pole-Zero Analysis The pole-zero analysis portion of Ngspice computes the poles and/or zeros in the small-signal ac transfer function. The program first computes the dc operating point and then determines the linearized, small-signal models for all the nonlinear devices in the circuit. This circuit is then used to find the poles and zeros of the transfer function. Two types of transfer functions are allowed: one of the form (output voltage)/(input voltage) and the other of the form (output voltage)/(input current). These two types of transfer functions cover all the cases and one can find the poles/zeros of functions like input/output impedance and voltage gain. The input and output ports are specified as two pairs of nodes. The pole-zero analysis works with resistors, capacitors, inductors, linear-controlled sources, independent sources, BJTs, MOSFETs, JFETs and diodes. Transmission lines are not supported. The method used in the analysis is a suboptimal numerical search. For large circuits it may take a considerable time or fail to find all poles and zeros. For some circuits, the method becomes ‘lost’ and finds an excessive number of poles or zeros. 1.2. SUPPORTED ANALYSES 1.2.5 39 Small-Signal Distortion Analysis The distortion analysis portion of Ngspice computes steady-state harmonic and intermodulation products for small input signal magnitudes. If signals of a single frequency are specified as the input to the circuit, the complex values of the second and third harmonics are determined at every point in the circuit. If there are signals of two frequencies input to the circuit, the analysis finds out the complex values of the circuit variables at the sum and difference of the input frequencies, and at the difference of the smaller frequency from the second harmonic of the larger frequency. Distortion analysis is supported for the following nonlinear devices: • Diodes (DIO), • BJT, • JFET (level 1), • MOSFETs (levels 1, 2, 3, 9, and BSIM1), • MESFET (level 1). All linear devices are automatically supported by distortion analysis. If there are switches present in the circuit, the analysis continues to be accurate provided the switches do not change state under the small excitations used for distortion calculations. If a device model does not support direct small signal distortion analysis, please use the Fourier of FFT statements and evaluate the output per scripting. 1.2.6 Sensitivity Analysis Ngspice will calculate either the DC operating-point sensitivity or the AC small-signal sensitivity of an output variable with respect to all circuit variables, including model parameters. Ngspice calculates the difference in an output variable (either a node voltage or a branch current) by perturbing each parameter of each device independently. Since the method is a numerical approximation, the results may demonstrate second order effects in highly sensitive parameters, or may fail to show very low but non-zero sensitivity. Further, since each variable is perturb by a small fraction of its value, zero-valued parameters are not analyzed (this has the benefit of reducing what is usually a very large amount of data). 1.2.7 Noise Analysis The noise analysis portion of Ngspice gives the device-generated noise for a given circuit. When provided with an input source and an output port, the analysis calculates the noise contributions of each device, and each noise generator within the device, to the output port voltage. It also calculates the equivalent input noise of the circuit, based on the output noise. This is done for every frequency point in a specified range - the calculated value of the noise corresponds to the spectral density of the circuit variable viewed as a stationary Gaussian stochastic process. After calculating the spectral densities, noise analysis integrates these values over the specified frequency range to arrive at the total noise voltage and current over this frequency range. The calculated values correspond to the variance of the circuit variables viewed as stationary Gaussian processes. 40 1.2.8 CHAPTER 1. INTRODUCTION Periodic Steady State Analysis Experimental code. PSS is a radio frequency periodical large-signal dedicated analysis. The implementation is based on a time domain shooting method that make use of transient analysis. As it is in early development stage, PSS performs analysis only on autonomous circuits, meaning that it is able to predict fundamental frequency and (harmonic) amplitude(s) for oscillators, VCOs, etc.. The algorithm is based on a search of the minimum error vector defined as the difference of RHS vectors between two occurrences of an estimated period. Convergence is reached when the mean of this error vector decreases below a given threshold parameter. Results of PSS are the basis of periodical large-signal analyses like PAC or PNoise. 1.3 Analysis at Different Temperatures Temperature, in ngspice, is a property associated to the entire circuit, rather than an analysis option. Circuit temperature has a default (nominal) value of 27°C (300.15 K) that can be changed using the TEMP option in an .option control line (see 15.1.1) or by the .TEMP line (see 2.11), which has precedence over the .option TEMP line. All analyses are, thus, performed at circuit temperature, and if you want to simulate circuit behavior at different temperatures you should prepare a netlist for each temperature. All input data for ngspice is assumed to have been measured at the circuit nominal temperature. This value can further be overridden for any device that models temperature effects by specifying the TNOM parameter on the .model itself. Individual instances may further override the circuit temperature through the specification of TEMP and DTEMP parameters on the instance. The two options are not independent even if you can specify both on the instance line, the TEMP option overrides DTEMP. The algorithm to compute instance temperature is described below: IF TEMP is specified THEN instance_temperature = TEMP ELSE IF instance_temperature = circuit_temperature + DTEMP END IF Algorithm 1: Instance temperature computation Temperature dependent support is provided for all devices except voltage and current sources (either independent and controlled) and BSIM models. BSIM MOSFETs have an alternate temperature dependency scheme that adjusts all of the model parameters before input to ngspice. For details of the BSIM temperature adjustment, see [6] and [7]. Temperature appears explicitly in the exponential terms of the BJT and diode model equations. In addition, saturation currents have a built-in temperature dependence. The temperature dependence of the saturation current in the BJT models is determined by: T1 IS (T1 ) = IS (T0 ) T0 XT I Eg q (T1 T0 ) exp k (T1 − T0 ) (1.1) where k is Boltzmann’s constant, q is the electronic charge, Eg is the energy gap model parameter, and XT I is the saturation current temperature exponent (also a model parameter, and usually equal to 3). 1.4. CONVERGENCE 41 The temperature dependence of forward and reverse beta is according to the formula: T1 B (T1 ) = B (T0 ) T0 XT B (1.2) where T0 and T1 are in degrees Kelvin, and XT B is a user-supplied model parameter. Temperature effects on beta are carried out by appropriate adjustment to the values of BF , ISE , BR , and ISC (SPICE model parameters BF, ISE, BR, and ISC, respectively). Temperature dependence of the saturation current in the junction diode model is determined by: T1 IS (T1 ) = IS (T0 ) T0 XT I N Eg q (T1 T0 ) exp Nk (T1 − T0 ) (1.3) where N is the emission coefficient model parameter, and the other symbols have the same meaning as above. Note that for Schottky barrier diodes, the value of the saturation current temperature exponent, XT I, is usually 2. Temperature appears explicitly in the value of junction potential, U (in Ngspice PHI), for all the device models. The temperature dependence is determined by: kT ln U (T ) = q Na Nd ! Ni (T )2 (1.4) where k is Boltzmann’s constant, q is the electronic charge, Na is the acceptor impurity density, Nd is the donor impurity density, Ni is the intrinsic carrier concentration, and Eg is the energy gap. Temperature appears explicitly in the value of surface mobility, M0 (or U0 ), for the MOSFET model. The temperature dependence is determined by: M0 (T0 ) M0 (T ) = 1.5 (1.5) T T0 The effects of temperature on resistors, capacitor and inductors is modeled by the formula: h i R (T ) = R (T0 ) 1 + TC1 (T − T0 ) + TC2 (T − T0 )2 (1.6) where T is the circuit temperature, T0 is the nominal temperature, and TC1 and TC2 are the first and second order temperature coefficients. 1.4 Convergence Ngspice uses the Newton-Raphson algorithm to solve nonlinear equations arising from circuit description. The NR algorithm is interactive and terminates when both of the following conditions hold: 42 CHAPTER 1. INTRODUCTION 1. The nonlinear branch currents converge to within a tolerance of 0.1% or 1 picoamp (1.0e12 Amp), whichever is larger. 2. The node voltages converge to within a tolerance of 0.1% or 1 microvolt (1.0e-6 Volt), whichever is larger. 1.4.1 Voltage convergence criterion The algorithm has reached convergence when the difference between the last iteration k and the current one (k + 1) (k+1) vn (k) − vn ≤ RELTOL vnmax + VNTOL, (1.7) where vnmax = max (k+1) vn , (k) vn . (1.8) The RELTOL (RELative TOLerance) parameter, which default value is 10−3 , specifies how small the solution update must be, relative to the node voltage, to consider the solution to have converged. The VNTOL (absolute convergence) parameter, which has 1µV as default value, becomes important when node voltages have near zero values. The relative parameter alone, in such case, would need too strict tolerances, perhaps lower than computer round-off error, and thus convergence would never be achieved. VNTOL forces the algorithm to consider as converged any node whose solution update is lower than its value. 1.4.2 Current convergence criterion Ngspice checks the convergence on the non-linear functions that describe the non-linear branches in circuit elements. In semiconductor devices the functions defines currents through the device and thus the name of the criterion. Ngspice computes the difference between the value of the nonlinear function computed for the last voltage and the linear approximation of the same current computed with the actual voltage \ (k+1) (k) ibranch − ibranch ≤ RELTOL ibrmax + ABSTOL, (1.9) where ibrmax \ (k+1) (k) = max ibranch , ibranch . (1.10) In the two expressions above, the i\ branch indicates the linear approximation of the current. 1.4. CONVERGENCE 1.4.3 43 Convergence failure Although the algorithm used in ngspice has been found to be very reliable, in some cases it fails to converge to a solution. When this failure occurs, the program terminates the job. Failure to converge in dc analysis is usually due to an error in specifying circuit connections, element values, or model parameter values. Regenerative switching circuits or circuits with positive feedback probably will not converge in the dc analysis unless the OFF option is used for some of the devices in the feedback path, .nodeset control line is used to force the circuit to converge to the desired state. 44 CHAPTER 1. INTRODUCTION Chapter 2 Circuit Description 2.1 2.1.1 General Structure and Conventions Input file structure The circuit to be analyzed is described to ngspice by a set of element instance lines, which define the circuit topology and element instance values, and a set of control lines, which define the model parameters and the run controls. All lines are assembled in an input file to be read by ngspice. Two lines are essential: • The first line in the input file must be the title, which is the only comment line that does not need any special character in the first place. • The last line must be .end. The order of the remaining lines is arbitrary (except, of course, that continuation lines must immediately follow the line being continued). This feature in the ngspice input language dates back to the punched card times where elements were written on separate cards (and cards frequently fell off). Leading white spaces in a line are ignored, as well as empty lines. The lines described in sections 2.1 to 2.12 are typically used in the core of the input file, outside of a .control section (see 16.4.3). An exception is the .include includefile line (2.6) that may be placed anywhere in the input file. The contents of includefile will be inserted exactly in place of the .include line. 2.1.2 Circuit elements (device instances) Each element in the circuit is a device instance specified by an instance line that contains: • the element instance name, • the circuit nodes to which the element is connected, • and the values of the parameters that determine the electrical characteristics of the element. 45 46 CHAPTER 2. CIRCUIT DESCRIPTION The first letter of the element instance name specifies the element type. The format for the ngspice element types is given in the following manual chapters. In the rest of the manual, the strings XXXXXXX, YYYYYYY, and ZZZZZZZ denote arbitrary alphanumeric strings. For example, a resistor instance name must begin with the letter R and can contain one or more characters. Hence, R, R1, RSE, ROUT, and R3AC2ZY are valid resistor names. Details of each type of device are supplied in a following section 3. Table 2.1 lists the element types available in ngspice, sorted by their first letter. First letter Element description A XSPICE code model B C D Behavioral (arbitrary) source Capacitor Diode E Voltage-controlled voltage source (VCVS) F Current-controlled current source (CCCs) G Voltage-controlled current source (VCCS) H I J K L Current-controlled voltage source (CCVS) Current source Junction field effect transistor (JFET) Coupled (Mutual) Inductors Inductor M Metal oxide field effect transistor (MOSFET) N O P Q R S T U V W X Y Z Numerical device for GSS Lossy transmission line Coupled multiconductor line (CPL) Bipolar junction transistor (BJT) Resistor Switch (voltage-controlled) Lossless transmission line Uniformly distributed RC line Voltage source Switch (current-controlled) Subcircuit Single lossy transmission line (TXL) Metal semiconductor field effect transistor (MESFET) Table 2.1: ngspice element types Comments, links 12 analog (12.2) digital (12.4) mixed signal (12.3) 5.1 3.2.5 7 linear (4.2.2), non-linear (5.2) linear (4.2.3) linear (4.2.1), non-linear (5.3) linear (4.2.4) 4.1 9 3.2.11 3.2.9 11 BSIM3 (11.2.10) BSIM4 (11.2.11) 14.2 6.2 6.4.2 8 3.2.1 3.2.14 6.1 6.3 4.1 3.2.14 2.4.3 6.4.1 10 2.1. GENERAL STRUCTURE AND CONVENTIONS 2.1.3 47 Some naming conventions Fields on a line are separated by one or more blanks, a comma, an equal (=) sign, or a left or right parenthesis; extra spaces are ignored. A line may be continued by entering a ‘+’ (plus) in column 1 of the following line; ngspice continues reading beginning with column 2. A name field must begin with a letter (A through Z) and cannot contain any delimiters. A number field may be an integer field (12, -44), a floating point field (3.14159), either an integer or floating point number followed by an integer exponent (1e-14, 2.65e3), or either an integer or a floating point number followed by one of the following scale factors: Suffix T G Meg K mil m u n p f Name Tera Giga Mega Kilo Mil milli micro nano pico femto Factor 1012 109 106 103 25.4 × 10−6 10−3 10−6 10−9 10−12 10−15 Table 2.2: Ngspice scale factors Letters immediately following a number that are not scale factors are ignored, and letters immediately following a scale factor are ignored. Hence, 10, 10V, 10Volts, and 10Hz all represent the same number, and M, MA, MSec, and MMhos all represent the same scale factor. Note that 1000, 1000.0, 1000Hz, 1e3, 1.0e3, 1kHz, and 1k all represent the same number. Note that ‘M’ or ‘m’ denote ‘milli’, i.e. 10−3 . Suffix meg has to be used for 106 . Nodes names may be arbitrary character strings and are case insensitive, if ngspice is used in batch mode (16.4.1). If in interactive (16.4.2) or control (16.4.3) mode, node names may either be plain numbers or arbitrary character strings, not starting with a number. The ground node must be named ‘0’ (zero). For compatibility reason gnd is accepted as ground node, and will internally be treated as a global node and be converted to ‘0’. Each circuit has to have a ground node (gnd or 0)! Note the difference in ngspice where the nodes are treated as character strings and not evaluated as numbers, thus ‘0’ and 00 are distinct nodes in ngspice but not in SPICE2. Ngspice requires that the following topological constraints are satisfied: • The circuit cannot contain a loop of voltage sources and/or inductors and cannot contain a cut-set of current sources and/or capacitors. • Each node in the circuit must have a dc path to ground. • Every node must have at least two connections except for transmission line nodes (to permit unterminated transmission lines) and MOSFET substrate nodes (which have two internal connections anyway). 48 CHAPTER 2. CIRCUIT DESCRIPTION 2.2 Basic lines 2.2.1 .TITLE line Examples: POWER AMPLIFIER CIRCUIT * additional lines following *... Test of CAM cell * additional lines following *... The title line must be the first in the input file. Its contents are printed verbatim as the heading for each section of output. As an alternative you may place a .TITLE line anywhere in your input deck. The first line of your input deck will be overridden by the contents of this line following the .TITLE statement. .TITLE line example: ****************************** * additional lines following *... .TITLE Test of CAM cell * additional lines following *... will internally be replaced by Internal input deck: Test of CAM cell * additional lines following *... *TITLE Test of CAM cell * additional lines following *... 2.2.2 .END Line Examples: .end The .end line must always be the last in the input file. Note that the period is an integral part of the name. 2.3. .MODEL DEVICE MODELS 2.2.3 49 Comments General Form: * Examples: * RF =1K Gain should be 100 * Check open -loop gain and phase margin The asterisk in the first column indicates that this line is a comment line. Comment lines may be placed anywhere in the circuit description. 2.2.4 End-of-line comments General Form: $ Examples: RF2 =1K $ Gain should be 100 C1 =10p $ Check open -loop gain and phase margin .param n1 =1 // new value ngspice supports comments that begin with double characters ‘$ ’ (dollar plus space) or ‘//’. For readability you should precede each comment character with a space. ngspice will accept the single character ‘$’. Please note that in .control sections the ‘;’ character means ‘continuation’ and can be used to put more than one statement on a line. 2.3 .MODEL Device Models General form: .model mname type( pname1 =pval1 pname2 =pval2 ... ) Examples: .model MOD1 npn (bf =50 is=1e -13 vbf =50) 50 CHAPTER 2. CIRCUIT DESCRIPTION Code R C L SW CSW URC LTRA D NPN PNP NJF PJF NMOS PMOS NMF PMF Model Type Semiconductor resistor model Semiconductor capacitor model Inductor model Voltage controlled switch Current controlled switch Uniform distributed RC model Lossy transmission line model Diode model NPN BJT model PNP BJT model N-channel JFET model P-channel JFET model N-channel MOSFET model P-channel MOSFET model N-channel MESFET model P-channel MESFET model Table 2.3: Ngspice model types Most simple circuit elements typically require only a few parameter values. However, some devices (semiconductor devices in particular) that are included in ngspice require many parameter values. Often, many devices in a circuit are defined by the same set of device model parameters. For these reasons, a set of device model parameters is defined on a separate .model line and assigned a unique model name. The device element lines in ngspice then refer to the model name. For these more complex device types, each device element line contains the device name, the nodes the device is connected to, and the device model name. In addition, other optional parameters may be specified for some devices: geometric factors and an initial condition (see the following section on Transistors (8 to 11) and Diodes (7) for more details). mname in the above is the model name, and type is one of the following fifteen types: Parameter values are defined by appending the parameter name followed by an equal sign and the parameter value. Model parameters that are not given a value are assigned the default values given below for each model type. Models are listed in the section on each device along with the description of device element lines. Model parameters and their default values are given in Chapt. 31. 2.4 .SUBCKT Subcircuits A subcircuit that consists of ngspice elements can be defined and referenced in a fashion similar to device models. Subcircuits are the way ngspice implements hierarchical modeling, but this is not entirely true because each subcircuit instance is flattened during parsing, and thus ngspice is not a hierarchical simulator. The subcircuit is defined in the input deck by a grouping of element cards delimited by the .subckt and the .ends cards (or the keywords defined by the substart and subend options 2.4. .SUBCKT SUBCIRCUITS 51 (see 17.7)); the program then automatically inserts the defined group of elements wherever the subcircuit is referenced. Instances of subcircuits within a larger circuit are defined through the use of an instance card that begins with the letter ‘X’. A complete example of all three of these cards follows: Example: * The following is the instance card: * xdiv1 10 7 0 vdivide * The following are the subcircuit definition cards: * . subckt vdivide 1 2 3 r1 1 2 10K r2 2 3 5K .ends The above specifies a subcircuit with ports numbered ‘1’, ‘2’ and ‘3’: • Resistor ‘R1’ is connected from port ‘1’ to port ‘2’, and has value 10 kOhms. • Resistor ‘R2’ is connected from port ‘2’ to port ‘3’, and has value 5 kOhms. The instance card, when placed in an ngspice deck, will cause subcircuit port ‘1’ to be equated to circuit node ‘10’, while port ‘2’ will be equated to node ‘7’ and port ‘3’ will equated to node ‘0’. There is no limit on the size or complexity of subcircuits, and subcircuits may contain other subcircuits. An example of subcircuit usage is given in Chapt. 21.6. 2.4.1 .SUBCKT Line General form: . SUBCKT subnam N1 Examples: . SUBCKT OPAMP 1 2 3 4 A circuit definition is begun with a .SUBCKT line. subnam is the subcircuit name, and N1, N2, ... are the external nodes, which cannot be zero. The group of element lines that immediately follow the .SUBCKT line define the subcircuit. The last line in a subcircuit definition is the .ENDS line (see below). Control lines may not appear within a subcircuit definition; however, subcircuit definitions may contain anything else, including other subcircuit definitions, device models, and subcircuit calls (see below). Note that any device models or subcircuit definitions included as part of a subcircuit definition are strictly local (i.e., such models and definitions 52 CHAPTER 2. CIRCUIT DESCRIPTION are not known outside the subcircuit definition). Also, any element nodes not included on the .SUBCKT line are strictly local, with the exception of 0 (ground) that is always global. If you use parameters, the .SUBCKT line will be extended (see 2.8.3). 2.4.2 .ENDS Line General form: .ENDS Examples: .ENDS OPAMP The .ENDS line must be the last one for any subcircuit definition. The subcircuit name, if included, indicates which subcircuit definition is being terminated; if omitted, all subcircuits being defined are terminated. The name is needed only when nested subcircuit definitions are being made. 2.4.3 Subcircuit Calls General form: XYYYYYYY N1 SUBNAM Examples: X1 2 4 17 3 1 MULTI Subcircuits are used in ngspice by specifying pseudo-elements beginning with the letter X, followed by the circuit nodes to be used in expanding the subcircuit. If you use parameters, the subcircuit call will be modified (see 2.8.3). 2.5 .GLOBAL General form: . GLOBAL nodename Examples: . GLOBAL gnd vcc 2.6. .INCLUDE 53 Nodes defined in the .GLOBAL statement are available to all circuit and subcircuit blocks independently from any circuit hierarchy. After parsing the circuit, these nodes are accessible from top level. 2.6 .INCLUDE General form: . INCLUDE filename Examples: . INCLUDE / users / spice / common /bsim3 -param.mod Frequently, portions of circuit descriptions will be reused in several input files, particularly with common models and subcircuits. In any ngspice input file, the .INCLUDE line may be used to copy some other file as if that second file appeared in place of the .INCLUDE line in the original file. There is no restriction on the file name imposed by ngspice beyond those imposed by the local operating system. 2.7 .LIB General form: .LIB filename libname Examples: .LIB / users / spice / common / mosfets .lib mos1 The .LIB statement allows to include library descriptions into the input file. Inside the *.lib file a library libname will be selected. The statements of each library inside the *.lib file are enclosed in .LIB libname <...> .ENDL statements. If the compatibility mode (16.13) is set to ’ps’ by set ngbehavior=ps (17.7) in spinit (16.5) or .spiceinit (16.6), then a simplified syntax .LIB filename is available: a warning is issued and filename is simply included as described in Chapt. 2.6. 2.8 .PARAM Parametric netlists Ngspice allows for the definition of parametric attributes in the netlists. This is an enhancement of the ngspice front-end that adds arithmetic functionality to the circuit description language. 54 2.8.1 CHAPTER 2. CIRCUIT DESCRIPTION .param line General form: .param = = ... Examples: .param .param .param .param .param pippo =5 po =6 pp =7.8 pap ={ AGAUSS (pippo , 1, 1.67)} pippp ={ pippo + pp} p={ pp} pop=’pp+p’ This line assigns numerical values to identifiers. More than one assignment per line is possible using a separating space. Parameter identifier names must begin with an alphabetic character. The other characters must be either alphabetic, a number, or ! # $ % [ ] _ as special characters. The variables time, temper, and hertz (see 5.1.1) are not valid identifier names. Other restrictions on naming conventions apply as well, see 2.8.6. The .param lines inside subcircuits are copied per call, like any other line. All assignments are executed sequentially through the expanded circuit. Before its first use, a parameter name must have been assigned a value. Expressions defining a parameter should be put within braces {p+p2}, or alternatively within single quotes ’AGAUSS(pippo, 1, 1.67)’. An assignment cannot be self-referential, something like .param pip = ’pip+3’ will not work. The current ngspice version does not always need quotes or braces in expressions, especially when spaces are used sparingly. However, it is recommended to do so, as the following examples demonstrate. .param .param .param .param .param 2.8.2 a a c c c = = = = = 123 * 3 b = sqrt (9) $ doesn ’t work , a <= 123 ’123 * 3’ b = sqrt (9) $ ok. a + 123 $ won ’t work ’a + 123 ’ $ ok. a+123 $ ok. Brace expressions in circuit elements: General form: { } Examples: These are allowed in .model lines and in device lines. A SPICE number is a floating point number with an optional scaling suffix, immediately glued to the numeric tokens (see Chapt. 2.8.5). Brace expressions ({..}) cannot be used to parametrize node names or parts of names. 2.8. .PARAM PARAMETRIC NETLISTS 55 All identifiers used within an must have known values at the time when the line is evaluated, else an error is flagged. 2.8.3 Subcircuit parameters General form: . subckt node node ... = = ... Examples: . subckt myfilter in out rval =100k cval =100 nF is the name of the subcircuit given by the user. node is an integer number or an identifier, for one of the external nodes. The first = introduces an optional section of the line. Each is a formal parameter, and each is either a SPICE number or a brace expression. Inside the .subckt ... .ends context, each formal parameter may be used like any identifier that was defined on a .param control line. The parts are supposed to be default values of the parameters. However, in the current version of , they are not used and each invocation of the subcircuit must supply the _exact_ number of actual parameters. The syntax of a subcircuit call (invocation) is: General form: X node node ... = = ... Examples: X1 input output myfilter rval =1k cval =1n Here is the symbolic name given to that instance of the subcircuit, is the name of a subcircuit defined beforehand. node node ... is the list of actual nodes where the subcircuit is connected. is either a SPICE number or a brace expression { } . The sequence of items on the X line must exactly match the number and the order of formal parameters of the subcircuit. 56 CHAPTER 2. CIRCUIT DESCRIPTION Subcircuit example with parameters: * Param - example .param amplitude = 1V * . subckt myfilter in out rval =100k cval =100 nF Ra in p1 {2* rval} Rb p1 out {2* rval} C1 p1 0 {2* cval} Ca in p2 {cval} Cb p2 out {cval} R1 p2 0 {rval} .ends myfilter * X1 input output myfilter rval =1k cval =1n V1 input 0 AC { amplitude } .end 2.8.4 Symbol scope All subcircuit and model names are considered global and must be unique. The .param symbols that are defined outside of any .subckt ... .ends section are global. Inside such a section, the pertaining params: symbols and any .param assignments are considered local: they mask any global identical names, until the .ends line is encountered. You cannot reassign to a global number inside a .subckt, a local copy is created instead. Scope nesting works up to a level of 10. For example, if the main circuit calls A that has a formal parameter xx, A calls B that has a param. xx, and B calls C that also has a formal param. xx, there will be three versions of ‘xx’ in the symbol table but only the most local one - belonging to C - is visible. 2.8.5 Syntax of expressions ( optional parts within [...] ) An expression may be one of: where is either a spice number or an identifier ( [ , ...] ) ( ) As expected, atoms, built-in function calls and stuff within parentheses are evaluated before the other operators. The operators are evaluated following a list of precedence close to the one of the C language. For equal precedence binary ops, evaluation goes left to right. Functions operate on real values only! 2.8. .PARAM PARAMETRIC NETLISTS Operator ! ** * / % \ + == != <= >= < > && || c?x:y Alias ^ <> Precedence 1 1 2 3 3 3 3 4 4 5 5 5 5 5 5 6 7 8 57 Description unary unary not power, like pwr multiply divide modulo integer divide add subtract equality non-equal less or equal greater or equal less than greater than boolean and boolean or ternary operator The number zero is used to represent boolean False. Any other number represents boolean True. The result of logical operators is 1 or 0. An example input file is shown below: Example input file with logical operators: * Logical operators v1or v1and v1not v1mod v1div v0not 1 2 3 4 5 6 0 0 0 0 0 0 . control op print allv .endc .end {1 {1 {! {5 {5 {! || 0} && 0} 1} % 3} \ 3} 0} 58 CHAPTER 2. CIRCUIT DESCRIPTION Built-in function sqr(x) sqrt(x) sin(x), cos(x), tan(x) sinh(x), cosh(x), tanh(x) asin(x), acos(x), atan(x) asinh(x), acosh(x), atanh(x) arctan(x) exp(x) ln(x), log(x) abs(x) nint(x) int(x) floor(x) ceil(x) pow(x,y) pwr(x,y) min(x, y) max(x, y) sgn(x) ternary_fcn(x, y, z) gauss(nom, rvar, sigma) agauss(nom, avar, sigma) unif(nom, rvar) aunif(nom, avar) limit(nom, avar) Notes y = x * x y = sqrt(x) atan(x), kept for compatibility Nearest integer, half integers towards even Nearest integer rounded towards 0 Nearest integer rounded towards -∞ Nearest integer rounded towards +∞ x raised to the power of y (pow from C runtime library) pow(fabs(x), y) 1.0 for x > 0, 0.0 for x == 0, -1.0 for x < 0 x ? y : z nominal value plus variation drawn from Gaussian distribution with mean 0 and standard deviation rvar (relative to nominal), divided by sigma nominal value plus variation drawn from Gaussian distribution with mean 0 and standard deviation avar (absolute), divided by sigma nominal value plus relative variation (to nominal) uniformly distributed between +/-rvar nominal value plus absolute variation uniformly distributed between +/-avar nominal value +/-avar, depending on random number in [-1, 1[ being > 0 or < 0 The scaling suffixes (any decorative alphanumeric string may follow): suffix g meg k m u n p f value 1e9 1e6 1e3 1e-3 1e-6 1e-9 1e-12 1e-15 Note: there are intentional redundancies in expression syntax, e.g. x^y , x**y and pwr(x,y) all have nearly the same result. 2.9. .FUNC 2.8.6 59 Reserved words In addition to the above function names and to the verbose operators ( not and or div mod ), other words are reserved and cannot be used as parameter names: or, defined, sqr, sqrt, sin, cos, exp, ln, log, log10, arctan, abs, pwr, time, temper, hertz. 2.8.7 A word of caution on the three ngspice expression parsers The historical parameter notation using & as the first character of a line as equivalence to .param. is deprecated and will be removed in a coming release. Confusion may arise in ngspice because of its multiple numerical expression features. The .param lines and the brace expressions (see Chapt. 2.9) are evaluated in the front-end, that is, just after the subcircuit expansion. (Technically, the X lines are kept as comments in the expanded circuit so that the actual parameters can be correctly substituted). Therefore, after the netlist expansion and before the internal data setup, all number attributes in the circuit are known constants. However, there are circuit elements in Spice that accept arithmetic expressions not evaluated at this point, but only later during circuit analysis. These are the arbitrary current and voltage sources (B-sources, 5), as well as E- and G-sources and R-, L-, or C-devices. The syntactic difference is that ‘compile-time’ expressions are within braces, but ‘run-time’ expressions have no braces. To make things more complicated, the back-end ngspice scripting language accepts arithmetic/logic expressions that operate only on its own scalar or vector data sets (17.2). Please see Chapt. 2.13. It would be desirable to have the same expression syntax, operator and function set, and precedence rules, for the three contexts mentioned above. In the current Numparam implementation, that goal is not achieved. 2.9 .FUNC This keyword defines a function. The syntax of the expression is the same as for a .param (2.8.5). General form: .func { } .func = { } Examples: .func icos(x) {cos(x) - 1} .func f(x,y) {x*y} .func foo(a,b) = {a + b} .func will initiate a replacement operation. After reading the input files, and before parameters are evaluated, all occurrences of the icos(x) function will be replaced by cos(x)-1. All occurrences of f(x,y) will be replaced by x*y. Function statements may be nested to a depth of t.b.d.. 60 CHAPTER 2. CIRCUIT DESCRIPTION 2.10 .CSPARAM Create a constant vector (see 17.8.2) from a parameter in plot (17.3) const. General form: . csparam = Examples: .param pippo =5 .param pp =6 . csparam pippp ={ pippo + pp} .param p={ pp} . csparam pap=’pp+p’ In the example shown, vectors pippp, and pap are added to the constants that already reside in plot const, having length one and real values. These vectors are generated during circuit parsing and thus cannot be changed later (same as with ordinary parameters). They may be used in ngspice scripts and .control sections (see Chapt. 17). The use of .csparam is still experimental and has to be tested. A simple usage is shown below. * test csparam .param TEMPS = 27 .csparam newt = {3*TEMPS} .csparam mytemp = ’2 + TEMPS’ .control echo $&newt $&mytemp .endc .end 2.11 .TEMP Sets the circuit temperature in degrees Celsius. General form: .temp value Examples: .temp 27 This card overrides the circuit temperature given in an .option line (15.1.1). 2.12. .IF CONDITION-CONTROLLED NETLIST 2.12 61 .IF Condition-Controlled Netlist A simple .IF-.ELSE(IF) block allows condition-controlling of the netlist. boolean expression is any expression according to Chapt. 2.8.5 that evaluates parameters and returns a boolean 1 or 0. The netlist block in between the .if ... .endif statements may contain device instances or .model cards that are selected according to the logic condition. General form: .if( boolean expression ) ... . elseif ( boolean expression ) ... .else ... .endif Example 1: * device instance in IF -ELSE block .param ok =0 ok2 =1 v1 1 0 1 R1 1 0 2 .if (ok && ok2) R11 1 0 2 .else R11 1 0 0.5 $ <-- selected .endif Example 2: * .model in IF -ELSE block .param m0 =0 m1 =1 M1 1 2 3 4 N1 W=1 L=0.5 .if(m0 ==1) .model N1 NMOS level =49 Version =3.1 . elseif (m1 ==1) .model N1 NMOS level =49 Version =3.2.4 .else .model N1 NMOS level =49 Version =3.3.0 .endif $ <-- selected For now this is a very restricted version of an .IF-.ELSE(IF) block, so several netlist components are currently not supported within the .IF-.ENDIF block: .SUBCKT, .INC, .LIB, and 62 CHAPTER 2. CIRCUIT DESCRIPTION .PARAM. Nesting of .IF-.ELSE(IF) blocks is not possible. Only one .elseif is allowed per block. 2.13 Parameters, functions, expressions, and command scripts In ngspice there are several ways to describe functional dependencies. In fact there are three independent function parsers, being active before, during, and after the simulation. So it might be due to have a few words on their interdependence. 2.13.1 Parameters Parameters (Chapt. 2.8.1) and functions, either defined within the .param statement or with the .func statement (Chapt. 2.9) are evaluated before any simulation is started, that is during the setup of the input and the circuit. Therefore these statements may not contain any simulation output (voltage or current vectors), because it is simply not yet available. The syntax is described in Chapt. 2.8.5. During the circuit setup all functions are evaluated, all parameters are replaced by their resulting numerical values. Thus it will not be possible to get feedback from a later stage (during or after simulation) to change any of the parameters. 2.13.2 Nonlinear sources During the simulation, the B source (Chapt. 5) and their associated E and G sources, as well as some devices (R, C, L) may contain expressions. These expressions may contain parameters from above (evaluated immediately upon ngspice start up), numerical data, predefined functions, but also node voltages and branch currents resulting from the simulation. The source or device values are continuously updated during the simulation. Therefore the sources are powerful tools to define non-linear behavior, you may even create new ‘devices’ by yourself. Unfortunately the expression syntax (see Chapt. 5.1) and the predefined functions may deviate from the ones for parameters listed in 2.8.1. 2.13.3 Control commands, Command scripts Commands, as described in detail in Chapt. 17.5, may be used interactively, but also as a command script enclosed in .control ... .endc lines. The scripts may contain expressions (see Chapt. 17.2). The expressions may work upon simulation output vectors (of node voltages, branch currents), as well as upon predefined or user defined vectors and variables, and are invoked after the simulation. Parameters from 2.8.1 defined by the .param statement are not allowed in these expressions. However you may define such parameters with .csparam (2.10). Again the expression syntax (see Chapt. 17.2) will deviate from the one for parameters or B sources listed in 2.8.1 and 5.1. If you want to use parameters from 2.8.1 inside your control script, you may use .csparam (2.10) or apply a trick by defining a voltage source with the parameter as its value, and then have it available as a vector (e.g. after a transient simulation) with a then constant output (the parameter). A feedback from here back into parameters (2.13.1) is never possible. Also you 2.13. PARAMETERS, FUNCTIONS, EXPRESSIONS, AND COMMAND SCRIPTS 63 cannot access non-linear sources of the preceding simulation. However you may start a first simulation inside your control script, then evaluate its output using expressions, change some of the element or model parameters with the alter and altermod statements (see Chapt. 17.5.3) and then automatically start a new simulation. Expressions and scripting are powerful tools within ngspice, and we will enhance the examples given in Chapt. 21 continuously to describe these features. 64 CHAPTER 2. CIRCUIT DESCRIPTION Chapter 3 Circuit Elements and Models Data fields that are enclosed in less-than and greater-than signs (‘< >’) are optional. All indicated punctuation (parentheses, equal signs, etc.) is optional but indicate the presence of any delimiter. Further, future implementations may require the punctuation as stated. A consistent style adhering to the punctuation shown here makes the input easier to understand. With respect to branch voltages and currents, ngspice uniformly uses the associated reference convention (current flows in the direction of voltage drop). 3.1 General options and information 3.1.1 Paralleling devices with multiplier m When it is needed to simulate several devices of the same kind in parallel, use the ‘m’ (parallel multiplier) instance parameter available for the devices listed in Table 3.1. This multiplies the value of the element’s matrix stamp with m’s value. The netlist below shows how to correctly use the parallel multiplier: Multiple device example: d1 2 0 mydiode m=10 d01 1 0 mydiode d02 1 0 mydiode d03 1 0 mydiode d04 1 0 mydiode d05 1 0 mydiode d06 1 0 mydiode d07 1 0 mydiode d08 1 0 mydiode d09 1 0 mydiode d10 1 0 mydiode ... The d1 instance connected between nodes 2 and 0 is equivalent to the 10 parallel devices d01-d10 connected between nodes 1 and 0. 65 66 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS The following devices support the multiplier m: First letter C D F G I J L M Q R X Z Element description Capacitor Diode Current-controlled current source (CCCs) Voltage-controlled current source (VCCS) Current source Junction field effect transistor (JFET) Inductor Metal oxide field effect transistor (MOSFET) Bipolar junction transistor (BJT) Resistor Subcircuit (for details see below) Metal semiconductor field effect transistor (MESFET) Table 3.1: ngspice elements supporting multiplier ’m’ When the X line (e.g. x1 a b sub1 m=5) contains the token m=value (as shown) or m=expression, subcircuit invocation is done in a special way. If an instance line of the subcircuit sub1 contains any of the elements shown in table 3.1, then these elements are instantiated with the additional parameter m (in this example having the value 5). If such an element already has an m multiplier parameter, the element m is multiplied with the m derived from the X line. This works recursively, meaning that if a subcircuit contains another subcircuit (a nested X line), then the latter m parameter will be multiplied by the former one, and so on. Example 1: .param madd = 6 X1 a b sub1 m=5 . subckt sub1 a1 b1 Cs1 a1 b1 C=5p m=’madd -2’ .ends In example 1, the capacitance between nodes a and b will be C = 5pF*(madd-2)*5 = 100pF. Example 2: .param madd = 4 X1 a b sub1 m=3 . subckt sub1 a1 b1 X2 a1 b1 sub2 m=’madd -2’ .ends . subckt sub2 a2 b2 Cs2 a2 b2 3p m=2 .ends In example 2, the capacitance between nodes a and b is C = 3pF*2*(madd-2)*3 = 36pF. 3.1. GENERAL OPTIONS AND INFORMATION 67 Using m may fail to correctly describe geometrical properties for real devices like MOS transistors. M1 d g s nmos W=0.3u L=0.18u m=20 is probably not be the same as M1 d g s nmos W=6u L=0.18u because the former may suffer from small width (or edge) effects, whereas the latter is simply a wide transistor. 3.1.2 Technology scaling Still to be implemented and written. 3.1.3 Model binning Binning is a kind of range partitioning for geometry dependent models like MOSFET’s. The purpose is to cover larger geometry ranges (Width and Length) with higher accuracy then the model built-in geometry formulas. Each size range described by the additional model parameters LMIN, LMAX, WMIN and WMAX has its own model parameter set. These model cards are defined by a number extension, like ‘nch.1’. NGSPICE has a algorithm to choose the right model card by the requested W and L. This is implemented for BSIM3 (11.2.10) and BSIM4 (11.2.11) models. 3.1.4 Initial conditions Two different forms of initial conditions may be specified for some devices. The first form is included to improve the dc convergence for circuits that contain more than one stable state. If a device is specified OFF, the dc operating point is determined with the terminal voltages for that device set to zero. After convergence is obtained, the program continues to iterate to obtain the exact value for the terminal voltages. If a circuit has more than one dc stable state, the OFF option can be used to force the solution to correspond to a desired state. If a device is specified OFF when in reality the device is conducting, the program still obtains the correct solution (assuming the solutions converge) but more iterations are required since the program must independently converge to two separate solutions. The .NODESET control line (see Chapt. 15.2.1) serves a similar purpose as the OFF option. The .NODESET option is easier to apply and is the preferred means to aid convergence. The second form of initial conditions are specified for use with the transient analysis. These are true ‘initial conditions’ as opposed to the convergence aids above. See the description of the .IC control line (Chapt. 15.2.2) and the .TRAN control line (Chapt. 15.3.9) for a detailed explanation of initial conditions. 68 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS 3.2 Elementary Devices 3.2.1 Resistors General form: RXXXXXXX n+ n- value + + Examples: R1 1 2 RC1 12 R2 5 7 RL 1 4 100 17 1K 1K ac =2K 2K m=2 Ngspice has a fairly complex model for resistors. It can simulate both discrete and semiconductor resistors. Semiconductor resistors in ngspice means: resistors described by geometrical parameters. So, do not expect detailed modeling of semiconductor effects. n+ and n- are the two element nodes, value is the resistance (in ohms) and may be positive or negative1 but not zero. Simulating small valued resistors: If you need to simulate very small resistors (0.001 Ohm or less), you should use CCVS (transresistance), it is less efficient but improves overall numerical accuracy. Think about that a small resistance is a large conductance. Ngspice can assign a resistor instance a different value for AC analysis, specified using the ac keyword. This value must not be zero as described above. The AC resistance is used in AC analysis only (neither Pole-Zero nor Noise). If you do not specify the ac parameter, it is defaulted to value. Ngspice calculates the nominal resistance as Rnom = VALUE scale m Racnom = ac scale m . (3.1) If you want to simulate temperature dependence of a resistor, you need to specify its temperature coefficients, using a .model line or as instance parameters, like in the examples below: 1A negative resistor modeling an active element can cause convergence problems, please avoid it. 3.2. ELEMENTARY DEVICES 69 Examples: RE1 1 2 800 newres dtemp =5 .MODEL newres R tc1 =0.001 RE2 a b 1.4k tc1 =2m tc2 =1.4u RE3 n1 n2 1Meg tce =700m The temperature coefficients tc1 and tc2 describe a quadratic temperature dependence (see equation 1.6) of the resistance. If given in the instance line (the R... line) their values will override the tc1 and tc2 of the .model line (3.2.3). Ngspice has an additional temperature model equation 3.2 parametrized by tce given in model or instance line. If all parameters are given (quadratic and exponential) the exponential temperature model is chosen. h i R (T ) = R (T0 ) 1.01TCE·(T −T0 ) (3.2) where T is the circuit temperature, T0 is the nominal temperature, and TCE is the exponential temperature coefficients. Instance temperature is useful even if resistance does not vary with it, since the thermal noise generated by a resistor depends on its absolute temperature. Resistors in ngspice generates two different noises: thermal and flicker. While thermal noise is always generated in the resistor, to add a flicker noise2 source you have to add a .model card defining the flicker noise parameters. It is possible to simulate resistors that do not generate any kind of noise using the noisy (or noise) keyword and assigning zero to it, as in the following example: Example: Rmd 134 57 1.5k noisy =0 If you are interested in temperature effects or noise equations, read the next section on semiconductor resistors. 3.2.2 Semiconductor Resistors General form: RXXXXXXX n+ n- + + Examples: RLOAD 2 10 10K RMOD 3 7 RMODEL L=10u W=1u 2 Flicker noise can be used to model carbon resistors. 70 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS This is the more general form of the resistor presented before (3.2.1) and allows the modeling of temperature effects and for the calculation of the actual resistance value from strictly geometric information and the specifications of the process. If value is specified, it overrides the geometric information and defines the resistance. If mname is specified, then the resistance may be calculated from the process information in the model mname and the given length and width. If value is not specified, then mname and length must be specified. If width is not specified, then it is taken from the default width given in the model. The (optional) temp value is the temperature at which this device is to operate, and overrides the temperature specification on the .option control line and the value specified in dtemp. 3.2.3 Semiconductor Resistor Model (R) The resistor model consists of process-related device data that allow the resistance to be calculated from geometric information and to be corrected for temperature. The parameters available are: Name Parameter Units Default Example Ω/◦C TC1 first order temperature coeff. 0.0 ◦ 2 Ω/ C TC2 second order temperature coeff. 0.0 Ω RSH sheet resistance / 50 DEFW default width m 1e-6 2e-6 NARROW narrowing due to side etching m 0.0 1e-7 SHORT shortening due to side etching m 0.0 1e-7 ◦ C TNOM parameter measurement temperature 27 50 KF flicker noise coefficient 0.0 1e-25 AF flicker noise exponent 0.0 1.0 WF flicker noise width exponent 1.0 LF flicker noise length exponent 1.0 EF flicker noise frequency exponent 1.0 R (RES) default value if element value not given Ω 1000 The sheet resistance is used with the narrowing parameter and l and w from the resistor device to determine the nominal resistance by the formula: Rnom = rsh l − SHORT w − NARROW (3.3) DEFW is used to supply a default value for w if one is not specified for the device. If either rsh or l is not specified, then the standard default resistance value of 1 mOhm is used. TNOM is used to override the circuit-wide value given on the .options control line where the parameters of this model have been measured at a different temperature. After the nominal resistance is calculated, it is adjusted for temperature by the formula: R(T ) = R(TNOM) 1 + TC1 (T − TNOM) + TC2 (T − TNOM)2 (3.4) where R(TNOM) = Rnom |Racnom . In the above formula, ‘T ’ represents the instance temperature, which can be explicitly set using the temp keyword or calculated using the circuit temperature and dtemp, if present. If both temp and dtemp are specified, the latter is ignored. Ngspice 3.2. ELEMENTARY DEVICES 71 improves SPICE’s resistors noise model, adding flicker noise (1/ f ) to it and the noisy (or noise) keyword to simulate noiseless resistors. The thermal noise in resistors is modeled according to the equation: 4kT ∆f i¯2R = R (3.5) where ‘k’ is the Boltzmann’s constant, and ‘T ’ the instance temperature. Flicker noise model is: i2R¯f n = KFIRAF ∆f W W F LLF f EF (3.6) A small list of sheet resistances (in Ω/) for conductors is shown below. The table represents typical values for MOS processes in the 0.5 - 1 um range. The table is taken from: N. Weste, K. Eshraghian - Principles of CMOS VLSI Design 2nd Edition, Addison Wesley. Material Inter-metal (metal1 - metal2) Top-metal (metal3) Polysilicon (poly) Silicide Diffusion (n+, p+) Silicided diffusion n-well 3.2.4 Min. 0.005 0.003 15 2 10 2 1000 Typ. 0.007 0.004 20 3 25 4 2000 Max. 0.1 0.05 30 6 100 10 5000 Resistors, dependent on expressions (behavioral resistor) General form: RXXXXXXX n+ n- R = ’expression ’ RXXXXXXX n+ n- ’expression ’ Examples: R1 rr 0 r = ’V(rr) < {Vt} ? {R0} : {2* R0}’ tc1 =2e -03 tc2 =3.3e -06 R2 r2 rr r = {5k + 50* TEMPER } Expression may be an equation or an expression containing node voltages or branch currents (in the form of i(vm)) and any other terms as given for the B source and described in Chapt. 5.1. It may contain parameters (2.8.1) and the special variables time, temper, and hertz (5.1.2). An example file is given below. 72 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS Example input file for non-linear resistor: Non - linear resistor .param R0 =1k Vi =1 Vt =0.5 * resistor depending on control voltage V(rr) R1 rr 0 r = ’V(rr) < {Vt} ? {R0} : {2* R0}’ * control voltage V1 rr 0 PWL (0 0 100u {Vi}) . control unset askquit tran 100n 100u uic plot i(V1) .endc .end 3.2.5 Capacitors General form: CXXXXXXX n+ n- + Examples: CBYP 13 0 1UF COSC 17 23 10U IC =3V Ngspice provides a detailed model for capacitors. Capacitors in the netlist can be specified giving their capacitance or their geometrical and physical characteristics. Following the original SPICE3 ‘convention’, capacitors specified by their geometrical or physical characteristics are called ‘semiconductor capacitors’ and are described in the next section. In this first form n+ and n- are the positive and negative element nodes, respectively and value is the capacitance in Farads. Capacitance can be specified in the instance line as in the examples above or in a .model line, as in the example below: C1 15 5 cstd C2 2 7 cstd .model cstd C cap =3n Both capacitors have a capacitance of 3nF. If you want to simulate temperature dependence of a capacitor, you need to specify its temperature coefficients, using a .model line, like in the example below: 3.2. ELEMENTARY DEVICES 73 CEB 1 2 1u cap1 dtemp =5 .MODEL cap1 C tc1 =0.001 The (optional) initial condition is the initial (time zero) value of capacitor voltage (in Volts). Note that the initial conditions (if any) apply only if the uic option is specified on the .tran control line. Ngspice calculates the nominal capacitance as described below: Cnom = value · scale · m (3.7) The temperature coefficients tc1 and tc2 describe a quadratic temperature dependence (see equation17.12) of the capacitance. If given in the instance line (the C... line) their values will override the tc1 and tc2 of the .model line (3.2.7). 3.2.6 Semiconductor Capacitors General form: CXXXXXXX n+ n- + Examples: CLOAD 2 10 10P CMOD 3 7 CMODEL L=10u W=1u This is the more general form of the Capacitor presented in section (3.2.5), and allows for the calculation of the actual capacitance value from strictly geometric information and the specifications of the process. If value is specified, it defines the capacitance and both process and geometrical information are discarded. If value is not specified, the capacitance is calculated from information contained model mname and the given length and width (l, w keywords, respectively). It is possible to specify mname only, without geometrical dimensions and set the capacitance in the .model line (3.2.5). 3.2.7 Semiconductor Capacitor Model (C) The capacitor model contains process information that may be used to compute the capacitance from strictly geometric information. 74 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS Name CAP CJ CJSW DEFW DEFL NARROW SHORT TC1 TC2 TNOM DI THICK Parameter model capacitance junction bottom capacitance junction sidewall capacitance default device width default device length narrowing due to side etching shortening due to side etching first order temperature coeff. second order temperature coeff. parameter measurement temperature relative dielectric constant insulator thickness Units F F/m2 F/m m m m m F/◦C F/◦C2 ◦C F/m m Default 0.0 1e-6 0.0 0.0 0.0 0.0 0.0 27 0.0 Example 1e-6 5e-5 2e-11 2e-6 1e-6 1e-7 1e-7 0.001 0.0001 50 1 1e-9 The capacitor has a capacitance computed as: If value is specified on the instance line then Cnom = value · scale · m (3.8) If model capacitance is specified then Cnom = CAP · scale · m (3.9) If neither value nor CAP are specified, then geometrical and physical parameters are take into account: C0 = CJ(l − SHORT)(w − NARROW) + 2CJSW(l − SHORT + w − NARROW) (3.10) CJ can be explicitly given on the .model line or calculated by physical parameters. When CJ is not given, is calculated as: If THICK is not zero: CJ = DI ε0 THICK CJ = εSiO2 THICK if DI is specified, (3.11) otherwise. If the relative dielectric constant is not specified the one for SiO2 is used. The values of the F F constants are: ε0 = 8.854214871e − 12 m and εSiO2 = 3.4531479969e − 11 m . The nominal capacitance is then computed as: Cnom = C0 scale m (3.12) After the nominal capacitance is calculated, it is adjusted for temperature by the formula: C(T ) = C(TNOM) 1 + TC1 (T − TNOM) + TC2 (T − TNOM)2 (3.13) 3.2. ELEMENTARY DEVICES 75 where C(TNOM) = Cnom . In the above formula, ‘T ’ represents the instance temperature, which can be explicitly set using the temp keyword or calculated using the circuit temperature and dtemp, if present. 3.2.8 Capacitors, dependent on expressions (behavioral capacitor) General form: CXXXXXXX n+ n- C = ’expression ’ CXXXXXXX n+ n- ’expression ’ Examples: C1 cc 0 c = ’V(cc) < {Vt} ? {C1} : {Ch}’ tc1 =-1e -03 tc2 =1.3e -05 Expression may be an equation or an expression containing node voltages or branch currents (in the form of i(vm)) and any other terms as given for the B source and described in Chapt. 5.1. It may contain parameters (2.8.1) and the special variables time, temper, and hertz (5.1.2). Example input file: Behavioral Capacitor .param Cl =5n Ch =1n Vt =1m Il =100n .ic v(cc) = 0 v(cc2) = 0 * capacitor depending on control voltage V(cc) C1 cc 0 c = ’V(cc) < {Vt} ? {Cl} : {Ch}’ *C1 cc 0 c ={ Ch} I1 0 1 {Il} Exxx n1 -copy n2 n2 cc2 1 Cxxx n1 -copy n2 1 Bxxx cc2 n2 I = ’(V(cc2) < {Vt} ? {Cl} : {Ch})’ * i(Exxx) I2 n2 22 {Il} vn2 n2 0 DC 0 * measure charge by integrating current aint1 %id (1 cc) 2 time_count aint2 %id (22 cc2) 3 time_count .model time_count int( in_offset =0.0 gain =1.0 + out_lower_limit =-1 e12 out_upper_limit =1 e12 + limit_range =1e -9 out_ic =0.0) . control unset askquit tran 100n 100u plot v(2) plot v(cc) v(cc2) .endc .end 76 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS 3.2.9 Inductors General form: LYYYYYYY n+ n- + + Examples: LLINK 42 69 1UH LSHUNT 23 51 10U IC =15.7 MA The inductor device implemented into ngspice has many enhancements over the original one.n+ and n- are the positive and negative element nodes, respectively. value is the inductance in Henry. Inductance can be specified in the instance line as in the examples above or in a .model line, as in the example below: L1 15 5 indmod1 L2 2 7 indmod1 .model indmod1 L ind =3n Both inductors have an inductance of 3nH. The nt is used in conjunction with a .model line, and is used to specify the number of turns of the inductor. If you want to simulate temperature dependence of an inductor, you need to specify its temperature coefficients, using a .model line, like in the example below: Lload 1 2 1u ind1 dtemp =5 .MODEL ind1 L tc1 =0.001 The (optional) initial condition is the initial (time zero) value of inductor current (in Amps) that flows from n+, through the inductor, to n-. Note that the initial conditions (if any) apply only if the UIC option is specified on the .tran analysis line. Ngspice calculates the nominal inductance as described below: Lnom = 3.2.10 value scale m (3.14) Inductor model The inductor model contains physical and geometrical information that may be used to compute the inductance of some common topologies like solenoids and toroids, wound in air or other material with constant magnetic permeability. 3.2. ELEMENTARY DEVICES Name IND CSECT LENGTH TC1 TC2 TNOM NT MU 77 Parameter model inductance cross section length first order temperature coeff. second order temperature coeff. parameter measurement temperature number of turns relative magnetic permeability Units H m2 m H/◦C H/◦C2 ◦C H/m Default 0.0 0.0 0.0 0.0 0.0 27 0.0 0.0 Example 1e-3 1e-3 1e-2 0.001 0.0001 50 10 - The inductor has an inductance computed as: If value is specified on the instance line then Lnom = value scale m (3.15) Lnom = IND scale m (3.16) If model inductance is specified then If neither value nor IND are specified, then geometrical and physical parameters are take into account. In the following formulas NT refers to both instance and model parameter (instance parameter overrides model parameter): If LENGTH is not zero: ( Lnom = Lnom = MU µ0 NT2 CSECT LENGTH µ0 NT2 CSECT LENGTH if MU is specified, (3.17) otherwise. with µ0 = 1.25663706143592 µH m . After the nominal inductance is calculated, it is adjusted for temperature by the formula L(T ) = L(TNOM) 1 + TC1 (T − TNOM) + TC2 (T − TNOM)2 , (3.18) where L(TNOM) = Lnom . In the above formula, ‘T ’ represents the instance temperature, which can be explicitly set using the temp keyword or calculated using the circuit temperature and dtemp, if present. 78 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS 3.2.11 Coupled (Mutual) Inductors General form: KXXXXXXX LYYYYYYY LZZZZZZZ value Examples: K43 LAA LBB 0.999 KXFRMR L1 L2 0.87 LYYYYYYY and LZZZZZZZ are the names of the two coupled inductors, and value is the coefficient of coupling, K, which must be greater than 0 and less than or equal to 1. Using the ‘dot’ convention, place a ‘dot’ on the first node of each inductor. 3.2.12 Inductors, dependent on expressions (behavioral inductor) General form: LXXXXXXX n+ n- L = ’expression ’ LXXXXXXX n+ n- ’expression ’ Examples: L1 l2 lll L = ’i(Vm) < {It} ? {Ll} : {Lh}’ tc1 =-4e -03 tc2 =6e -05 Expression may be an equation or an expression containing node voltages or branch currents (in the form of i(vm)) and any other terms as given for the B source and described in Chapt. 5.1. It may contain parameters (2.8.1) and the special variables time, temper, and hertz (5.1.2). 3.2. ELEMENTARY DEVICES 79 Example input file: Variable inductor .param Ll =0.5m Lh =5m It =50u Vi=2m .ic v( int21 ) = 0 * variable inductor depending on control current i(Vm) L1 l2 lll L = ’i(Vm) < {It} ? {Ll} : {Lh}’ * measure current through inductor vm lll 0 dc 0 * voltage on inductor V1 l2 0 {Vi} * fixed inductor L3 33 331 {Ll} * measure current through inductor vm33 331 0 dc 0 * voltage on inductor V3 33 0 {Vi} * non linear inductor ( discrete setup) F21 int21 0 B21 -1 L21 int21 0 1 B21 n1 n2 V = ’(i(Vm21) < {It} ? {Ll} : {Lh})’ * v(int21) * measure current through inductor vm21 n2 0 dc 0 V21 n1 0 {Vi} . control unset askquit tran 1u 100u uic plot i(Vm) i(vm33) plot i(vm21) i(vm33) plot i(vm)-i(vm21) .endc .end 3.2.13 Capacitor or inductor with initial conditions The simulator supports the specification of voltage and current initial conditions on capacitor and inductor models, respectively. These models are not the standard ones supplied with SPICE3, but are in fact code models that can be substituted for the SPICE models when realistic initial conditions are required. For details please refer to Chapter 12. A XSPICE deck example using these models is shown below: * * This circuit contains a capacitor and an inductor with 80 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS * initial conditions on them. Each of the components * has a parallel resistor so that an exponential decay * of the initial condition occurs with a time constant of * 1 second. * a1 1 0 cap .model cap capacitor (c=1000uf ic=1) r1 1 0 1k * a2 2 0 ind .model ind inductor (l=1H ic=1) r2 2 0 1.0 * .control tran 0.01 3 plot v(1) v(2) .endc .end 3.2.14 Switches Two types of switches are available: a voltage controlled switch (type SXXXXXX, model SW) and a current controlled switch (type WXXXXXXX, model CSW). A switching hysteresis may be defined, as well as on- and off-resistances (0 < R < ∞). General form: SXXXXXXX N+ N- NC+ NC - MODEL WYYYYYYY N+ N- VNAM MODEL Examples: s1 1 2 3 4 switch1 ON s2 5 6 3 0 sm2 off Switch1 1 2 10 0 smodel1 w1 1 2 vclock switchmod1 W2 3 0 vramp sm1 ON wreset 5 6 vclck lossyswitch OFF Nodes 1 and 2 are the nodes between which the switch terminals are connected. The model name is mandatory while the initial conditions are optional. For the voltage controlled switch, nodes 3 and 4 are the positive and negative controlling nodes respectively. For the current controlled switch, the controlling current is that through the specified voltage source. The direction of positive controlling current flow is from the positive node, through the source, to the negative node. The instance parameters ON or OFF are required, when the controlling voltage (current) starts inside the range of the hysteresis loop (different outputs during forward vs. backward voltage or current ramp). Then ON or OFF determine the initial state of the switch. 3.2. ELEMENTARY DEVICES 3.2.15 81 Switch Model (SW/CSW) The switch model allows an almost ideal switch to be described in ngspice. The switch is not quite ideal, in that the resistance can not change from 0 to infinity, but must always have a finite positive value. By proper selection of the on and off resistances, they can be effectively zero and infinity in comparison to other circuit elements. The parameters available are: Name VT IT VH IH RON ROFF Parameter threshold voltage threshold current hysteresis voltage hysteresis current on resistance off resistance Units V A V A Ω Ω Default 0.0 0.0 0.0 0.0 1.0 1.0e+12 (*) Switch model SW CSW SW CSW SW,CSW SW,CSW (*) Or 1/GMIN, if you have set GMIN to any other value, see the .OPTIONS control line (15.1.2) for a description of GMIN, its default value results in an off-resistance of 1.0e+12 ohms. The use of an ideal element that is highly nonlinear such as a switch can cause large discontinuities to occur in the circuit node voltages. A rapid change such as that associated with a switch changing state can cause numerical round-off or tolerance problems leading to erroneous results or time step difficulties. The user of switches can improve the situation by taking the following steps: • First, it is wise to set the ideal switch impedance just high or low enough to be negligible with respect to other circuit elements. Using switch impedances that are close to ‘ideal’ in all cases aggravates the problem of discontinuities mentioned above. Of course, when modeling real devices such as MOSFETS, the on resistance should be adjusted to a realistic level depending on the size of the device being modeled. • If a wide range of ON to OFF resistance must be used in the switches (ROFF/RON > 1e+12), then the tolerance on errors allowed during transient analysis should be decreased by using the .OPTIONS control line and specifying TRTOL to be less than the default value of 7.0. • When switches are placed around capacitors, then the option CHGTOL should also be reduced. Suggested values for these two options are 1.0 and 1e-16 respectively. These changes inform ngspice to be more careful around the switch points so that no errors are made due to the rapid change in the circuit. 82 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS Example input file: Switch test .tran 2us 5ms * switch control voltage v1 1 0 DC 0.0 PWL (0 0 2e-3 2 4e-3 0) * switch control voltage starting inside hysteresis window * please note influence of instance parameters ON , OFF v2 2 0 DC 0.0 PWL (0 0.9 2e-3 2 4e-3 0.4) * switch control current i3 3 0 DC 0.0 PWL (0 0 2e-3 2m 4e-3 0) $ <--- switch control current *load voltage v4 4 0 DC 2.0 *input load for current source i3 r3 3 33 10k vm3 33 0 dc 0 $ <--- measure the current * ouput load resistors r10 4 10 10k r20 4 20 10k r30 4 30 10k r40 4 40 10k * s1 10 0 1 0 switch1 OFF s2 20 0 2 0 switch1 OFF s3 30 0 2 0 switch1 ON .model switch1 sw vt =1 vh =0.2 ron =1 roff =10k * w1 40 0 vm3 wswitch1 off .model wswitch1 csw it=1m ih =0.2m ron =1 roff =10k * . control run plot v(1) v(10) plot v(10) vs v(1) $ <-- get hysteresis loop plot v(2) v(20) $ <--- different initial values plot v(20) vs v(2) $ <-- get hysteresis loop plot v(2) v(30) $ <--- different initial values plot v(30) vs v(2) $ <-- get hysteresis loop plot v(40) vs vm3# branch $ <--- current controlled switch hysteresis .endc .end Chapter 4 Voltage and Current Sources 4.1 Independent Sources for Voltage or Current General form: VXXXXXXX N+ N- < DC/TRAN VALUE > >> + >> >> IYYYYYYY N+ N- < DC/TRAN VALUE > >> + >> >> Examples: VCC 10 0 DC 6 VIN 13 2 0.001 AC 1 SIN (0 1 1MEG) ISRC 23 21 AC 0.333 45.0 SFFM (0 1 10K 5 1K) VMEAS 12 9 VCARRIER 1 0 DISTOF1 0.1 -90.0 VMODULATOR 2 0 DISTOF2 0.01 IIN1 1 5 AC 1 DISTOF1 DISTOF2 0.001 n+ and n- are the positive and negative nodes, respectively. Note that voltage sources need not be grounded. Positive current is assumed to flow from the positive node, through the source, to the negative node. A current source of positive value forces current to flow out of the n+ node, through the source, and into the n- node. Voltage sources, in addition to being used for circuit excitation, are the ‘ammeters’ for ngspice, that is, zero valued voltage sources may be inserted into the circuit for the purpose of measuring current. They of course have no effect on circuit operation since they represent short-circuits. DC/TRAN is the dc and transient analysis value of the source. If the source value is zero both for dc and transient analyses, this value may be omitted. If the source value is time-invariant (e.g., a power supply), then the value may optionally be preceded by the letters DC. ACMAG is the ac magnitude and ACPHASE is the ac phase. The source is set to this value in the ac analysis. If ACMAG is omitted following the keyword AC, a value of unity is assumed. If ACPHASE is omitted, a value of zero is assumed. If the source is not an ac small-signal input, the keyword AC and the ac values are omitted. 83 84 CHAPTER 4. VOLTAGE AND CURRENT SOURCES DISTOF1 and DISTOF2 are the keywords that specify that the independent source has distortion inputs at the frequencies F1 and F2 respectively (see the description of the .DISTO control line). The keywords may be followed by an optional magnitude and phase. The default values of the magnitude and phase are 1.0 and 0.0 respectively. Any independent source can be assigned a time-dependent value for transient analysis. If a source is assigned a time-dependent value, the time-zero value is used for dc analysis. There are nine independent source functions: • pulse, • exponential, • sinusoidal, • piece-wise linear, • single-frequency FM • AM • transient noise • random voltages or currents • and external data (only with ngspice shared library). If parameters other than source values are omitted or set to zero, the default values shown are assumed. TSTEP is the printing increment and TSTOP is the final time – see the .TRAN control line for an explanation. 4.1.1 Pulse General form (the PHASE parameter is only possible when XSPICE is enabled): PULSE (V1 V2 TD TR TF PW PER PHASE) Examples: VIN 3 0 PULSE (-1 1 2NS 2NS 2NS 50NS 100 NS) Name V1 V2 TD TR TF PW PER PHASE Parameter Initial value Pulsed value Delay time Rise time Fall time Pulse width Period Phase Default Value 0.0 TSTEP TSTEP TSTOP TSTOP 0.0 Units V, A V, A sec sec sec sec sec degrees 4.1. INDEPENDENT SOURCES FOR VOLTAGE OR CURRENT 85 A single pulse, without phase offset, is described by the following table: Time 0 TD TD+TR TD+TR+PW TD+TR+PW+TF TSTOP Value V1 V1 V2 V2 V1 V1 Intermediate points are determined by linear interpolation. 4.1.2 Sinusoidal General form (the PHASE parameter is only possible when XSPICE is enabled): SIN(VO VA FREQ TD THETA PHASE) Examples: VIN 3 0 SIN (0 1 100 MEG 1NS 1E10) Name VO VA FREQ TD THETA PHASE Parameter Offset Amplitude Frequency Delay Damping factor Phase Default Value 1/T ST OP 0.0 0.0 0.0 Units V, A V, A Hz sec 1/sec degrees The shape of the waveform is described by the following formula: ( V0 if 0 ≤ t < T D V (t) = V 0 +VA e−(t−T D)T HETA sin (2π · FREQ · (t − T D) + PHASE) if T D ≤ t < T ST OP. (4.1) 4.1.3 Exponential General Form: EXP(V1 V2 TD1 TAU1 TD2 TAU2) Examples: VIN 3 0 EXP (-4 -1 2NS 30NS 60NS 40NS) 86 CHAPTER 4. VOLTAGE AND CURRENT SOURCES Name V1 V2 TD1 TAU1 TD2 TAU2 Parameter Initial value pulsed value rise delay time rise time constant fall delay time fall time constant Default Value 0.0 TSTEP TD1+TSTEP TSTEP Units V, A V, A sec sec sec sec The shape of the waveform is described by the following formula: Let V 21 = V 2 −V 1,V 12 = V 1 −V 2: V1 if 0 ≤ t < T D1, (t−T D1) − TAU1 if T D1 ≤ t < T D2, V (t) = V 1 +V 21 1 − e (t−T D1) (t−T D2) V 1 +V 21 1 − e− TAU1 +V 12 1 − e− TAU2 if T D2 ≤ t < T ST OP. 4.1.4 (4.2) Piece-Wise Linear General Form: PWL(T1 V1 ) Examples: VCLOCK 7 5 PWL (0 -7 10NS -7 11NS -3 17NS -3 18NS -7 50NS -7) + r=0 td =15 NS Each pair of values (Ti , Vi ) specifies that the value of the source is Vi (in Volts or Amps) at time = Ti . The value of the source at intermediate values of time is determined by using linear interpolation on the input values. The parameter r determines a repeat time point. If r is not given, the whole sequence of values (Ti , Vi ) is issued once, then the output stays at its final value. If r = 0, the whole sequence from time 0 to time Tn is repeated forever. If r = 10ns, the sequence between 10ns and 50ns is repeated forever. the r value has to be one of the time points T1 to Tn of the PWL sequence. If td is given, the whole PWL sequence is delayed by the value of td. 4.1.5 Single-Frequency FM General Form (the PHASE parameters are only possible when XSPICE is enabled): SFFM(VO VA FC MDI FS PHASEC PHASES ) Examples: V1 12 0 SFFM (0 1M 20K 5 1K) 4.1. INDEPENDENT SOURCES FOR VOLTAGE OR CURRENT Name VO VA FC MDI FS PHASEC PHASES Parameter Offset Amplitude Carrier frequency Modulation index Signal frequency carrier phase signal phase Default value 1/T ST OP 1/T ST OP 0 0 87 Units V, A V, A Hz Hz degrees degrees The shape of the waveform is described by the following equation: V (t) = VO +VA sin (2π · FC · t + MDI sin (2π · FS · t + PHASES) + PHASEC) 4.1.6 (4.3) Amplitude modulated source (AM) General Form (the PHASE parameter is only possible when XSPICE is enabled): AM(VA VO MF FC TD PHASES ) Examples: V1 12 0 AM (0.5 1 20K 5MEG 1m) Name VA VO MF FC TD PHASES Parameter Amplitude Offset Modulating frequency Carrier frequency Signal delay Phase Default value 1/T ST OP 0.0 Units V, A V, A Hz Hz s degrees The shape of the waveform is described by the following equation: V (t) = VA (VO + sin (2π · MF · t) + PHASES) sin (2π · FC · t + PHASES) (4.4) 88 4.1.7 CHAPTER 4. VOLTAGE AND CURRENT SOURCES Transient noise source General Form: TRNOISE (NA NT NALPHA NAMP RTSAM RTSCAPT RTSEMT ) Examples: VNoiw 1 0 DC 0 TRNOISE (20n 0.5n 0 0) VNoi1of 1 0 DC 0 TRNOISE (0 10p 1.1 12p) VNoiw1of 1 0 DC 0 TRNOISE (20 10p 1.1 12p) IALL 10 0 DC 0 trnoise (1m 1u 1.0 0.1m 15m $ white $ 1/f $ white and 1/f 22u 50u) $ white , 1/f, RTS Transient noise is an experimental feature allowing (low frequency) transient noise injection and analysis. See Chapt. 15.3.10 for a detailed description. NA is the Gaussian noise rms voltage amplitude, NT is the time between sample values (breakpoints will be enforced on multiples of this value). NALPHA (exponent to the frequency dependency), NAMP (rms voltage or current amplitude) are the parameters for 1/f noise, RTSAM the random telegraph signal amplitude, RTSCAPT the mean of the exponential distribution of the trap capture time, and RTSEMT its emission time mean. White Gaussian, 1/f, and RTS noise may be combined into a single statement. Name Parameter Default value Units NA Rms noise amplitude (Gaussian) V, A NT Time step sec NALPHA 1/f exponent 0<α <2 NAMP Amplitude (1/f) V, A RTSAM Amplitude V, A RTSCAPT Trap capture time sec RTSEMT Trap emission time sec If you set NT and RTSAM to 0, the noise option TRNOISE ... is ignored. Thus you may switch off the noise contribution of an individual voltage source VNOI by the command alter @vnoi[trnoise] = [ 0 0 0 0 ] $ no noise alter @vrts[trnoise] = [ 0 0 0 0 0 0 0] $ no noise See Chapt. 17.5.3 for the alter command. You may switch off all TRNOISE noise sources by setting set notrnoise to your .spiceinit file (for all your simulations) or into your control section in front of the next run or tran command (for this specific and all following simulations). The command unset notrnoise will reinstate all noise sources. The noise generators are implemented into the independent voltage (vsrc) and current (isrc) sources. 4.1. INDEPENDENT SOURCES FOR VOLTAGE OR CURRENT 4.1.8 89 Random voltage source The TRRANDOM option yields statistically distributed voltage values, derived from the ngspice random number generator. These values may be used in the transient simulation directly within a circuit, e.g. for generating a specific noise voltage, but especially they may be used in the control of behavioral sources (B, E, G sources 5, voltage controllable A sources 12, capacitors 3.2.8, inductors 3.2.12, or resistors 3.2.4) to simulate the circuit dependence on statistically varying device parameters. A Monte-Carlo simulation may thus be handled in a single simulation run. General Form: TRRANDOM (TYPE TS >>) Examples: VR1 r1 0 dc 0 trrandom (2 10m 0 1) $ Gaussian TYPE determines the random variates generated: 1 is uniformly distributed, 2 Gaussian, 3 exponential, 4 Poisson. TS is the duration of an individual voltage value. TD is a time delay with 0 V output before the random voltage values start up. PARAM1 and PARAM2 depend on the type selected. TYPE 1 2 3 4 4.1.9 description Uniform Gaussian Exponential Poisson PARAM1 Range Standard Dev. Mean Lambda default 1 1 1 1 PARAM2 Offset Mean Offset Offset default 0 0 0 0 External voltage or current input General Form: EXTERNAL Examples: Vex 1 0 dc 0 external Iex i1 i2 dc 0 external Voltages or currents may be set from the calling process, if ngspice is compiled as a shared library and loaded by the process. See Chapt. 19.6.3 for an explanation. 90 CHAPTER 4. VOLTAGE AND CURRENT SOURCES 4.1.10 Arbitrary Phase Sources The XSPICE option supports arbitrary phase independent sources that output at TIME=0.0 a value corresponding to some specified phase shift. Other versions of SPICE use the TD (delay time) parameter to set phase-shifted sources to their time-zero value until the delay time has elapsed. The XSPICE phase parameter is specified in degrees and is included after the SPICE3 parameters normally used to specify an independent source. Partial XSPICE deck examples of usage for pulse and sine waveforms are shown below: * Phase shift is specified after Berkeley defined parameters * on the independent source cards. Phase shift for both of the * following is specified as +45 degrees * v1 1 0 0.0 sin(0 1 1k 0 0 45.0) r1 1 0 1k * v2 2 0 0.0 pulse(-1 1 0 1e-5 1e-5 5e-4 1e-3 45.0) r2 2 0 1k * 4.2 Linear Dependent Sources Ngspice allows circuits to contain linear dependent sources characterized by any of the four equations i = gv v = ev i = fi v = hi where g, e, f , and h are constants representing transconductance, voltage gain, current gain, and transresistance, respectively. Non-linear dependent sources for voltages or currents (B, E, G) are described in Chapt. 5. 4.2.1 Gxxxx: Linear Voltage-Controlled Current Sources (VCCS) General form: GXXXXXXX N+ N- NC+ NC - VALUE Examples: G1 2 0 5 0 0.1 n+ and n- are the positive and negative nodes, respectively. Current flow is from the positive node, through the source, to the negative node. nc+ and nc- are the positive and negative controlling nodes, respectively. value is the transconductance (in mhos). m is an optional multiplier to the output current. val may be a numerical value or an expression according to 2.8.5 containing references to other parameters. 4.2. LINEAR DEPENDENT SOURCES 4.2.2 91 Exxxx: Linear Voltage-Controlled Voltage Sources (VCVS) General form: EXXXXXXX N+ N- NC+ NC - VALUE Examples: E1 2 3 14 1 2.0 n+ is the positive node, and n- is the negative node. nc+ and nc- are the positive and negative controlling nodes, respectively. value is the voltage gain. 4.2.3 Fxxxx: Linear Current-Controlled Current Sources (CCCS) General form: FXXXXXXX N+ N- VNAM VALUE Examples: F1 13 5 VSENS 5 m=2 n+ and n- are the positive and negative nodes, respectively. Current flow is from the positive node, through the source, to the negative node. vnam is the name of a voltage source through which the controlling current flows. The direction of positive controlling current flow is from the positive node, through the source, to the negative node of vnam. value is the current gain. m is an optional multiplier to the output current. 4.2.4 Hxxxx: Linear Current-Controlled Voltage Sources (CCVS) General form: HXXXXXXX n+ n- vnam value Examples: HX 5 17 VZ 0.5K n+ and n- are the positive and negative nodes, respectively. vnam is the name of a voltage source through which the controlling current flows. The direction of positive controlling current flow is from the positive node, through the source, to the negative node of vnam. value is the transresistance (in ohms). 92 4.2.5 CHAPTER 4. VOLTAGE AND CURRENT SOURCES Polynomial Source Compatibility Dependent polynomial sources available in SPICE2G6 are fully supported in ngspice using the XSPICE extension (25.1). The form used to specify these sources is shown in Table 4.1. For details on its usage please see Chapt. 5.2.4. Source Type POLYNOMIAL VCVS POLYNOMIAL VCCS POLYNOMIAL CCCS POLYNOMIAL CCVS Dependent Polynomial Sources Instance Card EXXXXXXX N+ N- POLY(ND) NC1+ NC1- P0 (P1...) GXXXXXXX N+ N- POLY(ND) NC1+ NC1- P0 (P1...) FXXXXXXX N+ N- POLY(ND) VNAM1 !VNAM2...? P0 (P1...) HXXXXXXX N+ N- POLY(ND) VNAM1 !VNAM2...? P0 (P1...) Table 4.1: Dependent Polynomial Sources Chapter 5 Non-linear Dependent Sources (Behavioral Sources) The non-linear dependent sources B ( see Chapt. 5.1), E (see 5.2), G see (5.3) described in this chapter allow to generate voltages or currents that result from evaluating a mathematical expression. Internally E and G sources are converted to the more general B source. All three sources may be used to introduce behavioral modeling and analysis. 5.1 Bxxxx: Nonlinear dependent source (ASRC) 5.1.1 Syntax and usage General form: BXXXXXXX n+ n- + Examples: B1 B2 B3 B4 B5 + 0 1 I=cos(v (1))+ sin(v(2)) 0 1 V=ln(cos(log(v(1 ,2)^2))) -v (3)^4+ v(2)^v(1) 3 4 I=17 3 4 V=exp(pi^i(vdd )) 2 0 V = V(1) < {Vlow} ? {Vlow} : V(1) > { Vhigh } ? { Vhigh} : V(1) n+ is the positive node, and n- is the negative node. The values of the V and I parameters determine the voltages and currents across and through the device, respectively. If I is given then the device is a current source, and if V is given the device is a voltage source. One and only one of these parameters must be given. A simple model is implemented for temperature behavior by the formula: I(T ) = I(TNOM) 1 + TC1 (T − TNOM) + TC2 (T − TNOM)2 93 (5.1) 94 CHAPTER 5. NON-LINEAR DEPENDENT SOURCES (BEHAVIORAL SOURCES) or V (T ) = V (TNOM) 1 + TC1 (T − TNOM) + TC2 (T − TNOM)2 (5.2) In the above formula, ‘T ’ represents the instance temperature, which can be explicitly set using the temp keyword or calculated using the circuit temperature and dtemp, if present. If both temp and dtemp are specified, the latter is ignored. The small-signal AC behavior of the nonlinear source is a linear dependent source (or sources) with a proportionality constant equal to the derivative (or derivatives) of the source at the DC operating point. The expressions given for V and I may be any function of voltages and currents through voltage sources in the system. The following functions of a single real variable are defined: Trigonometric functions: cos, sin, tan, acos, asin, atan Hyperbolic functions: cosh, sinh, acosh, asinh, atanh Exponential and logarithmic: exp, ln, log, log10 (ln, log with base e, log10 with base 10) Other: abs, sqrt, u, u2, uramp, floor, ceil Functions of two variables are: min, max, pow Functions of three variables are: a ? b:c The function ‘u’ is the unit step function, with a value of one for arguments greater than zero and a value of zero for arguments less than zero. The function ‘u2’ returns a value of zero for arguments less than zero, one for arguments greater than one and assumes the value of the argument between these limits. The function ‘uramp’ is the integral of the unit step: for an input x, the value is zero if x is less than zero, or if x is greater than zero the value is x. These three functions are useful in synthesizing piece-wise non-linear functions, though convergence may be adversely affected. The following standard operators are defined: +, -, *, /, ^, unary Logical operators are !=, <>, >=, <=, ==, >, <, ||, &&, ! . A ternary function is defined as a ? b : c , which means IF a, THEN b, ELSE c. Be sure to place a space in front of ‘?’ to allow the parser distinguishing it from other tokens. 5.1. BXXXX: NONLINEAR DEPENDENT SOURCE (ASRC) 95 Example: Ternary function * B source test Clamped voltage source * C. P. Basso "Switched -mode power supplies ", New York , 2008 .param Vhigh = 4.6 .param Vlow = 0.4 Vin1 1 0 DC 0 PWL (0 0 1u 5) Bcl 2 0 V = V(1) < Vlow ? Vlow : V(1) > Vhigh ? Vhigh : V(1) . control unset askquit tran 5n 1u plot V(2) vs V(1) .endc .end If the argument of log, ln, or sqrt becomes less than zero, the absolute value of the argument is used. If a divisor becomes zero or the argument of log or ln becomes zero, an error will result. Other problems may occur when the argument for a function in a partial derivative enters a region where that function is undefined. Parameters may be used like {Vlow} shown in the example above. Parameters will be evaluated upon set up of the circuit, vectors like V(1) will be evaluated during the simulation. To get time into the expression you can integrate the current from a constant current source with a capacitor and use the resulting voltage (don’t forget to set the initial voltage across the capacitor). Non-linear resistors, capacitors, and inductors may be synthesized with the nonlinear dependent source. Nonlinear resistors, capacitors and inductors are implemented with their linear counterparts by a change of variables implemented with the nonlinear dependent source. The following subcircuit will implement a nonlinear capacitor: Example: Non linear capacitor . Subckt nlcap pos neg * Bx: calculate f( input voltage ) Bx 1 0 v = f(v(pos ,neg )) * Cx: linear capacitance Cx 2 0 1 * Vx: Ammeter to measure current into the capacitor Vx 2 1 DC 0 Volts * Drive the current through Cx back into the circuit Fx pos neg Vx 1 .ends Example for f(v(pos,neg)): Bx 1 0 V = v(pos ,neg )*v(pos ,neg) Non-linear resistors or inductors may be described in a similar manner. An example for a nonlinear resistor using this template is shown below. 96 CHAPTER 5. NON-LINEAR DEPENDENT SOURCES (BEHAVIORAL SOURCES) Example: Non linear resistor * use of ’hertz ’ variable in nonlinear resistor *. param rbase =1k * some tests B1 1 0 V = hertz *v(33) B2 2 0 V = v (33)* hertz b3 3 0 V = 6.283 e3 /( hertz +6.283 e3)*v(33) V1 33 0 DC 0 AC 1 *** Translate R1 10 0 R=’1k/sqrt(HERTZ)’ to B source *** . Subckt nlres pos neg rb=rbase * Bx: calculate f( input voltage ) Bx 1 0 v = -1 / {rb} / sqrt(HERTZ) * v(pos , neg) * Rx: linear resistance Rx 2 0 1 Example: Non linear resistor (continued) * Vx: Ammeter to measure current into the resistor Vx 2 1 DC 0 Volts * Drive the current through Rx back into the circuit Fx pos neg Vx 1 .ends Xres 33 10 nlres rb =1k *Rres 33 10 1k Vres 10 0 DC 0 . control define check (a,b) vecmax (abs(a - b)) ac lin 10 100 1k * some checks print v(1) v(2) v(3) if check (v(1) , frequency ) < 1e -12 echo "INFO: ok" end plot vres# branch .endc .end 5.1.2 Special B-Source Variables time, temper, hertz The special variables time and temper are available in a transient analysis, reflecting the actual simulation time and circuit temperature. temper returns the circuit temperature, given in degree C (see 2.11). The variable hertz is available in an AC analysis. time is zero in the AC analysis, hertz is zero during transient analysis. Using the variable hertz may cost some CPU time if you have a large circuit, because for each frequency the operating point has to be determined before calculating the AC response. 5.1. BXXXX: NONLINEAR DEPENDENT SOURCE (ASRC) 5.1.3 97 par(’expression’) The B source syntax may also be used in output lines like .plot as algebraic expressions for output (see Chapt.15.6.6 ). 5.1.4 Piecewise Linear Function: pwl Both B source types may contain a piece-wise linear dependency of one network variable: Example: pwl_current Bdio 1 0 I = pwl(v(A), 0,0, 33 ,10m, 100 ,33m, 200 ,50m) v(A) is the independent variable x. Each pair of values following describes the x,y functional relation: In this example at node A voltage of 0V the current of 0A is generated - next pair gives 10mA flowing from ground to node 1 at 33V on node A and so forth. The same is possible for voltage sources: Example: pwl_voltage Blimit b 0 V = pwl(v(1), -4,0, -2,2, 2,4, 4,5, 6,5) Monotony of the independent variable in the pwl definition is checked - non-monotonic x entries will stop the program execution. v(1) may be replaced by a controlling current source. v(1) may also be replaced by an expression, e.g. −2 i(Vin ). The value pairs may also be parameters, and have to be predefined by a .param statement. An example for the pwl function using all of these options is shown below. 98 CHAPTER 5. NON-LINEAR DEPENDENT SOURCES (BEHAVIORAL SOURCES) Example: pwl function in B source Demonstrates usage of the pwl function in an B source (ASRC) * Also emulates the TABLE function with limits .param .param .param .param .param .param x0=-4 y0 =0 x1=-2 y1 =2 x2 =2 y2=-2 x3 =4 y3 =1 xx0=x0 -1 xx3=x3 +1 Vin 1 0 R 1 0 2 DC =0V * no limits outside of the tabulated x values * ( continues linearily ) Btest2 2 0 I = pwl(v(1),’x0 ’,’y0 ’,’x1 ’,’y1 ’,’x2 ’,’y2 ’,’x3 ’,’y3 ’) * like TABLE function with limits : Btest3 3 0 I = (v(1) < ’x0 ’) ? ’y0 ’ : (v(1) < ’x3 ’) ? + pwl(v(1),’x0 ’,’y0 ’,’x1 ’,’y1 ’,’x2 ’,’y2 ’,’x3 ’,’y3 ’) : ’y3 ’ * more efficient and elegant TABLE function with limits *( voltage controlled ): Btest4 4 0 I = pwl(v(1), + ’xx0 ’,’y0 ’, ’x0 ’,’y0 ’, + ’x1 ’,’y1 ’, + ’x2 ’,’y2 ’, + ’x3 ’,’y3 ’, ’xx3 ’,’y3 ’) * * more efficient and elegant TABLE function with limits * ( controlled by current ): Btest5 5 0 I = pwl ( -2*i(Vin), + ’xx0 ’,’y0 ’, ’x0 ’,’y0 ’, + ’x1 ’,’y1 ’, + ’x2 ’,’y2 ’, + ’x3 ’,’y3 ’, ’xx3 ’,’y3 ’) Rint2 2 0 1 Rint3 3 0 1 Rint4 4 0 1 Rint5 5 0 1 . control dc Vin -6 6 0.2 plot v(2) v(3) v(4) -0.5 v (5)+0.5 .endc .end 5.2. EXXXX: NON-LINEAR VOLTAGE SOURCE 5.2 5.2.1 99 Exxxx: non-linear voltage source VOL General form: EXXXXXXX n+ n- vol=’expr ’ Examples: E41 4 0 vol = ’V(3)*V(3)-Offs ’ Expression may be an equation or an expression containing node voltages or branch currents (in the form of i(vm)) and any other terms as given for the B source and described in Chapt. 5.1. It may contain parameters (2.8.1) and the special variables time, temper, hertz (5.1.2). ’ or { } may be used to delimit the function. 5.2.2 VALUE Optional syntax: EXXXXXXX n+ n- value ={ expr} Examples: E41 4 0 value = {V(3)*V(3)- Offs} The ’=’ sign is optional. 5.2.3 TABLE Data may be entered from the listings of a data table similar to the pwl B-Source (5.1.4). Data are grouped into x, y pairs. Expression may be an equation or an expression containing node voltages or branch currents (in the form of i(vm)) and any other terms as given for the B source and described in Chapt. 5.1. It may contain parameters (2.8.1). ’ or { } may be used to delimit the function. Expression delivers the x-value, which is used to generate a corresponding yvalue according to the tabulated value pairs, using linear interpolation. If the x-value is below x0 , y0 is returned, above x2 y2 is returned (limiting function). The value pairs have to be real numbers, parameters are not allowed. 100 CHAPTER 5. NON-LINEAR DEPENDENT SOURCES (BEHAVIORAL SOURCES) Syntax for data entry from table: Exxx n1 n2 TABLE { expression } = (x0 , y0) (x1 , y1) (x2 , y2) Example (simple comparator): ECMP 11 0 TABLE {V(10 ,9)} = (-5mV , 0V) (5mV , 5V) An ’=’ sign may follow the keyword TABLE. 5.2.4 POLY Polynomial sources are only available when the XSPICE option (see 32) is enabled. General form: EXXXX N+ N- POLY(ND) NC1+ NC1 - (NC2+ NC2 -...) P0 (P1 ...) Example: ENONLIN 100 101 POLY (2) 3 0 4 0 0.0 13.6 0.2 0.005 POLY(ND) Specifies the number of dimensions of the polynomial. The number of pairs of controlling nodes must be equal to the number of dimensions. (N+) and (N-) nodes are output nodes. Positive current flows from the (+) node through the source to the (-) node. The and are in pairs and define a set of controlling voltages. A particular node can appear more than once, and the output and controlling nodes need not be different. The example yields a voltage output controlled by two input voltages v(3,0) and v(4,0). Four polynomial coefficients are given. The equivalent function to generate the output is: 0 + 13.6 * v(3) + 0.2 * v(4) + 0.005 * v(3) * v(3) Generally you will set the equation according to POLY(1) y = p0 + POLY(2) y = p0 + + + + POLY(3) y = p0 + + + p1*X1 + p2*X1*X1 + p3*X1*X1*X1 + ... p1*X1 + p2*X2 + p3*X1*X1 + p4*X2*X1 + p5*X2*X2 + p6*X1*X1*X1 + p7*X2*X1*X1 + p8*X2*X2*X1 + p9*X2*X2*X2 + ... p1*X1 + p2*X2 + p3*X3 + p4*X1*X1 + p5*X2*X1 + p6*X3*X1 + p7*X2*X2 + p8*X2*X3 + p9*X3*X3 + ... where X1 is the voltage difference of the first input node pair, X2 of the second pair and so on. Keeping track of all polynomial coefficient is rather tedious for large polynomials. 5.2. EXXXX: NON-LINEAR VOLTAGE SOURCE 5.2.5 101 LAPLACE Currently ngspice does not offer a direct E-Source element with the LAPLACE option. There is however a XSPICE code model equivalent called s_xfer (see Chapt. 12.2.16), which you may invoke manually. The XSPICE option has to be enabled (32.1). AC (15.3.1) and transient analysis (15.3.9) is supported. The following E-Source: ELOPASS 4 0 LAPLACE {V(1)} + {5 * (s/100 + 1) / (s ^2/42000 + s/60 + 1)} may be replaced by: AELOPASS 1 int_4 filter1 .model filter1 s_xfer (gain =5 + num_coeff =[{1/100} 1] + den_coeff =[{1/42000} {1/60} 1] + int_ic =[0 0]) ELOPASS 4 0 int_4 0 1 where you have the voltage of node 1 as input, an intermediate output node int_4 and an Esource as buffer to keep the name ‘ELOPASS’ available if further processing is required. If the controlling expression is more complex than just a voltage node, you may add a B-Source (5.1) for evaluating the expression before entering the A-device. E-Source with complex controlling expression: ELOPASS 4 0 LAPLACE {V(1)*v(2)} {10 / (s/6800 + 1)} may be replaced by: BELOPASS int_1 0 V=V(1)*v(2) AELOPASS int_1 int_4 filter1 .model filter1 s_xfer (gain =10 + num_coeff =[1] + den_coeff =[{1/6800} 1] + int_ic =[0]) ELOPASS 4 0 int_4 0 1 102 5.3 5.3.1 CHAPTER 5. NON-LINEAR DEPENDENT SOURCES (BEHAVIORAL SOURCES) Gxxxx: non-linear current source CUR General form: GXXXXXXX n+ n- cur=’expr ’ Examples: G51 55 225 cur = ’V(3)*V(3)-Offs ’ Expression may be an equation or an expression containing node voltages or branch currents (in the form of i(vm)) and any other terms as given for the B source and described in Chapt. 5.1. It may contain parameters (2.8.1) and special variables (5.1.2). m is an optional multiplier to the output current. val may be a numerical value or an expression according to 2.8.5 containing only references to other parameters (no node voltages or branch currents!), because it is evaluated before the simulation commences. 5.3.2 VALUE Optional syntax: GXXXXXXX n+ n- value =’expr ’ Examples: G51 55 225 value = ’V(3)*V(3)-Offs ’ The ’=’ sign is optional. 5.3.3 TABLE A data entry by a tabulated listing is available with syntax similar to the E-Source (see Chapt. 5.2.3). Syntax for data entry from table: Gxxx n1 n2 TABLE { expression } = + (x0 , y0) (x1 , y1) (x2 , y2) Example (simple comparator with current output and voltage control): GCMP 0 11 TABLE {V(10 ,9)} = (-5MV , 0V) (5MV , 5V) R 11 0 1k 5.3. GXXXX: NON-LINEAR CURRENT SOURCE 103 m is an optional multiplier to the output current. val may be a numerical value or an expression according to 2.8.5 containing only references to other parameters (no node voltages or branch currents!), because it is evaluated before the simulation commences. An ’=’ sign may follow the keyword TABLE. 5.3.4 POLY see E-Source at Chapt. 5.2.4. 5.3.5 LAPLACE See E-Source, Chapt. 5.2.5 , for an equivalent code model replacement. 5.3.6 Example An example file is given below. 104 CHAPTER 5. NON-LINEAR DEPENDENT SOURCES (BEHAVIORAL SOURCES) Example input file: VCCS , VCVS , non - linear dependency .param Vi =1 .param Offs = ’0.01*Vi ’ * VCCS depending on V(3) B21 int1 0 V = V(3)*V(3) G1 21 22 int1 0 1 * measure current through VCCS vm 22 0 dc 0 R21 21 0 1 * new VCCS depending on V(3) G51 55 225 cur = ’V(3)*V(3)-Offs ’ * measure current through VCCS vm5 225 0 dc 0 R51 55 0 1 * VCVS depending on V(3) B31 int2 0 V = V(3)*V(3) E1 1 0 int2 0 1 R1 1 0 1 * new VCVS depending on V(3) E41 4 0 vol = ’V(3)*V(3)-Offs ’ R4 4 0 1 * control voltage V1 3 0 PWL (0 0 100u {Vi}) . control unset askquit tran 10n 100u uic plot i(E1) i(E41) plot i(vm) i(vm5) .endc .end 5.4 Debugging a behavioral source The B, E, G, sources and the behavioral R, C, L elements are powerful tools to set up user defined models. Unfortunately debugging these models is not very comfortable. 5.4. DEBUGGING A BEHAVIORAL SOURCE 105 Example input file with bug (log(-2)): B source debugging V1 1 0 1 V2 2 0 -2 E41 4 0 vol = ’V(1)* log(V(2)) ’ . control tran 1 1 .endc .end The input file given above results in an error message: Error: -2 out of range for log In this trivial example, the reason and location for the bug is obvious. However, if you have several equations using behavioral sources, and several occurrences of the log function, then debugging is nearly impossible. However, if the variable ngdebug (see 17.7) is set (e.g. in file .spiceinit), a more distinctive error message is issued that (after some closer investigation) will reveal the location and value of the buggy parameter. Detailed error message for input file with bug (log(-2)): Error : -2 out of range for log calling PTeval , tree = (v0) * (log (v1)) d / d v0 : log (v1) d / d v1 : (v0) * ((0.434294) / (v1)) values : var0 = 1 var1 = -2 If variable strict_errorhandling (see 17.7) is set, ngspice exits after this message. If not, gmin and source stepping may be started, typically without success. 106 CHAPTER 5. NON-LINEAR DEPENDENT SOURCES (BEHAVIORAL SOURCES) Chapter 6 Transmission Lines Ngspice implements both the original SPICE3f5 transmission lines models and the one introduced with KSPICE. The latter provide an improved transient analysis of lossy transmission lines. Unlike SPICE models that use the state-based approach to simulate lossy transmission lines, KSPICE simulates lossy transmission lines and coupled multiconductor line systems using the recursive convolution method. The impulse response of an arbitrary transfer function can be determined by deriving a recursive convolution from the Pade approximations of the function. We use this approach for simulating each transmission line’s characteristics and each multiconductor line’s modal functions. This method of lossy transmission line simulation has been proved to give a speedup of one to two orders of magnitude over SPICE3f5. 6.1 Lossless Transmission Lines General form: TXXXXXXX N1 N2 N3 N4 Z0=VALUE + > Examples: T1 1 0 2 0 Z0 =50 TD =10 NS n1 and n2 are the nodes at port 1; n3 and n4 are the nodes at port 2. z0 is the characteristic impedance. The length of the line may be expressed in either of two forms. The transmission delay, td, may be specified directly (as td=10ns, for example). Alternatively, a frequency f may be given, together with nl, the normalized electrical length of the transmission line with respect to the wavelength in the line at the frequency ‘f’. If a frequency is specified but nl is omitted, 0.25 is assumed (that is, the frequency is assumed to be the quarter-wave frequency). Note that although both forms for expressing the line length are indicated as optional, one of the two must be specified. Note that this element models only one propagating mode. If all four nodes are distinct in the actual circuit, then two modes may be excited. To simulate such a situation, two transmission-line elements are required. (see the example in Chapt. 21.7 for further clarification.) The (optional) 107 108 CHAPTER 6. TRANSMISSION LINES initial condition specification consists of the voltage and current at each of the transmission line ports. Note that the initial conditions (if any) apply only if the UIC option is specified on the .TRAN control line. Note that a lossy transmission line (see below) with zero loss may be more accurate than the lossless transmission line due to implementation details. 6.2 Lossy Transmission Lines General form: OXXXXXXX n1 n2 n3 n4 mname Examples: O23 1 0 2 0 LOSSYMOD OCONNECT 10 5 20 5 INTERCONNECT This is a two-port convolution model for single conductor lossy transmission lines. n1 and n2 are the nodes at port 1; n3 and n4 are the nodes at port 2. Note that a lossy transmission line with zero loss may be more accurate than the lossless transmission line due to implementation details. 6.2.1 Lossy Transmission Line Model (LTRA) The uniform RLC/RC/LC/RG transmission line model (referred to as the LTRA model henceforth) models a uniform constant-parameter distributed transmission line. The RC and LC cases may also be modeled using the URC and TRA models; however, the newer LTRA model is usually faster and more accurate than the others. The operation of the LTRA model is based on the convolution of the transmission line’s impulse responses with its inputs (see [8]). The LTRA model takes a number of parameters, some of which must be given and some of which are optional. 6.2. LOSSY TRANSMISSION LINES Name R L G C LEN REL ABS NOSTEPLIMIT NO CONTROL LININTERP MIXEDINTERP COMPACTREL COMPACTABS TRUNCNR TRUNCDONTCUT Parameter resistance/length inductance/length conductance/length capacitance/length length of line breakpoint control breakpoint control don’t limit time-step to less than line delay don’t do complex time-step control use linear interpolation use linear when quadratic seems bad special reltol for history compaction special abstol for history compaction use Newton-Raphson method for time-step control don’t limit time-step to keep impulse-response errors low 109 Units/Type Ω/unit H/unit mhos/unit F/unit unit arbitrary unit flag Default 0.0 0.0 0.0 0.0 no default 1 1 not set Example 0.2 9.13e-9 0.0 3.65e-12 1.0 0.5 5 set flag not set set flag flag not set not set set set RELTOL 1.0e-3 ABSTOL 1.0e-9 flag not set set flag not set set The following types of lines have been implemented so far: • RLC (uniform transmission line with series loss only), • RC (uniform RC line), • LC (lossless transmission line), • RG (distributed series resistance and parallel conductance only). Any other combination will yield erroneous results and should not be tried. The length LEN of the line must be specified. NOSTEPLIMIT is a flag that will remove the default restriction of limiting time-steps to less than the line delay in the RLC case. NO CONTROL is a flag that prevents the default limiting of the time-step based on convolution error criteria in the RLC and RC cases. This speeds up simulation but may in some cases reduce the accuracy of results. LININTERP is a flag that, when specified, will use linear interpolation instead of the default quadratic interpolation for calculating delayed signals. MIXEDINTERP is a flag that, when specified, uses a metric for judging whether quadratic interpolation is not applicable and if so uses linear interpolation; otherwise it uses the default quadratic interpolation. TRUNCDONTCUT is a flag that removes the default cutting of the time-step to limit errors in the actual calculation of impulse-response related quantities. COMPACTREL and COMPACTABS are quantities that control the compaction of the past history of values stored for convolution. Larger values of these lower accuracy but usually increase simulation speed. These are to be used with the TRYTOCOMPACT option, described in the .OPTIONS section. TRUNCNR is a flag that turns on the use of NewtonRaphson iterations to determine an appropriate time-step in the time-step control routines. The 110 CHAPTER 6. TRANSMISSION LINES default is a trial and error procedure by cutting the previous time-step in half. REL and ABS are quantities that control the setting of breakpoints. The option most worth experimenting with for increasing the speed of simulation is REL. The default value of 1 is usually safe from the point of view of accuracy but occasionally increases computation time. A value greater than 2 eliminates all breakpoints and may be worth trying depending on the nature of the rest of the circuit, keeping in mind that it might not be safe from the viewpoint of accuracy. Breakpoints may usually be entirely eliminated if it is expected the circuit will not display sharp discontinuities. Values between 0 and 1 are usually not required but may be used for setting many breakpoints. COMPACTREL may also be experimented with when the option TRYTOCOMPACT is specified in a .OPTIONS card. The legal range is between 0 and 1. Larger values usually decrease the accuracy of the simulation but in some cases improve speed. If TRYTOCOMPACT is not specified on a .OPTIONS card, history compaction is not attempted and accuracy is high. NO CONTROL, TRUNCDONTCUT and NOSTEPLIMIT also tend to increase speed at the expense of accuracy. 6.3 Uniform Distributed RC Lines General form: UXXXXXXX n1 n2 n3 mname l=len Examples: U1 1 2 0 URCMOD L=50U URC2 1 12 2 UMODL l=1 MIL N=6 n1 and n2 are the two element nodes the RC line connects, while n3 is the node the capacitances are connected to. mname is the model name, len is the length of the RC line in meters. lumps, if specified, is the number of lumped segments to use in modeling the RC line (see the model description for the action taken if this parameter is omitted). 6.3.1 Uniform Distributed RC Model (URC) The URC model is derived from a model proposed by L. Gertzberg in 1974. The model is accomplished by a subcircuit type expansion of the URC line into a network of lumped RC segments with internally generated nodes. The RC segments are in a geometric progression, increasing toward the middle of the URC line, with K as a proportionality constant. The number of lumped segments used, if not specified for the URC line device, is determined by the following formula: log Fmax RL CL 2πL2 N= log K (K−1) 2 K (6.1) 6.4. KSPICE LOSSY TRANSMISSION LINES 111 The URC line is made up strictly of resistor and capacitor segments unless the ISPERL parameter is given a nonzero value, in which case the capacitors are replaced with reverse biased diodes with a zero-bias junction capacitance equivalent to the capacitance replaced, and with a saturation current of ISPERL amps per meter of transmission line and an optional series resistance equivalent to RSPERL ohms per meter. Name K FMAX RPERL CPERL ISPERL RSPERL 6.4 Parameter Propagation Constant Maximum Frequency of interest Resistance per unit length Capacitance per unit length Saturation Current per unit length Diode Resistance per unit length Units Hz Ω/m F/m A/m Ω/m Default 2.0 1.0 G 1000 10e-15 0 0 Example 1.2 6.5 Meg 10 1p - Area - KSPICE Lossy Transmission Lines Unlike SPICE3, which uses the state-based approach to simulate lossy transmission lines, KSPICE simulates lossy transmission lines and coupled multiconductor line systems using the recursive convolution method. The impulse response of an arbitrary transfer function can be determined by deriving a recursive convolution from the Pade approximations of the function. NGSPICE is using this approach for simulating each transmission line’s characteristics and each multiconductor line’s modal functions. This method of lossy transmission line simulation has shown to give a speedup of one to two orders of magnitude over SPICE3E. Please note that the following two models will support only transient simulation, no ac. Additional Documentation Available: • S. Lin and E. S. Kuh, ‘Pade Approximation Applied to Transient Simulation of Lossy Coupled Transmission Lines,’ Proc. IEEE Multi-Chip Module Conference, 1992, pp. 52-55. • S. Lin, M. Marek-Sadowska, and E. S. Kuh, ‘SWEC: A StepWise Equivalent Conductance Timing Simulator for CMOS VLSI Circuits,’ European Design Automation Conf., February 1991, pp. 142-148. • S. Lin and E. S. Kuh, ‘Transient Simulation of Lossy Interconnect,’ Proc. Design Automation Conference, Anaheim, CA, June 1992, pp. 81-86. 6.4.1 Single Lossy Transmission Line (TXL) General form: YXXXXXXX N1 0 N2 0 mname Example: Y1 1 0 2 0 ymod LEN =2 .MODEL ymod txl R =12.45 L =8.972e-9 G=0 C =0.468e -12 length =16 112 CHAPTER 6. TRANSMISSION LINES n1 and n2 are the nodes of the two ports. The optional instance parameter len is the length of the line and may be expressed in multiples of [unit]. Typically unit is given in meters. len will override the model parameter length for the specific instance only. The TXL model takes a number of parameters: Name R L G C LENGTH Parameter resistance/length inductance/length conductance/length capacitance/length length of line Units/Type Ω/unit H/unit mhos/unit F/unit unit Default 0.0 0.0 0.0 0.0 no default Example 0.2 9.13e-9 0.0 3.65e-12 1.0 Model parameter length must be specified as a multiple of unit. Typically unit is given in [m]. For transient simulation only. 6.4.2 Coupled Multiconductor Line (CPL) The CPL multiconductor line model is in theory similar to the RLGC model, but without frequency dependent loss (neither skin effect nor frequency-dependent dielectric loss). Up to 8 coupled lines are supported in NGSPICE. General form: PXXXXXXX NI1 NI2 ... NIX GND1 NO1 NO2 ... NOX GND2 mname Example: P1 in1 in2 0 b1 b2 0 PLINE .model PLINE CPL length ={ Len} +R=1 0 1 +L={ L11} {L12} {L22} +G=0 0 0 +C={ C11} {C12} {C22} .param Len =1 Rs =0 + C11 =9.143579E -11 C12 = -9.78265E -12 C22 =9.143578E -11 + L11 =3.83572E -7 L12 =8.26253E-8 L22 =3.83572E-7 ni1 ... nix are the nodes at port 1 with gnd1; no1 ... nox are the nodes at port 2 with gnd2. The optional instance parameter len is the length of the line and may be expressed in multiples of [unit]. Typically unit is given in meters. len will override the model parameter length for the specific instance only. The CPL model takes a number of parameters: Name R L G C LENGTH Parameter resistance/length inductance/length conductance/length capacitance/length length of line Units/Type Ω/unit H/unit mhos/unit F/unit unit Default 0.0 0.0 0.0 0.0 no default Example 0.2 9.13e-9 0.0 3.65e-12 1.0 6.4. KSPICE LOSSY TRANSMISSION LINES 113 All RLGC parameters are given in Maxwell matrix form. For the R and G matrices the diagonal elements must be specified, for L and C matrices the lower or upper triangular elements must specified. The parameter LENGTH is a scalar and is mandatory. For transient simulation only. 114 CHAPTER 6. TRANSMISSION LINES Chapter 7 Diodes 7.1 Junction Diodes General form: DXXXXXXX n+ n- mname + Examples: DBRIDGE 2 10 DIODE1 DCLMP 3 7 DMOD AREA =3.0 IC =0.2 The pn junction (diode) implemented in ngspice expands the one found in SPICE3f5. Perimeter effects and high injection level have been introduced into the original model and temperature dependence of some parameters has been added. n+ and n- are the positive and negative nodes, respectively. mname is the model name. Instance parameters may follow, dedicated to only the diode described on the respective line. area is the area scale factor, which may scale the saturation current given by the model parameters (and others, see table below). pj is the perimeter scale factor, scaling the sidewall saturation current and its associated capacitance. m is a multiplier of area and perimeter, and off indicates an (optional) starting condition on the device for dc analysis. If the area factor is omitted, a value of 1.0 is assumed. The (optional) initial condition specification using ic is intended for use with the uic option on the .tran control line, when a transient analysis is desired starting from other than the quiescent operating point. You should supply the initial voltage across the diode there. The (optional) temp value is the temperature at which this device is to operate, and overrides the temperature specification on the .option control line. The temperature of each instance can be specified as an offset to the circuit temperature with the dtemp option. 7.2 Diode Model (D) The dc characteristics of the diode are determined by the parameters is and n. An ohmic resistance, rs, is included. Charge storage effects are modeled by a transit time, tt, and a 115 116 CHAPTER 7. DIODES nonlinear depletion layer capacitance that is determined by the parameters cjo, vj, and m. The temperature dependence of the saturation current is defined by the parameters eg, the energy, and xti, the saturation current temperature exponent. The nominal temperature where these parameters were measured is tnom, which defaults to the circuit-wide value specified on the .options control line. Reverse breakdown is modeled by an exponential increase in the reverse diode current and is determined by the parameters bv and ibv (both of which are positive numbers). Junction DC parameters Name BV IBV IK (IKF) IKR IS (JS) JSW N RS Parameter Reverse breakdown voltage Current at breakdown voltage Forward knee current Reverse knee current Saturation current Sidewall saturation current Emission coefficient Ohmic resistance Units V A A A A A Ω Default ∞ 1.0e-3 1.0e-3 1.0e-3 1.0e-14 1.0e-14 1 0.0 Example 40 1.0e-4 1.0e-6 1.0e-6 1.0e-16 1.0e-15 1.5 100 Scale factor Parameter Zero-bias junction bottom-wall capacitance Zero-bias junction sidewall capacitance Coefficient for forward-bias depletion bottom-wall capacitance formula Coefficient for forward-bias depletion sidewall capacitance formula Area junction grading coefficient Periphery junction grading coefficient Junction potential Periphery junction potential Transit-time Units F Default 0.0 Example 2pF F 0.0 .1pF - 0.5 - - 0.5 - - 0.5 0.33 0.5 0.5 V V sec 1 1 0 0.6 0.6 0.1ns area perimeter 1/area Junction capacitance parameters Name CJO (CJ0) CJP (CJSW) FC FCS M (MJ) MJSW VJ (PB) PHP TT Scale factor area perimeter 7.3. DIODE EQUATIONS 117 Temperature effects Name Parameter Units Default EG Activation energy eV 1.11 TM1 TM2 TNOM (TREF) TRS1 (TRS) TRS2 TM1 TM2 TTT1 TTT2 1st order tempco for MJ 2nd order tempco for MJ Parameter measurement temperature 1st order tempco for RS 2nd order tempco for RS 1st order tempco for MJ 2nd order tempco for MJ 1st order tempco for TT 2nd order tempco for TT 1/◦C 1/◦C2 0.0 0.0 27 0.0 0.0 0.0 0.0 0.0 0.0 XTI Saturation current temperature exponent - 3.0 TLEV TLEVC CTA (CTC) CTP TCV Diode temperature equation selector Diode capac. temperature equation selector Area junct. cap. temperature coefficient Perimeter junct. cap. temperature coefficient Breakdown voltage temperature coefficient 1/◦C 1/◦C 1/◦C 0 0 0.0 0.0 0.0 ◦C 2 1/ ◦C 1/◦C 1/◦C2 1/◦C 1/◦C2 1/◦C Example 1.11 Si 0.69 Sbd 0.67 Ge 50 3.0 pn 2.0 Sbd - Noise modeling Name KF AF Parameter Flicker noise coefficient Flicker noise exponent Units - Default 0 1 Example Scale factor Diode models may be described in the input file (or an file included by .inc) according to the following example: General form: .model mname type( pname1 =pval1 pname2 =pval2 ... ) Examples: .model DMOD D (bv =50 is=1e -13 n =1.05) 7.3 Diode Equations The junction diode is the basic semiconductor device and the simplest one in ngspice, but its model is quite complex, even when not all the physical phenomena affecting a pn junction are handled. The diode is modeled in three different regions: 118 CHAPTER 7. DIODES • Forward bias: the anode is more positive than the cathode, the diode is ‘on’ and can conduct large currents. To avoid convergence problems and unrealistic high current, it is prudent to specify a series resistance to limit current with the rs model parameter. • Reverse bias: the cathode is more positive than the anode and the diode is ‘off’. A reverse bias diode conducts a small leakage current. • Breakdown: the breakdown region is modeled only if the bv model parameter is given. When a diode enters breakdown the current increases exponentially (remember to limit it); bv is a positive value. Parameters Scaling Model parameters are scaled using the unit-less parameters area and pj and the multiplier m as depicted below: AREAe f f = AREA m PJe f f = PJ m ISe f f = IS AREAe f f + JSW PJe f f IBVe f f = IBV AREAe f f IKe f f = IK AREAe f f IKRe f f = IKR AREAe f f CJe f f = CJ0 AREAe f f CJPe f f = CJP PJe f f Diode DC, Transient and AC model equations qVD NkT if VD ≥ −3 NkT q ISe f f (e − 1) +VD · GMIN, 3NkT 3 ID = −ISe f f [1 + ( qVD e ) ] +VD · GMIN, if − BVe f f < VD < −3 NkT q −q(BVe f f +VD ) NkT −ISe f f (e ) +VD · GMIN, if VD ≤ −BVe f f (7.1) The breakdown region must be described with more depth since the breakdown is not modeled physically. As written before, the breakdown modeling is based on two model parameters: the ‘nominal breakdown voltage’ bv and the current at the onset of breakdown ibv. For the diode model to be consistent, the current value cannot be arbitrarily chosen, since the reverse bias and breakdown regions must match. When the diode enters breakdown region from reverse bias, the current is calculated using the formula1 : Ibdwn = −ISe f f (e −qBV NkT − 1) (7.2) The computed current is necessary to adjust the breakdown voltage making the two regions match. The algorithm is a little bit convoluted and only a brief description is given here: 1 if you look at the source code in file diotemp.c you will discover that the exponential relation is replaced with a first order Taylor series expansion. 7.3. DIODE EQUATIONS 119 if IBVe f f < Ibdwn then IBVe f f = Ibdwn BVe f f = BV else IBVe f f BVe f f = BV − NVt ln( Ibdwn ) Algorithm 2: Diode breakdown current calculation Most real diodes shows a current increase that, at high current levels, does not follow the exponential relationship given above. This behavior is due to high level of carriers injected into the junction. High injection effects (as they are called) are modeled with ik and ikr. IDe f f = rID , 1+ IKID if VD ≥ −3 NkT q ef f rID 1+ IKRID , otherwise. (7.3) ef f Diode capacitance is divided into two different terms: • Depletion capacitance • Diffusion capacitance Depletion capacitance is composed by two different contributes, one associated to the bottom of the junction (bottom-wall depletion capacitance) and the other to the periphery (sidewall depletion capacitance). The basic equations are: CDiode = Cdi f f usion +Cdepletion Where the depletion capacitance is defined as: Cdepletion = Cdeplbw +Cdeplsw The diffusion capacitance, due to the injected minority carriers, is modeled with the transit time tt: Cdi f f usion = TT ∂ IDe f f ∂VD The depletion capacitance is more complex to model, since the function used to approximate it diverges when the diode voltage become greater than the junction built-in potential. To avoid function divergence, the capacitance function is approximated with a linear extrapolation for applied voltage greater than a fraction of the junction built-in potential. Cdeplbw = CJe f f (1 − VD )−MJ , VJ if VD < FC · VJ V D VJ CJe f f 1−FC(1+MJI)+MJ (1−FC)(1+MJ) , otherwise. (7.4) 120 CHAPTER 7. DIODES Cdeplsw = CJPe f f (1 − VD )−MJSW , PHP CJPe f f if VD < FCS · PHP VD 1−FCS(1+MJSW)+MJSW· PHP (1+MJSW) (1−FCS) , otherwise. (7.5) Temperature dependence The temperature affects many of the parameters in the equations above, and the following equations show how. One of the most significant parameters that varies with the temperature for a semiconductor is the band-gap energy: EGnom = 1.16 − 7.02e−4 TNOM2 TNOM + 1108.0 (7.6) −4 T2 TNOM + 1108.0 (7.7) EG(T ) = 1.16 − 7.02e The leakage current temperature’s dependence is: IS(T ) = IS e log f actor N JSW (T ) = JSW e log f actor N (7.8) (7.9) where ‘logfactor’ is defined as log f actor = EG T EG − + XTI ln( ) Vt (TNOM) Vt (T ) TNOM (7.10) The contact potentials (bottom-wall an sidewall) temperature dependence is: T T EGnom EG(T) V J(T ) = VJ( ) −Vt (T ) 3 · ln( )+ − TNOM TNOM Vt (TNOM) Vt (T ) (7.11) T T EGnom EG(T) PHP(T ) = PHP( ) −Vt (T ) 3 · ln( )+ − TNOM TNOM Vt (TNOM) Vt (T ) (7.12) The depletion capacitances temperature dependence is: V J(T ) −4 CJ(T ) = CJ 1 + MJ(4.0e (T − TNOM) − + 1) VJ PHP(T ) −4 CJSW (T ) = CJSW 1 + MJSW(4.0e (T − TNOM) − + 1) PHP (7.13) (7.14) The transit time temperature dependence is: T T (T ) = TT(1 + TTT1(T − TNOM) + TTT2(T − TNOM)2 ) (7.15) 7.3. DIODE EQUATIONS 121 The junction grading coefficient temperature dependence is: MJ(T ) = MJ(1 + TM1(T − TNOM) + TM2(T − TNOM)2 ) (7.16) The series resistance temperature dependence is: RS(T ) = RS(1 + TRS(T − TNOM) + TRS2(T − TNOM)2 ) (7.17) Noise model The diode has three noise contribution, one due to the presence of the parasitic resistance rs and the other two (shot and flicker) due to the pn junction. The thermal noise due to the parasitic resistance is: i2RS = 4kT ∆ f RS (7.18) The shot and flicker noise contributions are: i2d = 2qID ∆ f + KF · IDAF ∆f f (7.19) 122 CHAPTER 7. DIODES Chapter 8 BJTs 8.1 Bipolar Junction Transistors (BJTs) General form: QXXXXXXX nc nb ne mname + + Examples: Q23 10 24 13 QMOD IC =0.6 , 5.0 Q50A 11 26 4 20 MOD1 nc, nb, and ne are the collector, base, and emitter nodes, respectively. ns is the (optional) substrate node. When unspecified, ground is used. mname is the model name, area, areab, areac are the area factors (emitter, base and collector respectively), and off indicates an (optional) initial condition on the device for the dc analysis. If the area factor is omitted, a value of 1.0 is assumed. The (optional) initial condition specification using ic=vbe,vce is intended for use with the uic option on a .tran control line, when a transient analysis is desired to start from other than the quiescent operating point. See the .ic control line description for a better way to set transient initial conditions. The (optional) temp value is the temperature where this device is to operate, and overrides the temperature specification on the .option control line. Using the dtemp option one can specify the instance’s temperature relative to the circuit temperature. 8.2 BJT Models (NPN/PNP) Ngspice provides three BJT device models, which are selected by the .model card. .model QMOD1 BJT level=2 This is the minimal version, further optional parameters listed in the table below may replace the ngspice default parameters. The level keyword specifies the model to be used: 123 124 CHAPTER 8. BJTS • level=1: This is the original SPICE BJT model, and it is the default model if the level keyword is not specified on the .model line. • level=2: This is a modified version of the original SPICE BJT that models both vertical and lateral devices and includes temperature corrections of collector, emitter and base resistors. • level=4: Advanced VBIC model (see http://www.designers-guide.org/VBIC/ for details) The bipolar junction transistor model in ngspice is an adaptation of the integral charge control model of Gummel and Poon. This modified Gummel-Poon model extends the original model to include several effects at high bias levels. The model automatically simplifies to the simpler Ebers-Moll model when certain parameters are not specified. The parameter names used in the modified Gummel-Poon model have been chosen to be more easily understood by the user, and to reflect better both physical and circuit design thinking. The dc model is defined by the parameters is, bf, nf, ise, ikf, and ne, which determine the forward current gain characteristics, is, br, nr, isc, ikr, and nc, which determine the reverse current gain characteristics, and vaf and var, which determine the output conductance for forward and reverse regions. The level 1 model has among the standard temperature parameters an extension compatible with most foundry provided process design kits (see parameter table below tlev). The level 1 and 2 models include the substrate saturation current iss. Three ohmic resistances rb, rc, and re are included, where rb can be high current dependent. Base charge storage is modeled by forward and reverse transit times, tf and tr, where the forward transit time tf can be bias dependent if desired. Nonlinear depletion layer capacitances are defined with cje, vje, and nje for the B-E junction, cjc, vjc, and njc for the B-C junction and cjs, vjs, and mjs for the C-S (collector-substrate) junction. The level 1 and 2 model support a substrate capacitance that is connected to the device’s base or collector, to model lateral or vertical devices dependent on the parameter subs. The temperature dependence of the saturation currents, is and iss (for the level 2 model), is determined by the energy-gap, eg, and the saturation current temperature exponent, xti. In the new model, additional base current temperature dependence is modeled by the beta temperature exponent xtb. The values specified are assumed to have been measured at the temperature tnom, which can be specified on the .options control line or overridden by a specification on the .model line. The level 4 model (VBIC) has the following improvements beyond the GP models: improved Early effect modeling, quasi-saturation modeling, parasitic substrate transistor modeling, parasitic fixed (oxide) capacitance modeling, includes an avalanche multiplication model, improved temperature modeling, base current is decoupled from collector current, electrothermal modeling, smooth and continuous mode. The BJT parameters used in the modified Gummel-Poon model are listed below. The parameter names used in earlier versions of SPICE2 are still accepted. Gummel-Poon BJT Parameters (incl. model extensions) 8.2. BJT MODELS (NPN/PNP) Name SUBS IS ISS BF NF VAF (VA) IKF NKF ISE NE BR NR VAR (VB) IKR ISC NC RB IRB RBM RE RC CJE VJE (PE) MJE (ME) TF XTF VTF ITF Parameters Substrate connection: for vertical geometry, -1 for lateral geometry (level 2 only). Transport saturation current. Reverse saturation current, substrate-to-collector for vertical device or substrate-to-base for lateral (level 2 only). Ideal maximum forward beta. Forward current emission coefficient. Forward Early voltage. Corner for forward beta current roll-off. High current Beta rolloff exponent B-E leakage saturation current. B-E leakage emission coefficient. Ideal maximum reverse beta. Reverse current emission coefficient. Reverse Early voltage. Corner for reverse beta high current roll-off. B-C leakage saturation current (area is ‘areab’ for vertical devices and ‘areac’ for lateral). B-C leakage emission coefficient. Zero bias base resistance. Current where base resistance falls halfway to its min value. Minimum base resistance at high currents. Emitter resistance. Collector resistance. B-E zero-bias depletion capacitance. B-E built-in potential. B-E junction exponential factor. Ideal forward transit time. Coefficient for bias dependence of TF. Voltage describing VBC dependence of TF. High-current parameter for effect on TF. 125 Units Default 1 Example Scale factor A A 1.0e-16 1.0e-16 1.0e-15 1.0e-15 area area - 100 1.0 100 1 V A ∞ ∞ 200 0.01 A - 0.5 0.0 1.5 1 1 0.58 1e-13 2 0.1 1 V A ∞ ∞ 200 0.01 area A 0.0 1e-13 area Ω A 2 0 ∞ 1.5 100 0.1 area area Ω RB 10 area Ω Ω F 0 0 0 1 10 2pF area area area V sec - 0.75 0.33 0 0 0.6 0.33 0.1ns V ∞ A 0 - area area area 126 CHAPTER 8. BJTS PTF CJC VJC (PC) MJC XCJC TR CJS VJS (PS) MJS (MS) XTB EG XTI KF AF FC TNOM (TREF) TLEV TLEVC TRE1 TRE2 TRC1 TRC2 TRB1 TRB2 1 Hz. 2πT F B-C zero-bias depletion capacitance (area is ‘areab’ for vertical devices and ‘areac’ for lateral). B-C built-in potential. B-C junction exponential factor. Fraction of B-C depletion capacitance connected to internal base node. Ideal reverse transit time. Zero-bias collector-substrate capacitance (area is ‘areac’ for vertical devices and ‘areab’ for lateral). Substrate junction built-in potential. Substrate junction exponential factor. Forward and reverse beta temperature exponent. Energy gap for temperature effect on IS. Temperature exponent for effect on IS. Flicker-noise coefficient. Flicker-noise exponent. Coefficient for forward-bias depletion capacitance formula. Parameter measurement temperature. BJT temperature equation selector BJT capac. temperature equation selector 1st order temperature coefficient for RE. 2nd order temperature coefficient for RE. 1st order temperature coefficient for RC . 2nd order temperature coefficient for RC. 1st order temperature coefficient for RB. 2nd order temperature coefficient for RB. Excess phase at freq= deg 0 F 0 2pF V - 0.75 0.33 1 0.5 0.5 sec F 0 0 10ns 2pF V 0.75 - 0 - 0 eV 1.11 - 3 - 0 1 0.5 0 ◦C 27 50 - 0 0 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 0.5 area area 8.2. BJT MODELS (NPN/PNP) TRBM1 TRBM2 TBF1 TBF2 TBR1 TBR2 TIKF1 TIKF2 TIKR1 TIKR2 TIRB1 TIRB2 TNC1 TNC2 TNE1 TNE2 TNF1 TNF2 TNR1 TNR2 TVAF1 TVAF2 TVAR1 1st order temperature coefficient for RBM 2nd order temperature coefficient for RBM 1st order temperature coefficient for BF 2nd order temperature coefficient for BF 1st order temperature coefficient for BR 2nd order temperature coefficient for BR 1st order temperature coefficient for IKF 2nd order temperature coefficient for IKF 1st order temperature coefficient for IKR 2nd order temperature coefficient for IKR 1st order temperature coefficient for IRB 2nd order temperature coefficient for IRB 1st order temperature coefficient for NC 2nd order temperature coefficient for NC 1st order temperature coefficient for NE 2nd order temperature coefficient for NE 1st order temperature coefficient for NF 2nd order temperature coefficient for NF 1st order temperature coefficient for IKF 2nd order temperature coefficient for IKF 1st order temperature coefficient for VAF 2nd order temperature coefficient for VAF 1st order temperature coefficient for VAR 127 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 128 CHAPTER 8. BJTS TVAR2 CTC CTE CTS TVJC TVJE TITF1 TITF2 TTF1 TTF2 TTR1 TTR2 TMJE1 TMJE2 TMJC1 TMJC2 2nd order temperature coefficient for VAR 1st order temperature coefficient for CJC 1st order temperature coefficient for CJE 1st order temperature coefficient for CJS 1st order temperature coefficient for VJC 1st order temperature coefficient for VJE 1st order temperature coefficient for ITF 2nd order temperature coefficient for ITF 1st order temperature coefficient for TF 2nd order temperature coefficient for TF 1st order temperature coefficient for TR 2nd order temperature coefficient for TR 1st order temperature coefficient for MJE 2nd order temperature coefficient for MJE 1st order temperature coefficient for MJC 2nd order temperature coefficient for MJC 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C 0.0 1e-3 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 1/◦C 0.0 1e-3 1/◦C2 0.0 1e-5 Chapter 9 JFETs 9.1 Junction Field-Effect Transistors (JFETs) General form: JXXXXXXX nd ng ns mname Examples: J1 7 2 3 JM1 OFF nd, ng, and ns are the drain, gate, and source nodes, respectively. mname is the model name, area is the area factor, and off indicates an (optional) initial condition on the device for dc analysis. If the area factor is omitted, a value of 1.0 is assumed. The (optional) initial condition specification, using ic=VDS,VGS is intended for use with the uic option on the .TRAN control line, when a transient analysis is desired starting from other than the quiescent operating point. See the .ic control line for a better way to set initial conditions. The (optional) temp value is the temperature where this device is to operate, and overrides the temperature specification on the .option control line. 9.2 9.2.1 JFET Models (NJF/PJF) JFET level 1 model with Parker Skellern modification The level 1 JFET model is derived from the FET model of Shichman and Hodges. The dc characteristics are defined by the parameters VTO and BETA, which determine the variation of drain current with gate voltage, LAMBDA, which determines the output conductance, and IS, the saturation current of the two gate junctions. Two ohmic resistances, RD and RS, are included. vgst = vgs −V T O 129 (9.1) 130 CHAPTER 9. JFETS β p = BETA (1 + LAMBDA vds) b f ac = 1−B PB −V T O (9.2) (9.3) if vgst ≤ 0 vds · GMIN, IDrain = β p vds (vds (b f ac vds − B) vgst (2B + 3b f ac (vgst − vds))) + vds · GMIN, if vgst ≥ vds β p vgst 2 (B + vgst b f ac) + vds · GMIN, if vgst < vds (9.4) Note that in Spice3f and later, the fitting parameter B has been added by Parker and Skellern. For details, see [9]. If parameter B is set to 1 equation above simplifies to if vgst ≤ 0 vds · GMIN, IDrain = β p vds (2vgst − vds) + vds · GMIN, if vgst ≥ vds β p vgst 2 + vds · GMIN, if vgst < vds (9.5) Charge storage is modeled by nonlinear depletion layer capacitances for both gate junctions, which vary as the −1/2 power of junction voltage and are defined by the parameters CGS, CGD, and PB. Name Parameter Units Default Example Scaling factor VTO Threshold voltage VT 0 V -2.0 -2.0 A/V ” BETA Transconductance parameter (β ) 1.0e-4 1.0e-3 area 1/V LAMBDA Channel-length modulation 0 1.0e-4 parameter (λ ) RD Drain ohmic resistance Ω 0 100 area RS Source ohmic resistance Ω 0 100 area CGS Zero-bias G-S junction capacitance F 0 5pF area Cgs CGD Zero-bias G-D junction F 0 1pF area capacitance Cgd PB Gate junction potential V 1 0.6 IS Gate saturation current IS A 1.0e-14 1.0e-14 area B Doping tail parameter 1 1.1 KF Flicker noise coefficient 0 AF Flicker noise exponent 1 NLEV Noise equation selector 1 3 GDSNOI Channel noise coefficient for 1.0 2.0 nlev=3 FC Coefficient for forward-bias 0.5 depletion capacitance formula ◦C TNOM Parameter measurement 27 50 temperature 1/°C TCV Threshold voltage temperature 0.0 0.1 coefficient BEX Mobility temperature exponent 0.0 1.1 9.2. JFET MODELS (NJF/PJF) 131 Additional to the standard thermal and flicker noise model an alternative thermal channel noise model is implemented and is selectable by setting NLEV parameter to 3. This follows in a correct channel thermal noise in the linear region. Snoise = (1 + α + α 2 ) 2 4kT · BETA ·V gst GDSNOI 3 1+α (9.6) with α= 9.2.2 ( vds 1 − vgs−V T O , if vgs −V T O ≥ vds 0, else (9.7) JFET level 2 Parker Skellern model The level 2 model is an improvement to level 1. Details are available from Macquarie University. Some important items are: • The description maintains strict continuity in its high-order derivatives, which is essential for prediction of distortion and intermodulation. • Frequency dependence of output conductance and transconductance is described as a function of bias. • Both drain-gate and source-gate potentials modulate the pinch-off potential, which is consistent with S-parameter and pulsed-bias measurements. • Self-heating varies with frequency. • Extreme operating regions - subthreshold, forward gate bias, controlled resistance, and breakdown regions - are included. • Parameters provide independent fitting to all operating regions. It is not necessary to compromise one region in favor of another. • Strict drain-source symmetry is maintained. The transition during drain-source potential reversal is smooth and continuous. The model equations are described in this pdf document and in [19]. 132 Name ID ACGAM BETA CGD CGS DELTA FC HFETA HFE1 HFE2 HFGAM HFG1 HFG2 IBD IS LFGAM LFG1 LFG2 MVST N P Q RS RD TAUD TAUG VBD VBI VST VTO XC XI Z RG LG LS LD CDSS AFAC NFING TNOM TEMP CHAPTER 9. JFETS Description Device IDText Capacitance modulation Linear-region transconductance scale Zero-bias gate-source capacitance Zero-bias gate-drain capacitance Thermal reduction coefficient Forward bias capacitance parameter High-frequency VGS feedback parameter HFGAM modulation by VGD HFGAM modulation by VGS High-frequency VGD feedback parameter HFGAM modulation by VSG HFGAM modulation by VDG Gate-junction breakdown current Gate-junction saturation current Low-frequency feedback parameter LFGAM modulation by VSG LFGAM modulation by VDG Subthreshold modulation Gate-junction ideality factor Linear-region power-law exponent Saturated-region power-law exponent Source ohmic resistance Drain ohmic resistance Relaxation time for thermal reduction Relaxation time for gamma feedback Gate-junction breakdown potential Gate-junction potential Subthreshold potential Threshold voltage Capacitance pinch-off reduction factor Saturation-knee potential factor Knee transition parameter Gate ohmic resistance Gate inductance Source inductance Drain inductance Fixed Drain-source capacitance Gate-width scale factor Number of gate fingers scale factor Nominal Temperature (Not implemented) Temperature Unit Type Text None None Capacitance Capacitance None None None None None None None None Current Current None None None None None None None Resistance Resistance Time Time Voltage Voltage Voltage Voltage None None None Resistance Inductance Inductance Inductance Capacitance None None Temperature Temperature Default PF1 0 10−4 0F 0F 0W 0.5 0 0V −1 0 V−1 0 0 V−1 0 V−1 0A 10−14A 0 0 V−1 0 V−1 0 V−1 1 2 2 0 Ohm 0 Ohm 0s 0s 1V 1V 0V -2.0 V 0 1000 0.5 0 Ohm 0H 0H 0H 0F 1 1 300 K 300 K Chapter 10 MESFETs 10.1 MESFETs General form: ZXXXXXXX ND NG NS MNAME Examples: Z1 7 2 3 ZM1 OFF 10.2 MESFET Models (NMF/PMF) 10.2.1 Model by Statz e.a. The MESFET model level 1 is derived from the GaAs FET model of Statz et al. as described in [11]. The dc characteristics are defined by the parameters VTO, B, and BETA, which determine the variation of drain current with gate voltage, ALPHA, which determines saturation voltage, and LAMBDA, which determines the output conductance. The formula are given by: Id = B(Vgs −VT )2 1+b(Vgs −VT ) B(Vgs −VT )2 1+b(Vgs −VT ) (1 + LVds ) 1 − 1 − A V3ds 3 (1 + LVds ) for 0 < Vds < for V > 3 A (10.1) 3 A Two ohmic resistances, rd and rs, are included. Charge storage is modeled by total gate charge as a function of gate-drain and gate-source voltages and is defined by the parameters cgs, cgd, and pb. 133 134 CHAPTER 10. MESFETS Name VTO BETA B ALPHA LAMBDA RD RS CGS CGD PB KF AF FC Parameter Pinch-off voltage Transconductance parameter Doping tail extending parameter Saturation voltage parameter Channel-length modulation parameter Drain ohmic resistance Source ohmic resistance Zero-bias G-S junction capacitance Zero-bias G-D junction capacitance Gate junction potential Flicker noise coefficient Flicker noise exponent Coefficient for forward-bias depletion capacitance formula Units V A/V 2 1/V 1/V 1/V Ω Ω F F V - Default -2.0 1.0e-4 0.3 2 0 0 0 0 0 1 0 1 0.5 Example -2.0 1.0e-3 0.3 2 1.0e-4 100 100 5pF 1pF 0.6 Area * * * * * * * Device instance: z1 2 3 0 mesmod area =1.4 Model: .model mesmod nmf level =1 rd =46 rs =46 vt0 = -1.3 + lambda =0.03 alpha =3 beta =1.4e-3 10.2.2 Model by Ytterdal e.a. level 2 (and levels 3,4) Copyright 1993: T. Ytterdal, K. Lee, M. Shur and T. A. Fjeldly to be written M. Shur, T.A. Fjeldly, T. Ytterdal, K. Lee, "Unified GaAs MESFET Model for Circuit Simulation", Int. Journal of High Speed Electronics, vol. 3, no. 2, pp. 201-233, 1992 10.2.3 hfet1 level 5 to be written no documentation available 10.2.4 hfet2 level6 to be written no documentation available Chapter 11 MOSFETs Ngspice supports all the original mosfet models present in SPICE3f5 and almost all the newer ones that have been published and made open-source. Both bulk and SOI (Silicon on Insulator) models are available. When compiled with the cider option, ngspice implements the four terminals numerical model that can be used to simulate a MOSFET (please refer to numerical modeling documentation for additional information and examples). 11.1 MOSFET devices General form: MXXXXXXX nd ng ns nb mname + + Examples: M1 24 2 0 20 TYPE1 M31 2 17 6 10 MOSN L=5U W=2U M1 2 9 3 0 MOSP L=10U W=5U AD =100P AS =100P PD =40U PS =40U Note the suffixes in the example: the suffix ‘u’ specifies microns (1e-6 m) and ‘p’ sq-microns (1e-12 m2 ). The instance card for MOS devices starts with the letter ’M’. nd, ng, ns, and nb are the drain, gate, source, and bulk (substrate) nodes, respectively. mname is the model name and m is the multiplicity parameter, which simulates ‘m’ paralleled devices. All MOS models support the ‘m’ multiplier parameter. Instance parameters l and w, channel length and width respectively, are expressed in meters. The areas of drain and source diffusions: ad and as, in squared meters (m2 ). If any of l, w, ad, or as are not specified, default values are used. The use of defaults simplifies input file preparation, as well as the editing required if device geometries are to be changed. pd and ps are the perimeters of the drain and source junctions, in meters. nrd and nrs designate the equivalent number of squares of the drain and source diffusions; these values multiply the 135 136 CHAPTER 11. MOSFETS sheet resistance rsh specified on the .model control line for an accurate representation of the parasitic series drain and source resistance of each transistor. pd and ps default to 0.0 while nrd and nrs to 1.0. off indicates an (optional) initial condition on the device for dc analysis. The (optional) initial condition specification using ic=vds,vgs,vbs is intended for use with the uic option on the .tran control line, when a transient analysis is desired starting from other than the quiescent operating point. See the .ic control line for a better and more convenient way to specify transient initial conditions. The (optional) temp value is the temperature at which this device is to operate, and overrides the temperature specification on the .option control line. The temperature specification is ONLY valid for level 1, 2, 3, and 6 MOSFETs, not for level 4 or 5 (BSIM) devices. BSIM3 (v3.2 and v3.3.0), BSIM4 (v4.7 and v4.8) and BSIMSOI models are also supporting the instance parameter delvto and mulu0 for local mismatch and NBTI (negative bias temperature instability) modeling: Name delvto (delvt0) mulu0 11.2 Parameter Threshold voltage shift Low-field mobility multiplier (U0) Units V - Default 0.0 1.0 Example 0.07 0.9 MOSFET models (NMOS/PMOS) MOSFET models are the central part of ngspice, probably because they are the most widely used devices in the electronics world. Ngspice provides all the MOSFETs implemented in the original Spice3f and adds several models developed by UC Berkeley’s Device Group and other independent groups. Each model is invoked with a .model card. A minimal version is: .model MOSN NMOS level=8 version=3.3.0 The model name MOSN corresponds to the model name in the instance card (see 11.1). Parameter NMOS selects an n-channel device, PMOS would point to a p-channel transistor. The level and version parameters select the specific model. Further model parameters are optional and replace ngspice default values. Due to the large number of parameters (more than 100 for modern models), model cards may be stored in extra files and loaded into the netlist by the .include (2.6) command. Model cards are specific for a an IC manufacturing process and are typically provided by the IC foundry. Some generic parameter sets, not linked to a specific process, are made available by the model developers, e.g. UC Berkeley’s Device Group for BSIM4 and BSIMSOI. Ngspice provides several MOSFET device models, which differ in the formulation of the I-V characteristic, and are of varying complexity. Models available are listed in table 11.1. Current models for IC design are BSIM3 (11.2.10, down to channel length of 0.25 µm), BSIM4 (11.2.11, below 0.25 µm), BSIMSOI (11.2.13, silicon-on-insulator devices), HiSIM2 and HiSIM_HV (11.2.15, surface potential models for standard and high voltage/high power MOS devices). 11.2.1 MOS Level 1 This model is also known as the ‘Shichman-Hodges’ model. This is the first model written and the one often described in the introductory textbooks for electronics. This model is applicable Level 1 2 3 4 5 6 9 8, 49 8, 49 8, 49 8, 49 10, 58 14, 54 14, 54 14, 54 14, 54 44 45 55 56 57 60 68 73 Name MOS1 MOS2 MOS3 BSIM1 BSIM2 MOS6 MOS9 BSIM3v0 BSIM3v1 BSIM3v32 BSIM3 B4SOI BSIM4v5 BSIM4v6 BSIM4v7 BSIM4 EKV PSP B3SOIFD B3SOIDD B3SOIPD STAG HiSIM2 HiSIM_HV Model Shichman-Hodges Grove-Frohman Table 11.1: MOSFET model summary SOI3 2.8.0 1.2.4/2.2.0 1.0.2 3.0 3.1 3.2 - 3.2.4 3.3.0 4.3.1 4.0 - 4.5 4.6.5 4.7.0 4.8.1 Version - Developer Berkeley Berkeley Berkeley Berkeley Berkeley Berkeley Alan Gillespie Berkeley Berkeley Berkeley Berkeley Berkeley Berkeley Berkeley Berkeley Berkeley EPFL Gildenblatt Berkeley Berkeley Berkeley Southampton Hiroshima Hiroshima References High Voltage Version for LDMOS adms configured adms configured Multi version code extensions by Alan Gillespie extensions by Serban Popescu Multi version code Described in [13] Notes This is the classical quadratic model. Described in [2] A semi-empirical model (see [1]) Described in [3] Described in [5] Described in [2] 11.2. MOSFET MODELS (NMOS/PMOS) 137 138 CHAPTER 11. MOSFETS only to long channel devices. The use of Meyer’s model for the C-V part makes it non charge conserving. 11.2.2 MOS Level 2 This model tries to overcome the limitations of the Level 1 model addressing several shortchannel effects, like velocity saturation. The implementation of this model is complicated and this leads to many convergence problems. C-V calculations can be done with the original Meyer model (non charge conserving). 11.2.3 MOS Level 3 This is a semi-empirical model derived from the Level 2 model. In the 80s this model has often been used for digital design and, over the years, has proved to be robust. A discontinuity in the model with respect to the KAPPA parameter has been detected (see [10]). The supplied fix has been implemented in Spice3f2 and later. Since this fix may affect parameter fitting, the option badmos3 may be set to use the old implementation (see the section on simulation variables and the .options line). Ngspice level 3 implementation takes into account length and width mask adjustments (xl and xw) and device width narrowing due to diffusion (wd). 11.2.4 MOS Level 6 This model is described in [2]. The model can express the current characteristics of shortchannel MOSFETs at least down to 0.25 µm channel-length, GaAs FET, and resistance inserted MOSFETs. The model evaluation time is about 1/3 of the evaluation time of the SPICE3 mos level 3 model. The model also enables analytical treatments of circuits in short-channel region and makes up for a missing link between a complicated MOSFET current characteristics and circuit behaviors in the deep submicron region. 11.2.5 Notes on Level 1-6 models The dc characteristics of the level 1 through level 3 MOSFETs are defined by the device parameters vto, kp, lambda, phi and gamma. These parameters are computed by ngspice if process parameters (nsub, tox, ...) are given, but users specified values always override. vto is positive (negative) for enhancement mode and negative (positive) for depletion mode N-channel (P-channel) devices. Charge storage is modeled by three constant capacitors, cgso, cgdo, and cgbo, which represent overlap capacitances, by the nonlinear thin-oxide capacitance that is distributed among the gate, source, drain, and bulk regions, and by the nonlinear depletion-layer capacitances for both substrate junctions divided into bottom and periphery, which vary as the mj and mjsw power of junction voltage respectively, and are determined by the parameters cbd, cbs, cj, cjsw, mj, mjsw and pb. Charge storage effects are modeled by the piecewise linear voltages-dependent capacitance model proposed by Meyer. The thin-oxide charge-storage effects are treated slightly different for 11.2. MOSFET MODELS (NMOS/PMOS) 139 the level 1 model. These voltage-dependent capacitances are included only if tox is specified in the input description and they are represented using Meyer’s formulation. There is some overlap among the parameters describing the junctions, e.g. the reverse current can be input either as is (in A) or as js (in A/m2 ). Whereas the first is an absolute value the second is multiplied by ad and as to give the reverse current of the drain and source junctions respectively. This methodology has been chosen since there is no sense in relating always junction characteristics with ad and as entered on the device line; the areas can be defaulted. The same idea applies also to the zero-bias junction capacitances cbd and cbs (in F) on one hand, and cj (in F/m2 ) on the other. The parasitic drain and source series resistance can be expressed as either rd and rs (in ohms) or rsh (in ohms/sq.), the latter being multiplied by the number of squares nrd and nrs input on the device line. NGSPICE level 1, 2, 3 and 6 parameters Name LEVEL VTO KP GAMMA PHI LAMBDA RD RS CBD CBS IS PB CGSO CGDO CGBO Parameter Model index Zero-bias threshold voltage (VT 0 ) Transconductance parameter Bulk threshold parameter Surface potential (U) Channel length modulation (MOS1 and MOS2 only) (λ ) Drain ohmic resistance Source ohmic resistance Zero-bias B-D junction capacitance Zero-bias B-S junction capacitance Bulk junction saturation current (IS ) Bulk junction potential Gate-source overlap capacitance per meter channel width Gate-drain overlap capacitance per meter channel width Gate-bulk overlap capacitance per meter channel width Units V Default 1 0.0 Example A/V 2 2.0e-5 3.1e-5 √ V V 1/V 0.0 0.6 0.0 0.37 0.65 0.02 Ω Ω F 0.0 0.0 0.0 1.0 1.0 20fF F 0.0 20fF A 1.0e-14 1.0e-15 V F/m 0.8 0.0 0.87 4.0e-11 F/m 0.0 4.0e-11 F/m 0.0 2.0e-11 1.0 140 CHAPTER 11. MOSFETS Name RSH CJ MJ CJSW MJSW JS TOX NSUB NSS NFS TPG XJ LD UO UCRIT UEXP UTRA VMAX NEFF KF AF FC DELTA THETA Parameter Drain and source diffusion sheet resistance Zero-bias bulk junction bottom cap. per sq-meter of junction area Bulk junction bottom grading coeff. Zero-bias bulk junction sidewall cap. per meter of junction perimeter Units Ω/ Default 0.0 Example 10 F/m2 0.0 2.0e-4 - 0.5 0.5 F/m 0.0 1.0e-9 Bulk junction sidewall grading coeff. Bulk junction saturation current Oxide thickness Substrate doping Surface state density Fast surface state density Type of gate material: +1 opp. to substrate, -1 same as substrate, 0 Al gate Metallurgical junction depth Lateral diffusion Surface mobility Critical field for mobility degradation (MOS2 only) Critical field exponent in mobility degradation (MOS2 only) Transverse field coeff. (mobility) (deleted for MOS2) Maximum drift velocity of carriers Total channel-charge (fixed and mobile) coefficient (MOS2 only) Flicker noise coefficient Flicker noise exponent Coefficient for forward-bias depletion capacitance formula Width effect on threshold voltage (MOS2 and MOS3) Mobility modulation (MOS3 only) - 0.50 (level1) 0.33 (level2, 3) m cm−3 cm−2 cm−2 - 1.0e-7 0.0 0.0 0.0 1.0 1.0e-7 4.0e15 1.0e10 1.0e10 m m cm2/V ·sec V/cm 0.0 0.0 600 1.0e4 1M 0.8M 700 1.0e4 - 0.0 0.1 - 0.0 0.3 m/s 0.0 5.0e4 - 1.0 5.0 - 0.0 1.0 0.5 1.0e-26 1.2 - 0.0 1.0 1/V 0.0 0.1 11.2. MOSFET MODELS (NMOS/PMOS) Name ETA KAPPA TNOM 11.2.6 141 Parameter Static feedback (MOS3 only) Saturation field factor (MOS3 only) Parameter measurement temperature Units - Default 0.0 Example 1.0 - 0.2 0.5 ◦C 27 50 MOS Level 9 Documentation is not available.. 11.2.7 BSIM Models Ngspice implements many of the BSIM models developed by Berkeley’s BSIM group. BSIM stands for Berkeley Short-Channel IGFET Model and groups a class of models that is continuously updated. BSIM3 (11.2.10) and BSIM4 (11.2.11) are industry standards for CMOS processes down to 0.15 µm (BSIM3) and below (BSIM4), are very stable and are supported by model parameter sets from foundries all over the world. BSIM1 and BSIM2 are obsolete today. In general, all parameters of BSIM models are obtained from process characterization, in particular level 4 and level 5 (BSIM1 and BSIM2) parameters can be generated automatically. J. Pierret [4] describes a means of generating a ‘process’ file, and the program ngproc2mod provided with ngspice converts this file into a sequence of BSIM1 .model lines suitable for inclusion in an ngspice input file. Parameters marked below with an * in the l/w column also have corresponding parameters with a length and width dependency. For example, vfb is the basic parameter with units of Volts, and lvfb and wvfb also exist and have units of Volt-meter. The formula P = P0 + PL Leffective + PW Weffective (11.1) is used to evaluate the parameter for the actual device specified with Leffective = Linput − DL (11.2) Weffective = Winput − DW (11.3) Note that unlike the other models in ngspice, the BSIM models are designed for use with a process characterization system that provides all the parameters, thus there are no defaults for the parameters, and leaving one out is considered an error. For an example set of parameters and the format of a process file, see the SPICE2 implementation notes [3]. For more information on BSIM2, see reference [5]. BSIM3 (11.2.10) and BSIM4 (11.2.11) represent state of the art for submicron and deep submicron IC design. 142 11.2.8 CHAPTER 11. MOSFETS BSIM1 model (level 4) BSIM1 model (the first is a long series) is an empirical model. Developers placed less emphasis on device physics and based the model on parametrical polynomial equations to model the various physical effects. This approach pays in terms of circuit simulation behavior but the accuracy degrades in the submicron region. A known problem of this model is the negative output conductance and the convergence problems, both related to poor behavior of the polynomial equations. Ngspice BSIM (level 4) parameters Name VFB PHI K1 K2 ETA MUZ DL DW U0 U1 X2MZ X2E X3E X2U0 X2U1 MUS X2MS X3MS X3U1 TOX TEMP VDD CGDO CGSO Parameter Flat-band voltage Surface inversion potential Body effect coefficient Drain/source depletion charge-sharing coefficient Zero-bias drain-induced barrier-lowering coefficient Zero-bias mobility Shortening of channel Narrowing of channel Zero-bias transverse-field mobility degradation coefficient Zero-bias velocity saturation coefficient Sens. of mobility to substrate bias at v=0 Sens. of drain-induced barrier lowering effect to substrate bias Sens. of drain-induced barrier lowering effect to drain bias at Vds = Vdd Sens. of transverse field mobility degradation effect to substrate bias Sens. of velocity saturation effect to substrate bias Mobility at zero substrate bias and at Vds = Vdd Sens. of mobility to substrate bias at Vds = Vdd Sens. of mobility to drain bias at Vds = Vdd Sens. of velocity saturation effect on drain bias at Vds=Vdd Gate oxide thickness Temperature where parameters were measured Measurement bias range Gate-drain overlap capacitance per meter channel width Gate-source overlap capacitance per meter channel width Units V √V V - l/w * * * * - * cm2/V ·sec µm µm 1/V µ/V * /V 2 ·sec 1/V * * * 1/V * 1/V 2 * µm/V 2 * cm2 cm2/V 2 sec cm2/V 2 sec cm2/V 2 sec µm/V 2 µm ◦C V F/m F/m * * * 11.2. MOSFET MODELS (NMOS/PMOS) Name CGBO XPART N0 NB ND RSH JS PB MJ PBSW MJSW CJ CJSW WDF DELL Parameter Gate-bulk overlap capacitance per meter channel length Gate-oxide capacitance-charge model flag Zero-bias subthreshold slope coefficient Sens. of subthreshold slope to substrate bias Sens. of subthreshold slope to drain bias Drain and source diffusion sheet resistance Source drain junction current density Built in potential of source drain junction Grading coefficient of source drain junction Built in potential of source, drain junction sidewall Grading coefficient of source drain junction sidewall Source drain junction capacitance per unit area source drain junction sidewall capacitance per unit length Source drain junction default width Source drain junction length reduction 143 Units F/m Ω/ A/m2 V V l/w * * * F/m2 F/m m m xpart = 0 selects a 40/60 drain/source charge partition in saturation, while xpart=1 selects a 0/100 drain/source charge partition. nd, ng, and ns are the drain, gate, and source nodes, respectively. mname is the model name, area is the area factor, and off indicates an (optional) initial condition on the device for dc analysis. If the area factor is omitted, a value of 1.0 is assumed. The (optional) initial condition specification, using ic=vds,vgs is intended for use with the uic option on the .tran control line, when a transient analysis is desired starting from other than the quiescent operating point. See the .ic control line for a better way to set initial conditions. 11.2.9 BSIM2 model (level 5) This model contains many improvements over BSIM1 and is suitable for analog simulation. Nevertheless, even BSIM2 breaks transistor operation into several distinct regions and this leads to discontinuities in the first derivative in C-V and I-V characteristics that can cause numerical problems during simulation. 11.2.10 BSIM3 model (levels 8, 49) BSIM3 solves the numerical problems of previous models with the introduction of smoothing functions. It adopts a single equation to describe device characteristics in the operating regions. This approach eliminates the discontinuities in the I-V and C-V characteristics. The original model, BSIM3 evolved through three versions: BSIM3v1, BSIM3v2 and BSIM3v3. Both BSIM3v1 and BSIM3v2 had suffered from many mathematical problems and were replaced by BSIM3v3. The latter is the only surviving release and has itself a long revision history. The following table summarizes the story of this model: 144 CHAPTER 11. MOSFETS Release BSIM3v3.0 BSIM3v3.1 BSIM3v3.2 Date 10/30/1995 12/09/1996 06/16/1998 BSIM3v3.3 07/29/2005 Notes Revisions available: BSIM3v3.2.2, BSIM3v3.2.3, and BSIM3v3.2.4 Parallel processing with OpenMP is available for BSIM3v3.2.4. Parallel processing with OpenMP is available for this model. Version flag 3.0 3.1 3.2, 3.2.2, 3.2.3, 3.2.4 3.3.0 BSIM3v2 and 3v3 models has proved for accurate use in 0.18 µm technologies. The model is publicly available as source code form from University of California, Berkeley. A detailed description is given in the user’s manual available from here . We recommend that you use only the most recent BSIM3 models (version 3.3.0), because it contains corrections to all known bugs. To achieve that, change the version parameter in your modelcard files to VERSION = 3.3.0. If no version number is given in the .model card, this (newest) version is selected as the default. BSIM3v3.2.4 supports the extra model parameter lmlt on channel length scaling and is still used by many foundries today. The older models will not be supported, they are made available for reference only. 11.2.11 BSIM4 model (levels 14, 54) This is the newest class of the BSIM family and introduces noise modeling and extrinsic parasitics. BSIM4, as the extension of BSIM3 model, addresses the MOSFET physical effects into sub-100nm regime. It is a physics-based, accurate, scalable, robust and predictive MOSFET SPICE model for circuit simulation and CMOS technology development. It is developed by the BSIM Research Group in the Department of Electrical Engineering and Computer Sciences (EECS) at the University of California, Berkeley (see BSIM4 home page). BSIM4 has a long revision history, which is summarized below. Release BSIM4.0.0 BSIM4.1.0 BSIM4.2.0 BSIM4.2.1 BSIM4.3.0 BSIM4.4.0 BSIM4.5.0 BSIM4.6.0 ... BSIM4.6.5 BSIM4.7.0 BSIM4.8.1 Date 03/24/2000 10/11/2000 04/06/2001 10/05/2001 05/09/2003 03/04/2004 07/29/2005 12/13/2006 Notes Version flag * * * * ** 4.2.1 4.3.0 4.4.0 4.5.0 09/09/2009 04/08/2011 15/02/2017 * ** * ** * ** 4.6.5 4.7 4.8 *) supported in ngspice, using e.g. the version= flag in the parameter file. 11.2. MOSFET MODELS (NMOS/PMOS) 145 **) Parallel processing using OpenMP support is available for this model. Details of any revision are to be found in the Berkeley user’s manuals, a pdf download of the most recent edition is to be found here. We recommend that you use only the most recent BSIM4 model (version 4.8.1), because it contains corrections to all known bugs. To achieve that, change the version parameter in your modelcard files to VERSION = 4.8. If no version number is given in the .model card, this (newest) version is selected as the default. The older models will typically not be supported, they are made available for reference only. 11.2.12 EKV model Level 44 model (EKV) is not available in the standard distribution since it is not released in source form by the EKV group. To obtain the code please refer to the (EKV model home page, EKV group home page). A verilog-A version is available contributed by Ivan Riis Nielsen 11/2006. 11.2.13 BSIMSOI models (levels 10, 58, 55, 56, 57) BSIMSOI is a SPICE compact model for SOI (Silicon-On-Insulator) circuit design, created by University of California at Berkeley. This model is formulated on top of the BSIM3 framework. It shares the same basic equations with the bulk model so that the physical nature and smoothness of BSIM3v3 are retained. Four models are supported in ngspice, those based on BSIM3 and modeling fully depleted (FD, level 55), partially depleted (PD, level 57) and both (DD, level 56), as well as the modern BSIMSOI version 4 model (levels 10, 58). Detailed descriptions are beyond the scope of this manual, but see e.g. BSIMSOIv4.4 User Manual for a very extensive description of the recent model version. OpenMP support is available for levels 10, 58, version 4.4. 11.2.14 SOI3 model (level 60) see literature citation [18] for a description. 11.2.15 HiSIM models of the University of Hiroshima There are two model implementations available - see also HiSIM Research Center: 1. HiSIM2 model: Surface-Potential-Based MOSFET Model for Circuit Simulation version 2.8.0 - level 68 (see link to HiSIM2 for source code and manual). 2. HiSIM_HV model: Surface-Potential-Based HV/LD-MOSFET Model for Circuit Simulation version 1.2.4 and 2.2.0 - level 73 (see link to HiSIM_HV for source code and manual). 146 CHAPTER 11. MOSFETS Chapter 12 Mixed-Mode and Behavioral Modeling with XSPICE Ngspice implements XSPICE extensions for behavioral and mixed-mode (analog and digital) modeling. In the XSPICE framework this is referred to as code level modeling. Behavioral modeling may benefit dramatically because XSPICE offers a means to add analog functionality programmed in C. Many examples (amplifiers, oscillators, filters ...) are presented in the following. Even more flexibility is available because you may define your own models and use them in addition and in combination with all the already existing ngspice functionality. Digital and mixed mode simulation is speeded up significantly by simulating the digital part in an event driven manner, in that state equations use only a few allowed states and are evaluated only during switching, and not continuously in time and signal as in a pure analog simulator. This chapter describes the predefined models available in ngspice, stemming from the original XSPICE simulator or being added to enhance the usability. The instructions for writing new code models are given in Chapt. 28. To make use of the XSPICE extensions, you need to compile them in. Linux, CYGWIN, MINGW and other users may add the flag --enable-xspice to their ./configure command and then recompile. The pre-built ngspice for Windows distribution has XSPICE already enabled. For detailed compiling instructions see Chapt. 32.1. 12.1 Code Model Element & .MODEL Cards 12.1.1 Syntax Ngspice includes a library of predefined ‘Code Models’ that can be placed within any circuit description in a manner similar to that used to place standard device models. Code model instance cards always begin with the letter ‘A’, and always make use of a .MODEL card to describe the code model desired. Section 28 of this document goes into greater detail as to how a code model similar to the predefined models may be developed, but once any model is created and linked into the simulator it may be placed using one instance card and one .MODEL card (note here we conform to the SPICE custom of referring to a single logical line of information as a ‘card’). As an example, the following uses a predefined ‘gain’ code model taking as an input some value on node 1, multiplies it by a gain of 5.0, and outputs the new value to node 2. 147 148 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Note that, by convention, input ports are specified first on code models. Output ports follow the inputs. Example: a1 1 2 amp . model amp gain(gain =5.0) In this example the numerical values picked up from single-ended (i.e. ground referenced) input node 1 and output to single-ended output node 2 will be voltages, since in the Interface Specification File for this code model (i.e., gain), the default port type is specified as a voltage (more on this later). However, if you didn’t know this, the following modifications to the instance card could be used to insure it: Example: a1 %v(1) %v(2) amp . model amp gain(gain =5.0) The specification %v preceding the input and output node numbers of the instance card indicate to the simulator that the inputs to the model should be single-ended voltage values. Other possibilities exist, as described later. Some of the other features of the instance and .MODEL cards are worth noting. Of particular interest is the portion of the .MODEL card that specifies gain=5.0. This portion of the card assigns a value to a parameter of the ‘gain’ model. There are other parameters that can be assigned values for this model, and in general code models will have several. In addition to numeric values, code model parameters can take non-numeric values (such as TRUE and FALSE), and even vector values. All of these topics will be discussed at length in the following pages. In general, however, the instance and .MODEL cards that define a code model will follow the abstract form described below. This form illustrates that the number of inputs and outputs and the number of parameters that can be specified is relatively open-ended and can be interpreted in a variety of ways (note that angle-brackets ‘<’ and ‘>’ enclose optional inputs): 12.1. CODE MODEL ELEMENT & .MODEL CARDS 149 Example: AXXXXXXX <%v ,%i ,%vd ,%id ,%g,%gd ,%h,%hd , or %d> + <[> <~><%v ,%i ,%vd ,%id ,%g,%gd ,%h,%hd , or %d> + + <~>...< NIN2 .. <]> > + <%v ,%i ,%vd ,%id ,%g,%gd ,%h,%hd ,%d or %vnam > + <[> <~><%v ,%i ,%vd ,%id ,%g,%gd ,%h,%hd , or %d>< NOUT1 or +NOUT1 -NOUT1 > + <~>...< NOUT2 .. <]>> + MODELNAME . MODEL MODELNAME MODELTYPE + <( PARAMNAME1 = <[> VAL1 > PARAMNAME2 ..>)> Square brackets ([ ]) are used to enclose vector input nodes. In addition, these brackets are used to delineate vectors of parameters. The literal string ‘null’, when included in a node list, is interpreted as no connection at that input to the model. ‘Null’ is not allowed as the name of a model’s input or output if the model only has one input or one output. Also, ‘null’ should only be used to indicate a missing connection for a code model; use on other XSPICE component is not interpreted as a missing connection, but will be interpreted as an actual node name. The tilde, ‘~’, when prepended to a digital node name, specifies that the logical value of that node be inverted prior to being passed to the code model. This allows for simple inversion of input and output polarities of a digital model in order to handle logically equivalent cases and others that frequently arise in digital system design. The following example defines a NAND gate, one input of which is inverted: a1 [~1 2] 3 nand1 . model nand1 d_nand ( rise_delay =0.1 fall_delay =0.2) The optional symbols %v, %i, %vd, etc. specify the type of port the simulator is to expect for the subsequent port or port vector. The meaning of each symbol is given in Table 12.1. The symbols described in Table 12.1 may be omitted if the default port type for the model is desired. Note that non-default port types for multi-input or multi-output (vector) ports must be specified by placing one of the symbols in front of EACH vector port. On the other hand, if all ports of a vector port are to be declared as having the same non-default type, then a symbol may be specified immediately prior to the opening bracket of the vector. The following examples should make this clear: Example 1: - Specifies two differential voltage connections, one to nodes 1 & 2, and one to nodes 3 & 4. 150 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Port Type Modifiers Modifier %v %i %g %h %d %vnam %vd %id %gd %hd Interpretation represents a single-ended voltage port - one node name or number is expected for each port. represents a single-ended current port - one node name or number is expected for each port. represents a single-ended voltage-input, current-output (VCCS) port - one node name or number is expected for each port. This type of port is automatically an input/output. represents a single-ended current-input, voltage-output (CCVS) port - one node name or number is expected for each port. This type of port is automatically an input/output. represents a digital port - one node name or number is expected for each port. This type of port may be either an input or an output. represents the name of a voltage source, the current through which is taken as an input. This notation is provided primarily in order to allow models defined using SPICE2G6 syntax to operate properly in XSPICE. represents a differential voltage port - two node names or numbers are expected for each port. represents a differential current port - two node names or numbers are expected for each port. represents a differential VCCS port - two node names or numbers are expected for each port. represents a differential CCVS port - two node names or numbers are expected for each port. Table 12.1: Port Type Modifiers 12.1. CODE MODEL ELEMENT & .MODEL CARDS 151 %vd [1 2 3 4] Example 2: - Specifies two single-ended connections to node 1 and at node 2, and one differential connection to nodes 3 & 4. %v [1 2 %vd 3 4] Example 3: - Identical to the previous example...parenthesis are added for additional clarity. %v [1 2 %vd(3 4)] Example 4: - Specifies that the node numbers are to be treated in the default fashion for the particular model. If this model had ‘%v” as a default for this port, then this notation would represent four single-ended voltage connections. [1 2 3 4] The parameter names listed on the .MODEL card must be identical to those named in the code model itself. The parameters for each predefined code model are described in detail in Sections 12.2 (analog), 12.3 (Hybrid, A/D) and 12.4 (digital) . The steps required in order to specify parameters for user-defined models are described in Chapter 28. 12.1.2 Examples The following is a list of instance card and associated .MODEL card examples showing use of predefined models within an XSPICE deck: a1 1 2 amp .model amp gain(in_offset=0.1 gain=5.0 out_offset=-0.01) a2 %i[1 2] 3 sum1 .model sum1 summer(in_offset=[0.1 -0.2] in_gain=[2.0 1.0] + out_gain=5.0 out_offset=-0.01) a21 %i[1 %vd(2 5) 7 10] 3 sum2 .model sum2 summer(out_gain=10.0) a5 1 2 limit5 .model limit5 limit(in_offset=0.1 gain=2.5 + out_lower.limit=-5.0 out_upper_limit=5.0 limit_domain=0.10 + fraction=FALSE) a7 2 %id(4 7) xfer.cntl1 .model xfer_cntl1 pwl(x_array=[-2.0 -1.0 2.0 4.0 5.0] + y_array=[-0.2 -0.2 0.1 2.0 10.0] + input_domain=0.05 fraction=TRUE) a8 3 %gd(6 7) switch3 .model switch3 aswitch(cntl_off=0.0 cntl_on=5.0 r_off=1e6 + r_on=10.0 log=TRUE) 152 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE 12.1.3 Search path for file input Several code models (filesource 12.2.8, d_source 12.4.21, d_state 12.4.18) call additional files for supply of input data. A call to file="path/filename" (or input_file=, state_file=) in the .model card will start a search sequence for finding the file. path may be an absolute path. If path is omitted or is a relative path, filename is looked for according to the following search list: Infile_Path/ (Infile_Path is the path of the input file *.sp containing the netlist) NGSPICE_INPUT_DIR/ (where an additional path is set by the environmental variable) (where the search is relative to the current directory (OS dependent)) 12.2 Analog Models The following analog models are supplied with XSPICE. The descriptions included consist of the model Interface Specification File and a description of the model’s operation. This is followed by an example of a simulator-deck placement of the model, including the .MODEL card and the specification of all available parameters. 12.2.1 Gain NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: cm_gain gain "A simple gain block" PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector.Bounds: Null.Allowed: in "input" in v [v,vd,i,id,vnam] no no PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: in_offset "input offset" real 0.0 no out "output" out v [v,vd,i,id] no no gain "gain" real 1.0 no out_offset "output offset" real 0.0 no 12.2. ANALOG MODELS Vector_Bounds: Null_Allowed: 153 yes yes yes Description: This function is a simple gain block with optional offsets on the input and the output. The input offset is added to the input, the sum is then multiplied by the gain, and the result is produced by adding the output offset. This model will operate in DC, AC, and Transient analysis modes. Example: a1 1 2 amp . model amp gain( in_offset =0.1 gain =5.0 + out_offset = -0.01) 12.2.2 Summer NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: cm_summer summer "A summer block" PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: in "input vector" in v [v,vd,i,id,vnam] yes no PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: in_offset "input offset vector" real 0.0 yes in yes in_gain "input gain vector" real 1.0 yes in yes PARAMETER_TABLE: Parameter_Name: Description: Data_Type: out_gain "output gain" real out_offset "output offset" real out "output" out v [v,vd,i,id] no no 154 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 1.0 no yes 0.0 no yes Description: This function is a summer block with 2-to-N input ports. Individual gains and offsets can be applied to each input and to the output. Each input is added to its respective offset and then multiplied by its gain. The results are then summed, multiplied by the output gain and added to the output offset. This model will operate in DC, AC, and Transient analysis modes. Example usage: a2 [1 2] 3 sum1 .model sum1 summer ( in_offset =[0.1 -0.2] in_gain =[2.0 1.0] + out_gain =5.0 out_offset = -0.01) 12.2.3 Multiplier NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: cm_mult mult "multiplier block" in "input vector" in v [v,vd,i,id,vnam] yes [2 -] no out "output" out v [v,vd,i,id] no no in_offset "input offset vector" real 0.0 yes in yes in_gain "input gain vector" real 1.0 yes in yes out_gain "output gain" out_offset "output offset" 12.2. ANALOG MODELS Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 155 real 1.0 no yes real 0.0 no yes Description: This function is a multiplier block with 2-to-N input ports. Individual gains and offsets can be applied to each input and to the output. Each input is added to its respective offset and then multiplied by its gain. The results are multiplied along with the output gain and are added to the output offset. This model will operate in DC, AC, and Transient analysis modes. However, in ac analysis it is important to remember that results are invalid unless only one input of the multiplier is connected to a node that i connected to an AC signal (this is exemplified by the use of a multiplier to perform a potentiometer function: one input is DC, the other carries the AC signal). Example SPICE Usage: a3 [1 2 3] 4 sigmult . model sigmult mult( in_offset =[0.1 0.1 -0.1] + in_gain =[10.0 10.0 10.0] out_gain =5.0 out_offset =0.05) 12.2.4 Divider NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: cm_divide divide "divider block" num "numerator" in v [v,vd,i,id,vnam] no no den "denominator" in v [v,vd,i,id,vnam] no no num_offset "numerator offset" real 0.0 no yes num_gain "numerator gain" real 1.0 no yes out "output" out v [v,vd,i,id] no no 156 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: den_offset "denominator offset" real 0.0 no yes den_gain "denominator gain" real 1.0 no yes den_lower_limit "denominator lower limit" real 1.0e-10 no yes den_domain "denominator smoothing domain" real 1.0e-10 no yes fraction "smoothing fraction/absolute value switch" boolean false no yes out_gain "output gain" real 1.0 no yes out_offset "output offset" real 0.0 no yes Description: This function is a two-quadrant divider. It takes two inputs; num (numerator) and den (denominator). Divide offsets its inputs, multiplies them by their respective gains, 12.2. ANALOG MODELS 157 divides the results, multiplies the quotient by the output gain, and offsets the result. The denominator is limited to a value above zero via a user specified lower limit. This limit is approached through a quadratic smoothing function, the domain of which may be specified as a fraction of the lower limit value (default), or as an absolute value. This model will operate in DC, AC and Transient analysis modes. However, in ac analysis it is important to remember that results are invalid unless only one input of the divider is connected to a node that is connected to an ac signal (this is exemplified by the use of the divider to perform a potentiometer function: one input is dc, the other carries the ac signal). Example SPICE Usage: a4 1 2 4 divider .model divider divide(num_offset=0.1 num_gain=2.5 den_offset=-0.1 + den_gain=5.0 den_lower.limit=1e-5 den_domain=1e-6 + fraction=FALSE out_gain=1.0 out_offset=0.0) 12.2.5 Limiter NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: cm_limit limit "limit block" in "input" in v [v,vd,i,id] no no out "output" out v [v,vd,i,id] no no in_offset "input offset" real 0.0 no yes gain "gain" real 1.0 no yes out_lower_limit "output lower limit" real 0.0 no yes out_upper_limit "output upper limit" real 1.0 no yes 158 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: limit_range "upper & lower smoothing range" real 1.0e-6 no yes fraction "smoothing fraction/absolute value switch" boolean FALSE no yes Description: The Limiter is a single input, single output function similar to the Gain Block. However, the output of the Limiter function is restricted to the range specified by the output lower and upper limits. This model will operate in DC, AC and Transient analysis modes. Note that the limit range is the value below the upper limit and above the lower limit at which smoothing of the output begins. For this model, then, the limit range represents the delta with respect to the output level at which smoothing occurs. Thus, for an input gain of 2.0 and output limits of 1.0 and -1.0 volts, the output will begin to smooth out at ±0.9 volts, which occurs when the input value is at ±0.4. Example SPICE Usage: a5 1 2 limit5 .model limit5 limit(in_offset=0.1 gain=2.5 out_lower_limit=-5.0 + out_upper_limit=5.0 limit_range=0.10 fraction=FALSE) 12.2.6 Controlled Limiter NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: cm_climit climit "controlled limiter block" in "input" in v [v,vd,i,id,vnam] no no cntl_upper "upper lim. control input" in v [v,vd,i,id,vnam] no no 12.2. ANALOG MODELS PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 159 cntl_lower "lower limit control input" in v [v,vd,i,id,vnam] no no out "output" out v [v,vd,i,id] no no in_offset "input offset" real 0.0 no yes gain "gain" real 1.0 no yes upper_delta "output upper delta" real 0.0 no yes lower_delta "output lower delta" real 0.0 no yes limit_range "upper & lower sm. range" real 1.0e-6 no yes fraction "smoothing %/abs switch" boolean FALSE no yes Description: The Controlled Limiter is a single input, single output function similar to the Gain Block. However, the output of the Limiter function is restricted to the range specified by the output lower and upper limits. This model will operate in DC, AC, and Transient analysis modes. Note that the limit range is the value below the cntl_upper limit and above the cntl_lower limit at which smoothing of the output begins (minimum positive value of voltage must exist between the cntl_upper input and the cntl_lower input at all times). For this model, then, the limit range represents the delta with respect to the output level at which smoothing occurs. Thus, for an input gain of 2.0 and output limits of 1.0 and -1.0 volts, the output will begin to smooth out at ±0.9 volts, which occurs when the input value is at ±0.4. Note also that the Controlled Limiter code tests the input values of cntl_upper and cntl_lower to make sure that they are spaced far enough 160 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE apart to guarantee the existence of a linear range between them. The range is calculated as the difference between (cntl_upper − upper_delta − limit_range) and (cntl_lower + lower_delta + limit_range) and must be greater than or equal to zero. Note that when the limit range is specified as a fractional value, the limit range used in the above is taken as the calculated fraction of the difference between cntl_upper and cntl_lower. Still, the potential exists for too great a limit range value to be specified for proper operation, in which case the model will return an error message. Example SPICE Usage: a6 3 6 8 4 varlimit . . .model varlimit climit(in_offset=0.1 gain=2.5 upper_delta=0.0 + lower_delta=0.0 limit_range=0.10 fraction=FALSE) 12.2.7 PWL Controlled Source NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: cm_pwl pwl "piecewise linear controlled source" in "input" in v [v,vd,i,id,vnam] no no out "output" out v [v,vd,i,id] no no x_array "x-element array" real yes [2 -] no y_array "y-element array" real yes [2 -] no input_domain "input sm. domain" real 0.01 [1e-12 0.5] no yes fraction "smoothing %/abs switch" boolean TRUE no yes 12.2. ANALOG MODELS STATIC_VAR_TABLE: Static_Var_Name: Data_Type: Description: 161 last_x_value pointer "iteration holding variable for limiting" Description: The Piece-Wise Linear Controlled Source is a single input, single output function similar to the Gain Block. However, the output of the PWL Source is not necessarily linear for all values of input. Instead, it follows an I/O relationship specified by you via the x_array and y_array coordinates. This is detailed below. The x_array and y_array values represent vectors of coordinate points on the x and y axes, respectively. The x_array values are progressively increasing input coordinate points, and the associated y_array values represent the outputs at those points. There may be as few as two (x_array[n], y_array[n]) pairs specified, or as many as memory and simulation speed allow. This permits you to very finely approximate a non-linear function by capturing multiple input-output coordinate points. Two aspects of the PWL Controlled Source warrant special attention. These are the handling of endpoints and the smoothing of the described transfer function near coordinate points. In order to fully specify outputs for values of in outside of the bounds of the PWL function (i.e., less than x_array[0] or greater than x_array[n], where n is the largest user-specified coordinate index), the PWL Controlled Source model extends the slope found between the lowest two coordinate pairs and the highest two coordinate pairs. This has the effect of making the transfer function completely linear for in less than x_array[0] and in greater than x_array[n]. It also has the potentially subtle effect of unrealistically causing an output to reach a very large or small value for large inputs. You should thus keep in mind that the PWL Source does not inherently provide a limiting capability. In order to diminish the potential for non-convergence of simulations when using the PWL block, a form of smoothing around the x_array, y_array coordinate points is necessary. This is due to the iterative nature of the simulator and its reliance on smooth first derivatives of transfer functions in order to arrive at a matrix solution. Consequently, the input_domain and fraction parameters are included to allow you some control over the amount and nature of the smoothing performed. Fraction is a switch that is either TRUE or FALSE. When TRUE (the default setting), the simulator assumes that the specified input domain value is to be interpreted as a fractional figure. Otherwise, it is interpreted as an absolute value. Thus, if fraction=TRUE and input_domain=0.10, The simulator assumes that the smoothing radius about each coordinate point is to be set equal to 10% of the length of either the x_array segment above each coordinate point, or the x_array segment below each coordinate point. The specific segment length chosen will be the smallest of these two for each coordinate point. On the other hand, if fraction=FALSE and input=0.10, then the simulator will begin smoothing the transfer function at 0.10 volts (or amperes) below each x_array coordinate and will continue the smoothing process for another 0.10 volts (or amperes) above each x_array coordinate point. Since the overlap of smoothing domains is not allowed, checking is done by the model to ensure that the specified input domain value is not excessive. One subtle consequence of the use of the fraction=TRUE feature of the PWL Controlled Source is that, in certain cases, you may inadvertently create extreme smoothing 162 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE of functions by choosing inappropriate coordinate value points. This can be demonstrated by considering a function described by three coordinate pairs, such as (-1,-1), (1,1), and (2,1). In this case, with a 10% input_domain value specified (fraction=TRUE, input_domain=0.10), you would expect to see rounding occur between in=0.9 and in=1.1, and nowhere else. On the other hand, if you were to specify the same function using the coordinate pairs (-100,-100), (1,1) and (201,1), you would find that rounding occurs between in=-19 and in=21. Clearly in the latter case the smoothing might cause an excessive divergence from the intended linearity above and below in=1. Example SPICE Usage: a7 2 4 xfer_cntl1 . . .model xfer_cntl1 pwl(x_array=[-2.0 -1.0 2.0 4.0 5.0] + y_array=[-0.2 -0.2 0.1 2.0 10.0] + input_domain=0.05 fraction=TRUE) 12.2.8 Filesource NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: cm_filesource filesource "File Source" out "output" out v [v,vd,i,id] yes [1 -] no timeoffset "time offset" real 0.0 no yes timescale "timescale" real 1.0 no yes timerelative "relative time" boolean FALSE no amplstep "step amplitude" boolean FALSE no 12.2. ANALOG MODELS Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 163 yes yes amploffset "ampl offset" real yes [1 -] yes amplscale "amplscale" real yes [1 -] yes file "file name" string "filesource.txt" no yes Description: The File Source is similar to the Piece-Wise Linear Source, except that the waveform data is read from a file instead of being taken from parameter vectors. The file format is line oriented ASCII. ‘#’ and ‘;’ are comment characters; all characters from a comment character until the end of the line are ignored. Each line consists of two or more real values. The first value is the time; subsequent values correspond to the outputs. Values are separated by spaces. Time values are absolute and must be monotonically increasing, unless timerelative is set to TRUE, in which case the values specify the interval between two samples and must be positive. Waveforms may be scaled and shifted in the time dimension by setting timescale and timeoffset. Amplitudes can also be scaled and shifted using amplscale and amploffset. Amplitudes are normally interpolated between two samples, unless amplstep is set to TRUE. Note: The file named by the parameter filename in file="filename" is sought after according to a search list described in12.1.3. Example SPICE Usage: a8 %vd([1 0 2 0]) filesrc . . .model filesrc filesource (file="sine.m" amploffset=[0 0] amplscale=[1 1] + timeoffset=0 timescale=1 + timerelative=false amplstep=false) Example input file: # name: sine.m 164 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE # two output ports # column 1: time # columns 2, 3: values 0 0 1 3.90625e-09 0.02454122852291229 0.9996988186962042 7.8125e-09 0.04906767432741801 0.9987954562051724 1.171875e-08 0.07356456359966743 0.9972904566786902 ... 12.2.9 multi_input_pwl block NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: cm_multi_input_pwl multi_input_pwl "multi_input_pwl block" in "input array" in vd [vd,id] yes [2 -] no out "output" out vd [vd,id] no no x "x array" real 0.0 yes [2 -] no y "y array" real 0.0 yes [2 -] no model "model type" string "and" no yes Description: Multi-input gate voltage controlled voltage source that supports and or or gating. The x’s and y’s represent the piecewise linear variation of output (y) as a function of input (x). The type of gate is selectable by the parameter model. In case the model is and, the smallest input determines the output value (i.e. the and function). In case the model is or, 12.2. ANALOG MODELS 165 the largest input determines the output value (i.e. the or function). The inverse of these functions (i.e. nand and nor) is constructed by complementing the y array. Example SPICE Usage: a82 [1 0 2 0 3 0] 7 0 pwlm . . .model pwlm multi_input_pwl((x=[-2.0 -1.0 2.0 4.0 5.0] + y=[-0.2 -0.2 0.1 2.0 10.0] + model="and") 12.2.10 Analog Switch NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: cm_aswitch aswitch "analog switch" cntl_in "input" in v [v,vd,i,id] no no out "resistive output" out gd [gd] no no cntl_off cntl_on "control ‘off’ value" "control ‘on’ value" real real 0.0 1.0 no no yes yes r_off "off resistance" real 1.0e12 no yes r_on "on resistance" real log "log/linear switch" boolean TRUE no yes 166 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 1.0 no yes Description: The Analog Switch is a resistor that varies either logarithmically or linearly between specified values of a controlling input voltage or current. Note that the input is not internally limited. Therefore, if the controlling signal exceeds the specified OFF state or ON state value, the resistance may become excessively large or excessively small (in the case of logarithmic dependence), or may become negative (in the case of linear dependence). For the experienced user, these excursions may prove valuable for modeling certain devices, but in most cases you are advised to add limiting of the controlling input if the possibility of excessive control value variation exists. Example SPICE Usage: a8 3 %gd(6 7) switch3 . . .model switch3 aswitch(cntl_off=0.0 cntl_on=5.0 r_off=1e6 + r_on=10.0 log=TRUE) 12.2.11 Zener Diode NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: cm_zener zener "zener diode" z "zener" inout gd [gd] no no v_breakdown "breakdown voltage" real [1.0e-6 1.0e6] no no i_breakdown "breakdown current" real 2.0e-2 [1.0e-9 -] no yes i_sat n_forward 12.2. ANALOG MODELS Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: STATIC_VAR_TABLE: Static_Var_Name: Data_Type: Description: 167 "saturation current" real 1.0e-12 [1.0e-15 -] no yes "forward emission coefficient" real 1.0 [0.1 10] no yes limit_switch "switch for on-board limiting (convergence aid)" boolean FALSE no yes previous_voltage pointer "iteration holding variable for limiting" Description: The Zener Diode models the DC characteristics of most zeners. This model differs from the Diode/Rectifier by providing a user-defined dynamic resistance in the reverse breakdown region. The forward characteristic is defined by only a single point, since most data sheets for zener diodes do not give detailed characteristics in the forward region. The first three parameters define the DC characteristics of the zener in the breakdown region and are usually explicitly given on the data sheet. The saturation current refers to the relatively constant reverse current that is produced when the voltage across the zener is negative, but breakdown has not been reached. The reverse leakage current determines the slight increase in reverse current as the voltage across the zener becomes more negative. It is modeled as a resistance parallel to the zener with value v breakdown / i rev. Note that the limit switch parameter engages an internal limiting function for the zener. This can, in some cases, prevent the simulator from converging to an unrealistic solution if the voltage across or current into the device is excessive. If use of this feature fails to yield acceptable results, the convlimit option should be tried (add the following statement to the SPICE input deck: .options convlimit) Example SPICE Usage: a9 3 4 vref10 . . .model vref10 zener(v_breakdown=10.0 i_breakdown=0.02 + r_breakdown=1.0 i_rev=1e-6 i_sat=1e-12) 12.2.12 Current Limiter NAME_TABLE: 168 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: cm_ilimit ilimit "current limiter block" in "input" in v [v,vd] no no pos_pwr "positive power supply" inout g [g,gd] no yes neg_pwr "negative power supply" inout g [g,gd] no yes out "output" inout g [g,gd] no no in_offset "input offset" real 0.0 no yes gain "gain" real 1.0 no yes r_out_source "sourcing resistance" real 1.0 [1.0e-9 1.0e9] no yes r_out_sink "sinking resistance" real 1.0 [1.0e-9 1.0e9] no yes i_limit_source "current sourcing limit" real [1.0e-12 -] no yes 12.2. ANALOG MODELS PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 169 i_limit_sink "current sinking limit" real [1.0e-12 -] no yes v_pwr_range "upper & lower power supply smoothing range" real 1.0e-6 [1.0e-15 -] no yes i_source_range "sourcing current smoothing range" real 1.0e-9 [1.0e-15 -] no yes i_sink_range "sinking current smoothing range" real 1.0e-9 [1.0e-15 -] no yes r_out_domain "internal/external voltage delta smoothing range" real 1.0e-9 [1.0e-15 -] no yes Description: The Current Limiter models the behavior of an operational amplifier or comparator device at a high level of abstraction. All of its pins act as inputs; three of the four also act as outputs. The model takes as input a voltage value from the in connector. It then applies an offset and a gain, and derives from it an equivalent internal voltage (veq), which it limits to fall between pos_pwr and neg_pwr. If veq is greater than the output voltage seen on the out connector, a sourcing current will flow from the output pin. Conversely, if the voltage is less than vout, a sinking current will flow into the output pin. Depending on the polarity of the current flow, either a sourcing or a sinking resistance value (r_out_source, r_out_sink) is applied to govern the vout/i_out relationship. The chosen resistance will continue to control the output current until it reaches a maximum value specified by either i_limit_source or i_limit_sink. The latter mimics 170 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE the current limiting behavior of many operational amplifier output stages. During all operation, the output current is reflected either in the pos_pwr connector current or the neg_pwr current, depending on the polarity of i_out. Thus, realistic power consumption as seen in the supply rails is included in the model. The user-specified smoothing parameters relate to model operation as follows: v_pwr_range controls the voltage below vpos_pwr and above vneg_pwr inputs beyond which veq = gain(vin+vo f f set ) is smoothed; i_source_range specifies the current below i_limit_source at which smoothing begins, as well as specifying the current increment above i_out=0.0 at which i_pos_pwr begins to transition to zero; i_sink_range serves the same purpose with respect to i_limit_sink and i_neg_pwr that i_source_range serves for i_limit_source and i_pos_pwr; r_out_domain specifies the incremental value above and below (veq-vout)=0.0 at which r_out will be set to r_out_source and r_out_sink, respectively. For values of (veq-vout) less than r_out_domain and greater than -r_out_domain, r_out is interpolated smoothly between r_out_source and r_out_sink. Example SPICE Usage: a10 3 10 20 4 amp3 . . .model amp3 ilimit(in_offset=0.0 gain=16.0 r_out_source=1.0 + r_out_sink=1.0 i_limit_source=1e-3 + i_limit_sink=10e-3 v_pwr_range=0.2 + i_source_range=1e-6 i_sink_range=1e-6 + r_out_domain=1e-6) 12.2.13 Hysteresis Block NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: cm_hyst hyst "hysteresis block" in "input" in v [v,vd,i,id] no no out "output" out v [v,vd,i,id] no no in_low "input low value" real 0.0 no - in_high "input high value" real 1.0 no - 12.2. ANALOG MODELS Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 171 yes yes hyst "hysteresis" real 0.1 [0.0 -] no yes out_lower_limit "output lower limit" real 0.0 no yes out_upper_limit "output upper limit" real 1.0 no yes input_domain "input smoothing domain" real 0.01 no yes fraction "smoothing fraction/absolute value switch" boolean TRUE no yes Description: The Hysteresis block is a simple buffer stage that provides hysteresis of the output with respect to the input. The in low and in high parameter values specify the center voltage or current inputs about which the hysteresis effect operates. The output values are limited to out lower limit and out upper limit. The value of hyst is added to the in low and in high points in order to specify the points at which the slope of the hysteresis function would normally change abruptly as the input transitions from a low to a high value. Likewise, the value of hyst is subtracted from the in high and in low values in order to specify the points at which the slope of the hysteresis function would normally change abruptly as the input transitions from a high to a low value. In fact, the slope of the hysteresis function is never allowed to change abruptly but is smoothly varied whenever the input domain smoothing parameter is set greater than zero. Example SPICE Usage: a11 1 2 schmitt1 . . .model schmitt1 hyst(in_low=0.7 in_high=2.4 hyst=0.5 + out_lower_limit=0.5 out_upper_limit=3.0 + input_domain=0.01 fraction=TRUE) 172 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE 12.2.14 Differentiator NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: cm_d_dt d_dt "time-derivative block" in "input" in v [v,vd,i,id] no no out "output" out v [v,vd,i,id] no no gain "gain" real 1.0 no yes out_offset "output offset" real 0.0 no yes out_lower_limit "output lower limit" real no yes out_upper_limit "output upper limit" real no yes limit_range "upper & lower limit smoothing range" real 1.0e-6 no yes Description: The Differentiator block is a simple derivative stage that approximates the time derivative of an input signal by calculating the incremental slope of that signal since the previous time point. The block also includes gain and output offset parameters to allow for tailoring of the required signal, and output upper and lower limits to prevent convergence errors resulting from excessively large output values. The incremental value of output below the output upper limit and above the output lower limit at which smoothing 12.2. ANALOG MODELS 173 begins is specified via the limit range parameter. In AC analysis, the value returned is equal to the radian frequency of analysis multiplied by the gain. Note that since truncation error checking is not included in the d_dt block, it is not recommended that the model be used to provide an integration function through the use of a feedback loop. Such an arrangement could produce erroneous results. Instead, you should make use of the "integrate" model, which does include truncation error checking for enhanced accuracy. Example SPICE Usage: a12 7 12 slope_gen . . .model slope_gen d_dt(out_offset=0.0 gain=1.0 + out_lower_limit=1e-12 out_upper_limit=1e12 + limit_range=1e-9) 12.2.15 Integrator NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: cm_int int "time-integration block" in "input" in v [v,vd,i,id] no no out "output" out v [v,vd,i,id] no no in_offset "input offset" real 0.0 no yes gain "gain" real 1.0 no yes out_lower_limit "output lower limit" real no - out_upper_limit "output upper limit" real no - 174 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: yes yes limit_range "upper & lower limit smoothing range" real 1.0e-6 no yes out_ic "output initial condition" real 0.0 no yes Description: The Integrator block is a simple integration stage that approximates the integral with respect to time of an input signal. The block also includes gain and input offset parameters to allow for tailoring of the required signal, and output upper and lower limits to prevent convergence errors resulting from excessively large output values. Note that these limits specify integrator behavior similar to that found in an operational amplifierbased integration stage, in that once a limit is reached, additional storage does not occur. Thus, the input of a negative value to an integrator that is currently driving at the out upper limit level will immediately cause a drop in the output, regardless of how long the integrator was previously summing positive inputs. The incremental value of output below the output upper limit and above the output lower limit at which smoothing begins is specified via the limit range parameter. In AC analysis, the value returned is equal to the gain divided by the radian frequency of analysis. Note that truncation error checking is included in the int block. This should provide for a more accurate simulation of the time integration function, since the model will inherently request smaller time increments between simulation points if truncation errors would otherwise be excessive. Example SPICE Usage: a13 7 12 time_count . . .model time_count int(in_offset=0.0 gain=1.0 + out_lower_limit=-1e12 out_upper_limit=1e12 + limit_range=1e-9 out_ic=0.0) 12.2.16 S-Domain Transfer Function NAME_TABLE: 12.2. ANALOG MODELS C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 175 cm_s_xfer s_xfer "s-domain transfer function" in "input" in v [v,vd,i,id] no no out "output" out v [v,vd,i,id] no no in_offset "input offset" real 0.0 no yes gain "gain" real 1.0 no yes num_coeff "numerator polynomial coefficients" real yes [1 -] no den_coeff "denominator polynomial coefficients" real yes [1 -] no int_ic "integrator stage initial conditions" real 0.0 yes den_coeff yes 176 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: denormalized_freq "denorm. corner freq.(radians) for 1 rad/s coeffs" real 1.0 no yes Description: The s-domain transfer function is a single input, single output transfer function in the Laplace transform variable ‘s’ that allows for flexible modulation of the frequency domain characteristics of a signal. Ac and transient simulations are supported. The code model may be configured to produce an arbitrary s-domain transfer function with the following restrictions: 1. The degree of the numerator polynomial cannot exceed that of the denominator polynomial in the variable "s". 2. The coefficients for a polynomial must be stated explicitly. That is, if a coefficient is zero, it must be included as an input to the num coeff or den coeff vector. The order of the coefficient parameters is from that associated with the highest-powered term decreasing to that of the lowest. Thus, for the coefficient parameters specified below, the equation in ‘s’ is shown: .model filter s_xfer(gain=0.139713 + num_coeff=[1.0 0.0 0.7464102] + den_coeff=[1.0 0.998942 0.001170077] + int_ic=[0 0]) ...specifies a transfer function of the form... 2 s +0.7464102 N(s) = 0.139713 · s2 +0.998942s+0.00117077 The s-domain transfer function includes gain and in_offset (input offset) parameters to allow for tailoring of the required signal. There are no limits on the internal signal values or on the output value of the s-domain transfer function, so you are cautioned to specify gain and coefficient values that will not cause the model to produce excessively large values. In AC analysis, the value returned is equal to the real and imaginary components of the total s-domain transfer function at each frequency of interest. The denormalized_freq term allows you to specify coefficients for a normalized filter (i.e. one in which the frequency of interest is 1 rad/s). Once these coefficients are included, specifying the denormalized frequency value ‘shifts’ the corner frequency to the actual one of interest. As an example, the following transfer function describes a Chebyshev low-pass filter with a corner (pass-band) frequency of 1 rad/s: 1.0 N(s) = 0.139713 · s2 +1.09773s+1.10251 12.2. ANALOG MODELS 177 In order to define an s_xfer model for the above, but with the corner frequency equal to 1500 rad/s (9425 Hz), the following instance and model lines would be needed: a12 node1 node2 cheby1 .model cheby1 s_xfer(num_coeff=[1] den_coeff=[1 1.09773 1.10251] + int_ic=[0 0] denormalized_freq=1500) In the above, you add the normalized coefficients and scale the filter through the use of the denormalized freq parameter. Similar results could have been achieved by performing the denormalization prior to specification of the coefficients, and setting denormalized freq to the value 1.0 (or not specifying the frequency, as the default is 1.0 rad/s) Note in the above that frequencies are always specified as radians/second. Truncation error checking is included in the s-domain transfer block. This should provide for more accurate simulations, since the model will inherently request smaller time increments between simulation points if truncation errors would otherwise be excessive. The int_ic parameter is an array that must be of size one less as the array of values specified for the den_coeff parameter. Even if a 0 start value is required, you have to add the specific int_ic vector to the set of coefficients (see the examples above and below). Example SPICE Usage: a14 9 22 cheby_LP_3kHz . . .model cheby_LP_3kHz s_xfer(in_offset=0.0 gain=1.0 int_ic=[0 0] + num_coeff=[1.0] + den_coeff=[1.0 1.42562 1.51620]) 12.2.17 Slew Rate Block NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: cm_slew slew "A simple slew rate follower block" in "input" in v [v,vd,i,id] no no out "output" out v [v,vd,i,id] no no rise_slope "maximum rising slope value" real 1.0e9 178 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: no yes fall_slope "maximum falling slope value" real 1.0e9 no yes range "smoothing range" real 0.1 no yes Description: This function is a simple slew rate block that limits the absolute slope of the output with respect to time to some maximum or value. The actual slew rate effects of over-driving an amplifier circuit can thus be accurately modeled by cascading the amplifier with this model. The units used to describe the maximum rising and falling slope values are expressed in volts or amperes per second. Thus a desired slew rate of 0.5 V/µs will be expressed as 0.5e+6, etc. The slew rate block will continue to raise or lower its output until the difference between the input and the output values is zero. Thereafter, it will resume following the input signal, unless the slope again exceeds its rise or fall slope limits. The range input specifies a smoothing region above or below the input value. Whenever the model is slewing and the output comes to within the input + or - the range value, the partial derivative of the output with respect to the input will begin to smoothly transition from 0.0 to 1.0. When the model is no longer slewing (output = input), dout/din will equal 1.0. Example SPICE Usage: a15 1 2 slew1 .model slew1 slew(rise_slope=0.5e6 fall_slope=0.5e6) 12.2.18 Inductive Coupling NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: cm_lcouple lcouple "inductive coupling (for use with ’core’ model)" 12.2. ANALOG MODELS Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 179 l "inductor" inout hd [h,hd] no no mmf_out "mmf output (in ampere-turns)" inout hd [hd] no no num_turns "number of inductor turns" real 1.0 no yes Description: This function is a conceptual model that is used as a building block to create a wide variety of inductive and magnetic circuit models. This function is normally used in conjunction with the core model, but can also be used with resistors, hysteresis blocks, etc. to build up systems that mock the behavior of linear and nonlinear components. The lcouple takes as an input (on the ‘l’ port), a current. This current value is multiplied by the num_turns value, N, to produce an output value (a voltage value that appears on the mmf_out port). The mmf_out acts similar to a magnetomotive force in a magnetic circuit; when the lcouple is connected to the core model, or to some other resistive device, a current will flow. This current value (which is modulated by whatever the lcouple is connected to) is then used by the lcouple to calculate a voltage ‘seen’ at the l port. The voltage is a function of the derivative with respect to time of the current value seen at mmf_out. The most common use for lcouples will be as a building block in the construction of transformer models. To create a transformer with a single input and a single output, you would require two lcouple models plus one core model. The process of building up such a transformer is described under the description of the core model, below. Example SPICE Usage: a150 (7 0) (9 10) lcouple1 .model lcouple1 lcouple(num_turns=10.0) 12.2.19 Magnetic Core NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: cm_core core "magnetic core" mc "magnetic core" 180 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Direction: Default_Type: Allowed_Types: Vector: no Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: inout gd [g,gd] no H_array "magnetic field array" real yes [2 -] no B_array "flux density array" real yes [2 -] no area "cross-sectional area" real no no length "core length" real no no input_domain "input sm. domain" real 0.01 [1e-12 0.5] no yes fraction "smoothing fraction/abs switch" boolean TRUE no yes mode "mode switch (1 = pwl, 2 = hyst)" int 1 [1 2] 12.2. ANALOG MODELS Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 181 no yes in_low "input low value" real 0.0 no yes in_high "input high value" real 1.0 no yes hyst "hysteresis" real 0.1 [0 -] no yes out_lower_limit "output lower limit" real 0.0 no yes out_upper_limit "output upper limit" real 1.0 no yes Description: This function is a conceptual model that is used as a building block to create a wide variety of inductive and magnetic circuit models. This function is almost always expected to be used in conjunction with the lcouple model to build up systems that mock the behavior of linear and nonlinear magnetic components. There are two fundamental modes of operation for the core model. These are the pwl mode (which is the default, and which is the most likely to be of use to you) and the hysteresis mode. These are detailed below. PWL Mode (mode = 1) The core model in PWL mode takes as input a voltage that it treats as a magnetomotive force (mmf) value. This value is divided by the total effective length of the core to produce a value for the Magnetic Field Intensity, H. This value of H is then used to find the corresponding Flux Density, B, using the piecewise linear relationship described by you in the H array / B array coordinate pairs. B is then multiplied by the cross-sectional area of the core to find the Flux value, which is output as a current. The pertinent mathematical equations are listed below: 182 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE H = mmf =L, where L = Length Here H, the Magnetic Field Intensity, is expressed in ampere-turns/meter. B = f (H) The B value is derived from a piecewise linear transfer function described to the model via the (H_array[],B_array[]) parameter coordinate pairs. This transfer function does not include hysteretic effects; for that, you would need to substitute a HYST model for the core. φ = BA, where A = Area The final current allowed to flow through the core is equal to φ . This value in turn is used by the "lcouple" code model to obtain a value for the voltage reflected back across its terminals to the driving electrical circuit. The following example code shows the use of two lcouple models and one core model to produce a simple primary/secondary transformer. Example SPICE Usage: a1 (2 0) (3 0) primary .model primary lcouple (num_turns = 155) a2 (3 4) iron_core .model iron_core core (H_array = [-1000 -500 -375 -250 -188 -125 -63 0 + 63 125 188 250 375 500 1000] + B_array = [-3.13e-3 -2.63e-3 -2.33e-3 -1.93e-3 + -1.5e-3 -6.25e-4 -2.5e-4 0 2.5e-4 + 6.25e-4 1.5e-3 1.93e-3 2.33e-3 + 2.63e-3 3.13e-3] + area = 0.01 length = 0.01) a3 (5 0) (4 0) secondary .model secondary lcouple (num_turns = 310) HYSTERESIS Mode (mode = 2) The core model in HYSTERESIS mode takes as input a voltage that it treats as a magnetomotive force (mmf) value. This value is used as input to the equivalent of a hysteresis code model block. The parameters defining the input low and high values, the output low and high values, and the amount of hysteresis are as in that model. The output from this mode, as in PWL mode, is a current value that is seen across the mc port. An example of the core model used in this fashion is shown below: Example SPICE Usage: a1 (2 0) (3 0) primary .model primary lcouple (num_turns = 155) a2 (3 4) iron_core .model iron_core core (mode = 2 in_low=-7.0 in_high=7.0 + out_lower_limit=-2.5e-4 out_upper_limit=2.5e-4 + hyst = 2.3 ) a3 (5 0) (4 0) secondary .model secondary lcouple (num_turns = 310) 12.2. ANALOG MODELS 183 One final note to be made about the two core model nodes is that certain parameters are available in one mode, but not in the other. In particular, the in_low, in_high, out_lower_limit, out_upper_limit, and hysteresis parameters are not available in PWL mode. Likewise, the H_array, B_array, area, and length values are unavailable in HYSTERESIS mode. The input domain and fraction parameters are common to both modes (though their behavior is somewhat different; for explanation of the input domain and fraction values for the HYSTERESIS mode, you should refer to the hysteresis code model discussion). 12.2.20 Controlled Sine Wave Oscillator NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: cm_sine sine "controlled sine wave oscillator" cntl_in "control input" in v [v,vd,i,id] no no out "output" out v [v,vd,i,id] no no cntl_array "control array" real 0.0 yes [2 -] no freq_array "frequency array" real 1.0e3 [0 -] yes cntl_array no out_low out_high "output peak low value" "output peak high value" real real -1.0 1.0 no no yes yes Description: This function is a controlled sine wave oscillator with parametrizable values of low and high peak output. It takes an input voltage or current value. This value is used as the independent variable in the piecewise linear curve described by the coordinate points of the cntl array and freq array pairs. From the curve, a frequency value is determined, and the oscillator will output a sine wave at that frequency. From the above, it is easy to see that array sizes of 2 for both the cntl array and the freq array will yield a linear 184 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE variation of the frequency with respect to the control input. Any sizes greater than 2 will yield a piecewise linear transfer characteristic. For more detail, refer to the description of the piecewise linear controlled source, which uses a similar method to derive an output value given a control input. Example SPICE Usage: asine 1 2 in_sine .model in_sine sine(cntl_array = [-1 0 5 6] + freq_array=[10 10 1000 1000] out_low = -5.0 + out_high = 5.0) 12.2.21 Controlled Triangle Wave Oscillator NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: cm_triangle triangle "controlled triangle wave oscillator" cntl_in "control input" in v [v,vd,i,id] no no out "output" out v [v,vd,i,id] no no cntl_array "control array" real 0.0 yes [2 -] no freq_array "frequency array" real 1.0e3 [0 -] yes cntl_array no out_low out_high "output peak low value" "output peak high value" real real -1.0 1.0 no no yes yes duty_cycle "rise time duty cycle" real 12.2. ANALOG MODELS Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 185 0.5 [1e-10 0.999999999] no yes Description: This function is a controlled triangle/ramp wave oscillator with parametrizable values of low and high peak output and rise time duty cycle. It takes an input voltage or current value. This value is used as the independent variable in the piecewise linear curve described by the coordinate points of the cntl_array and freq_array pairs. From the curve, a frequency value is determined, and the oscillator will output a triangle wave at that frequency. From the above, it is easy to see that array sizes of 2 for both the cntl_array and the freq_array will yield a linear variation of the frequency with respect to the control input. Any sizes greater than 2 will yield a piecewise linear transfer characteristic. For more detail, refer to the description of the piecewise linear controlled source, which uses a similar method to derive an output value given a control input. Example SPICE Usage: ain 1 2 ramp1 .model ramp1 triangle(cntl_array = [-1 0 5 6] + freq_array=[10 10 1000 1000] out_low = -5.0 + out_high = 5.0 duty_cycle = 0.9) 12.2.22 Controlled Square Wave Oscillator NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: cm_square square "controlled square wave oscillator" cntl_in "control input" in v [v,vd,i,id] no no out "output" out v [v,vd,i,id] no no cntl_array "control array" real 0.0 yes [2 -] no freq_array "frequency array" real 1.0e3 [0 -] yes cntl_array no 186 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER.TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: no Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: out_low out_high "output peak low value" "output peak high value" real real -1.0 1.0 no no yes yes duty_cycle "duty cycle" real 0.5 [1e-6 0.999999] rise_time "output rise time" real 1.0e-9 - yes yes fall_time "output fall time" real 1.0e-9 no yes Description: This function is a controlled square wave oscillator with parametrizable values of low and high peak output, duty cycle, rise time, and fall time. It takes an input voltage or current value. This value is used as the independent variable in the piecewise linear curve described by the coordinate points of the cntl_array and freq_array pairs. From the curve, a frequency value is determined, and the oscillator will output a square wave at that frequency. From the above, it is easy to see that array sizes of 2 for both the cntl_array and the freq_array will yield a linear variation of the frequency with respect to the control input. Any sizes greater than 2 will yield a piecewise linear transfer characteristic. For more detail, refer to the description of the piecewise linear controlled source, which uses a similar method to derive an output value given a control input. Example SPICE Usage: ain 1 2 pulse1 .model pulse1 square(cntl_array = [-1 0 5 6] + freq_array=[10 10 1000 1000] out_low = 0.0 + out_high = 4.5 duty_cycle = 0.2 + rise_time = 1e-6 fall_time = 2e-6) 12.2.23 Controlled One-Shot NAME_TABLE: 12.2. ANALOG MODELS C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 187 cm_oneshot oneshot "controlled one-shot" clk "clock input" in v [v,vd,i,id] no no cntl_in "control input" in v [v,vd,i,id] no yes clear "clear signal" in v [v,vd,i,id] no yes out "output" out v [v,vd,i,id] no no clk_trig "clock trigger value" real 0.5 no no retrig "retrigger switch" boolean FALSE no yes pos_edge_trig "positive/negative edge trigger switch" boolean TRUE no no cntl_array "control array" real 0.0 yes yes pw_array "pulse width array" real 1.0e-6 [0.00 -] yes cntl_array yes 188 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: out_low "output low value" real 0.0 no yes out_high "output high value" real 1.0 no yes fall_time "output fall time" real 1.0e-9 no yes rise_time "output rise time" real 1.0e-9 no yes rise_delay "output delay from trigger" real 1.0e-9 no yes fall_delay "output delay from pw" real 1.0e-9 no yes Description: This function is a controlled oneshot with parametrizable values of low and high peak output, input trigger value level, delay, and output rise and fall times. It takes an input voltage or current value. This value is used as the independent variable in the piecewise linear curve described by the coordinate points of the cntl_array and pw_array pairs. From the curve, a pulse width value is determined. The one-shot will output a pulse of that width, triggered by the clock signal (rising or falling edge), delayed by the delay value, and with specified rise and fall times. A positive slope on the clear input will immediately terminate the pulse, which resets with its fall time. From the above, it is easy to see that array sizes of 2 for both the cntl_array and the pw_array will yield a linear variation of the pulse width with respect to the control input. Any sizes greater than 2 will yield a piecewise linear transfer characteristic. For more 12.2. ANALOG MODELS 189 detail, refer to the description of the piecewise linear controlled source, which uses a similar method to derive an output value given a control input. Example SPICE Usage: ain 1 2 3 4 pulse2 .model pulse2 oneshot(cntl_array = [-1 0 10 11] + pw_array=[1e-6 1e-6 1e-4 1e-4] + clk_trig = 0.9 pos_edge_trig = FALSE + out_low = 0.0 out_high = 4.5 + rise_delay = 20.0-9 fall_delay = 35.0e-9) 12.2.24 Capacitance Meter NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: cm_cmeter cmeter "capacitance meter" in "input" in v [v,vd,i,id] no no out "output" out v [v,vd,i,id] no no gain "gain" real 1.0 no yes Description: The capacitance meter is a sensing device that is attached to a circuit node and produces as an output a scaled value equal to the total capacitance seen on its input multiplied by the gain parameter. This model is primarily intended as a building block for other models that must sense a capacitance value and alter their behavior based upon it. Example SPICE Usage: atest1 1 2 ctest .model ctest cmeter(gain=1.0e12) 12.2.25 Inductance Meter NAME_TABLE: 190 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: cm_lmeter lmeter "inductance meter" in "input" in v [v,vd,i,id] no no out "output" out v [v,vd,i,id] no no gain "gain" real 1.0 no yes Description: The inductance meter is a sensing device that is attached to a circuit node and produces as an output a scaled value equal to the total inductance seen on its input multiplied by the gain parameter. This model is primarily intended as a building block for other models that must sense an inductance value and alter their behavior based upon it. Example SPICE Usage: atest2 1 2 ltest .model ltest lmeter(gain=1.0e6) 12.2.26 Memristor NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: cm_memristor memristor "Memristor Interface" memris "memristor terminals" inout gd [gd] no no rmin rmax 12.2. ANALOG MODELS Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 191 "minimum resistance" real 10.0 no no "maximum resistance" real 10000.0 no no rinit "initial resistance" real 7000.0 no no vt "threshold" real 0.0 no no alpha "model parameter 1" real 0.0 no no beta "model parameter 2" real 1.0 no no Description: The memristor is a two-terminal resistor with memory, whose resistance depends on the time integral of the voltage across its terminals. rmin and rmax provide the lower and upper limits of the resistance, rinit is its starting value (no voltage applied so far). The voltage has to be above a threshold vt to become effective in changing the resistance. alpha and beta are two model parameters. The memristor code model is derived from a SPICE subcircuit published in [23]. Example SPICE Usage: amen 1 2 memr .model memr memristor (rmin=1k rmax=10k rinit=7k + alpha=0 beta=2e13 vt=1.6) 12.2.27 2D table model NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: Direction: cm_table2D table2D "2D table model" inx "inputx" in iny "inputy" in out "output" out 192 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: v [v,vd,i,id,vnam] no no v [v,vd,i,id,vnam] no no order "order" int 3 no yes verbose "verbose" int 0 no yes offset "offset" real 0.0 no yes gain "gain" real 1.0 no yes i [v,vd,i,id] no no file "file name" string "2D-table-model.txt" no yes Description: The 2D table model reads a matrix from file "file name" (default 2D-tablemodel.txt) which has x columns and y rows. Each x,y pair, addressed by inx and iny, yields an output value out. Linear interpolation is used for out, eno (essentially non oscillating) interpolation for its derivatives. Parameters offset (default 0) and gain (default 1) modify the output table values according to o f f set + gain out. Parameter order (default 3) influences the calculation of the derivatives. Parameter verbose (default 0) yields test outputs, if set to 1 or 2. The table format is shown below. Be careful to include the data point inx = 0, iny = 0 into your table, because ngspice uses these during .OP computations. The x horizontal and y vertical address values have to increase monotonically. The usage example consists of two input voltages referenced to ground and a current source output with two floating nodes. Table Example: * table source * number of columns (x) 12.2. ANALOG MODELS 193 8 * number of rows (y) 9 * x horizontal (column) address values (real numbers) -1 0 1 2 3 4 5 6 * y vertical (row) address values (real numbers) -0.6 0 0.6 1.2 1.8 2.4 3.0 3.6 4.2 * table with output data (horizontally addressed by x, vertically by y) 1 0.9 0.8 0.7 0.6 0.5 0.4 0.3 1 1 1 1 1 1 1 1 1 1.2 1.4 1.6 1.8 2 2.2 2.4 1 1.5 2 2.5 3 3.5 4 4.5 1 2 3 4 5 6 7 8 1 2.5 4 5.5 7 8.5 10 11.5 1 3 5 7 9 11 13 15 1 3.5 6 8.5 11 13.5 16 18.5 1 4 7 10 13 16 19 22 Example SPICE Usage: atab inx iny %id(out1 out2) tabmod .model tabmod table2d (offset=0.0 gain=1 order=3 file="table-simple.txt") 12.2.28 3D table model NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: cm_table3D table3D "3D table model" inx "inputx" in v [v,vd,i,id,vnam] no no iny "inputy" in v [v,vd,i,id,vnam] no no out "output" out i [v,vd,i,id] no no order "order" verbose "verbose" inz "inputz" in v [v,vd,i,id,vnam] no no 194 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: int 3 no yes offset "offset" real 0.0 no yes int 0 no yes gain "gain" real 1.0 no yes file "file name" string "3D-table-model.txt" no yes Description: The 3D table model reads a matrix from file "file name" (default 3D-tablemodel.txt) which has x columns, y rows per table and z tables. Each x,y,z triple, addressed by inx, iny, and inz, yields an output value out. Linear interpolation is used for out, eno (essentially non oscillating) interpolation for its derivatives. Parameters offset (default 0) and gain (default 1) modify the output table values according to o f f set + gain out. Parameter order (default 3) influences the calculation of the derivatives. Parameter verbose (default 0) yields test outputs, if set to 1 or 2. The table format is shown below. Be careful to include the data point inx = 0, iny = 0, inz = 0 into your table, because ngspice needs these to for the .OP calculation. The x horizontal, y vertical, and z table address values have to increase monotonically. The usage example simulates a NMOS transistor with independent drain, gate and bulk nodes, referenced to source. Parameter gain may be used to emulate transistor width, with respect to the table transistor. Table Example: * 3D table for nmos bsim 4, W=10um, L=0.13um *x 39 *y 39 *z 11 *x (drain voltage) 12.3. HYBRID MODELS 195 -0.1 -0.05 0 0.05 0.1 0.15 0.2 0.25 ... *y (gate voltage) -0.1 -0.05 0 0.05 0.1 0.15 0.2 0.25 ... *z (substrate voltage) -1.8 -1.6 -1.4 -1.2 -1 -0.8 -0.6 -0.4 -0.2 0 0.2 *table -1.8 -4.50688E-10 -4.50613E-10 -4.50601E-10 -4.50599E-10 ... -4.49622E-10 -4.49267E-10 -4.4921E-10 -4.49202E-10 ... -4.50672E-10 -4.49099E-10 -4.48838E-10 -4.48795E-10 ... -4.55575E-10 -4.4953E-10 -4.48435E-10 -4.48217E-10 ... ... *table -1.6 -3.10015E-10 -3.09767E-10 -3.0973E-10 -3.09724E-10 ... -3.09748E-10 -3.08524E-10 -3.08339E-10 -3.08312E-10 ... ... *table -1.4 -2.04848E-10 -2.04008E-10 -2.03882E-10 ... -2.07275E-10 -2.03117E-10 -2.02491E-10 ... ... Example SPICE Usage: amos1 %vd(d s) %vd(g s) %vd(b s) %id(d s) mostable1 .model mostable1 table3d (offset=0.0 gain=0.5 order=3 + verbose=1 file="table-3D-bsim4n.txt") 12.3 Hybrid Models The following hybrid models are supplied with XSPICE. The descriptions included below consist of the model Interface Specification File and a description of the model’s operation. This is followed by an example of a simulator-deck placement of the model, including the .MODEL card and the specification of all available parameters. A note should be made with respect to the use of hybrid models for other than simple digital-toanalog and analog-to-digital translations. The hybrid models represented in this section address that specific need, but in the development of user-defined nodes you may find a need to translate not only between digital and analog nodes, but also between real and digital, real and int, etc. In most cases such translations will not need to be as involved or as detailed as shown in the following. 12.3.1 Digital-to-Analog Node Bridge NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: cm_dac_bridge dac_bridge "digital-to-analog node bridge" in "input" out "output" 196 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: in d [d] yes no out v [v,vd,i,id,d] yes no out_low "0-valued analog output" real 0.0 no yes out_high "1-valued analog output" real 1.0 no yes out_undef "U-valued analog output" real 0.5 no yes input_load "input load (F)" real 1.0e-12 no yes t_rise "rise time 0->1" real 1.0e-9 no yes t_fall "fall time 1->0" real 1.0e-9 no yes Description: The dac_bridge is the first of two node bridge devices designed to allow for the ready transfer of digital information to analog values and back again. The second device is the adc_bridge (which takes an analog value and maps it to a digital one).The dac_bridge takes as input a digital value from a digital node. This value by definition may take on only one of the values ‘0’, ‘1’ or ‘U’. The dac_bridge then outputs the value 12.3. HYBRID MODELS 197 out_low, out_high or out_undef, or ramps linearly toward one of these ‘final’ values from its current analog output level. The speed at which this ramping occurs depends on the values of t_rise and t_fall. These parameters are interpreted by the model such that the rise or fall slope generated is always constant. Note that the dac_bridge includes test code in its cfunc.mod file for determining the presence of the out_undef parameter. If this parameter is not specified by you, and if out_high and out_low values are specified, then out_undef is assigned the value of the arithmetic mean of out_high and out_low. This simplifies coding of output buffers, where typically a logic family will include an out_low and out_high voltage, but not an out_undef value. This model also posts an input load value (in farads) based on the parameter input load. Example SPICE Usage: abridge1 [7] [2] dac1 .model dac1 dac_bridge(out_low = 0.7 out_high = 3.5 out_undef = 2.2 + input_load = 5.0e-12 t_rise = 50e-9 + t_fall = 20e-9) 12.3.2 Analog-to-Digital Node Bridge NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: cm_adc_bridge adc_bridge "analog-to-digital node bridge" in "input" in v [v,vd,i,id,d] yes no out "output" out d [d] yes no in_low "maximum 0-valued analog input" real 1.0 no yes in_high "minimum 1-valued analog input" real 2.0 no 198 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: yes rise_delay "rise delay" real 1.0e-9 [1.0e-12 -] no yes fall_delay "fall delay" real 1.0e-9 [1.0e-12 -] no yes Description: The adc_bridge is one of two node bridge devices designed to allow for the ready transfer of analog information to digital values and back again. The second device is the dac_bridge (which takes a digital value and maps it to an analog one). The adc_bridge takes as input an analog value from an analog node. This value by definition may be in the form of a voltage, or a current. If the input value is less than or equal to in_low, then a digital output value of ‘0’ is generated. If the input is greater than or equal to in_high, a digital output value of ‘1’ is generated. If neither of these is true, then a digital ‘UNKNOWN’ value is output. Note that unlike the case of the dac_bridge, no ramping time or delay is associated with the adc_bridge. Rather, the continuous ramping of the input value provides for any associated delays in the digitized signal. Example SPICE Usage: abridge2 [1] [8] adc_buff .model adc_buff adc_bridge(in_low = 0.3 in_high = 3.5) 12.3.3 Controlled Digital Oscillator NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: cm_d_osc d_osc "controlled digital oscillator" cntl_in "control input" in v [v,vd,i,id] no no out "output" out d [d] no no cntl_array "control array" real 0.0 - freq_array "frequency array" real 1.0e6 [0 -] 12.3. HYBRID MODELS Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 199 yes [2 -] no yes cntl_array no duty_cycle "duty cycle" real 0.5 [1e-6 0.999999] no yes init_phase "initial phase of output" real 0 [-180.0 +360.0] no yes rise_delay "rise delay" real 1e-9 [0 -] no yes fall_delay "fall delay" real 1e-9 [0 -] no yes Description: The digital oscillator is a hybrid model that accepts as input a voltage or current. This input is compared to the voltage-to-frequency transfer characteristic specified by the cntl_array/freq_array coordinate pairs, and a frequency is obtained that represents a linear interpolation or extrapolation based on those pairs. A digital time-varying signal is then produced with this fundamental frequency. The output waveform, which is the equivalent of a digital clock signal, has rise and fall delays that can be specified independently. In addition, the duty cycle and the phase of the waveform are also variable and can be set by you. Example SPICE Usage: a5 1 8 var_clock .model var_clock d_osc(cntl_array + freq_array + duty_cycle + rise_delay 12.3.4 = = = = [-2 -1 1 2] [1e3 1e3 10e3 10e3] 0.4 init_phase = 180.0 10e-9 fall_delay=8e-9) Node bridge from digital to real with enable NAME_TABLE: Spice_Model_Name: d_to_real C_Function_Name: ucm_d_to_real Description: "Node bridge from digital to real with enable" PORT_TABLE: Port_Name: in enable out Description: "input" "enable" "output" Direction: in in out 200 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Default_Type: d d Allowed_Types: [d] [d] Vector: no no Vector_Bounds: Null_Allowed: no yes PARAMETER_TABLE: Parameter_Name: zero Description: "value for 0" Data_Type: real Default_Value: 0.0 Limits: Vector: no Vector_Bounds: Null_Allowed: yes 12.3.5 real [real] no no one "value for 1" real 1.0 no yes delay "delay" real 1e-9 [1e-15 -] no yes A Z**-1 block working on real data NAME_TABLE: Spice_Model_Name: real_delay C_Function_Name: ucm_real_delay Description: "A Z ** -1 block working on real data" PORT_TABLE: Port_Name: in clk out Description: "input" "clock" "output" Direction: in in out Default_Type: real d real Allowed_Types: [real] [d] [real] Vector: no no no Vector_Bounds: Null_Allowed: no no no PARAMETER_TABLE: Parameter_Name: delay Description: "delay from clk to out" Data_Type: real Default_Value: 1e-9 Limits: [1e-15 -] Vector: no Vector_Bounds: Null_Allowed: yes 12.3.6 A gain block for event-driven real data NAME_TABLE: Spice_Model_Name: C_Function_Name: Description: PORT_TABLE: Port_Name: real_gain ucm_real_gain "A gain block for event-driven real data" in out 12.3. HYBRID MODELS Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 12.3.7 201 "input" in real [real] no no "output" out real [real] no no in_offset "input offset" real 0.0 no yes gain "gain" real 1.0 no yes delay "delay" real 1.0e-9 no yes ic "initial condition" real 0.0 no yes out_offset "output offset" real 0.0 no yes Node bridge from real to analog voltage NAME_TABLE: Spice_Model_Name: C_Function_Name: Description: PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: real_to_v ucm_real_to_v "Node bridge from real to analog voltage" in "input" in real [real] no no out "output" out v [v, vd, i, id] no no gain "gain" real 1.0 no transition_time "output transition time" real 1e-9 [1e-15 -] no 202 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Vector_Bounds: Null_Allowed: 12.4 yes yes Digital Models The following digital models are supplied with XSPICE. The descriptions included below consist of an example model Interface Specification File and a description of the model’s operation. This is followed by an example of a simulator-deck placement of the model, including the .MODEL card and the specification of all available parameters. Note that these models have not been finalized at this time. Some information common to all digital models and/or digital nodes is included here. The following are general rules that should make working with digital nodes and models more straightforward: 1. All digital nodes are initialized to ZERO at the start of a simulation (i.e., when INIT=TRUE). This means that a model need not post an explicit value to an output node upon initialization if its output would normally be a ZERO (although posting such would certainly cause no harm). 2. Digital nodes may have one out of twelve possible node values. See 12.5.1 for details. 3. Digital models typically have defined their rise and fall delays for their output signals. A capacitive input load value may be defined as well to determine a load-dependent delay, but is currently not used in any code model (see 28.7.1.4). 4. Several commands are available for outputting data, e.g. eprint, edisplay, and eprvcd. Digital inputs may be read from files. Please see Chapt. 12.5.4 for more details. 5. Hybrid models (see Chapt. 12.3) provide an interface between the digital event driven world and the analog world of ngspice to enable true mixed mode simulation. 12.4.1 Buffer NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: cm_d_buffer d_buffer "digital one-bit-wide buffer" in "input" in d [d] no no out "output" out d [d] no no 12.4. DIGITAL MODELS Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 203 rise_delay "rise delay" real 1.0e-9 [1.0e-12 -] no yes fall_delay "fall delay" real 1.0e-9 [1.0e-12 -] no yes input_load "input load value (F)" real 1.0e-12 no yes Description: The buffer is a single-input, single-output digital buffer that produces as output a time-delayed copy of its input. The delays associated with an output rise and those associated with an output fall may be different. The model also posts an input load value (in farads) based on the parameter input load. The output of this model does not, however, respond to the total loading it sees on its output; it will always drive the output strongly with the specified delays. Example SPICE Usage: a6 1 8 buff1 .model buff1 d_buffer(rise_delay = 0.5e-9 fall_delay = 0.3e-9 + input_load = 0.5e-12) 12.4.2 Inverter NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: cm_d_inverter d_inverter "digital one-bit-wide inverter" in "input" in d [d] no no out "output" out d [d] no no rise_delay "rise delay" fall_delay "fall delay" 204 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: real 1.0e-9 [1.0e-12 -] no yes real 1.0e-9 [1.0e-12 -] no yes input_load "input load value (F)" real 1.0e-12 no yes Description: The inverter is a single-input, single-output digital inverter that produces as output an inverted, time-delayed copy of its input. The delays associated with an output rise and those associated with an output fall may be specified independently. The model also posts an input load value (in farads) based on the parameter input load. The output of this model does not, however, respond to the total loading it sees on its output; it will always drive the output strongly with the specified delays. Example SPICE Usage: a6 1 8 inv1 .model inv1 d_inverter(rise_delay = 0.5e-9 fall_delay = 0.3e-9 + input_load = 0.5e-12) 12.4.3 And NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: cm_d_and d_and "digital ‘and’ gate" in "input" in d [d] yes [2 -] no out "output" out d [d] no no rise_delay "rise delay" real 1.0e-9 fall_delay "fall delay" real 1.0e-9 12.4. DIGITAL MODELS Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 205 [1.0e-12 -] no yes [1.0e-12 -] no yes input_load "input load value (F)" real 1.0e-12 no yes Description: The digital and gate is an n-input, single-output and gate that produces an active ‘1’ value if, and only if, all of its inputs are also ‘1’ values. If ANY of the inputs is a ‘0’, the output will also be a ‘0’; if neither of these conditions holds, the output will be unknown. The delays associated with an output rise and those associated with an output fall may be specified independently. The model also posts an input load value (in farads) based on the parameter input load. The output of this model does not, however, respond to the total loading it sees on its output; it will always drive the output strongly with the specified delays. Example SPICE Usage: a6 [1 2] 8 and1 .model and1 d_and(rise_delay = 0.5e-9 fall_delay = 0.3e-9 + input_load = 0.5e-12) 12.4.4 Nand NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: cm_d_nand d_nand "digital ‘nand’ gate" in "input" in d [d] yes [2 -] no out "output" out d [d] no no rise_delay "rise delay" real 1.0e-9 fall_delay "fall delay" real 1.0e-9 206 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: [1.0e-12 -] no yes [1.0e-12 -] no yes input_load "input load value (F)" real 1.0e-12 no yes Description: The digital nand gate is an n-input, single-output nand gate that produces an active ‘0’ value if and only if all of its inputs are ‘1’ values. If ANY of the inputs is a ‘0’, the output will be a ‘1’; if neither of these conditions holds, the output will be unknown. The delays associated with an output rise and those associated with an output fall may be specified independently. The model also posts an input load value (in farads) based on the parameter input load. The output of this model does not, however, respond to the total loading it sees on its output; it will always drive the output strongly with the specified delays. Example SPICE Usage: a6 [1 2 3] 8 nand1 .model nand1 d_nand(rise_delay = 0.5e-9 fall_delay = 0.3e-9 + input_load = 0.5e-12) 12.4.5 Or NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: cm_d_or d_or "digital ‘or’ gate" in "input" in d [d] yes [2 -] no out "output" out d [d] no no rise_delay "rise delay" real 1.0e-9 fall_delay "fall delay" real 1.0e-9 12.4. DIGITAL MODELS Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 207 [1.0e-12 -] no yes [1.0e-12 -] no yes input_load "input load value (F)" real 1.0e-12 no yes Description: The digital or gate is an n-input, single-output or gate that produces an active ‘1’ value if at least one of its inputs is a ‘1’ value. The gate produces a ‘0’ value if all inputs are ‘0’; if neither of these two conditions holds, the output is unknown. The delays associated with an output rise and those associated with an output fall may be specified independently. The model also posts an input load value (in farads) based on the parameter input load. The output of this model does not, however, respond to the total loading it sees on its output; it will always drive the output strongly with the specified delays. Example SPICE Usage: a6 [1 2 3] 8 or1 .model or1 d_or(rise_delay = 0.5e-9 fall_delay = 0.3e-9 + input_load = 0.5e-12) 12.4.6 Nor NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: cm_d_nor d_nor "digital ‘nor’ gate" in "input" in d [d] yes [2 -] no out "output" out d [d] no no rise_delay "rise delay" real 1.0e-9 fall_delay "fall delay" real 1.0e-9 208 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: [1.0e-12 -] no yes [1.0e-12 -] no yes input_load "input load value (F)" real 1.0e-12 no yes Description: The digital nor gate is an n-input, single-output nor gate that produces an active ‘0’ value if at least one of its inputs is a ‘1’ value. The gate produces a ‘0’ value if all inputs are ‘0’; if neither of these two conditions holds, the output is unknown. The delays associated with an output rise and those associated with an output fall may be specified independently. The model also posts an input load value (in farads) based on the parameter input load. The output of this model does not, however, respond to the total loading it sees on its output; it will always drive the output strongly with the specified delays. Example SPICE Usage: anor12 [1 2 3 4] 8 nor12 .model nor12 d_or(rise_delay = 0.5e-9 fall_delay = 0.3e-9 + input_load = 0.5e-12) 12.4.7 Xor NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: cm_d_xor d_xor "digital exclusive-or gate" in "input" in d [d] yes [2 -] no out "output" out d [d] no no rise_delay "rise delay" real 1.0e-9 fall_delay "fall delay" real 1.0e-9 12.4. DIGITAL MODELS Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 209 [1.0e-12 -] no yes [1.0e-12 -] no yes input_load "input load value (F)" real 1.0e-12 no yes Description: The digital xor gate is an n-input, single-output xor gate that produces an active ‘1’ value if an odd number of its inputs are also ‘1’ values. The delays associated with an output rise and those associated with an output fall may be specified independently. The model also posts an input load value (in farads) based on the parameter input load. The output of this model does not, however, respond to the total loading it sees on its output; it will always drive the output strongly with the specified delays. Note also that to maintain the technology-independence of the model, any UNKNOWN input, or any floating input causes the output to also go UNKNOWN. Example SPICE Usage: a9 [1 2] 8 xor3 .model xor3 d_xor(rise_delay = 0.5e-9 fall_delay = 0.3e-9 + input_load = 0.5e-12) 12.4.8 Xnor NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: cm_d_xnor d_xnor "digital exclusive-nor gate" in "input" in d [d] yes [2 -] no out "output" out d [d] no no rise_delay "rise delay" real 1.0e-9 fall_delay "fall delay" real 1.0e-9 210 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: [1.0e-12 -] no yes [1.0e-12 -] no yes input_load "input load value (F)" real 1.0e-12 no yes Description: The digital xnor gate is an n-input, single-output xnor gate that produces an active ‘0’ value if an odd number of its inputs are also ‘1’ values. It produces a ‘1’ output when an even number of ‘1’ values occurs on its inputs. The delays associated with an output rise and those associated with an output fall may be specified independently. The model also posts an input load value (in farads) based on the parameter input load. The output of this model does not, however, respond to the total loading it sees on its output; it will always drive the output strongly with the specified delays. Note also that to maintain the technology-independence of the model, any UNKNOWN input, or any floating input causes the output to also go UNKNOWN. Example SPICE Usage: a9 [1 2] 8 xnor3 .model xnor3 d_xnor(rise_delay = 0.5e-9 fall_delay = 0.3e-9 + input_load = 0.5e-12) 12.4.9 Tristate NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: cm_d_tristate d_tristate "digital tristate buffer" in "input" in d [d] no no delay "delay" real enable "enable" in d [d] no no out "output" out d [d] no no 12.4. DIGITAL MODELS Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 211 1.0e-9 [1.0e-12 -] no yes input_load "input load value (F)" real 1.0e-12 no yes enable_load "enable load value (F)" real 1.0e-12 no yes Description: The digital tristate is a simple tristate gate that can be configured to allow for open-collector behavior, as well as standard tristate behavior. The state seen on the input line is reflected in the output. The state seen on the enable line determines the strength of the output. Thus, a ONE forces the output to its state with a STRONG strength. A ZERO forces the output to go to a HI_IMPEDANCE strength. The delays associated with an output state or strength change cannot be specified independently, nor may they be specified independently for rise or fall conditions; other gate models may be used to provide such delays if needed. The model posts input and enable load values (in farads) based on the parameters input load and enable. The output of this model does not, however, respond to the total loading it sees on its output; it will always drive the output with the specified delay. Note also that to maintain the technology-independence of the model, any UNKNOWN input, or any floating input causes the output to also go UNKNOWN. Likewise, any UNKNOWN input on the enable line causes the output to go to an UNDETERMINED strength value. Example SPICE Usage: a9 1 2 8 tri7 .model tri7 d_tristate(delay = 0.5e-9 input_load = 0.5e-12 + enable_load = 0.5e-12) 12.4.10 Pullup NAME_TABLE: C_Function_Name: cm_d_pullup 212 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: d_pullup "digital pullup resistor" out "output" out d [d] no no load "load value (F)" real 1.0e-12 no yes Description: The digital pullup resistor is a device that emulates the behavior of an analog resistance value tied to a high voltage level. The pullup may be used in conjunction with tristate buffers to provide open-collector wired or constructs, or any other logical constructs that rely on a resistive pullup common to many tristated output devices. The model posts an input load value (in farads) based on the parameter load. Example SPICE Usage: a2 9 pullup1 .model pullup1 d_pullup(load = 20.0e-12) 12.4.11 Pulldown NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: cm_d_pulldown d_pulldown "digital pulldown resistor" out "output" out d [d] no no load 12.4. DIGITAL MODELS Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 213 "load value (F)" real 1.0e-12 no yes Description: The digital pulldown resistor is a device that emulates the behavior of an analog resistance value tied to a low voltage level. The pulldown may be used in conjunction with tristate buffers to provide open-collector wired or constructs, or any other logical constructs that rely on a resistive pulldown common to many tristated output devices. The model posts an input load value (in farads) based on the parameter load. Example SPICE Usage: a4 9 pulldown1 .model pulldown1 d_pulldown(load = 20.0e-12) 12.4.12 D Flip Flop NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: cm_d_dff d_dff "digital d-type flip flop" data "input data" in d [d] no no clk "clock" in d [d] no no set "asynch. set" in d [d] no yes reset "asynch. reset" in d [d] no yes out "data output" out d [d] Nout "inverted data output" out d [d] 214 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector.Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: no yes no yes clk_delay "delay from clk" real 1.0e-9 [1.0e-12 -] no yes set_delay "delay from set" real 1.0e-9 [1.0e-12 -] no yes reset_delay "delay from reset" real 1.0e-9 [1.0e-12 -] no yes ic "output initial state" int 0 [0 2] no yes data_load "data load value (F)" real 1.0e-12 no yes clk_load "clk load value (F)" real 1.0e-12 no yes set_load "set load value (F)" real 1.0e-12 no yes reset_load "reset load (F)" real 1.0e-12 no yes rise_delay "rise delay" real 1.0e-9 [1.0e-12 -] no yes fall_delay "fall delay" real 1.0e-9 [1.0e-12 -] no yes 12.4. DIGITAL MODELS 215 Description: The digital d-type flip flop is a one-bit, edge-triggered storage element that will store data whenever the clk input line transitions from low to high (ZERO to ONE). In addition, asynchronous set and reset signals exist, and each of the three methods of changing the stored output of the d_dff have separate load values and delays associated with them. Additionally, you may specify separate rise and fall delay values that are added to those specified for the input lines; these allow for more faithful reproduction of the output characteristics of different IC fabrication technologies. Note that any UNKNOWN input on the set or reset lines immediately results in an UNKNOWN output. Example SPICE Usage: a7 1 2 3 4 5 6 flop1 .model flop1 d_dff(clk_delay = 13.0e-9 set_delay = 25.0e-9 + reset_delay = 27.0e-9 ic = 2 rise_delay = 10.0e-9 + fall_delay = 3e-9) 12.4.13 JK Flip Flop NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: cm_d_jkff d_jkff "digital jk-type flip flop" j "j input" in d [d] no no k "k input" in d [d] no no clk "clock" in d [d] no no set "asynchronous set" in d [d] no - reset "asynchronous reset" in d [d] no - 216 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: yes yes out "data output" out d [d] no yes Nout "inverted data output" out d [d] no yes clk_delay "delay from clk" real 1.0e-9 [1.0e-12 -] no yes set_delay "delay from set" real 1.0e-9 [1.0e-12 -] no yes reset_delay "delay from reset" real 1.0e-9 [1.0e-12 -] no yes ic "output initial state" int 0 [0 2] no yes jk_load "j,k load values (F)" real 1.0e-12 no yes clk_load "clk load value (F)" real 1.0e-12 no yes set_load "set load value (F)" real 1.0e-12 no yes reset_load "reset load (F)" real 1.0e-12 no yes rise_delay fall_delay 12.4. DIGITAL MODELS Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 217 "rise delay" real 1.0e-9 [1.0e-12 -] no yes "fall delay" real 1.0e-9 [1.0e-12 -] no yes Description: The digital jk-type flip flop is a one-bit, edge-triggered storage element that will store data whenever the clk input line transitions from low to high (ZERO to ONE). In addition, asynchronous set and reset signals exist, and each of the three methods of changing the stored output of the d_jkff have separate load values and delays associated with them. Additionally, you may specify separate rise and fall delay values that are added to those specified for the input lines; these allow for more faithful reproduction of the output characteristics of different IC fabrication technologies. Note that any UNKNOWN inputs other than j or k cause the output to go UNKNOWN automatically. Example SPICE Usage: a8 1 2 3 4 5 6 7 flop2 .model flop2 d_jkff(clk_delay = 13.0e-9 set_delay = 25.0e-9 + reset_delay = 27.0e-9 ic = 2 rise_delay = 10.0e-9 + fall_delay = 3e-9) 12.4.14 Toggle Flip Flop NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: cm_d_tff d_tff "digital toggle flip flop" t "toggle input" in d [d] no no clk "clock" in d [d] no no set "set" in d [d] no yes reset "reset" in d [d] no yes 218 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE PORT.TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default.Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: out "data output" out d [d] no yes Nout "inverted data output" out d [d] no yes clk_delay "delay from clk" real 1.0e-9 [1.0e-12 -] no yes set_delay "delay from set" real 1.0e-9 [1.0e-12 -] no yes reset_delay "delay from reset" real 1.0e-9 [1.0e-12 -] no yes ic "output initial state" int 0 [0 2] no yes t_load clk_load "toggle load value (F)" "clk load value (F)" real real 1.0e-12 1.0e-12 no no yes yes set_load "set load value (F)" real 1.0e-12 no yes reset_load "reset load (F)" real 1.0e-12 no yes rise_delay "rise delay" fall_delay "fall delay" 12.4. DIGITAL MODELS Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 219 real 1.0e-9 [1.0e-12 -] no yes real 1.0e-9 [1.0e-12 -] no yes Description: The digital toggle-type flip flop is a one-bit, edge-triggered storage element that will toggle its current state whenever the clk input line transitions from low to high (ZERO to ONE). In addition, asynchronous set and reset signals exist, and each of the three methods of changing the stored output of the d_tff have separate load values and delays associated with them. Additionally, you may specify separate rise and fall delay values that are added to those specified for the input lines; these allow for more faithful reproduction of the output characteristics of different IC fabrication technologies. Note that any UNKNOWN inputs other than t immediately cause the output to go UNKNOWN. Example SPICE Usage: a8 2 12 4 5 6 3 flop3 .model flop3 d_tff(clk_delay = 13.0e-9 set_delay = 25.0e-9 + reset_delay = 27.0e-9 ic = 2 rise_delay = 10.0e-9 + fall_delay = 3e-9 t_load = 0.2e-12) 12.4.15 Set-Reset Flip Flop NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: cm_d_srff d_srff "digital set-reset flip flop" s "set input" in d [d] no no r "reset input" in d [d] no no clk "clock" in d [d] no no set reset 220 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: "asynchronous set" in d [d] no yes "asynchronous reset" in d [d] no yes out "data output" out d [d] no yes Nout "inverted data output" out d [d] no yes clk_delay "delay from clk" real 1.0e-9 [1.0e-12 -] no yes set_delay "delay from set" real 1.0e-9 [1.0e-12 -] no yes reset_delay "delay from reset" real 1.0e-9 [1.0e-12 -] no yes ic "output initial state" int 0 [0 2] no yes sr_load "set/reset loads (F)" real 1.0e-12 no yes clk_load "clk load value (F)" real 1.0e-12 no yes set_load "set load value (F)" real 1.0e-12 reset_load "reset load (F)" real 1.0e-12 12.4. DIGITAL MODELS Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 221 no yes no yes rise_delay "rise delay" real 1.0e-9 [1.0e-12 -] no yes fall_delay "fall delay" real 1.0e-9 [1.0e-12 -] no yes Description: The digital sr-type flip flop is a one-bit, edge-triggered storage element that will store data whenever the clk input line transitions from low to high (ZERO to ONE). The value stored (i.e., the out value) will depend on the s and r input pin values, and will be: out=ONE out=ZERO out=previous value out=UNKNOWN if if if if s=ONE and r=ZERO; s=ZERO and r=ONE; s=ZERO and r=ZERO; s=ONE and r=ONE; In addition, asynchronous set and reset signals exist, and each of the three methods of changing the stored output of the d_srff have separate load values and delays associated with them. You may also specify separate rise and fall delay values that are added to those specified for the input lines; these allow for more faithful reproduction of the output characteristics of different IC fabrication technologies. Note that any UNKNOWN inputs other than s and r immediately cause the output to go UNKNOWN. Example SPICE Usage: a8 2 12 4 5 6 3 14 flop7 .model flop7 d_srff(clk_delay = 13.0e-9 set_delay = 25.0e-9 + reset_delay = 27.0e-9 ic = 2 rise_delay = 10.0e-9 + fall_delay = 3e-9) 12.4.16 D Latch NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: cm_d_dlatch d_dlatch "digital d-type latch" data "input data" in enable "enable input" in 222 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: d [d] no no d [d] no no set "set" in d [d] no yes reset "reset" in d [d] no yes out "data output" out d [d] no no Nout "inverter data output" out d [d] no no data_delay "delay from data" real 1.0e-9 [1.0e-12 -] no yes enable_delay "delay from enable" real 1.0e-9 [1.0e-12 -] no yes set_delay "delay from SET" real 1.0e-9 [1.0e-12 -] no yes reset_delay "delay from RESET" real 1.0e-9 [1.0e-12 -] no ic "output initial state" boolean 0 no 12.4. DIGITAL MODELS Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 223 yes yes data_load "data load (F)" real 1.0e-12 no yes enable_load "enable load value (F)" real 1.0e-12 no yes set_load "set load value (F)" real 1.0e-12 no yes reset_load "reset load (F)" real 1.0e-12 no yes rise_delay "rise delay" real 1.0e-9 [1.0e-12 -] no yes fall_delay "fall delay" real 1.0e-9 [1.0e-12 -] no yes Description: The digital d-type latch is a one-bit, level-sensitive storage element that will output the value on the data line whenever the enable input line is high (ONE). The value on the data line is stored (i.e., held on the out line) whenever the enable line is low (ZERO). In addition, asynchronous set and reset signals exist, and each of the four methods of changing the stored output of the d_dlatch (i.e., data changing with enable=ONE, enable changing to ONE from ZERO with a new value on data, raising set and raising reset) have separate delays associated with them. You may also specify separate rise and fall delay values that are added to those specified for the input lines; these allow for more faithful reproduction of the output characteristics of different IC fabrication technologies. Note that any UNKNOWN inputs other than on the data line when enable=ZERO immediately cause the output to go UNKNOWN. Example SPICE Usage: a4 12 4 5 6 3 14 latch1 .model latch1 d_dlatch(data_delay = 13.0e-9 enable_delay = 22.0e-9 + set_delay = 25.0e-9 + reset_delay = 27.0e-9 ic = 2 + rise_delay = 10.0e-9 fall_delay = 3e-9) 224 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE 12.4.17 Set-Reset Latch NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: no no Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: cm_d_srlatch d_srlatch "digital sr-type latch" s "set" in d [d] no no r "reset" in d [d] no no enable "enable" in d [d] no no set "set" in d [d] no yes reset "reset" in d [d] no yes out "data output" out d [d] Nout "inverted data output" out d [d] no no sr_delay "delay from s or r input change" real 1.0e-9 [1.0e-12 -] no 12.4. DIGITAL MODELS Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 225 yes enable_delay "delay from enable" real 1.0e-9 [1.0e-12 -] no yes set_delay "delay from SET" real 1.0e-9 [1.0e-12 -] no yes reset_delay "delay from RESET" real 1.0e-9 [1.0e-12 -] no yes ic "output initial state" boolean 0 no yes sr_load enable_load "s & r input loads (F)" "enable load value (F)" real real 1.0e-12 1.0e-12 no no yes yes set_load "set load value (F)" real 1.0e-12 no yes reset_load "reset load (F)" real 1.0e-12 no yes rise_delay "rise delay" real 1.0e-9 [1.0e-12 -] no yes fall_delay "fall delay" real 1.0e-9 [1.0e-12 -] no yes Description: The digital sr-type latch is a one-bit, level-sensitive storage element that will 226 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE output the value dictated by the state of the s and r pins whenever the enable input line is high (ONE). This value is stored (i.e., held on the out line) whenever the enable line is low (ZERO). The particular value chosen is as shown below: s=ZERO, r=ZERO => s=ZERO, r=ONE s=ONE, r=ZERO s=ONE, r=ONE out=current value (i.e., not change in output) => out=ZERO => out=ONE => out=UNKNOWN Asynchronous set and reset signals exist, and each of the four methods of changing the stored output of the d srlatch (i.e., s/r combination changing with enable=ONE, enable changing to ONE from ZERO with an output-changing combination of s and r, raising set and raising reset) have separate delays associated with them. You may also specify separate rise and fall delay values that are added to those specified for the input lines; these allow for more faithful reproduction of the output characteristics of different IC fabrication technologies. Note that any UNKNOWN inputs other than on the s and r lines when enable=ZERO immediately cause the output to go UNKNOWN. Example SPICE Usage: a4 12 4 5 6 3 14 16 latch2 .model latch2 d_srlatch(sr_delay = 13.0e-9 enable_delay = 22.0e-9 + set_delay = 25.0e-9 + reset_delay = 27.0e-9 ic = 2 + rise_delay = 10.0e-9 fall_delay = 3e-9) 12.4.18 State Machine NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: cm_d_state d_state "digital state machine" in "input" in d [d] yes [1 -] yes clk "clock" in d [d] no no reset "reset" in d [d] out "output" out d [d] 12.4. DIGITAL MODELS Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: 227 no yes yes [1 -] no clk_delay reset_delay "delay from CLK" "delay from RESET" real real 1.0e-9 1.0e-9 [1.0e-12 -] [1.0e-12 -] no no yes yes Parameter_Name: state_file "state transition specification file name" string "state.txt" no no reset_state "default state on RESET & at DC" int 0 no no input_load "input loading capacitance (F)" real 1.0e-12 no yes clk_load "clock loading capacitance (F)" real 1.0e-12 no yes 228 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: reset_load "reset loading capacitance (F)" real 1.0e-12 no yes Description: The digital state machine provides for straightforward descriptions of clocked combinational logic blocks with a variable number of inputs and outputs and with an unlimited number of possible states. The model can be configured to behave as virtually any type of counter or clocked combinational logic block and can be used to replace very large digital circuit schematics with an identically functional but faster representation. The d state model is configured through the use of a state definition file (state.in) that resides in a directory of your choosing. The file defines all states to be understood by the model, plus input bit combinations that trigger changes in state. An example state.in file is shown below: ----------- begin file ------------* This is an example state.in file. This file * defines a simple 2-bit counter with one input. The * value of this input determines whether the counter counts * up (in = 1) or down (in = 0). 0 0s 0s 0 -> 3 1 -> 1 1 0s 1z 0 -> 0 1 -> 2 2 1z 0s 0 -> 1 1 -> 3 3 1z 1z 0 -> 2 3 1z 1z 1 -> 0 ------------------ end file --------------Several attributes of the above file structure should be noted. First, all lines in the file must be one of four types. These are: 1. A comment, beginning with a ‘*’ in the first column. 2. A header line, which is a complete description of the current state, the outputs corresponding to that state, an input value, and the state that the model will assume should that input be encountered. The first line of a state definition must always be a header line. 3. A continuation line, which is a partial description of a state, consisting of an input value and the state that the model will assume should that input be encountered. Note that continuation lines may only be used after the initial header line definition for a state. 4. A line containing nothing but white-spaces (space, form-feed, newline, carriage return, tab, vertical tab). 12.4. DIGITAL MODELS 229 A line that is not one of the above will cause a file-loading error. Note that in the example shown, whitespace (any combination of blanks, tabs, commas) is used to separate values, and that the character -> is used to underline the state transition implied by the input preceding it. This particular character is not critical in of itself, and can be replaced with any other character or non-broken combination of characters that you prefer (e.g. ==>, >>, ‘:’, resolves_to, etc.) The order of the output and input bits in the file is important; the first column is always interpreted to refer to the ‘zeroth’ bit of input and output. Thus, in the file above, the output from state 1 sets out[0] to 0s, and out[1] to 1z. The state numbers need not be in any particular order, but a state definition (which consists of the sum total of all lines that define the state, its outputs, and all methods by which a state can be exited) must be made on contiguous line numbers; a state definition cannot be broken into sub-blocks and distributed randomly throughout the file. On the other hand, the state definition can be broken up by as many comment lines as you desire. Header files may be used throughout the state.in file, and continuation lines can be discarded completely if you so choose: continuation lines are primarily provided as a convenience. Example SPICE Usage: a4 [2 3 4 5] 1 12 [22 23 24 25 26 27 28 29] state1 .model state1 d_state(clk_delay = 13.0e-9 reset_delay = 27.0e-9 + state_file = "newstate.txt" reset_state = 2) Note: The file named by the parameter filename in state_file="filename" is sought after according to a search list described in12.1.3. 12.4.19 Frequency Divider NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: cm_d_fdiv d_fdiv "digital frequency divider" freq_in "frequency input" in d [d] no no freq_out "frequency output" out d [d] no no div_factor "divide factor" int 2 [1 -] no high_cycles "# of cycles for high out" int 1 [1 div_factor-1] no 230 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: yes yes i_count "divider initial count value" int 0 no yes rise_delay "rise delay" real 1.0e-9 [1.0e-12 -] yes in yes fall_delay "fall delay" real 1.0e-9 [1.0e-12 -] yes in yes freq_in_load "freq_in load value (F)" real 1.0e-12 no yes Description: The digital frequency divider is a programmable step-down divider that accepts an arbitrary divisor (div_factor), a duty-cycle term (high_cycles), and an initial count value (i_count). The generated output is synchronized to the rising edges of the input signal. Rise delay and fall delay on the outputs may also be specified independently. Example SPICE Usage: a4 3 7 divider .model divider d_fdiv(div_factor = 5 high_cycles = 3 + i_count = 4 rise_delay = 23e-9 + fall_delay = 9e-9) 12.4.20 RAM NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: cm_d_ram d_ram "digital random-access memory" 12.4. DIGITAL MODELS Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: 231 data_in "data input line(s)" in d [d] yes [1 -] no data_out "data output line(s)" out d [d] yes data_in no address write_en "address input line(s)" "write enable line" in in d d [d] [d] yes no [1 -] no no select "chip select line(s)" in d [d] yes [1 16] no select_value "decimal active value for select line comparison" int 1 [0 32767] no yes ic "initial bit state @ dc" int 2 [0 2] no yes read_delay "read delay from address/select/write.en active" real 232 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 100.0e-9 [1.0e-12 -] no yes data_load address_load "data_in load value (F)" "addr. load value (F)" real real 1.0e-12 1.0e-12 no no yes yes select_load "select load value (F)" real 1.0e-12 no yes enable_load "enable line load value (F)" real 1.0e-12 no yes Description: The digital RAM is an M-wide, N-deep random access memory element with programmable select lines, tristated data out lines, and a single write/~read line. The width of the RAM words (M) is set through the use of the word width parameter. The depth of the RAM (N) is set by the number of address lines input to the device. The value of N is related to the number of address input lines (P) by the following equation: 2P = N There is no reset line into the device. However, an initial value for all bits may be specified by setting the ic parameter to either 0 or 1. In reading a word from the ram, the read delay value is invoked, and output will not appear until that delay has been satisfied. Separate rise and fall delays are not supported for this device. Note that UNKNOWN inputs on the address lines are not allowed during a write. In the event that an address line does indeed go unknown during a write, the entire contents of the ram will be set to unknown. This is in contrast to the data in lines being set to unknown during a write; in that case, only the selected word will be corrupted, and this is 12.4. DIGITAL MODELS 233 corrected once the data lines settle back to a known value. Note that protection is added to the write en line such that extended UNKNOWN values on that line are interpreted as ZERO values. This is the equivalent of a read operation and will not corrupt the contents of the RAM. A similar mechanism exists for the select lines. If they are unknown, then it is assumed that the chip is not selected. Detailed timing-checking routines are not provided in this model, other than for the enable delay and select delay restrictions on read operations. You are advised, therefore, to carefully check the timing into and out of the RAM for correct read and write cycle times, setup and hold times, etc. for the particular device they are attempting to model. Example SPICE Usage: a4 [3 4 5 6] [3 4 5 6] [12 13 14 15 16 17 18 19] 30 [22 23 24] ram2 .model ram2 d_ram(select_value = 2 ic = 2 read_delay = 80e-9) 12.4.21 Digital Source NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: cm_d_source d_source "digital signal source" out "output" out d [d] yes no input_file "digital input vector filename" string "source.txt" no no input_load "input loading capacitance (F)" real 1.0e-12 no no 234 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Description: The digital source provides for straightforward descriptions of digital signal vectors in a tabular format. The model reads input from the input file and, at the times specified in the file, generates the inputs along with the strengths listed. The format of the input file is as shown below. Note that comment lines are delineated through the use of a single ‘*’ character in the first column of a line. This is similar to the way the SPICE program handles comments. * T * i * m * e * 0.0000 1.234e-9 1.376e-9 2.5e-7 2.5006e-7 5.0e-7 c l o c k Uu 0s 0s 1s 1s 0s n o d e a Uu 1s 0s 0s 1s 1s n o d e b Us 1s 1s 1s 1s 1s n . . . o . . . d . . . e . . . c . . . Uu . . . 0z . . . 0z . . . 0z . . . 0z . . . 0z . . . Note that in the example shown, whitespace (any combination of blanks, tabs, commas) is used to separate the time and state/strength tokens. The order of the input columns is important; the first column is always interpreted to mean ‘time’. The second through the N’th columns map to the out[0] through out[N-2] output nodes. A non-commented line that does not contain enough tokens to completely define all outputs for the digital source will cause an error. Also, time values must increase monotonically or an error will result in reading the source file. Errors will also occur if a line exists in source.txt that is neither a comment nor vector line. The only exception to this is in the case of a line that is completely blank; this is treated as a comment (note that such lines often occur at the end of text within a file; ignoring these in particular prevents nuisance errors on the part of the simulator). Example SPICE Usage: a3 [2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17] input_vector .model input_vector d_source(input_file = "source_simple.text") Note: The file named by the parameter filename in input_file="filename" is sought after according to a search list described in12.1.3. 12.4.22 LUT NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: Direction: cm_d_lut d_lut "digital n-input look-up table gate" in out "input" in "output" out 12.4. DIGITAL MODELS Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 235 d [d] yes [1 -] no d [d] no no rise_delay "rise delay" real 1.0e-9 [1.0e-12 -] no yes fall_delay "fall delay" real 1.0e-9 [1.0e-12 -] no yes input_load "input load value (F)" real 1.0e-12 no yes table_values "lookup table values" string "0" no no 236 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Description: The lookup table provides a way to map any arbitrary n-input, 1-output combinational logic block to XSPICE. The inputs are mapped to the output using a string of length 2^n. The string may contain values "0", "1" or "X", corresponding to an output of low, high, or unknown, respectively. The outputs are only mapped for inputs which are valid logic levels. Any unknown bit in the input vector will always produce an unknown output. The first character of the string table_values corresponds to all inputs value zero, and the last (2^n) character corresponds to all inputs value one, with the first signal in the input vector being the least significant bit. For example, a 2-input lookup table representing the function (A * B) (that is, A AND B), with input vector [A B] can be constructed with a table_values string of "0001"; function (~A * B) with input vector [A B] can be constructed with a table_values string of "0010". The delays associated with an output rise and those associated with an output fall may be specified independently. The model also posts an input load value (in farads) based on the parameter input_load. The output of this model does not respond to the total loading it sees on the output; it will always drive the output strongly with the specified delays. Example SPICE Usage: * LUT encoding 3-bit parity function a4 [1 2 3] 5 lut_pty3_1 .model lut_pty3_1 d_lut(table_values = "01101001" + input_load 2.0e-12) 12.4.23 General LUT NAME_TABLE: C_Function_Name: Spice_Model_Name: Description: PORT_TABLE: Port_Name: Description: Direction: Default_Type: Allowed_Types: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: cm_d_genlut d_genlut "digital n-input x m-output look-up table gate" in "input" in d [d] yes no rise_delay "rise delay" real 1.0e-9 [1.0e-12 -] yes yes out "output" out d [d] yes no fall_delay "fall delay" real 1.0e-9 [1.0e-12 -] yes yes input_load "input load value (F)" input_delay "input delay" 12.4. DIGITAL MODELS Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: PARAMETER_TABLE: Parameter_Name: Description: Data_Type: Default_Value: Limits: Vector: Vector_Bounds: Null_Allowed: 237 real 1.0e-12 yes yes real 0.0 yes yes table_values "lookup table values" string "0" no no Description: The lookup table provides a way to map any arbitrary n-input, m-output combinational logic block to XSPICE. The inputs are mapped to the output using a string of length m * (2^n). The string may contain values "0", "1", "X", or "Z", corresponding to an output of low, high, unknown, or high-impedance, respectively. The outputs are only mapped for inputs which are valid logic levels. Any unknown bit in the input vector will always produce an unknown output. The character string is in groups of (2^n) characters, one group corresponding to each output pin, in order. The first character of a group in the string table_values corresponds to all inputs value zero, and the last (2^n) character in the group corresponds to all inputs value one, with the first signal in the input vector being the least significant bit. For example, a 2-input lookup table representing the function (A * B) (that is, A AND B), with input vector [A B] can be constructed with a table_values string of "0001"; function (~A * B) with input vector [A B] can be constructed with a "table_values" string of "0010". The delays associated with each output pin’s rise and those associated with each output pin’s fall may be specified independently. The model also posts independent input load values per input pin (in farads) based on the parameter input_load. The parameter input_delay provides a way to specify additional delay between each input pin and the output. This delay is added to the rise- or fall-time of the output. The output of this model does not respond to the total loading it sees on the output; it will always drive the output strongly with the specified delays. Example SPICE Usage: * LUT encoding 3-bit parity function a4 [1 2 3] [5] lut_pty3_1 .model lut_pty3_1 d_genlut(table_values = "01101001" + input_load [2.0e-12]) * LUT encoding a tristate inverter function (en in out) a2 [1 2] [3] lut_triinv_1 .model lut_triinv_1 d_genlut(table_values = "Z1Z0") * LUT encoding a half-adder function (A B Carry Sum) a8 [1 2] [3 4] lut_halfadd_1 .model lut_halfadd_1 d_genlut(table_values = "00010110" + rise_delay [ 1.5e-9 1.0e-9 ] fall_delay [ 1.5e-9 1.0e-9 ]) 238 12.5 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Predefined Node Types for event driven simulation The following pre-written node types are included with the XSPICE simulator. These should provide you not only with valuable event-driven modeling capabilities, but also with examples to use for guidance in creating new UDN (user defined node) types. You may access these node data by the plot (17.5.45) or eprint (17.5.24) commands. 12.5.1 Digital Node Type The ‘digital’ node type is directly built into the simulator. 12 digital node values are available. They are described by a two character string (the state/strength token). The first character (0, 1, or U) gives the state of the node (logic zero, logic one, or unknown logic state). The second character (s, r, z, u) gives the "strength" of the logic state (strong, resistive, hi-impedance, or undetermined). So these are the values we have: 0s, 1s, Us, 0r, 1r, Ur, 0z, 1z, Uz, 0u, 1u, Uu. 12.5.2 Real Node Type The ‘real’ node type provides for event-driven simulation with double-precision floating point data. This type is useful for evaluating sampled-data filters and systems. The type implements all optional functions for User-Defined Nodes, including inversion and node resolution. For inversion, the sign of the value is reversed. For node resolution, the resultant value at a node is the sum of all values output to that node. The node is implemented as a user defined node in ngspice/src/xspice/icm/xtraevt/real. 12.5.3 Int Node Type The ‘int’ node type provides for event-driven simulation with integer data. This type is useful for evaluating round-off error effects in sampled-data systems. The type implements all optional functions for User-Defined Nodes, including inversion and node resolution. For inversion, the sign of the integer value is reversed. For node resolution, the resultant value at a node is the sum of all values output to that node. The node is implemented as a user defined node in ngspice/src/xspice/icm/xtraevt/int. 12.5.4 (Digital) Input/Output The analog code models use the standard (analog) nodes provided by ngspice and thus are using all the commands for sourcing, storing, printing, and plotting data. I/O for event nodes (digital, real, int, and UDNs) is offered by the following tools: For output you may use the plot (17.5.45) or eprint (17.5.24) commands, as well as edisplay (17.5.23) and eprvcd (17.5.25). The latter writes all node data to a VCD file (a digital standard interface) that may be analysed by viewers like gtkwave. For input, you may create a test bench with existing code models (oscillator (12.3.3), frequency divider (12.4.19), state machine (12.4.18) etc.). Reading data from a file is offered by d_source (12.4.21). Some comments and hints have been provided by Sdaau. You may also use the analog input from file, (filesource 12.2.8) and convert its analog input to the digital type by the adc_bridge (12.3.2). If you want reading 12.5. PREDEFINED NODE TYPES FOR EVENT DRIVEN SIMULATION 239 data from a VCD file, please have a look at ngspice tips and examples forum and apply a python script provided by Sdaau to translate the VCD data to d_source or filesource input. 240 CHAPTER 12. MIXED-MODE AND BEHAVIORAL MODELING WITH XSPICE Chapter 13 Verilog A Device models 13.1 Introduction The ngspice-adms interface will implement extra HICUM level0 and level2 (HICUM model web page), MEXTRAM(MEXTRAM model web page), EKV(EKV model web page) and PSP(NXP MOS model 9 web page) models written in Verilog-A behavior language. 13.2 adms To compile Verilog-A compact models into ngspice-ready C models the the program admsXml is required. Details of this software are described in adms home page. 13.3 How to integrate a Verilog-A model into ngspice 13.3.1 How to setup a *.va model for ngspice The root entry for new Verilog-A models is \src\spicelib\devices\adms. Below the modelname entry the Verilog-A code should reside in folder admsva (e.g.: ngspice\src\spicelib\devices\adms\ekv\admsva\ekv.va). The file extension is fixed to .va. Certain files must modified to create the interface to ngspice - see the guideline README.adms in the ngspice root. 13.3.2 Adding admsXml to your build environment To facilitate the installation of adms, a source code package has been assembled for use with ngspice, available as a zip file for download. It is based on adms source code from the subversion repository downloaded on August 1st, 2010, and has been slightly modified (see ChangeLog). Under OS Linux (tested with SUSE 11.2, 64 bit) you may expand the zip file and run ./autogen_lin.sh, followed by ’make’ and ’make install’. 241 242 CHAPTER 13. VERILOG A DEVICE MODELS Under OS CYGWIN (tested with actual CYGWIN on MS Windows 7, 64 bit), please use ./autogen_cyg.sh, followed by ’make’ and ’make install’. Under OS MINGW, a direct compilation would require the additional installation of perl module XML-LibXML, which is not as straightforward as it should be. However you may start with a CYGWIN compile as described above. If you then go to your MSYS window, cd to the adms top directory and start ./mingw-compile.sh, you will obtain admsXml.exe, copied to MSYS /bin, and you are ready to go. To facilitate installation under MS Windows, a admsXml.exe zipped binary is available. Just copy it to MSYS /bin directory and start working on your verilog models. A short test of a successful installation is: $ admsXml -v $ [usage..] release name="admsXml" version="2.3.0" date="Aug 4 2010" time="10:24:18" Compilation of admsXml with MS Visual Studio is not possible, because the source code has variable declarations not only at the top of a block, but deliberately also in the following lines. This is ok by the C99 standard, but not supported by MS Visual Studio. Chapter 14 Mixed-Level Simulation (ngspice with TCAD) 14.1 Cider Ngspice implements mixed-level simulation through the merging of its code with CIDER (details see Chapt. 30). CIDER is a mixed-level circuit and device simulator that provides a direct link between technology parameters and circuit performance. A mixed-level circuit and device simulator can provide greater simulation accuracy than a stand-alone circuit or device simulator by numerically modeling the critical devices in a circuit. Compact models can be used for noncritical devices. CIDER couples the latest version of SPICE3 (version 3F.2) [JOHN92] to a internal C-based device simulator, DSIM. SPICE3 provides circuit analyses, compact models for semiconductor devices, and an interactive user interface. DSIM provides accurate, one- and two-dimensional numerical device models based on the solution of Poisson’s equation, and the electron and hole current-continuity equations. DSIM incorporates many of the same basic physical models found in the the Stanford two-dimensional device simulator PISCES [PINT85]. Input to CIDER consists of a SPICE-like description of the circuit and its compact models, and PISCES-like descriptions of the structures of numerically modeled devices. As a result, CIDER should seem familiar to designers already accustomed to these two tools. For example, SPICE3F.2 input files should run without modification, producing identical results. CIDER is based on the mixed-level circuit and device simulator CODECS [MAYA88] and is a replacement for this program. The basic algorithms of the two programs are the same. Some of the differences between CIDER and CODECS are described below. The CIDER input format has greater flexibility and allows increased access to physical model parameters. New physical models have been added to allow simulation of state-of-the-art devices. These include transverse field mobility degradation [GATE90] that is important in scaled-down MOSFETs and a polysilicon model for poly-emitter bipolar transistors. Temperature dependence has been included for most physical models over the range from -50°C to 150°C. The numerical models can be used to simulate all the basic types of semiconductor devices: resistors, MOS capacitors, diodes, BJTs, JFETs and MOSFETs. BJTs and JFETs can be modeled with or without a substrate contact. Support has been added for the management of device internal states. Post-processing of device states can be performed using the NUTMEG user interface of SPICE3. Previously 243 244 CHAPTER 14. MIXED-LEVEL SIMULATION (NGSPICE WITH TCAD) computed states can be loaded into the program to provide accurate initial guesses for subsequent analyses. Finally, numerous small bugs have been discovered and fixed, and the program has been ported to a wider variety of computing platforms. Berkeley tradition calls for the naming of new versions of programs by affixing a (number, letter, number) triplet to the end of the program name. Under this scheme, CIDER should instead be named CODECS2A.l. However, tradition has been broken in this case because major incompatibilities exist between the two programs and because it was observed that the acronym CODECS is already used in the analog design community to refer to coder-decoder circuits. Details of the basic semiconductor equations and the physical models used by CIDER are not provided in this manual. Unfortunately, no other single source exists that describes all of the relevant background material. Comprehensive reviews of device simulation can be found in [PINT90] and the book [SELB84]. CODECS and its inversion-layer mobility model are described in [MAYA88] and LGATE90], respectively. PISCES and its models are described in [PINT85]. Temperature dependencies for the PISCES models used by CIDER are available in [SOLL90]. 14.2 GSS, Genius For Linux users the cooperation of the TCAD software GSS with ngspice might be of interest, see http://ngspice.sourceforge.net/gss.html. This project is no longer maintained however, but has moved into the Genius simulator, still available as open source cogenda genius. Chapter 15 Analyses and Output Control (batch mode) The command lines described in this chapter are specifying analyses and outputs within the circuit description file. They start with a ‘.’ (dot commands). Specifying analyses and plots (or tables) in the input file with dot commands is used with batch runs. Batch mode is entered when either the -b option is given upon starting ngspice ngspice -b -r rawfile.raw circuitfile.cir or when the default input source is redirected from a file (see also Chapt. 16.4.1). ngspice < circuitfile.cir In batch mode, the analyses specified by the control lines in the input file (e.g. .ac, .tran, etc.) are immediately executed. If the -r rawfile option is given then all data generated is written to a ngspice rawfile. The rawfile may later be read by the interactive mode of ngspice using the load command (see 17.5.38). In this case, the .save line (see 15.6) may be used to record the value of internal device variables (see Appendix, Chapt. 31). If a rawfile is not specified, then output plots (in ‘line-printer’ form) and tables can be printed according to the .print, .plot, and .four control lines, described in Chapt. 15.6. If ngspice is started in interactive mode (see Chapt. 16.4.2), like ngspice circuitfile.cir and no control section (.control ... .endc, see 16.4.3) is provided in the circuit file, the dot commands are not executed immediately, but are waiting for manually receiving the command run. 15.1 Simulator Variables (.options) Various parameters of the simulations available in Ngspice can be altered to control the accuracy, speed, or default values for some devices. These parameters may be changed via the option command (described in Chapt. 17.5.44) or via the .options line: 245 246 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) General form: . options opt1 opt2 ... (or opt= optval ...) Examples: . options reltol =.005 trtol =8 The options line allows the user to reset program control and user options for specific simulation purposes. Options specified to Ngspice via the option command (see Chapt. 17.5.44) are also passed on as if specified on a .options line. Any combination of the following options may be included, in any order. ‘x’ (below) represents some positive number. 15.1.1 General Options ACCT causes accounting and run time statistics to be printed. NOACCT no printing of statistics, no printing of the Initial Transient Solution. NOINIT suppresses only printing of the Initial Transient Solution, maybe combined with ACCT. LIST causes the summary listing of the input data to be printed. NOMOD suppresses the printout of the model parameters. NOPAGE suppresses page ejects. NODE causes the printing of the node table. OPTS causes the option values to be printed. TEMP=x Resets the operating temperature of the circuit. The default value is 27 ◦C (300K). TEMP can be overridden per device by a temperature specification on any temperature dependent instance. May also be generally overridden by a .TEMP card (2.11). TNOM=x resets the nominal temperature at which device parameters are measured. The default value is 27 ◦C (300 deg K). TNOM can be overridden by a specification on any temperature dependent device model. WARN=1|0 enables or turns of SOA (Safe Operating Area) voltage warning messages (default: 0). MAXWARNS=x specifies the maximum number of SOA (Safe Operating Area) warning messages per model (default: 5). SAVECURRENTS save currents through all terminals of the following devices: M, J, Q, D, R, C, L, B, F, G, W, S, I (see 2.1.2). Recommended only for small circuits, because otherwise memory requirements explode and simulation speed suffers. See 15.7 for more details. 15.1. SIMULATOR VARIABLES (.OPTIONS) 15.1.2 247 DC Solution Options The following options controls properties pertaining to DC analysis and algorithms. Since transient analysis is based on DC many of the options affect the latter one. ABSTOL=x resets the absolute current error tolerance of the program. The default value is 1 pA. GMIN=x resets the value of GMIN, the minimum conductance allowed by the program. The default value is 1.0e-12. ITL1=x resets the dc iteration limit. The default is 100. ITL2=x resets the dc transfer curve iteration limit. The default is 50. KEEPOPINFO Retain the operating point information when either an AC, Distortion, or PoleZero analysis is run. This is particularly useful if the circuit is large and you do not want to run a (redundant) .OP analysis. PIVREL=x resets the relative ratio between the largest column entry and an acceptable pivot value. The default value is 1.0e-3. In the numerical pivoting algorithm the allowed minimum pivot value is determined by EPSREL = AMAX1(PIVREL · MAXVAL, PIVTOL) where MAXVAL is the maximum element in the column where a pivot is sought (partial pivoting). PIVTOL=x resets the absolute minimum value for a matrix entry to be accepted as a pivot. The default value is 1.0e-13. RELTOL=x resets the relative error tolerance of the program. The default value is 0.001 (0.1%). RSHUNT=x introduces a resistor from each analog node to ground. The value of the resistor should be high enough to not interfere with circuit operations. The XSPICE option has to be enabled (see 32.1.5) . VNTOL=x resets the absolute voltage error tolerance of the program. The default value is 1 µV . 15.1.2.1 Matrix Conditioning info In most SPICE-based simulators, problems can arise with certain circuit topologies. One of the most common problems is the absence of a DC path to ground at some node. This may happen, for example, when two capacitors are connected in series with no other connection at the common node or when certain code models are cascaded. The result is an ill-conditioned or nearly singular matrix that prevents the simulation from completing. The XSPICE option introduces the rshunt option to help eliminate this problem. When used, this option inserts resistors to ground at all the analog nodes in the circuit. In general, the value of rshunt should be set to some very high resistance (e.g. 1000 Meg Ohms or greater) so that the operation of the circuit is essentially unaffected, but the matrix problems are corrected. If you should encounter a ‘no DC path to ground’ or a ‘matrix is nearly singular’ error message with your circuit, you should try adding the following .option card to your circuit description deck. 248 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) .option rshunt = 1.0e12 Usually a value of 1.0e12 is sufficient to correct the matrix problems. However, if you still have problems, you may wish to try lowering this value to 1.0e10 or 1.0e9. Another matrix conditioning problem might occur if you try to place an inductor in parallel to a voltage source. An ac simulation will fail, because it is preceded by an op analysis. Option noopac (15.1.3) will help if the circuit is linear. If the circuit is non-linear, you will need the op analysis. Then adding a small resistor (e.g. 1e-4 Ohms) in series to the inductor will help to obtain convergence. .option rseries = 1.0e-4 will add a series resistor to each inductor in the circuit. Be careful if you use behavioral inductors (see 3.2.12), because the result may become unpredictable. 15.1.3 AC Solution Options NOOPAC Do not do an operating point (OP) analysis before the AC analysis. To become valid, this option requires that the circuit is linear, thus consists only of R, L, and C devices, independent V, I sources and linear dependent E, G, H, and F sources (without poly statement, non-behavioral). If a non-linear device is detected, the OP analysis will be executed automatically. This option is of interest for example in nested LC circuits, where there is no series resistance for the L device given, which during OP analysis may result in an ill formed matrix, yields an error message and aborts the simulation. 15.1.4 Transient Analysis Options AUTOSTOP stops a transient analysis after successfully calculating all measure functions (15.4) specified with the dot command .meas. Autostop is not available with meas (17.5.39) used in control mode. CHGTOL=x resets the charge tolerance of the program. The default value is 1.0e-14. CONVSTEP=x relative step limit applied to code models. CONVABSSTEP=x absolute step limit applied to code models. GMINSTEPS=x [*] sets number of Gmin steps to be attempted. If the value is set to zero, the gmin stepping algorithm is disabled. In such case the source stepping algorithm becomes the standard when the standard procedure fails to converge to a solution. INTERP interpolates output data onto fixed time steps, detemined by TSTEP (15.3.9). Uses linear interpolation between previous and next time value. Simulation itself is not influenced by this option. May be used in all simulation modes (batch, control or interactive, 16.4). This option may drastically reduce memory requirements in control mode or file size in batch mode, but be careful not to choose a too large TSTEP value, otherwise your output data may be corrupted by undersampling. See command ’linearize’ (17.5.36) in control or interactive mode to achieve similar outputs by post-processing of data. See ngspice/examples/xspice/delta-sigma/delta-sigma-1.cir how INTERP will reduce memory requirements and speeds up plotting. 15.1. SIMULATOR VARIABLES (.OPTIONS) 249 ITL3=x resets the lower transient analysis iteration limit. the default value is 4. (Note: not implemented in Spice3). ITL4=x resets the transient analysis time-point iteration limit. the default is 10. ITL5=x resets the transient analysis total iteration limit. the default is 5000. Set ITL5=0 to omit this test. (Note: not implemented in Spice3). ITL6=x [*] synonym for SRCSTEPS. MAXEVITER=x sets the number of event iterations that are allowed at an analysis point MAXOPALTER=x specifies the maximum number of analog/event alternations that the simulator can use in solving a hybrid circuit. MAXORD=x [*] specifies the maximum order for the numerical integration method used by SPICE. Possible values for the Gear method are from 2 (the default) to 6. Using the value 1 with the trapezoidal method specifies backward Euler integration. METHOD=name sets the numerical integration method used by SPICE. Possible names are ‘Gear’ or ‘trapezoidal’ (or just ‘trap’). The default is trapezoidal. NOOPALTER=TRUE|FALSE if set to false alternations between analog/event are enabled. RAMPTIME=x this options sets the rate of change of independent supplies and code model inductors and capacitors with initial conditions specified. SRCSTEPS=x [*] a non-zero value causes SPICE to use a source-stepping method to find the DC operating point. Its value specifies the number of steps. TRTOL=x resets the transient error tolerance. The default value is 7. This parameter is an estimate of the factor by which ngspice overestimates the actual truncation error. If XSPICE is enabled and ’A’ devices included, the value is internally set to 1 for higher precision. This will cost a factor of two in CPU time during transient analysis. XMU=x sets a damping factor for trapezoidal integration. The default value is XMU=0.5. A value < 0.5 may be chosen. Even a small reduction, e.g. to 0.495, may suppress trap ringing. The reduction has to be set carefully in order not to excessively damp circuits that are prone to ringing, and lead the simulation (and the user) to believe that the circuit is stable. 15.1.5 ELEMENT Specific options BADMOS3 Use the older version of the MOS3 model with the ‘kappa’ discontinuity. DEFAD=x resets the value for MOS drain diffusion area; the default is 0.0. DEFAS=x resets the value for MOS source diffusion area; the default is 0.0. DEFL=x resets the value for MOS channel length; the default is 100.0 µm. DEFW=x resets the value for MOS channel width; the default is 100.0 µm. 250 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) SCALE=x set the element scaling factor for geometric element parameters whose default unit is meters. As an example: scale=1u and a MOSFET instance parameter W=10 will result in a width of 10µm for this device. An area parameter AD=20 will result in 20e-12 m2 . Following instance parameters are scaled: • Resistors and Capacitors: W, L • Diodes: W, L, Area • JFET, MESFET: W, L, Area • MOSFET: W, L, AS, AD, PS, PD, SA, SB, SC, SD 15.1.6 Transmission Lines Specific Options TRYTOCOMPACT Applicable only to the LTRA model (see 6.2.1). When specified, the simulator tries to condense LTRA transmission line’s past history of input voltages and currents. 15.1.7 Precedence of option and .options commands There are various ways to set the above mentioned options in Ngspice. If no option or .options lines are set by the user, internal default values are given for each of the simulator variables. You may set options in the init files spinit or .spiceinit via the option command (see Chapt. 17.5.44). The values given here will supersede the default values. If you set options via the .options line in your input file, their values will supersede the default and init file data. Finally if you set options inside a .control ... .endc section, these values will supersede any values of the respective simulator variables given so far. 15.2 Initial Conditions 15.2.1 .NODESET: Specify Initial Node Voltage Guesses General form: . NODESET V( NODNUM )= VAL V( NODNUM )= VAL ... . NODESET ALL=VAL Examples: . NODESET V (12)=4.5 V (4)=2.23 . NODESET ALL =1.5 15.2. INITIAL CONDITIONS 251 The .nodeset line helps the program find the dc or initial transient solution by making a preliminary pass with the specified nodes held to the given voltages. The restriction is then released and the iteration continues to the true solution. The .nodeset line may be necessary for convergence on bistable or a-stable circuits. .nodeset all=val allows to set all starting node voltages (except for the ground node) in a single line. In general, the .nodeset line should not be necessary. 15.2.2 .IC: Set Initial Conditions General form: .ic v( nodnum )= val v( nodnum )= val ... Examples: .ic v (11)=5 v(4)= -5 v (2)=2.2 The .ic line is for setting transient initial conditions. It has two different interpretations, depending on whether the uic parameter is specified on the .tran control line. Also, one should not confuse this line with the .nodeset line. The .nodeset line is only to help dc convergence, and does not affect the final bias solution (except for multi-stable circuits). The two interpretations of this line are as follows: 1. When the uic parameter is specified on the .tran line, then the node voltages specified on the .ic control line are used to compute the capacitor, diode, BJT, JFET, and MOSFET initial conditions. This is equivalent to specifying the ic=... parameter on each device line, but is much more convenient. The ic=... parameter can still be specified and takes precedence over the .ic values. Since no dc bias (initial transient) solution is computed before the transient analysis, one should take care to specify all dc source voltages on the .ic control line if they are to be used to compute device initial conditions. 2. When the uic parameter is not specified on the .tran control line, the dc bias (initial transient) solution is computed before the transient analysis. In this case, the node voltages specified on the .ic control lines are forced to the desired initial values during the bias solution. During transient analysis, the constraint on these node voltages is removed. This is the preferred method since it allows ngspice to compute a consistent dc solution. 252 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) 15.3 Analyses 15.3.1 .AC: Small-Signal AC Analysis General form: .ac dec nd fstart fstop .ac oct no fstart fstop .ac lin np fstart fstop Examples: .ac dec 10 1 10K .ac dec 10 1K 100 MEG .ac lin 100 1 100 HZ dec stands for decade variation, and nd is the number of points per decade. oct stands for octave variation, and no is the number of points per octave. lin stands for linear variation, and np is the number of points. fstart is the starting frequency, and fstop is the final frequency. If this line is included in the input file, ngspice performs an AC analysis of the circuit over the specified frequency range. Note that in order for this analysis to be meaningful, at least one independent source must have been specified with an ac value. Typically it does not make much sense to specify more than one ac source. If you do, the result will be a superposition of all sources, thus difficult to interpret. Example: Basic RC circuit r 1 2 1.0 c 2 0 1.0 vin 1 0 dc 0 ac 1 $ <--- the ac source . options noacct .ac dec 10 .01 10 .plot ac vdb (2) xlog .end In this ac (or ’small signal’) analysis all non-linear devices are linearized around their actual dc operating point. All Ls and Cs get their imaginary value, depending on the actual frequency step. Each output vector will be calculated relative to the input voltage (current) given by the ac value (Vin equals to 1 in the example above). The resulting node voltages (and branch currents) are complex vectors. Therefore you have to be careful using the plot command. Especially you may use the variants of vxx(node) described in Chapt. 15.6.2 like vdb(2) (see example above). 15.3. ANALYSES 15.3.2 253 .DC: DC Transfer Function General form: .dc srcnam vstart vstop vincr [src2 start2 stop2 incr2] Examples: .dc .dc .dc .dc .dc VIN 0.25 VDS 0 10 VCE 0 10 RLoad 1k TEMP -15 5.0 0.25 .5 VGS 0 5 1 .25 IB 0 10u 1u 2k 100 75 5 The .dc line defines the dc transfer curve source and sweep limits (again with capacitors open and inductors shorted). srcnam is the name of an independent voltage or current source, a resistor or the circuit temperature. vstart, vstop, and vincr are the starting, final, and incrementing values respectively. The first example causes the value of the voltage source VIN to be swept from 0.25 Volts to 5.0 Volts in increments of 0.25 Volts. A second source (src2) may optionally be specified with associated sweep parameters. In this case, the first source is swept over its range for each value of the second source. This option can be useful for obtaining semiconductor device output characteristics. See the example circuit description on transistor characteristics (21.3). 15.3.3 .DISTO: Distortion Analysis General form: .disto dec nd fstart fstop .disto oct no fstart fstop .disto lin np fstart fstop Examples: .disto dec 10 1kHz 100 MEG .disto dec 10 1kHz 100 MEG 0.9 The .disto line does a small-signal distortion analysis of the circuit. A multi-dimensional Volterra series analysis is done using multi-dimensional Taylor series to represent the nonlinearities at the operating point. Terms of up to third order are used in the series expansions. If the optional parameter f2overf1 is not specified, .disto does a harmonic analysis - i.e., it analyses distortion in the circuit using only a single input frequency F1 , which is swept as specified by arguments of the .disto command exactly as in the .ac command. Inputs at this frequency may be present at more than one input source, and their magnitudes and phases are specified by the arguments of the distof1 keyword in the input file lines for the input sources 254 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) (see the description for independent sources). (The arguments of the distof2 keyword are not relevant in this case). The analysis produces information about the AC values of all node voltages and branch currents at the harmonic frequencies 2F1 and , vs. the input frequency F1 as it is swept. (A value of 1 (as a complex distortion output) signifies cos(2π(2F1 )t) at 2F1 and cos(2π(3F1 )t) at 3F1 , using the convention that 1 at the input fundamental frequency is equivalent to cos(2πF1t).) The distortion component desired (2F1 or 3F1 ) can be selected using commands in ngnutmeg, and then printed or plotted. (Normally, one is interested primarily in the magnitude of the harmonic components, so the magnitude of the AC distortion value is looked at). It should be noted that these are the AC values of the actual harmonic components, and are not equal to HD2 and HD3. To obtain HD2 and HD3, one must divide by the corresponding AC values at F1 , obtained from an .ac line. This division can be done using ngnutmeg commands. If the optional f2overf1 parameter is specified, it should be a real number between (and not equal to) 0.0 and 1.0; in this case, .disto does a spectral analysis. It considers the circuit with sinusoidal inputs at two different frequencies F1 and F2 . F1 is swept according to the .disto control line options exactly as in the .ac control line. F2 is kept fixed at a single frequency as F1 sweeps - the value at which it is kept fixed is equal to f2overf1 times fstart. Each independent source in the circuit may potentially have two (superimposed) sinusoidal inputs for distortion, at the frequencies F1 and F2 . The magnitude and phase of the F1 component are specified by the arguments of the distof1 keyword in the source’s input line (see the description of independent sources); the magnitude and phase of the F2 component are specified by the arguments of the distof2 keyword. The analysis produces plots of all node voltages/branch currents at the intermodulation product frequencies F1 + F2 , F1 − F2 , and (2F1 ) − F2 , vs the swept frequency F1 . The IM product of interest may be selected using the setplot command, and displayed with the print and plot commands. It is to be noted as in the harmonic analysis case, the results are the actual AC voltages and currents at the intermodulation frequencies, and need to be normalized with respect to .ac values to obtain the IM parameters. If the distof1 or distof2 keywords are missing from the description of an independent source, then that source is assumed to have no input at the corresponding frequency. The default values of the magnitude and phase are 1.0 and 0.0 respectively. The phase should be specified in degrees. It should be carefully noted that the number f2overf1 should ideally be an irrational number, and that since this is not possible in practice, efforts should be made to keep the denominator in its fractional representation as large as possible, certainly above 3, for accurate results (i.e., if f2overf1 is represented as a fraction A/B, where A and B are integers with no common factors, B should be as large as possible; note that A < B because f2overf1 is constrained to be < 1). To illustrate why, consider the cases where f2overf1 is 49/100 and 1/2. In a spectral analysis, the outputs produced are at F1 + F2 , F1 − F2 and 2F1 − F2 . In the latter case, F1 − F2 = F2 , so the result at the F1 − F2 component is erroneous because there is the strong fundamental F2 component at the same frequency. Also, F1 + F2 = 2F1 − F2 in the latter case, and each result is erroneous individually. This problem is not there in the case where f2overf1 = 49/100, because F1 − F2 = 51/100 F1 <> 49/100 F1 = F2 . In this case, there are two very closely spaced frequency components at F2 and F1 − F2 . One of the advantages of the Volterra series technique is that it computes distortions at mix frequencies expressed symbolically (i.e. nF1 + mF2 ), therefore one is able to obtain the strengths of distortion components accurately even if the separation between them is very small, as opposed to transient analysis for example. The disadvantage is of course that if two of the mix frequencies coincide, the results are not 15.3. ANALYSES 255 merged together and presented (though this could presumably be done as a postprocessing step). Currently, the interested user should keep track of the mix frequencies himself or herself and add the distortions at coinciding mix frequencies together should it be necessary. Only a subset of the ngspice nonlinear device models supports distortion analysis. These are • Diodes (DIO), • BJT, • JFET (level 1), • MOSFETs (levels 1, 2, 3, 9, and BSIM1), • MESFET (level 1). 15.3.4 .NOISE: Noise Analysis General form: .noise v( output <,ref >) src ( dec | lin | oct ) pts fstart fstop + Examples: .noise v(5) VIN dec 10 1kHz 100 MEG .noise v(5 ,3) V1 oct 8 1.0 1.0 e6 1 The .noise line does a noise analysis of the circuit. output is the node at which the total output noise is desired; if ref is specified, then the noise voltage v(output) - v(ref) is calculated. By default, ref is assumed to be ground. src is the name of an independent source to which input noise is referred. pts, fstart and fstop are .ac type parameters that specify the frequency range over which plots are desired. pts_per_summary is an optional integer; if specified, the noise contributions of each noise generator is produced every pts_per_summary frequency points. The .noise control line produces two plots: √ Hz 1. one for the Noise Spectral Density (in V/ √ Hz or A/ ) curves and 2. one for the total Integrated Noise (in V or A) over the specified frequency range. 15.3.5 .OP: Operating Point Analysis General form: .op The inclusion of this line in an input file directs ngspice to determine the dc operating point of the circuit with inductors shorted and capacitors opened. 256 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) Note: a DC analysis is automatically performed prior to a transient analysis to determine the transient initial conditions, and prior to an AC small-signal, Noise, and Pole-Zero analysis to determine the linearized, small-signal models for nonlinear devices (see the KEEPOPINFO variable 15.1.2). 15.3.6 .PZ: Pole-Zero Analysis General form: .pz .pz .pz .pz .pz .pz node1 node1 node1 node1 node1 node1 node2 node2 node2 node2 node2 node2 node3 node3 node3 node3 NODE3 node3 node4 node4 node4 node4 node4 node4 cur cur cur vol vol vol pol zer pz pol zer pz Examples: .pz 1 0 3 0 cur pol .pz 2 3 5 0 vol zer .pz 4 1 4 1 cur pz cur stands for a transfer function of the type (output voltage)/(input current) while vol stands for a transfer function of the type (output voltage)/(input voltage). pol stands for pole analysis only, zer for zero analysis only and pz for both. This feature is provided mainly because if there is a non-convergence in finding poles or zeros, then, at least the other can be found. Finally, node1 and node2 are the two input nodes and node3 and node4 are the two output nodes. Thus, there is complete freedom regarding the output and input ports and the type of transfer function. In interactive mode, the command syntax is the same except that the first field is pz instead of .pz. To print the results, one should use the command print all. 15.3. ANALYSES 15.3.7 257 .SENS: DC or Small-Signal AC Sensitivity Analysis General form: .SENS .SENS .SENS .SENS OUTVAR OUTVAR AC DEC ND FSTART FSTOP OUTVAR AC OCT NO FSTART FSTOP OUTVAR AC LIN NP FSTART FSTOP Examples: .SENS V(1, OUT) .SENS V(OUT) AC DEC 10 100 100k .SENS I( VTEST ) The sensitivity of OUTVAR to all non-zero device parameters is calculated when the SENS analysis is specified. OUTVAR is a circuit variable (node voltage or voltage-source branch current). The first form calculates sensitivity of the DC operating-point value of OUTVAR. The second form calculates sensitivity of the AC values of OUTVAR. The parameters listed for AC sensitivity are the same as in an AC analysis (see .AC above). The output values are in dimensions of change in output per unit change of input (as opposed to percent change in output or per percent change of input). 15.3.8 .TF: Transfer Function Analysis General form: .tf outvar insrc Examples: .tf v(5, 3) VIN .tf i( VLOAD ) VIN The .tf line defines the small-signal output and input for the dc small-signal analysis. outvar is the small signal output variable and insrc is the small-signal input source. If this line is included, ngspice computes the dc small-signal value of the transfer function (output/input), input resistance, and output resistance. For the first example, ngspice would compute the ratio of V(5, 3) to VIN, the small-signal input resistance at VIN, and the small signal output resistance measured across nodes 5 and 3. 258 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) 15.3.9 .TRAN: Transient Analysis General form: .tran tstep tstop > Examples: .tran 1ns 100 ns .tran 1ns 1000 ns 500 ns .tran 10 ns 1us tstep is the printing or plotting increment for line-printer output. For use with the postprocessor, tstep is the suggested computing increment. tstop is the final time, and tstart is the initial time. If tstart is omitted, it is assumed to be zero. The transient analysis always begins at time zero. In the interval , the circuit is analyzed (to reach a steady state), but no outputs are stored. In the interval , the circuit is analyzed and outputs are stored. tmax is the maximum stepsize that ngspice uses; for default, the program chooses either tstep or (tstop-tstart)/50.0, whichever is smaller. tmax is useful when one wishes to guarantee a computing interval that is smaller than the printer increment, tstep. An initial transient operating point at time zero is calculated according to the following procedure: all independent voltages and currents are applied with their time zero values, all capacitances are opened, inductances are shorted, the non linear device equations are solved iteratively. uic (use initial conditions) is an optional keyword that indicates that the user does not want ngspice to solve for the quiescent operating point before beginning the transient analysis. If this keyword is specified, ngspice uses the values specified using IC=... on the various elements as the initial transient condition and proceeds with the analysis. If the .ic control line has been specified (see 15.2.2), then the node voltages on the .ic line are used to compute the initial conditions for the devices. IC=... will take precedence over the values given in the .ic control line. If neither IC=... nor the .ic control line is given for a specific node, node voltage zero is assumed. Look at the description on the .ic control line (15.2.2) for its interpretation when uic is not specified. 15.3.10 Transient noise analysis (at low frequency) In contrast to the analysis types described above the transient noise simulation (noise current or voltage versus time) is not implemented as a dot command, but is integrated with the independent voltage source vsrc (isrc not yet available) (see 4.1.7) and used in combination with the .tran transient analysis (15.3.9). Transient noise analysis deals with noise currents or voltages added to your circuits as a time dependent signal of randomly generated voltage excursion on top of a fixed dc voltage. The sequence of voltage values has random amplitude, but equidistant time intervals, selectable by the user (parameter NT). The resulting voltage waveform is differentiable and thus does not require any modifications of the matrix solving algorithms. 15.3. ANALYSES 259 White noise is generated by the ngspice random number generator, applying the Box-Muller transform. Values are generated on the fly, each time when a breakpoint is hit. The 1/f noise is generated with an algorithm provided by N. J. Kasdin (‘Discrete simulation of colored noise and stochastic processes and 1/ f a power law noise generation’, Proceedings of the IEEE, Volume 83, Issue 5, May 1995 Page(s):802–827). The noise sequence (one for each voltage/current source with 1/f selected) is generated upon start up of the simulator and stored for later use. The number of points is determined by the total simulation time divided by NT, rounded up the the nearest power of 2. Each time a breakpoint (n ? NT , relevant to the noise signal) is hit, the next value is retrieved from the sequence. If you want a random, but reproducible sequence, you may select a seed value for the random number generator by adding set rndseed=nn to the spinit or .spiceinit file, nn being a positive integer number. The transient noise analysis will allow the simulation of the three most important noise sources. Thermal noise is described by the Gaussian white noise. Flicker noise (pink noise or 1 over f noise) with an exponent between 0 and 2 is provided as well. Shot noise is dependent on the current flowing through a device and may be simulated by applying a non-linear source as demonstrated in the following example: Example: * Shot noise test with B source , diode * voltage on device (diode , forward ) Vdev out 0 DC 0 PULSE (0.4 0.45 10u) * diode , forward direction , to be modeled with noise D1 mess 0 DMOD .model DMOD D IS =1e -14 N=1 X1 0 mess out ishot * device between 1 and 2 * new output terminals of device including noise: 1 and 3 . subckt ishot 1 2 3 * white noise source with rms 1V * 20000 sample points VNG 0 11 DC 0 TRNOISE (1 1n 0 0) * measure the current i(v1) V1 2 3 DC 0 * calculate the shot noise * sqrt (2* current *q* bandwidth ) BI 1 3 I=sqrt (2* abs(i(v1 ))*1.6e -19*1 e7)*v(11) .ends ishot .tran 1n 20u . control run plot ( -1)*i(vdev) .endc .end 260 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) The selection of the delta time step (NT) is worth discussing. Gaussian white noise has unlimited bandwidth and thus unlimited energy content. This is unrealistic. The bandwidth of real noise is limited, but it is still called ‘White’ if it is the same level throughout the frequency range of interest, e.g. the bandwidth of your system. Thus you may select NT to be a factor of 10 smaller than the frequency limit of your circuit. A thorough analysis is still needed to clarify the appropriate factor. The transient method is probably most suited to circuits including switches, which are not amenable to the small signal .NOISE analysis (Chapt. 15.3.4). There is a price you have to pay for transient noise analysis: the number of required time steps, and thus the simulation time, increases. In addition to white and 1/f noise the independent voltage and current sources offer a random telegraph signal (RTS) noise source, also known as burst noise or popcorn noise, again for transient analysis. For each voltage (current) source offering RTS noise an individual noise amplitude is required for input, as well as a mean capture time and a mean emission time. The amplitude resembles the influence of a single trap on the current or voltage. The capture and emission times emulate the filling and emptying of the trap, typically following a Poisson process. They are generated from an random exponential distribution with respective mean values given by the user. To simulate an ensemble of traps, you may combine several current or voltage sources with different parameters. All three sources (white, 1/f, and RTS) may be combined in a single command line. 15.3. ANALYSES 261 RTS noise example: * white noise , 1/f noise , RTS noise * voltage source VRTS2 13 12 DC 0 trnoise (0 0 0 0 5m 18u 30u) VRTS3 11 0 DC 0 trnoise (0 0 0 0 10m 20u 40u) VALL 12 11 DC 0 trnoise (1m 1u 1.0 0.1m 15m 22u 50u) VW1of 21 0 DC trnoise (1m 1u 1.0 0.1m) * current source IRTS2 10 0 DC 0 trnoise (0 0 0 0 5m 18u 30u) IRTS3 10 0 DC 0 trnoise (0 0 0 0 10m 20u 40u) IALL 10 0 DC 0 trnoise (1m 1u 1.0 0.1m 15m 22u 50u) R10 10 0 1 IW1of 9 0 DC Rall 9 0 1 trnoise (1m 1u 1.0 0.1m) * sample points .tran 1u 500u . control run plot v(13) v(21) plot v(10) v(9) .endc .end Some details on RTS noise modeling are available in a recent article [20], available here. This transient noise feature is still experimental. The following questions (among others) are to be solved: • clarify the theoretical background • noise limit of plain ngspice (numerical solver, fft etc.) • time step (NT) selection • calibration of noise spectral density • how to generate noise from a transistor model • application benefits and limits 262 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) 15.3.11 .PSS: Periodic Steady State Analysis Experimental code, not yet made publicly available. General form: .pss gfreq tstab oscnob psspoints harms sciter steadycoeff Examples: .pss 150 200e -3 2 1024 11 50 5e-3 uic .pss 624 e6 1u v_plus 1024 10 150 5e-3 uic .pss 624 e6 500n bout 1024 10 100 5e-3 uic gfreq is guessed frequency of fundamental suggested by user. When performing transient analysis the PSS algorithm tries to infer a new rough guess rgfreq on the fundamental. If gfreq is out of ±10% with respect to rgfreq then gfreq is discarded. tstab is stabilization time before the shooting begin to search for the PSS. It has to be noticed that this parameter heavily influence the possibility to reach the PSS. Thus is a good practice to ensure a circuit to have a right tstab, e.g. performing a separate TRAN analysis before to run PSS analysis. oscnob is the node or branch where the oscillation dynamic is expected. PSS analysis will give a brief report of harmonic content at this node or branch. psspoints is number of step in evaluating predicted period after convergence is reached. It is useful only in Time Domain plots. However this number should be higher than 2 times the requested harms. Otherwise the PSS analysis will properly adjust it. harms number of harmonics to be calculated as requested by the user. sciter number of allowed shooting cycle iterations. Default is 50. steady_coeff is the weighting coefficient for calculating the Global Convergence Error (GCE), which is the reference value in order to infer is convergence is reached. The lower steady_coeff is set, the higher the accuracy of predicted frequency can be reached but at longer analysis time and sciter number. Default is 1e-3. uic (use initial conditions) is an optional keyword that indicates that the user does not want ngspice to solve for the quiescent operating point before beginning the transient analysis. If this keyword is specified, ngspice uses the values specified using IC=... on the various elements as the initial transient condition and proceeds with the analysis. If the .ic control line has been specified, then the node voltages on the .ic line are used to compute the initial conditions for the devices. Look at the description on the .ic control line for its interpretation when uic is not specified. 15.4. MEASUREMENTS AFTER AC, DC AND TRANSIENT ANALYSIS 15.4 Measurements after AC, DC and Transient Analysis 15.4.1 .meas(ure) 263 The .meas or .measure statement (and its equivalent meas command, see Chapt. 17.5.39) are used to analyze the output data of a tran, ac, or dc simulation. The command is executed immediately after the simulation has finished. 15.4.2 batch versus interactive mode .meas analysis may not be used in batch mode (-b command line option), if an output file (rawfile) is given at the same time (-r rawfile command line option). In this batch mode ngspice will write its simulation output data directly to the output file. The data is not kept in memory, thus is no longer available for further analysis. This is made to allow a very large output stream with only a relatively small memory usage. For .meas to be active you need to run the batch mode with a .plot or .print command. A better alternative may be to start ngspice in interactive mode. If you need batch like operation, you may add a .control ... file: .endc section to the input Example: *input file ... .tran 1ns 1000 ns ... ********************************* . control run write outputfile data .endc ********************************* .end and start ngspice in interactive mode, e.g. by running the command ngspice inputfile . .meas then prints its user-defined data analysis to the standard output. The analysis includes propagation, delay, rise time, fall time, peak-to-peak voltage, minimum or maximum voltage, the integral or derivative over a specified period and several other user defined values. 15.4.3 General remarks The measure type {DC|AC|TRAN|SP} depends on the data that is to be evaluated, either originating from a dc analysis, an ac analysis, or a transient simulation. The type SP to analyze a spectrum from the spec or fft commands is only available when executed in a meas command, see 17.5.39. 264 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) result will be a vector containing the result of the measurement. trig_variable, targ_variable, and out_variable are vectors stemming from the simulation, e.g. a voltage vector v(out). VAL=val expects a real number val. It may be as well a parameter delimited by ” or {} expanding to a real number. TD=td and AT=time expect a time value if measure type is tran. For ac and sp AT will be a frequency value, TD is ignored. For dc analysis AT is a voltage (or current), TD is ignored as well. CROSS=# requires an integer number #. CROSS=LAST is possible as well. The same is expected by RISE and FALL. Frequency and time values may start at 0 and extend to positive real numbers. Voltage (or current) inputs for the independent (scale) axis in a dc analysis may start or end at arbitrary real valued numbers. Please note that not all of the .measure commands have been implemented. 15.4.4 Input In the following lines you will get some explanation on the .measure commands. A simple simulation file with two sines of different frequencies may serve as an example. The transient simulation delivers time as the independent variable and two voltages as output (dependent variables). Input file: File: simple -meas -tran.sp * Simple . measure examples * transient simulation of two sine * signals with different frequencies vac1 1 0 DC 0 sin (0 1 1k 0 0) vac2 2 0 DC 0 sin (0 1.2 0.9k 0 0) .tran 10u 5m * . measure tran ... $ for the different inputs see below! * . control run plot v(1) v(2) .endc .end After displaying the general syntax of the .measure statement, some examples are posted, referring to the input file given above. 15.4.5 Trig Targ .measure according to general form 1 measures the difference in dc voltage, frequency or time between two points selected from one or two output vectors. The current examples all are using 15.4. MEASUREMENTS AFTER AC, DC AND TRANSIENT ANALYSIS 265 transient simulation. Measurements for tran analysis start after a delay time td. If you run other examples with ac simulation or spectrum analysis, time may be replaced by frequency, after a dc simulation the independent variable may become a voltage or current. General form 1: . MEASURE {DC|AC|TRAN|SP} result TRIG trig_variable VAL= val + + TARG targ_variable + VAL=val Measure statement example (for use in the input file given above): .measure tran tdiff TRIG v(1) VAL=0.5 RISE=1 TARG v(1) VAL=0.5 RISE=2 measures the time difference between v(1) reaching 0.5 V for the first time on its first rising slope (TRIG) versus reaching 0.5 V again on its second rising slope (TARG), i.e. it measures the signal period. Output: tdiff = 1.000000e-003 targ= 1.083343e-003 trig= 8.334295e-005 Measure statement example: .measure tran tdiff TRIG v(1) VAL=0.5 RISE=1 TARG v(1) VAL=0.5 RISE=3 measures the time difference between v(1) reaching 0.5 V for the first time on its rising slope versus reaching 0.5 V on its rising slope for the third time (i.e. two periods). Measure statement: .measure tran tdiff TRIG v(1) VAL=0.5 RISE=1 TARG v(1) VAL=0.5 FALL=1 measures the time difference between v(1) reaching 0.5V for the first time on its rising slope versus reaching 0.5 V on its first falling slope. Measure statement: .measure tran tdiff TRIG v(1) VAL=0 FALL=3 TARG v(2) VAL=0 FALL=3 measures the time difference between v(1) reaching 0V its third falling slope versus v(2) reaching 0 V on its third falling slope. Measure statement: .measure tran tdiff TRIG v(1) VAL=-0.6 CROSS=1 TARG v(2) VAL=-0.8 CROSS=1 measures the time difference between v(1) crossing -0.6 V for the first time (any slope) versus v(2) crossing -0.8 V for the first time (any slope). Measure statement: .measure tran tdiff TRIG AT=1m TARG v(2) VAL=-0.8 CROSS=3 measures the time difference between the time point 1ms versus the time when v(2) crosses -0.8 V for the third time (any slope). 266 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) 15.4.6 Find ... When The FIND and WHEN functions allow to measure any dependent or independent time, frequency, or dc parameter, when two signals cross each other or a signal crosses a given value. Measurements start after a delay TD and may be restricted to a range between FROM and TO. General form 2: . MEASURE {DC|AC|TRAN|SP} result WHEN out_variable =val + + Measure statement: .measure tran teval WHEN v(2)=0.7 CROSS=LAST measures the time point when v(2) crosses 0.7 V for the last time (any slope). General form 3: . MEASURE {DC|AC|TRAN|SP} result + WHEN out_variable = out_variable2 + + Measure statement: .measure tran teval WHEN v(2)=v(1) RISE=LAST measures the time point when v(2) and v(1) are equal, v(2) rising for the last time. General form 4: . MEASURE {DC|AC|TRAN|SP} result FIND out_variable + WHEN out_variable2 =val + + Measure statement: .measure tran yeval FIND v(2) WHEN v(1)=-0.4 FALL=LAST returns the dependent (y) variable drawn from v(2) at the time point when v(1) equals a value of -0.4, v(1) falling for the last time. General form 5: . MEASURE {DC|AC|TRAN|SP} result FIND out_variable + WHEN out_variable2 = out_variable3 + + Measure statement: .measure tran yeval FIND v(2) WHEN v(1)=v(3) FALL=2 15.4. MEASUREMENTS AFTER AC, DC AND TRANSIENT ANALYSIS 267 returns the dependent (y) variable drawn from v(2) at the time point when v(1) crosses v(3), v(1) falling for the second time. General form 6: . MEASURE {DC|AC|TRAN|SP} result FIND out_variable AT= val Measure statement: .measure tran yeval FIND v(2) AT=2m returns the dependent (y) variable drawn from v(2) at the time point 2 ms (given by AT=time). 15.4.7 AVG|MIN|MAX|PP|RMS|MIN_AT|MAX_AT General form 7: . MEASURE {DC|AC|TRAN|SP} result + {AVG|MIN|MAX|PP|RMS| MIN_AT | MAX_AT } + out_variable Measure statements: .measure tran ymax MAX v(2) from=2m to=3m returns the maximum value of v(2) inside the time interval between 2 ms and 3 ms. .measure tran tymax MAX_AT v(2) from=2m to=3m returns the time point of the maximum value of v(2) inside the time interval between 2 ms and 3 ms. .measure tran ypp PP v(1) from=2m to=4m returns the peak to peak value of v(1) inside the time interval between 2 ms and 4 ms. .measure tran yrms RMS v(1) from=2m to=4m returns the root mean square value of v(1) inside the time interval between 2 ms and 4 ms. .measure tran yavg AVG v(1) from=2m to=4m returns the average value of v(1) inside the time interval between 2 ms and 4 ms. 15.4.8 Integ General form 8: . MEASURE {DC|AC|TRAN|SP} result INTEG out_variable + Measure statement: .measure tran yint INTEG v(2) from=2m to=3m returns the area under v(2) inside the time interval between 2 ms and 3 ms. 268 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) 15.4.9 param General form 9: . MEASURE {DC|AC|TRAN|SP} result param=’expression ’ Measure statement: .param fval=5 .measure tran yadd param=’fval + 7’ will evaluate the given expression fval + 7 and return the value 12. ’Expression’ is evaluated according to the rules given in Chapt. 2.8.5 during start up of ngspice. It may contain parameters defined with the .param statement. It may also contain parameters resulting from preceding .meas statements. .param vout_diff=50u ... .measure tran tdiff TRIG AT=1m TARG v(2) VAL=-0.8 CROSS=3 .meas tran bw_chk param=’(tdiff < vout_diff) ? 1 : 0’ will evaluate the given ternary function and return the value 1 in bw_chk, if tdiff measured is smaller than parameter vout_diff. The expression may not contain vectors like v(10), e.g. anything resulting directly from a simulation. This may be handled with the following .meas command option. 15.4.10 par(’expression’) The par(’expression’) option (15.6.6) allows to use algebraic expressions on the .measure lines. Every out_variable may be replaced by par(’expression’) using the general forms 1. . . 9 described above. Internally par(’expression’) is substituted by a vector according to the rules of the B source (Chapt. 5.1). A typical example of the general form is shown below: General form 10: . MEASURE {DC|TRAN|AC|SP} result + FIND par(’ expression ’) AT=val The measure statement .measure tran vtest find par(’(v(2)*v(1))’) AT=2.3m returns the product of the two voltages at time point 2.3 ms. Note that a B-source, and therefore the par(’...’) feature, operates on values of type complex in AC analysis mode. 15.4. MEASUREMENTS AFTER AC, DC AND TRANSIENT ANALYSIS 15.4.11 269 Deriv General form: . MEASURE {DC|AC|TRAN|SP} result DERIV out_variable + AT=val . MEASURE {DC|AC|TRAN|SP} result DERIV out_variable + WHEN out_variable2 =val + + . MEASURE {DC|AC|TRAN|SP} result DERIV out_variable + WHEN out_variable2 = out_variable3 + + 15.4.12 More examples Some other examples, also showing the use of parameters, are given below. Corresponding demonstration input files are distributed with ngspice in folder /examples/measure. 270 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) Other examples: .meas tran inv_delay2 trig v(in) val=’vp/2’ td=1n fall =1 + targ v(out) val=’vp/2’ rise =1 .meas tran test_data1 trig AT = 1n targ v(out) + val=’vp/2’ rise =3 .meas tran out_slew trig v(out) val = ’0.2*vp ’ rise =2 + targ v(out) val = ’0.8*vp ’ rise =2 .meas tran delay_chk param =’( inv_delay < 100 ps) ? 1 : 0’ .meas tran skew when v(out)=0.6 .meas tran skew2 when v(out)= skew_meas .meas tran skew3 when v(out)= skew_meas fall =2 .meas tran skew4 when v(out)= skew_meas fall=LAST .meas tran skew5 FIND v(out) AT=2n .meas tran v0_min min i(v0) + from=’dfall ’ to=’dfall+period ’ .meas tran v0_avg avg i(v0) + from=’dfall ’ to=’dfall+period ’ .meas tran v0_integ integ i(v0) + from=’dfall ’ to=’dfall+period ’ .meas tran v0_rms rms i(v0) + from=’dfall ’ to=’dfall+period ’ .meas dc is_at FIND i(vs) AT=1 .meas dc is_max max i(vs) from =0 to =3.5 .meas dc vds_at when i(vs)=0.01 .meas ac vout_at FIND v(out) AT=1 MEG .meas ac vout_atd FIND vdb(out) AT=1 MEG .meas ac vout_max max v(out) from =1k to =10 MEG .meas ac freq_at when v(out)=0.1 .meas ac vout_diff trig v(out) val =0.1 rise =1 targ v( out) + val =0.1 fall =1 .meas ac fixed_diff trig AT = 10k targ v(out) + val =0.1 rise =1 .meas ac vout_avg avg v(out) from =10k to=1 MEG .meas ac vout_integ integ v(out) from =20k to =500k .meas ac freq_at2 when v(out)=0.1 fall=LAST .meas ac bw_chk param =’( vout_diff < 100k) ? 1 : 0’ .meas ac vout_rms rms v(out) from =10 to=1G 15.5 Safe Operating Area (SOA) warning messages By setting .option warn=1 the Safe Operation Area check algorithm is enabled. In this case for .op, .dc and .tran analysis warning messages are issued if the branch voltages of devices 15.5. SAFE OPERATING AREA (SOA) WARNING MESSAGES 271 (Resistors, Capacitors, Diodes, BJTs and MOSFETs) exceed limits that are specified by model parameters. All these parameters are positive with default value of infinity. The check is executed after Newton-Raphson iteration is finished i.e. in transient analysis in each time step. The user can specify an additional .option maxwarns (default: 5) to limit the count of messages. The output goes on default to stdout or alternatively to a file specified by command line option --soa-log=filename. 15.5.1 Resistor and Capacitor SOA model parameters 1. Bv_max: 15.5.2 if |Vr| or |Vc| exceed Bv_max, SOA warning is issued. Diode SOA model parameter 1. Bv_max: if |Vj| exceeds Bv_max, SOA warning is issued. 2. Fv_max: if |Vf| exceeds Fv_max, SOA warning is issued. 15.5.3 BJT SOA model parameter 1. Vbe_max: if |Vbe| exceeds Vbe_max, SOA warning is issued. 2. Vbc_max: if |Vbc| exceeds Vbc_max, SOA warning is issued. 3. Vce_max: if |Vce| exceeds Vce_max, SOA warning is issued. 4. Vcs_max: if |Vcs| exceeds Vcs_max, SOA warning is issued. 15.5.4 MOS SOA model parameter 1. Vgs_max: if |Vgs| exceeds Vgs_max, SOA warning is issued. 2. Vgd_max: if |Vgd| exceeds Vgd_max, SOA warning is issued. 3. Vgb_max: if |Vgb| exceeds Vgb_max, SOA warning is issued. 4. Vds_max: if |Vds| exceeds Vds_max, SOA warning is issued. 5. Vbs_max: if |Vbs| exceeds Vbs_max, SOA warning is issued. 6. Vbd_max: if |Vbd| exceeds Vbd_max, SOA warning is issued. 272 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) 15.6 Batch Output The following commands .print (15.6.2), .plot (15.6.3) and .four (15.6.4) are valid only if ngspice is started in batch mode (see 16.4.1), whereas .save and the equivalent .probe are aknowledged in all operating modes. If you start ngspice in batch mode using the -b command line option, the outputs of .print, .plot, and .four are printed to the console output. You may use the output redirection of your shell to direct this printout into a file (not available with MS Windows GUI). As an alternative you may extend the ngspice command by specifying an output file: ngspice -b -o output.log input.cir If you however add the command line option -r to create a rawfile, .print and .plot are ignored. If you want to involve the graphics plot output of ngspice, use the control mode (16.4.3) instead of the -b batch mode option. 15.6.1 .SAVE: Name vector(s) to be saved in raw file General form: .save vector vector vector ... Examples: .save i(vin) node1 v( node2) .save @m1[id] vsource # branch .save all @m2[ vdsat ] The vectors listed on the .SAVE line are recorded in the rawfile for use later with ngspice or ngnutmeg (ngnutmeg is just the data-analysis half of ngspice, without the ability to simulate). The standard vector names are accepted. Node voltages may be saved by giving the nodename or v(nodename). Currents through an independent voltage source are given by i(sourcename) or sourcename#branch. Internal device data are accepted as @dev[param]. If no .SAVE line is given, then the default set of vectors is saved (node voltages and voltage source branch currents). If .SAVE lines are given, only those vectors specified are saved. For more discussion on internal device data, e.g. @m1[id], see Appendix, Chapt. 31.1. If you want to save internal data in addition to the default vector set, add the parameter all to the additional vectors to be saved. If the command .save vm(out) is given, and you store the data in a rawfile, only the original data v(out) are stored. The request for storing the magnitude is ignored, because this may be added later during rawfile data evaluation with ngnutmeg or ngspice. See also the section on the interactive command interpreter (Chapt. 17.5) for information on how to use the rawfile. 15.6. BATCH OUTPUT 15.6.2 273 .PRINT Lines General form: .print prtype ov1 Examples: .print tran v(4) i(vin) .print dc v(2) i(vsrc) v(23, 17) .print ac vm(4, 2) vr (7) vp(8, 3) The .print line defines the contents of a tabular listing of one to eight output variables. prtype is the type of the analysis (DC, AC, TRAN, NOISE, or DISTO) for which the specified outputs are desired. The form for voltage or current output variables is the same as given in the previous section for the print command; Spice2 restricts the output variable to the following forms (though this restriction is not enforced by ngspice): V(N1<,N2>) I(VXXXXXXX) specifies the voltage difference between nodes N1 and N2. If N2 (and the preceding comma) is omitted, ground (0) is assumed. See the print command in the previous section for more details. For compatibility with SPICE2, the following five additional values can be accessed for the ac analysis by replacing the ‘V’ in V(N1,N2) with: VR Real part VI Imaginary part VM Magnitude VP Phase VDB 20log10(magnitude) specifies the current flowing in the independent voltage source named VXXXXXXX. Positive current flows from the positive node, through the source, to the negative node. (Not yet implemented: For the ac analysis, the corresponding replacements for the letter I may be made in the same way as described for voltage outputs.) Output variables for the noise and distortion analyses have a different general form from that of the other analyses. There is no limit on the number of .print lines for each type of analysis. The par(’expression’) option (15.6.6) allows to use algebraic expressions in the .print lines. .width (15.6.7) selects the maximum number of characters per line. 15.6.3 .PLOT Lines .plot creates a printer plot output. 274 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) General form: .plot pltype ov1 <(plo1 , phi1)> ... ov8 > Examples: .plot .plot .plot .plot .plot dc v(4) v(5) v(1) tran v(17 , 5) (2, 5) i(vin) v(17) (1, 9) ac vm (5) vm (31 , 24) vdb (5) vp (5) disto hd2 hd3(R) sim2 tran v(5, 3) v(4) (0, 5) v(7) (0, 10) The .plot line defines the contents of one plot of from one to eight output variables. pltype is the type of analysis (DC, AC, TRAN, NOISE, or DISTO) for which the specified outputs are desired. The syntax for the ovi is identical to that for the .print line and for the plot command in the interactive mode. The overlap of two or more traces on any plot is indicated by the letter ‘X’. When more than one output variable appears on the same plot, the first variable specified is printed as well as plotted. If a printout of all variables is desired, then a companion .print line should be included. There is no limit on the number of .plot lines specified for each type of analysis. The par(’expression’) option (15.6.6) allows to use algebraic expressions in the .plot lines. 15.6.4 .FOUR: Fourier Analysis of Transient Analysis Output General form: .four freq ov1 Examples: .four 100K v(5) The .four (or Fourier) line controls whether ngspice performs a Fourier analysis as a part of the transient analysis. freq is the fundamental frequency, and ov1 is the desired vector to be analyzed. The Fourier analysis is performed over the interval , where TSTOP is the final time specified for the transient analysis, and period is one period of the fundamental frequency. The dc component and the first nine harmonics are determined. For maximum accuracy, TMAX (see the .tran line) should be set to period/100.0 (or less for very high-Q circuits). The par(’expression’) option (15.6.6) allows to use algebraic expressions in the .four lines. 15.6. BATCH OUTPUT 15.6.5 275 .PROBE: Name vector(s) to be saved in raw file General form: .probe vector Examples: .probe i(vin) input output .probe @m1[id] Same as .SAVE (see Chapt. 15.6.1). 15.6.6 par(’expression’): Algebraic expressions for output General form: par(’ expression ’) output =par(’ expression ’) $ not in . measure ac Examples: .four 1001 sq1=par(’v(1)*v(1) ’) . measure tran vtest find par (’(v(2)*v(1)) ’) AT =2.3m .print tran output =par(’v(1)/v(2) ’) v(1) v(2) .plot dc v(1) diff=par (’(v(4)-v (2))/0.01 ’) out222 With the output lines .four, .plot, .print, .save and in .measure evaluation it is possible to add algebraic expressions for output, in addition to vectors. All of these output lines accept par(’expression’), where expression is any expression valid for a B source (see Chapt. 5.1). Thus expression may contain predefined functions, numerical values, constants, simulator output like v(n1) or i(vdb), parameters predefined by a .param statement, and the variables hertz, temper, and time. Note that a B-source, and therefore the par(’...’) feature, operates on values of type complex in AC analysis mode. Internally the expression is replaced by a generated voltage node that is the output of a B source, one node, and the B source implementing par(’...’). Several par(’...’) are allowed in each line, up to 99 per input file. The internal nodes are named pa_00 to pa_99. An error will occur if the input file contains any of these reserved node names. In .four, .plot, .print, .save, but not in .measure, an alternative syntax output=par(’expression’) is possible. par(’expression’) may be used as described above. output is the name of the new node to replace the expression. So output has to be unique and a valid node name. The syntax of output=par(expression) is strict, no spaces between par and (’, or between ( and ’ are allowed, (’ and ’) both are required. Also there is not much error checking on your input, if there is a typo, for example, an error may pop up at an unexpected place. 276 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) 15.6.7 .width Set the width of a print-out or plot with the following card: .with out = 256 Parameter out yields the maximum number of characters plotted in a row, if printing in columns or an ASCII-plot is selected. 15.7 Measuring current through device terminals 15.7.1 Adding a voltage source in series Originally the ngspice matrix solver delivers node voltages and currents through independent voltage sources. So to measure the currents through a resistor you may add a voltage source in series with dc voltage 0. Current measurement with series voltage source * measure current through R1 V1 1 0 1 R1 1 0 5 R2 1 0 10 * will become V1 1 0 1 R1 1 11 5 Vmess 11 0 dc 0 R2 1 0 10 15.7.2 Using option ’savecurrents’ Current measurement with series voltage source * measure current through R1 and R2 V1 1 0 1 R1 1 0 5 R2 1 0 10 . options savecurrents The option savecurrents will add .save lines (15.6.1) like .save @r1[i] .save @r2[i] to your input file information read during circuit parsing. These newly created vectors contain the terminal currents of the devices R1 and R2. You will find information of the nomenclature in Chapt. 31, also how to plot these vectors. The following devices are supported: M, J, Q, D, R, C, L, B, F, G, W, S, I (see 2.1.2). For M only 15.7. MEASURING CURRENT THROUGH DEVICE TERMINALS 277 MOSFET models MOS1 to MOS9 are included so far. Devices in subcircuits are supported as well. Be careful when choosing this option in larger circuits, because 1 to 4 additional output vectors are created per device and this may consume lots of memory. 278 CHAPTER 15. ANALYSES AND OUTPUT CONTROL (BATCH MODE) Chapter 16 Starting ngspice 16.1 Introduction Ngspice consists of the simulator and a front-end for data analysis and plotting. Input to the simulator is a netlist file, including commands for circuit analysis and output control. Interactive ngspice can plot data from a simulation on a PC or a workstation display. Ngspice on Linux (and OSs like Cygwin, BCD, Solaris ...) uses the X Window System for plotting (see Chapt. 18.3) if the environment variable DISPLAY is available. Otherwise, a console mode (non-graphical) interface is used. If you are using X on a workstation, the DISPLAY variable should already be set; if you want to display graphics on a system different from the one you are running ngspice or ngutmeg on, DISPLAY should be of the form machine:0.0. See the appropriate documentation on the X Window System for more details. The MS Windows versions of ngspice and ngnutmeg will have a native graphics interface (see Chapt. 18.1). The front-end may be run as a separate ‘stand-alone’ program under the name ngnutmeg. ngnutmeg is a subset of ngspice dedicated to data evaluation, still made available for historical reasons. Ngnutmeg will read in the ‘raw’ data output file created by ngspice -r or by the write command during an interactive ngspice session. 16.2 Where to obtain ngspice The actual distribution of ngspice may be downloaded from the ngspice download web page. The installation for Linux or MS Windows is described in the file INSTALL to be found in the top level directory. You may also have a look at Chapt. 32 of this manual for compiling instructions. If you want to check out the source code that is actually under development, you may have a look at the ngspice source code repository, which is stored using the Git Source Code Management (SCM) tool. The Git repository may be browsed on the Git web page, also useful for downloading individual files. You may however download (or clone) the complete repository including all source code trees from the console window (Linux, CYGWIN or MSYS/MINGW) by issuing the command (in a single line) 279 280 CHAPTER 16. STARTING NGSPICE git clone git://git.code.sf.net/p/ngspice/ngspice You need to have Git installed, which is available for all three OSs. The whole source tree is then available in