Ngspice User Manual 26

ngspice-26-manual

User Manual: Pdf

Open the PDF directly: View PDF PDF.
Page Count: 586 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Ngspice Users Manual
Version 26
(Describes ngspice-26 release version)
Paolo Nenzi, Holger Vogt
January 11, 2014
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 the following. More is surely
needed. You are invited to report bugs, missing items, wrongly described items, bad English
style etc.
To Do
1. Review of chapt. 1.3
2. hfet1,2 model descriptions
How to use this manual
The manual is a “work in progress”. It may accompany a specific ngspice release, e.g. ngspice-
24 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.
Part I
Ngspice User Manual
3
Contents
I Ngspice User Manual 3
1 Introduction 33
1.1 Simulation Algorithms .............................. 34
1.1.1 Analog Simulation ............................ 34
1.1.2 Digital Simulation ............................ 35
1.1.3 Mixed-Mode Simulation ......................... 35
1.1.4 Mixed-Level Simulation ......................... 36
1.2 Supported Analyses ................................ 37
1.2.1 DC Analyses ............................... 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 .............................. 40
1.2.8 Periodic Steady State Analysis ..................... 40
1.3 Analysis at Different Temperatures ........................ 40
1.4 Convergence ................................... 42
1.4.1 Voltage convergence criterion ...................... 42
1.4.2 Current convergence criterion ...................... 43
1.4.3 Convergence failure ........................... 43
2 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
6CONTENTS
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 .................................... 52
2.7 .LIB ........................................ 53
2.8 .PARAM Parametric netlists ........................... 53
2.8.1 .param line ................................ 53
2.8.2 Brace expressions in circuit elements: .................. 54
2.8.3 Subcircuit parameters ........................... 54
2.8.4 Symbol scope ............................... 55
2.8.5 Syntax of expressions .......................... 55
2.8.6 Reserved words ............................. 58
2.8.7 Alternative syntax ............................ 58
2.9 .FUNC ....................................... 58
2.10 .CSPARAM .................................... 59
2.11 .TEMP ....................................... 59
2.12 .IF Condition-Controlled Netlist ......................... 60
2.13 Parameters, functions, expressions, and command scripts ............ 61
2.13.1 Parameters ................................ 61
2.13.2 Nonlinear sources ............................. 61
2.13.3 Control commands, Command scripts .................. 61
3 Circuit Elements and Models 63
3.1 General options and information ......................... 63
3.1.1 Simulating more devices in parallel ................... 63
3.1.2 Technology scaling ............................ 64
3.1.3 Model binning .............................. 64
CONTENTS 7
3.1.4 Multiplier m, initial conditions ...................... 64
3.2 Elementary Devices ................................ 65
3.2.1 Resistors ................................. 65
3.2.2 Semiconductor Resistors ......................... 66
3.2.3 Semiconductor Resistor Model (R) ................... 66
3.2.4 Resistors, dependent on expressions (behavioral resistor) ........ 68
3.2.5 Capacitors ................................ 68
3.2.6 Semiconductor Capacitors ........................ 69
3.2.7 Semiconductor Capacitor Model (C) ................... 69
3.2.8 Capacitors, dependent on expressions (behavioral capacitor) ...... 71
3.2.9 Inductors ................................. 72
3.2.10 Inductor model .............................. 72
3.2.11 Coupled (Mutual) Inductors ....................... 73
3.2.12 Inductors, dependent on expressions (behavioral inductor) ....... 74
3.2.13 Capacitor or inductor with initial conditions .............. 75
3.2.14 Switches ................................. 76
3.2.15 Switch Model (SW/CSW) ........................ 77
4 Voltage and Current Sources 79
4.1 Independent Sources for Voltage or Current ................... 79
4.1.1 Pulse ................................... 80
4.1.2 Sinusoidal ................................. 81
4.1.3 Exponential ................................ 81
4.1.4 Piece-Wise Linear ............................ 82
4.1.5 Single-Frequency FM .......................... 82
4.1.6 Amplitude modulated source (AM) ................... 83
4.1.7 Transient noise source .......................... 83
4.1.8 Random voltage source .......................... 84
4.1.9 External voltage or current input ..................... 84
4.1.10 Arbitrary Phase Sources ......................... 85
4.2 Linear Dependent Sources ............................ 85
4.2.1 Gxxxx: Linear Voltage-Controlled Current Sources (VCCS) ...... 85
4.2.2 Exxxx: Linear Voltage-Controlled Voltage Sources (VCVS) ...... 86
4.2.3 Fxxxx: Linear Current-Controlled Current Sources (CCCS) ...... 86
4.2.4 Hxxxx: Linear Current-Controlled Voltage Sources (CCVS) ...... 86
4.2.5 Polynomial Source Compatibility .................... 87
8CONTENTS
5 Non-linear Dependent Sources (Behavioral Sources) 89
5.1 Bxxxx: Nonlinear dependent source (ASRC) .................. 89
5.1.1 Syntax and usage ............................. 89
5.1.2 Special B-Source Variables time, temper, hertz ............. 92
5.1.3 par(’expression’) ............................. 92
5.1.4 Piecewise Linear Function: pwl ..................... 92
5.2 Exxxx: non-linear voltage source* ........................ 95
5.2.1 VOL ................................... 95
5.2.2 VALUE .................................. 95
5.2.3 TABLE .................................. 95
5.2.4 POLY ................................... 95
5.2.5 LAPLACE ................................ 96
5.3 Gxxxx: non-linear current source* ........................ 97
5.3.1 CUR ................................... 97
5.3.2 VALUE .................................. 97
5.3.3 TABLE .................................. 97
5.3.4 POLY ................................... 98
5.3.5 LAPLACE ................................ 98
5.3.6 Example ................................. 98
5.4 Debugging a behavioral source .......................... 99
6 Transmission Lines 101
6.1 Lossless Transmission Lines ........................... 101
6.2 Lossy Transmission Lines ............................ 102
6.2.1 Lossy Transmission Line Model (LTRA) ................ 102
6.3 Uniform Distributed RC Lines .......................... 104
6.3.1 Uniform Distributed RC Model (URC) ................. 104
6.4 KSPICE Lossy Transmission Lines ........................ 105
6.4.1 Single Lossy Transmission Line (TXL) ................. 105
6.4.2 Coupled Multiconductor Line (CPL) ................... 106
7 Diodes 107
7.1 Junction Diodes .................................. 107
7.2 Diode Model (D) ................................. 107
7.3 Diode Equations .................................. 109
CONTENTS 9
8 BJTs 115
8.1 Bipolar Junction Transistors (BJTs) ....................... 115
8.2 BJT Models (NPN/PNP) ............................. 115
9 JFETs 121
9.1 Junction Field-Effect Transistors (JFETs) .................... 121
9.2 JFET Models (NJF/PJF) ............................. 121
9.2.1 JFET level 1 model with Parker Skellern modification ......... 121
9.2.2 JFET level 2 Parker Skellern model ................... 123
10 MESFETs 125
10.1 MESFETs ..................................... 125
10.2 MESFET Models (NMF/PMF) .......................... 125
10.2.1 Model by Statz e.a. ............................ 125
10.2.2 Model by Ytterdal e.a. .......................... 126
10.2.3 hfet1 ................................... 126
10.2.4 hfet2 ................................... 126
11 MOSFETs 127
11.1 MOSFET devices ................................. 127
11.2 MOSFET models (NMOS/PMOS) ........................ 128
11.2.1 MOS Level 1 ............................... 128
11.2.2 MOS Level 2 ............................... 130
11.2.3 MOS Level 3 ............................... 130
11.2.4 MOS Level 6 ............................... 130
11.2.5 Notes on Level 1-6 models ........................ 130
11.2.6 BSIM Models ............................... 133
11.2.7 BSIM1 model (level 4) .......................... 133
11.2.8 BSIM2 model (level 5) .......................... 136
11.2.9 BSIM3 model (levels 8, 49) ....................... 136
11.2.10 BSIM4 model (levels 14, 54) ....................... 137
11.2.11 EKV model ................................ 137
11.2.12 BSIMSOI models (levels 10, 58, 55, 56, 57) ............... 138
11.2.13 SOI3 model (level 60) .......................... 138
11.2.14 HiSIM models of the University of Hiroshima .............. 138
10 CONTENTS
12 Mixed-Mode and Behavioral Modeling with XSPICE 139
12.1 Code Model Element & .MODEL Cards .................... 139
12.2 Analog Models .................................. 143
12.2.1 Gain .................................... 143
12.2.2 Summer .................................. 144
12.2.3 Multiplier ................................. 145
12.2.4 Divider .................................. 146
12.2.5 Limiter .................................. 148
12.2.6 Controlled Limiter ............................ 149
12.2.7 PWL Controlled Source ......................... 151
12.2.8 Filesource ................................. 153
12.2.9 multi_input_pwl block .......................... 155
12.2.10 Analog Switch .............................. 156
12.2.11 Zener Diode ............................... 157
12.2.12 Current Limiter .............................. 159
12.2.13 Hysteresis Block ............................. 161
12.2.14 Differentiator ............................... 163
12.2.15 Integrator ................................. 164
12.2.16 S-Domain Transfer Function ....................... 166
12.2.17 Slew Rate Block ............................. 168
12.2.18 Inductive Coupling ............................ 170
12.2.19 Magnetic Core .............................. 171
12.2.20 Controlled Sine Wave Oscillator ..................... 174
12.2.21 Controlled Triangle Wave Oscillator ................... 175
12.2.22 Controlled Square Wave Oscillator .................... 176
12.2.23 Controlled One-Shot ........................... 178
12.2.24 Capacitance Meter ............................ 180
12.2.25 Inductance Meter ............................. 181
12.2.26 Memristor ................................. 181
12.3 Hybrid Models .................................. 183
12.3.1 Digital-to-Analog Node Bridge ..................... 183
12.3.2 Analog-to-Digital Node Bridge ..................... 184
12.3.3 Controlled Digital Oscillator ....................... 186
12.3.4 Node bridge from digital to real with enable ............... 187
12.3.5 A Z**-1 block working on real data ................... 187
CONTENTS 11
12.3.6 A gain block for event-driven real data .................. 188
12.3.7 Node bridge from real to analog voltage ................. 189
12.4 Digital Models .................................. 189
12.4.1 Buffer ................................... 189
12.4.2 Inverter .................................. 190
12.4.3 And .................................... 191
12.4.4 Nand ................................... 192
12.4.5 Or ..................................... 193
12.4.6 Nor .................................... 194
12.4.7 Xor .................................... 195
12.4.8 Xnor ................................... 196
12.4.9 Tristate .................................. 197
12.4.10 Pullup ................................... 199
12.4.11 Pulldown ................................. 199
12.4.12 D Flip Flop ................................ 200
12.4.13 JK Flip Flop ............................... 202
12.4.14 Toggle Flip Flop ............................. 204
12.4.15 Set-Reset Flip Flop ............................ 206
12.4.16 D Latch .................................. 209
12.4.17 Set-Reset Latch .............................. 211
12.4.18 State Machine ............................... 213
12.4.19 Frequency Divider ............................ 216
12.4.20 RAM ................................... 218
12.4.21 Digital Source .............................. 220
12.5 Predefined Node Types for event driven simulation ............... 222
12.5.1 Digital Node Type ............................ 222
12.5.2 Real Node Type ............................. 222
12.5.3 Int Node Type .............................. 222
12.5.4 (Digital) Input/Output .......................... 222
13 Verilog A Device models 223
13.1 Introduction .................................... 223
13.2 adms ........................................ 223
13.3 How to integrate a Verilog-A model into ngspice ................ 223
13.3.1 How to setup a *.va model for ngspice .................. 223
13.3.2 Adding admsXml to your build environment .............. 223
12 CONTENTS
14 Mixed-Level Simulation (ngspice with TCAD) 225
14.1 Cider ....................................... 225
14.2 GSS, Genius .................................... 226
15 Analyses and Output Control (batch mode) 227
15.1 Simulator Variables (.options) .......................... 227
15.1.1 General Options ............................. 228
15.1.2 DC Solution Options ........................... 228
15.1.3 AC Solution Options ........................... 230
15.1.4 Transient Analysis Options ........................ 230
15.1.5 ELEMENT Specific options ....................... 231
15.1.6 Transmission Lines Specific Options ................... 231
15.1.7 Precedence of option and .options commands .............. 232
15.2 Initial Conditions ................................. 232
15.2.1 .NODESET: Specify Initial Node Voltage Guesses ........... 232
15.2.2 .IC: Set Initial Conditions ........................ 232
15.3 Analyses ...................................... 233
15.3.1 .AC: Small-Signal AC Analysis ..................... 233
15.3.2 .DC: DC Transfer Function ........................ 234
15.3.3 .DISTO: Distortion Analysis ....................... 234
15.3.4 .NOISE: Noise Analysis ......................... 236
15.3.5 .OP: Operating Point Analysis ...................... 236
15.3.6 .PZ: Pole-Zero Analysis ......................... 237
15.3.7 .SENS: DC or Small-Signal AC Sensitivity Analysis .......... 237
15.3.8 .TF: Transfer Function Analysis ..................... 238
15.3.9 .TRAN: Transient Analysis ........................ 238
15.3.10 Transient noise analysis (at low frequency) ............... 239
15.3.11 .PSS: Periodic Steady State Analysis .................. 242
15.4 Measurements after AC, DC and Transient Analysis ............... 242
15.4.1 .meas(ure) ................................. 242
15.4.2 batch versus interactive mode ...................... 243
15.4.3 General remarks ............................. 243
15.4.4 Input ................................... 244
15.4.5 Trig Targ ................................. 244
15.4.6 Find ... When ............................... 245
CONTENTS 13
15.4.7 AVG|MIN|MAX|PP|RMS|MIN_AT|MAX_AT .............. 247
15.4.8 Integ ................................... 247
15.4.9 param ................................... 247
15.4.10 par(’expression’) ............................. 248
15.4.11 Deriv ................................... 248
15.4.12 More examples .............................. 248
15.5 Safe Operating Area (SOA) warning messages .................. 249
15.5.1 Resistor and Capacitor SOA model parameters ............. 250
15.5.2 Diode SOA model parameter ....................... 250
15.5.3 BJT SOA model parameter ........................ 250
15.5.4 MOS SOA model parameter ....................... 250
15.6 Batch Output ................................... 250
15.6.1 .SAVE: Name vector(s) to be saved in raw file .............. 251
15.6.2 .PRINT Lines ............................... 251
15.6.3 .PLOT Lines ............................... 252
15.6.4 .FOUR: Fourier Analysis of Transient Analysis Output ......... 253
15.6.5 .PROBE: Name vector(s) to be saved in raw file ............. 253
15.6.6 par(’expression’): Algebraic expressions for output ........... 253
15.6.7 .width ................................... 254
16 Starting ngspice 255
16.1 Introduction .................................... 255
16.2 Where to obtain ngspice ............................. 255
16.3 Command line options for starting ngspice and ngnutmeg ............ 256
16.4 Starting options .................................. 258
16.4.1 Batch mode ................................ 258
16.4.2 Interactive mode ............................. 258
16.4.3 Control mode (Interactive mode with control file or control section) . . 259
16.5 Standard configuration file spinit ......................... 260
16.6 User defined configuration file .spiceinit ..................... 261
16.7 Environmental variables ............................. 261
16.7.1 Ngspice specific variables ........................ 261
16.7.2 Common environment variables ..................... 262
16.8 Memory usage .................................. 262
16.9 Simulation time .................................. 262
14 CONTENTS
16.10Ngspice on multi-core processors using OpenMP ................ 263
16.10.1 Introduction ................................ 263
16.10.2 Some results ............................... 264
16.10.3 Usage ................................... 264
16.10.4 Literature ................................. 265
16.11Server mode option -s ............................... 265
16.12Ngspice control via input, output fifos ...................... 266
16.13Compatibility ................................... 268
16.13.1 Compatibility mode ........................... 268
16.13.2 Missing functions ............................. 268
16.13.3 Devices .................................. 269
16.13.4 Controls and commands ......................... 269
16.14Tests ........................................ 270
16.15Reporting bugs and errors ............................. 271
17 Interactive Interpreter 273
17.1 Introduction .................................... 273
17.2 Expressions, Functions, and Constants ...................... 273
17.3 Plots ........................................ 278
17.4 Command Interpretation ............................. 279
17.4.1 On the console .............................. 279
17.4.2 Scripts .................................. 279
17.4.3 Add-on to circuit file ........................... 279
17.5 Commands .................................... 280
17.5.1 Ac*: Perform an AC, small-signal frequency response analysis . . . . . 280
17.5.2 Alias: Create an alias for a command .................. 281
17.5.3 Alter*: Change a device or model parameter .............. 281
17.5.4 Altermod*: Change model parameter(s) ................ 282
17.5.5 Asciiplot: Plot values using old-style character plots .......... 283
17.5.6 Aspice*: Asynchronous ngspice run ................... 284
17.5.7 Bug: Mail a bug report .......................... 284
17.5.8 Cd: Change directory ........................... 284
17.5.9 Cdump: Dump the control flow to the screen .............. 284
17.5.10 Circbyline*: Enter a circuit line by line ................. 285
17.5.11 Codemodel*: Load an XSPICE code model library ........... 285
CONTENTS 15
17.5.12 Compose: Compose a vector ....................... 286
17.5.13 Dc*: Perform a DC-sweep analysis ................... 286
17.5.14 Define: Define a function ......................... 286
17.5.15 Deftype: Define a new type for a vector or plot ............. 286
17.5.16 Delete*: Remove a trace or breakpoint .................. 287
17.5.17 Destroy: Delete an output data set .................... 287
17.5.18 Devhelp: information on available devices ................ 287
17.5.19 Diff: Compare vectors .......................... 288
17.5.20 Display: List known vectors and types .................. 288
17.5.21 Echo: Print text .............................. 288
17.5.22 Edit*: Edit the current circuit ...................... 288
17.5.23 Eprint*: Print an event driven node (only used with XSPICE option) . . 289
17.5.24 FFT: fast Fourier transform of vectors .................. 289
17.5.25 Fourier: Perform a Fourier transform .................. 291
17.5.26 Gnuplot: Graphics output via Gnuplot .................. 292
17.5.27 Hardcopy: Save a plot to a file for printing ............... 292
17.5.28 Help: Print summaries of Ngspice commands ............. 293
17.5.29 History: Review previous commands .................. 293
17.5.30 Inventory: Print circuit inventory ..................... 293
17.5.31 Iplot*: Incremental plot ......................... 293
17.5.32 Jobs*: List active asynchronous ngspice runs .............. 293
17.5.33 Let: Assign a value to a vector ...................... 294
17.5.34 Linearize*: Interpolate to a linear scale ................. 294
17.5.35 Listing*: Print a listing of the current circuit .............. 294
17.5.36 Load: Load rawfile data ......................... 295
17.5.37 Meas*: Measurements on simulation data ................ 295
17.5.38 Mdump*: Dump the matrix values to a file (or to console) ....... 295
17.5.39 Mrdump*: Dump the matrix right hand side values to a file (or to console)296
17.5.40 Noise*: Noise analysis .......................... 296
17.5.41 Op*: Perform an operating point analysis ................ 297
17.5.42 Option*: Set a ngspice option ...................... 297
17.5.43 Plot: Plot values on the display ...................... 298
17.5.44 Pre_<command>: execute commands prior to parsing the circuit . . . . 298
17.5.45 Print: Print values ............................ 299
17.5.46 Quit: Leave Ngspice or Nutmeg ..................... 299
16 CONTENTS
17.5.47 Rehash: Reset internal hash tables .................... 300
17.5.48 Remcirc*: Remove the current circuit .................. 300
17.5.49 Reset*: Reset an analysis ......................... 300
17.5.50 Reshape: Alter the dimensionality or dimensions of a vector ...... 300
17.5.51 Resume*: Continue a simulation after a stop .............. 301
17.5.52 Rspice*: Remote ngspice submission .................. 301
17.5.53 Run*: Run analysis from the input file .................. 301
17.5.54 Rusage: Resource usage ......................... 302
17.5.55 Save*: Save a set of outputs ....................... 303
17.5.56 Sens*: Run a sensitivity analysis ..................... 304
17.5.57 Set: Set the value of a variable ...................... 304
17.5.58 Setcirc*: Change the current circuit ................... 304
17.5.59 Setplot: Switch the current set of vectors ................ 304
17.5.60 Setscale: Set the scale vector for the current plot ............ 305
17.5.61 Settype: Set the type of a vector ..................... 305
17.5.62 Shell: Call the command interpreter ................... 305
17.5.63 Shift: Alter a list variable ......................... 305
17.5.64 Show*: List device state ......................... 306
17.5.65 Showmod*: List model parameter values ................ 306
17.5.66 Snload*: Load the snapshot file ..................... 306
17.5.67 Snsave*: Save a snapshot file ...................... 307
17.5.68 Source: Read a ngspice input file .................... 308
17.5.69 Spec: Create a frequency domain plot .................. 309
17.5.70 Status*: Display breakpoint information ................. 309
17.5.71 Step*: Run a fixed number of time-points ................ 309
17.5.72 Stop*: Set a breakpoint .......................... 309
17.5.73 Strcmp: Compare two strings ...................... 310
17.5.74 Sysinfo*: Print system information ................... 310
17.5.75 Tf*: Run a Transfer Function analysis .................. 311
17.5.76 Trace*: Trace nodes ........................... 312
17.5.77 Tran*: Perform a transient analysis ................... 312
17.5.78 Transpose: Swap the elements in a multi-dimensional data set . . . . . 312
17.5.79 Unalias: Retract an alias ......................... 313
17.5.80 Undefine: Retract a definition ...................... 313
17.5.81 Unlet: Delete the specified vector(s) ................... 313
CONTENTS 17
17.5.82 Unset: Clear a variable .......................... 313
17.5.83 Version: Print the version of ngspice ................... 314
17.5.84 Where*: Identify troublesome node or device .............. 315
17.5.85 Wrdata: Write data to a file (simple table) ................ 315
17.5.86 Write: Write data to a file (Spice3f5 format) ............... 315
17.5.87 Wrs2p: Write scattering parameters to file (Touchstone® format) . . . 316
17.5.88 Xgraph: use the xgraph(1) program for plotting. ............ 316
17.6 Control Structures ................................. 317
17.6.1 While - End ................................ 317
17.6.2 Repeat - End ............................... 317
17.6.3 Dowhile - End .............................. 317
17.6.4 Foreach - End ............................... 317
17.6.5 If - Then - Else .............................. 318
17.6.6 Label ................................... 318
17.6.7 Goto ................................... 318
17.6.8 Continue ................................. 318
17.6.9 Break ................................... 319
17.7 Internally predefined variables .......................... 319
17.8 Scripts ....................................... 324
17.8.1 Variables ................................. 324
17.8.2 Vectors .................................. 324
17.8.3 Commands ................................ 325
17.8.4 control structures ............................. 325
17.8.5 Example script ’spectrum’ ........................ 328
17.8.6 Example script for random numbers ................... 330
17.8.7 Parameter sweep ............................. 331
17.8.8 Output redirection ............................ 331
17.9 Scattering parameters (s-parameters) ....................... 332
17.9.1 Intro .................................... 332
17.9.2 S-parameter measurement basics ..................... 333
17.9.3 Usage ................................... 334
17.10MISCELLANEOUS (old stuff, has to be checked for relevance) ........ 335
17.11Bugs (old stuff, has to be checked for relevance) ................. 335
18 CONTENTS
18 Ngspice User Interfaces 337
18.1 MS Windows Graphical User Interface ...................... 337
18.2 MS Windows Console .............................. 339
18.3 LINUX ...................................... 340
18.4 CygWin ...................................... 340
18.5 Error handling ................................... 340
18.6 Postscript printing options ............................ 341
18.7 Gnuplot ...................................... 342
18.8 Integration with CAD software and “third party” GUIs ............. 342
18.8.1 KJWaves ................................. 342
18.8.2 GNU Spice GUI ............................. 342
18.8.3 XCircuit ................................. 342
18.8.4 GEDA ................................... 343
18.8.5 CppSim .................................. 343
18.8.6 NGSPICE Online ............................. 343
18.8.7 Spicy Schematics ............................. 343
18.8.8 MSEspice ................................. 343
18.8.9 PartSim .................................. 343
19 ngspice as shared library or dynamic link library 345
19.1 Compile options .................................. 345
19.1.1 How to get the sources .......................... 345
19.1.2 LINUX, MINGW, CYGWIN ....................... 345
19.1.3 MS Visual Studio ............................. 345
19.2 Linking shared ngspice to a calling application ................. 346
19.2.1 Linking during creating the caller .................... 346
19.2.2 Loading at runtime ............................ 346
19.3 Shared ngspice API ................................ 346
19.3.1 structs and types defined for transporting data .............. 346
19.3.2 Exported functions ............................ 348
19.3.3 Callback functions ............................ 350
19.4 General remarks on using the API ........................ 352
19.4.1 Loading a netlist ............................. 352
19.4.2 Running the simulation .......................... 353
19.4.3 Accessing data .............................. 354
CONTENTS 19
19.4.4 Altering model or device parameters ................... 354
19.4.5 Output .................................. 354
19.4.6 Error handling .............................. 355
19.5 Example applications ............................... 355
19.6 ngspice parallel .................................. 355
19.6.1 Go parallel! ................................ 356
19.6.2 Additional exported functions ...................... 357
19.6.3 Additional callback functions ...................... 358
19.6.4 Parallel ngspice example ......................... 359
20 TCLspice 361
20.1 tclspice framework ................................ 361
20.2 tclspice documentation .............................. 361
20.3 spicetoblt ..................................... 361
20.4 Running TCLspice ................................ 362
20.5 examples ..................................... 362
20.5.1 Active capacitor measurement ...................... 362
20.5.2 Optimization of a linearization circuit for a Thermistor ......... 365
20.5.3 Progressive display ............................ 369
20.6 Compiling ..................................... 370
20.6.1 LINUX .................................. 370
20.6.2 MS Windows ............................... 370
20.7 MS Windows 32 Bit binaries ........................... 371
21 Example Circuits 373
21.1 AC coupled transistor amplifier .......................... 373
21.2 Differential Pair .................................. 379
21.3 MOSFET Characterization ............................ 379
21.4 RTL Inverter .................................... 379
21.5 Four-Bit Binary Adder (Bipolar) ......................... 380
21.6 Four-Bit Binary Adder (MOS) .......................... 382
21.7 Transmission-Line Inverter ............................ 383
20 CONTENTS
22 Statistical circuit analysis 385
22.1 Introduction .................................... 385
22.2 Using random param(eters) ............................ 385
22.3 Behavioral sources (B, E, G, R, L, C) with random control ........... 387
22.4 ngspice scripting language ............................ 388
22.5 Monte-Carlo Simulation ............................. 389
22.5.1 Example 1 ................................ 389
22.5.2 Example 2 ................................ 391
22.5.3 Example 3 ................................ 391
22.6 Data evaluation with Gnuplot ........................... 391
23 Circuit optimization with ngspice 395
23.1 Optimization of a circuit ............................. 395
23.2 ngspice optimizer using ngspice scripts ..................... 396
23.3 ngspice optimizer using tclspice ......................... 396
23.4 ngspice optimizer using a Python script ..................... 396
23.5 ngspice optimizer using ASCO .......................... 396
23.5.1 Three stage operational amplifier ..................... 397
23.5.2 Digital inverter .............................. 398
23.5.3 Bandpass ................................. 400
23.5.4 Class-E power amplifier ......................... 400
24 Notes 401
24.1 Glossary ...................................... 401
24.2 Acronyms and Abbreviations ........................... 402
II XSPICE Software User’s Manual 405
25 XSPICE Basics 407
25.1 ngspice with the XSPICE option ......................... 407
25.2 The XSPICE Code Model Subsystem ...................... 407
25.3 XSPICE Top-Level Diagram ........................... 408
26 Execution Procedures 409
26.1 Simulation and Modeling Overview ....................... 409
26.1.1 Describing the Circuit .......................... 409
26.2 Circuit Description Syntax ............................ 415
26.2.1 XSPICE Syntax Extensions ....................... 415
26.3 How to create code models ............................ 417
CONTENTS 21
27 Example circuits 421
27.1 Amplifier with XSPICE model “gain” ...................... 421
27.2 XSPICE advanced usage ............................. 423
27.2.1 Circuit example C3 ............................ 423
27.2.2 Running example C3 ........................... 426
28 Code Models and User-Defined Nodes 431
28.1 Code Model Data Type Definitions ........................ 432
28.2 Creating Code Models .............................. 432
28.3 Creating User-Defined Nodes ........................... 433
28.4 Adding a new code model library ......................... 434
28.5 Compiling and loading the new code model (library) .............. 434
28.6 Interface Specification File ............................ 435
28.6.1 The Name Table ............................. 437
28.6.2 The Port Table .............................. 437
28.6.3 The Parameter Table ........................... 439
28.6.4 Static Variable Table ........................... 440
28.7 Model Definition File .............................. 442
28.7.1 Macros .................................. 442
28.7.2 Function Library ............................. 451
28.8 User-Defined Node Definition File ........................ 458
28.8.1 Macros .................................. 458
28.8.2 Function Library ............................. 459
28.8.3 Example UDN Definition File ...................... 461
29 Error Messages 465
29.1 Preprocessor Error Messages ........................... 465
29.2 Simulator Error Messages ............................ 470
29.3 Code Model Error Messages ........................... 471
29.3.1 Code Model aswitch ........................... 471
29.3.2 Code Model climit ............................ 472
29.3.3 Code Model core ............................. 472
29.3.4 Code Model d_osc ............................ 472
29.3.5 Code Model d_source .......................... 473
29.3.6 Code Model d_state ........................... 473
29.3.7 Code Model oneshot ........................... 474
22 CONTENTS
29.3.8 Code Model pwl ............................. 474
29.3.9 Code Model s_xfer ............................ 474
29.3.10 Code Model sine ............................. 475
29.3.11 Code Model square ........................... 475
29.3.12 Code Model triangle ........................... 476
III CIDER 477
30 CIDER User’s Manual 479
30.1 SPECIFICATION ................................. 479
30.1.1 Examples ................................. 480
30.2 BOUNDARY, INTERFACE ........................... 481
30.2.1 DESCRIPTION ............................. 481
30.2.2 PARAMETERS ............................. 482
30.2.3 EXAMPLES ............................... 482
30.3 COMMENT .................................... 482
30.3.1 DESCRIPTION ............................. 483
30.3.2 EXAMPLES ............................... 483
30.4 CONTACT .................................... 483
30.4.1 DESCRIPTION ............................. 483
30.4.2 PARAMETERS ............................. 483
30.4.3 EXAMPLES ............................... 483
30.4.4 SEE ALSO ................................ 483
30.5 DOMAIN, REGION ............................... 484
30.5.1 DESCRIPTION ............................. 484
30.5.2 PARAMETERS ............................. 484
30.5.3 EXAMPLES ............................... 484
30.5.4 SEE ALSO ................................ 485
30.6 DOPING ..................................... 485
30.6.1 DESCRIPTION ............................. 485
30.6.2 PARAMETERS ............................. 488
30.6.3 EXAMPLES ............................... 488
30.6.4 SEE ALSO ................................ 489
30.7 ELECTRODE ................................... 489
30.7.1 DESCRIPTION ............................. 489
CONTENTS 23
30.7.2 PARAMETERS ............................. 490
30.7.3 EXAMPLES ............................... 490
30.7.4 SEE ALSO ................................ 490
30.8 END ....................................... 490
30.8.1 DESCRIPTION ............................. 491
30.9 MATERIAL ................................... 491
30.9.1 DESCRIPTION ............................. 491
30.9.2 PARAMETERS ............................. 492
30.9.3 EXAMPLES ............................... 492
30.9.4 SEE ALSO ................................ 492
30.10METHOD .................................... 493
30.10.1 DESCRIPTION ............................. 493
30.10.2 Parameters ................................ 493
30.10.3 Examples ................................. 493
30.11Mobility ...................................... 494
30.11.1 Description ................................ 494
30.11.2 Parameters ................................ 495
30.11.3 Examples ................................. 495
30.11.4 SEE ALSO ................................ 495
30.11.5 BUGS .................................. 496
30.12MODELS ..................................... 496
30.12.1 DESCRIPTION ............................. 496
30.12.2 Parameters ................................ 496
30.12.3 Examples ................................. 496
30.12.4 See also .................................. 497
30.12.5 Bugs ................................... 497
30.13OPTIONS .................................... 497
30.13.1 DESCRIPTION ............................. 497
30.13.2 Parameters ................................ 498
30.13.3 Examples ................................. 498
30.13.4 See also .................................. 498
30.14OUTPUT ..................................... 499
30.14.1 DESCRIPTION ............................. 499
30.14.2 Parameters ................................ 500
30.14.3 Examples ................................. 500
24 CONTENTS
30.14.4 SEE ALSO ................................ 501
30.15TITLE ....................................... 501
30.15.1 DESCRIPTION ............................. 501
30.15.2 EXAMPLES ............................... 501
30.15.3 BUGS .................................. 501
30.16X.MESH, Y.MESH ................................ 501
30.16.1 DESCRIPTION ............................. 502
30.16.2 Parameters ................................ 503
30.16.3 EXAMPLES ............................... 503
30.16.4 SEE ALSO ................................ 503
30.17NUMD ...................................... 504
30.17.1 DESCRIPTION ............................. 504
30.17.2 Parameters ................................ 505
30.17.3 EXAMPLES ............................... 505
30.17.4 SEE ALSO ................................ 506
30.17.5 BUGS .................................. 506
30.18NBJT ....................................... 506
30.18.1 DESCRIPTION ............................. 506
30.18.2 Parameters ................................ 507
30.18.3 EXAMPLES ............................... 507
30.18.4 SEE ALSO ................................ 508
30.18.5 BUGS .................................. 508
30.19NUMOS ..................................... 508
30.19.1 DESCRIPTION ............................. 508
30.19.2 Parameters ................................ 509
30.19.3 EXAMPLES ............................... 509
30.19.4 SEE ALSO ................................ 510
30.20Cider examples .................................. 510
IV Appendices 511
31 Model and Device Parameters 513
31.1 Accessing internal device parameters ....................... 513
31.2 Elementary Devices ................................ 515
31.2.1 Resistor .................................. 515
CONTENTS 25
31.2.2 Capacitor - Fixed capacitor ........................ 517
31.2.3 Inductor - Fixed inductor ......................... 518
31.2.4 Mutual - Mutual Inductor ......................... 519
31.3 Voltage and current sources ............................ 520
31.3.1 ASRC - Arbitrary source ......................... 520
31.3.2 Isource - Independent current source ................... 521
31.3.3 Vsource - Independent voltage source .................. 522
31.3.4 CCCS - Current controlled current source ................ 523
31.3.5 CCVS - Current controlled voltage source ................ 523
31.3.6 VCCS - Voltage controlled current source ................ 524
31.3.7 VCVS - Voltage controlled voltage source ................ 524
31.4 Transmission Lines ................................ 525
31.4.1 CplLines - Simple Coupled Multiconductor Lines ............ 525
31.4.2 LTRA - Lossy transmission line ..................... 526
31.4.3 Tranline - Lossless transmission line ................... 527
31.4.4 TransLine - Simple Lossy Transmission Line .............. 528
31.4.5 URC - Uniform R. C. line ........................ 529
31.5 BJTs ........................................ 530
31.5.1 BJT - Bipolar Junction Transistor .................... 530
31.5.2 BJT - Bipolar Junction Transistor Level 2 ................ 533
31.5.3 VBIC - Vertical Bipolar Inter-Company Model ............. 536
31.6 MOSFETs ..................................... 540
31.6.1 MOS1 - Level 1 MOSFET model with Meyer capacitance model . . . . 540
31.6.2 MOS2 - Level 2 MOSFET model with Meyer capacitance model . . . . 543
31.6.3 MOS3 - Level 3 MOSFET model with Meyer capacitance model . . . 547
31.6.4 MOS6 - Level 6 MOSFET model with Meyer capacitance model . . . 551
31.6.5 MOS9 - Modified Level 3 MOSFET model ............... 554
31.6.6 BSIM1 - Berkeley Short Channel IGFET Model ............ 558
31.6.7 BSIM2 - Berkeley Short Channel IGFET Model ............ 561
31.6.8 BSIM3 .................................. 565
31.6.9 BSIM4 .................................. 566
26 CONTENTS
32 Compilation notes 569
32.1 Ngspice Installation under LINUX (and other ’UNIXes’) ............ 569
32.1.1 Prerequisites ............................... 569
32.1.2 Install from Git .............................. 569
32.1.3 Install from a tarball, e.g. ngspice-rework-25.tgz ............ 571
32.1.4 Compilation using an user defined directory tree for object files . . . . 571
32.1.5 Advanced Install ............................. 571
32.1.6 Compilers and Options .......................... 573
32.1.7 Compiling For Multiple Architectures .................. 574
32.1.8 Installation Names ............................ 574
32.1.9 Optional Features ............................. 574
32.1.10 Specifying the System Type ....................... 575
32.1.11 Sharing Defaults ............................. 575
32.1.12 Operation Controls ............................ 575
32.2 Ngspice Compilation under WINDOWS OS .................. 575
32.2.1 How to make ngspice with MINGW and MSYS ............ 575
32.2.2 64 Bit executables with MINGW-w64 .................. 577
32.2.3 make ngspice with MS Visual Studio 2008 or 2010 ........... 578
32.2.4 make ngspice with pure CYGWIN .................... 580
32.2.5 ngspice mingw or cygwin console executable w/o graphics ....... 580
32.2.6 make ngspice with CYGWIN and external MINGW32 ......... 581
32.2.7 make ngspice with CYGWIN and internal MINGW32 (use config.h
made above) ............................... 581
32.3 Reporting errors .................................. 582
33 Copyrights and licenses 583
33.1 Documentation license .............................. 583
33.1.1 Spice documentation copyright ...................... 583
33.1.2 XSPICE SOFTWARE (documentation) copyright ............ 583
33.1.3 CIDER RESEARCH SOFTWARE AGREEMENT (superseded by 33.2.1)584
33.2 ngspice license .................................. 584
33.2.1 “Modified” BSD license ......................... 585
33.2.2 XSPICE .................................. 586
33.2.3 tclspice, numparam ............................ 586
33.2.4 Linking to GPLd libraries (e.g. readline, fftw): ............. 586
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 cut of 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 dome Emmanuel Rouat and Arno W. Peters for converting to
T
E
Xinfo the original spice3f documentation, their effort gave ngspice users the only available
documentation that described the changes for many years. A good source of ideas for this
manual comes from the on-line spice3f manual written by Charles D.H. Williams (Spice3f5
User Guide), constantly updated and useful for some insight that he gives in it.
As always, errors, omissions and unreadable phrases are only my fault.
Paolo Nenzi
Roma, March 24th 2001
27
28 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 Kings Ale
Preface to the actual edition (as of January 2013)
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 L
Y
X 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.
Holger Vogt
Mülheim, 2013
Acknowledgments
ngspice contributors
Spice was originally written at The University of California at Berkeley (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,
Jeffrey M. Hsu,
JianHui Huang,
S. Hwang,
Chris Inbody,
Gordon M. Jacobs,
Min-Chie Jeng,
29
30 CONTENTS
Beorn Johnson,
Stefan Jones,
Kenneth H. Keller,
Francesco Lannutti,
Robert Larice,
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,
CONTENTS 31
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 omis-
sion was unintentional. If you feel you should be on this list then please write to <ngspice-
devel@lists.sourceforge.net>. Do not be shy, we would like to make a list as complete as
possible.
XSPICE
The XSPICE simulator is based on the SPICE3 program developed by the Electronics Research
Laboratory, Department of Electrical Engineering and Computer Sciences, University of Cali-
fornia at Berkeley. The authors of XSPICE gratefully acknowledge UC Berkeley’s development
and distribution of this software, and their licensing policies which promote further improve-
ments to simulation technology.
We also gratefully acknowledge the participation and support of our U.S. Air Force spon-
sors, the Aeronautical Systems Center and the Warner Robins Air Logistics Command, without
which the development of XSPICE would not have been possible.
32 CONTENTS
Chapter 1
Introduction
Ngspice is a general-purpose circuit simulation program for nonlinear and linear analyses. Cir-
cuits 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 chapter 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 param-
eters 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 current-dependent
output conductance may be included. The second bipolar model BJT2 adds dc current com-
putation 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 param-
eters 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. The mixed-
level extensions to ngspice are two:
CIDER: a mixed-level circuit and device simulator integrated into ngspice code. CIDER
was originally the name of the mixed-level extension made to spice3f5.
GSS: GSS (now called GENIUS) TCAD is a 2D simulator developed independently from
ngspice. The device simulator itself is free and not included into ngspice, but a socket
interface is provided.
Ngspice supports mixed-signal simulation through the integration of XSPICE code into it.
XSPICE software, developed as an extension to Spice3C1 from GeorgiaTech, has been ported
to ngspice to provide “board” level and mixed-signal simulation.
New devices can be added to ngspice by two means: the XSPICE code-model interface 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 Kirchhoffs
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 Kirchhoffs
laws form a set of simultaneous equations, the simulator operates by solving a matrix of equa-
tions at each time point. This matrix processing generally results in slower simulation times
when compared to digital circuit simulators.
1.1. SIMULATION ALGORITHMS 35
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 time-
varying behavior of reactive elements is neglected and the simulator calculates the DC solution
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 Kirchhoffs 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-Mode 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 algo-
rithm 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.
36 CHAPTER 1. INTRODUCTION
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
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 which 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)
DSIM provides accurate, one- and two-dimensional numerical device models based on the so-
lution 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. CIDER is based on the mixed-level circuit and device simulator CODECS, 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 trans-
verse 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 semi-
conductor 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 which enables two-dimensional numerical simulation of semiconduc-
tor device with well-known drift-diffusion and hydrodynamic method. GSS has Basic DDM
1.2. SUPPORTED ANALYSES 37
(drift-diffusion method) solver, Lattice Temperature Corrected DDM solver, EBM (energy bal-
ance method) solver and Quantum corrected DDM solver which based on density-gradient the-
ory. 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 inter-
face) 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).
GSS is no longer updated, but is still available as open source as a limited edition of the com-
mercial GENIUS TCAD tool.
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 Analyses
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 which require the analog
simulator algorithm and those which 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.
38 CHAPTER 1. INTRODUCTION
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, small-
signal 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 temperature1is stepped over a user-
specified range and the dc output variables are stored for each sequential source value.
1.2.2 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 small-
signal 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 be-
gins 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 rein-
troduced, 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 which 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
1Temperature (TEMP) and resistance sweeps have been introduced in Ngspice, they were not available in the
original code of Spice3f5.
1.2. SUPPORTED ANALYSES 39
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 sub-
optimal 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.5 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
statement 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 sen-
sitivity 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 affects 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).
40 CHAPTER 1. INTRODUCTION
1.2.7 Noise Analysis
The noise analysis portion of Ngspice does analysis device-generated noise for the given cir-
cuit. 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 input noise to the circuit, equivalent to the output noise referred
to the specified input source. 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/cur-
rent (over this frequency range). This calculated value corresponds to the variance of the circuit
variable viewed as a stationary Gaussian process.
1.2.8 Periodic Steady State Analysis
(Experimental code, not yet made publicly available!)
PSS is a radio frequency periodical large-signal dedicated analysis. The implementation is
based on a time domain shooting like method which make use of Transient analysis. As it is in
early development stage, PSS performs analysis only on autonomous circuits, meaning that it is
only able to predict fundamental frequency and amplitude (and also harmonics) for oscillators,
VCOs, etc.. The algorithm is based on a minimum search of the error vector taken as the
difference of RHS vectors between two occurrences of an estimated period. The convergence
is reached when the mean of error vector decrease below a given threshold that can be set as a
analysis parameter. Results of this analysis are the basis of every periodical large-signal analysis
as PAC or PNoise.
1.3 Analysis at Different Temperatures
Temperature, in ngspice, is a property associated to the entire circuit, rather than an analysis op-
tion. 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 tempera-
ture. This value can further be overridden for any device which 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:
1.3. ANALYSIS AT DIFFERENT TEMPERATURES 41
Algorithm 1.1 Instance temperature computation
IF TEMP is specified THEN
instance_temperature = TEMP
ELSE IF
instance_temperature = circuit_temperature + DTEMP
END IF
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 tem-
perature dependency scheme which 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:
IS(T1) = IS(T0)T1
T0XT I
expEgq(T1T0)
k(T1T0)(1.1)
where kis Boltzmann’s constant, qis the electronic charge, Egis the energy gap which is a
model parameter, and X T I is the saturation current temperature exponent (also a model param-
eter, and usually equal to 3).
The temperature dependence of forward and reverse beta is according to the formula:
B(T1) = B(T0)T1
T0XT B
(1.2)
where T0and T1are in degrees Kelvin, and X T B is a user-supplied model parameter. Tempera-
ture 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:
IS(T1) = IS(T0)T1
T0X T I
N
expEgq(T1T0)
Nk (T1T0)(1.3)
where Nis the emission coefficient, which is a 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:
U(T) = kT
qln NaNd
Ni(T)2!(1.4)
where kis Boltzmann’s constant, qis the electronic charge, Nais the acceptor impurity den-
sity, Ndis the donor impurity density, Niis the intrinsic carrier concentration, and Egis the
42 CHAPTER 1. INTRODUCTION
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(T) = M0(T0)
T
T01.5(1.5)
The effects of temperature on resistors, capacitor and inductors is modeled by the formula:
R(T) = R(T0)h1+TC1(TT0) + TC2(TT0)2i(1.6)
where Tis the circuit temperature, T0is the nominal temperature, and TC1and TC2are 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 condi-
tions hold:
1. The nonlinear branch currents converge to within a tolerance of 0.1% or 1 picoamp (1.0e-
12 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 if the difference between the last iteration kand the
current one (k+1):
v(k+1)
nv(k)
nRELTOL vnmax +VNTOL (1.7)
where
vnmax =maxv(k+1)
n,v(k)
n(1.8)
The RELTOL (RELative TOLerance) parameter, which default value is 103, specifies how small
the solution update must be, relative to the node voltage, to consider the solution to have con-
verged. The VNTOL (absolute convergence) parameter, which has 1µVas default becomes im-
portant 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 conver-
gence would never be achieved. VNTOL forces the algorithm to consider as converged any node
whose solution update is lower than its value.
1.4. CONVERGENCE 43
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 last
voltage and the linear approximation of the same current computed with the actual voltage:
\
i(k+1)
branch i(k)
branchRELTOL ibrmax +ABSTOL (1.9)
where
ibrmax =max\
i(k+1)
branch,i(k)
branch(1.10)
In the two expressions above, the
\
ibranch indicates the linear approximation of the current.
1.4.3 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 General Structure and Conventions
2.1.1 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 fre-
quently fell off). Leading white spaces in a line are ignored, as well as empty lines.
The lines decribed 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) which
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 ele-
ment.
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 Rand 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 which are
available in ngspice, sorted by the first letter.
First letter Element description Comments, links
A XSPICE code model
12
analog (12.2)
digital (12.4)
mixed signal (12.3)
B Behavioral (arbitrary) source 5.1
C Capacitor 3.2.5
D Diode 7
E Voltage-controlled voltage source (VCVS) linear (4.2.2),
non-linear (5.2)
F Current-controlled current source (CCCs) linear (4.2.3)
G Voltage-controlled current source (VCCS) linear (4.2.1),
non-linear (5.3)
H Current-controlled voltage source (CCVS) linear (4.2.4)
I Current source 4.1
J Junction field effect transistor (JFET) 9
K Coupled (Mutual) Inductors 3.2.11
L Inductor 3.2.9
M Metal oxide field effect transistor (MOSFET)
11
BSIM3 (11.2.9)
BSIM4 (11.2.10)
N Numerical device for GSS 14.2
O Lossy transmission line 6.2
P Coupled multiconductor line (CPL) 6.4.2
Q Bipolar junction transistor (BJT) 8
R Resistor 3.2.1
S Switch (voltage-controlled) 3.2.14
T Lossless transmission line 6.1
U Uniformly distributed RC line 6.3
V Voltage source 4.1
W Switch (current-controlled) 3.2.14
X Subcircuit 2.4.3
Y Single lossy transmission line (TXL) 6.4.1
Z Metal semiconductor field effect transistor (MESFET) 10
Table 2.1: ngspice element types
2.1. GENERAL STRUCTURE AND CONVENTIONS 47
2.1.3 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 Name Factor
T Tera 1012
G Giga 109
Meg Mega 106
K Kilo 103
mil Mil 25.4×106
m milli 103
u micro 106
n nano 109
p pico 1012
f femto 1015
Table 2.2: Ngspice scale factors
Letters immediately following a number that are not scale factors are ignored, and letters im-
mediately 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 Mor
mdenote ’milli’, i.e. 103. 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
*a d d i t i o n a l l i n e s f o l l o w i n g
*...
T e s t of CAM c e l l
*a d d i t i o n a l l i n e s f o l l o w i n g
*...
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 <any 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:
******************************
*a d d i t i o n a l l i n e s f o l l o w i n g
*...
. TITLE T e s t o f CAM c e l l
*a d d i t i o n a l l i n e s f o l l o w i n g
*...
will internally be replaced by
Internal input deck:
T e s t of CAM c e l l
*a d d i t i o n a l l i n e s f o l l o w i n g
*...
*TITLE T e s t o f CAM c e l l
*a d d i t i o n a l l i n e s f o l l o w i n g
*...
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 49
2.2.3 Comments
General Form:
*<any comment >
Examples:
*RF=1K Gain s h o u l d be 100
*Check openl o o p g a i n a nd p h a s e m ar g in
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:
<any command> ; < any comment >
<any command> $ <an y comment >
Examples:
RF2=1K ; Gain s h o u l d be 100
C1=10p $ Check openl o o p g a i n an d p h a s e m a r gi n
. param n1 =1 / / new v a l u e
ngspice supports comments that begin with single characters ’;’ or double characters ’$ ’ (dollar
plus space) or ’//’. For readability you should precede each comment character with a space.
ngspice will accept the single character ’$’, but only outside of a .control section.
2.3 .MODEL Device Models
General form:
. model mname t y p e ( pname1= p v a l 1 pname2= p v a l 2 . . . )
Examples:
. mo del MOD1 npn ( b f =50 i s =1 e13 vb f =50)
Most simple circuit elements typically require only a few parameter values. However, some de-
vices (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 to which the device is connected, 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 (8to 11) and Diodes (7) for more details). mname in the
above is the model name, and type is one of the following fifteen types:
50 CHAPTER 2. CIRCUIT DESCRIPTION
Code Model Type
R Semiconductor resistor model
C Semiconductor capacitor model
L Inductor model
SW Voltage controlled switch
CSW Current controlled switch
URC Uniform distributed RC model
LTRA Lossy transmission line model
D Diode model
NPN NPN BJT model
PNP PNP BJT model
NJF N-channel JFET model
PJF P-channel JFET model
NMOS N-channel MOSFET model
PMOS P-channel MOSFET model
NMF N-channel MESFET model
PMF P-channel MESFET model
Table 2.3: Ngspice model 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
chapter 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
(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 which begins with the letter “X”. A complete example of all three of
these cards follows:
2.4. .SUBCKT SUBCIRCUITS 51
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 10 K
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 chapter 21.6.
2.4.1 .SUBCKT Line
General form:
. SUBCKT subnam N1 <N2 N3 . . . >
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 which 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
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) which is always global. If you
use parameters, the .SUBCKT line will be extended (see 2.8.3).
52 CHAPTER 2. CIRCUIT DESCRIPTION
2.4.2 .ENDS Line
General form:
. ENDS <SUBNAM>
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 <N2 N3 . . . > 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
Nodes defined in the .GLOBAL statement are available to all circuit and subcircuit blocks inde-
pendently from any circuit hierarchy. After parsing the circuit, these nodes are accessible from
top level.
2.6 .INCLUDE
General form:
. INCLUDE f i l e n a m e
Examples:
. INCLUDE / u s e r s / s p i c e / common / bsim3param . mod
2.7. .LIB 53
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 f i l e n a m e l i b n a m e
Examples:
. LIB / u s e r s / s p i c e / common / m o s f e t s . l i b 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 which adds arithmetic functionality to the circuit description language.
2.8.1 .param line
General form:
. param < i d e n t > = <expr > < i d e n t > = < expr > . . . .
Examples:
. pa ra m p i p p o =5
. param po =6 pp = 7. 8 pap ={AGAUSS( pip po , 1 , 1 . 6 7 ) }
. pa ra m p i p p p ={ p i p p o + pp }
. pa ra m p={ pp }
. param pop = ’ pp+p
This line assigns numerical values to identifiers. More than one assignment per line is possible
using a space as separator. Parameter identifier names must begin with an alphabetic character.
The other characters must be either alphabetic, a number, or ! # $ % [ ] _ as special charac-
ters. The variables time,temper, and hertz (see 5.1.1) are no valid identifier names. Other
restrictions on naming conventions apply as well, see 2.8.6.
54 CHAPTER 2. CIRCUIT DESCRIPTION
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. Expression defining a parameter have to be put into braces {p+p2},
alternatively into single quotes ’AGAUSS(pippo, 1, 1.67)’.
2.8.2 Brace expressions in circuit elements:
General form:
{ < expr > }
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.
All identifiers used within an <expr> must have known values at the time when the line is
evaluated, else an error is flagged.
2.8.3 Subcircuit parameters
General form:
. s u b c k t < i d e n t n > node node . . . < i d e n t >=< va lu e > < i d e n t >=< v al ue > . . .
Examples:
. s u b c k t m y f i l t e r i n o u t r v a l =100 k c v a l =100nF
<identn> 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 <ident>=<value> introduces an optional
section of the line. Each <ident> is a formal parameter, and each <value> 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 <value> 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<name > nod e no de . . . < i d e n t n > < i d e n t >=< v a l u e > < i d e n t >=< v a l u e > . . .
Examples:
X1 i n p u t o u t p u t m y f i l t e r r v a l =1k c v a l =1n
Here <name> is the symbolic name given to that instance of the subcircuit, <identn> is the
name of a subcircuit defined beforehand. node node ... is the list of actual nodes where the
subcircuit is connected. <value> is either a spice number or a brace expression { <expr> } .
The sequence of <value> items on the Xline must exactly match the number and the order of
formal parameters of the subcircuit.
2.8. .PARAM PARAMETRIC NETLISTS 55
Subcircuit example with parameters:
*Paramexamp le
. param a m p l i t u d e = 1V
*
. s u b c k t m y f i l t e r i n o u t r v a l =100 k c v a l =100 nF
Ra i n p1 {2*rval}
Rb p1 o u t {2*rval}
C1 p1 0 {2*c v a l }
Ca i n p2 { c v a l }
Cb p2 o u t { c v a l }
R1 p2 0 { r v a l }
. e nd s m y f i l t e r
*
X1 i n p u t o u t p u t m y f i l t e r r v a l =1k c v a l =1n
V1 i n p u t 0 AC { a m p l i t u d e }
. 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 which has a formal parameter xx, A calls
B which has a param. xx, and B calls C which 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.
A word of caution: Ngspice allows to define circuits with nested subcircuits. Currently it is
not possible however to issue .param statements inside of a .subckt ... .ends section, when there
are additional, nested .subckt ... .ends in the same section. This is a bug, which will be removed
asap.
2.8.5 Syntax of expressions
<expr> ( optional parts within [ ...] ):
An expression may be one of:
<atom > where <atom > i s e i t h e r a s p i c e number o r an i d e n t i f i e r
< u na r y o p e r a t o r > <atom >
<functionname> ( < ex pr > [ , <e xp r > . . . ] )
<atom > < b i n a r y o p e r a t o r > < ex pr >
( < ex pr > )
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
56 CHAPTER 2. CIRCUIT DESCRIPTION
of the C language. For equal precedence binary ops, evaluation goes left to right. Functions
operate on real values only!
Operator Alias Precedence Description
- 1 unary -
! 1 unary not
** ^ 2 power, like pwr
* 3 multiply
/ 3 divide
% 3 modulo
\ 3 integer divide
+ 4 add
- 4 subtract
== 5 equality
!= <> 5 non-equal
<= 5 less or equal
>= 5 greater or equal
< 5 less than
> 5 greater than
&& 6 boolean and
|| 7 boolean or
c?x:y 8 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:
*L o g i c a l o p e r a t o r s
v1 or 1 0 {1 | | 0}
v1and 2 0 {1 && 0}
v 1 n o t 3 0 { ! 1}
v1mod 4 0 {5 % 3}
v 1 d i v 5 0 {5 \ 3}
v 0 n o t 6 0 { ! 0}
. control
op
p r i n t a l l v
. endc
. end
2.8. .PARAM PARAMETRIC NETLISTS 57
Built-in function Notes
sqr(x) y = x * x
sqrt(x) y = 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) atan(x), kept for compatibility
exp(x)
ln(x), log(x)
abs(x)
nint(x) Nearest integer, half integers towards even
int(x) Nearest integer rounded towards 0
floor(x) Nearest integer rounded towards -
ceil(x) Nearest integer rounded towards +
pow(x,y) x raised to the power of y (pow from C runtime library)
pwr(x,y) pow(fabs(x), y)
min(x, y)
max(x, y)
sgn(x) 1.0 for x > 0, 0.0 for x == 0, -1.0 for x < 0
ternary_fcn(x, y, z) x ? y : z
gauss(nom, rvar, sigma) nominal value plus variation drawn from Gaussian
distribution with mean 0 and standard deviation rvar
(relative to nominal), divided by sigma
agauss(nom, avar, sigma) nominal value plus variation drawn from Gaussian
distribution with mean 0 and standard deviation avar
(absolute), divided by sigma
unif(nom, rvar) nominal value plus relative variation (to nominal)
uniformly distributed between +/-rvar
aunif(nom, avar) nominal value plus absolute variation uniformly distributed
between +/-avar
limit(nom, 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 value
g 1e9
meg 1e6
k 1e3
m 1e-3
u 1e-6
n 1e-9
p 1e-12
f 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.
58 CHAPTER 2. CIRCUIT DESCRIPTION
2.8.6 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: and, or, not, div, mod, defined,
sqr, sqrt, sin, cos, exp, ln, arctan, abs, pwr, time, temper, hertz.
2.8.7 Alternative syntax
The & sign is tolerated to provide some “historical” parameter notation: & as the first character
of a line is equivalent to: .param.
Inside a line, the notation &(....) is equivalent to {....}, and &identifier means the same
thing as {identifier} .
Comments in the style of C++ line trailers (//) are detected and erased.
Warning: this is NOT possible in embedded .control parts of a source file, these lines are outside
of this scope.
Now, there is some possible confusion in ngspice because of multiple numerical expression
features. The .param lines and the braces expressions (see next chapter 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 correctly be substituted).
So, after the netlist expansion and before the internal data setup, all number attributes in the
circuit are known constants. However, there are some circuit elements in Spice which accept
arithmetic expressions that are 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 also accepts arithmetic/logic expressions that operate on its own
scalar or vector data sets (17.2). Please see also chapt. 2.13.
It would be desirable to have the same expression syntax, operator and function set, and prece-
dence rules, for the three contexts mentioned above. In the current Numparam implementation,
that goal is not yet achieved...
2.9 .FUNC
With this line a function may be defined. The syntax of its expression is equivalent to the
expression syntax from the .param line (2.8.5).
General form:
. fu n c < i d e n t > { < exp r > }
Examples:
. f u n c i c o s ( x ) { c o s ( x ) 1}
. f u n c f ( x , y ) { x*y}
.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
2.10. .CSPARAM 59
occurrences of f(x,y) will be replaced by x*y. Function statements may be nested to a depth
of t.b.d..
2.10 .CSPARAM
Create a constant vector (see 17.8.2) from a parameter in plot (17.3) “const”.
General form:
. cs par am < i d e n t > = < exp r >
Examples:
. pa ra m p i p p o =5
. param pp =6
. c s pa r a m p i p p p ={ p i p p o + pp }
. pa ra m p={ pp }
. cs par am pap = ’ pp+p
In the example shown, vectors pippp, and pap are added to the constants, which already reside
in plot “const”, with 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 v a l u e
Examples:
. temp 27
This card overrides the circuit temperature given in an .option line (15.1.1).
60 CHAPTER 2. CIRCUIT DESCRIPTION
2.12 .IF Condition-Controlled Netlist
A simple IF-ELSE block allows condition-controlling of the netlist. boolean expression is
any expression according to chapt. 2.8.5 which 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 which are selected according to the logic condition.
General form:
. i f ( b oo le a n e x p r e s s i o n )
. . .
. e l s e i f ( b o o le a n e x p r e s s i o n )
. . .
. e n d i f
Example 1:
*d e v i c e i n s t a n c e i n IFELSE b l o c k
. pa ra m ok =0 ok2 =1
v1 1 0 1
R1 1 0 2
. i f ( ok && ok2 )
R11 1 0 2
. else
R11 1 0 0 . 5 ; <s e l e c t e d
. e n d i f
Example 2:
*. model i n IFELSE b l o c k
. param m0=0 m1=1
M1 1 2 3 4 N1 W=1 L =0 .5
. i f (m0==1)
. model N1 NMOS l e v e l =49 V e r s i o n = 3 . 1
. e l s e i f ( m1==1)
. model N1 NMOS l e v e l =49 V er s io n = 3 . 2 . 4 ; <s e l e c t e d
. else
. model N1 NMOS l e v e l =49 V er s io n = 3 . 3 . 0
. e n d i f
For now this is a very restricted version of an IF-ELSE block, so several netlist components are
currently not supported within the IF-ELSE block: .SUBCKT, .INC, .LIB, .PARAM. Nesting
of IF-ELSE blocks is not possible. Only one .elseif is allowed per block.
2.13. PARAMETERS, FUNCTIONS, EXPRESSIONS, AND COMMAND SCRIPTS 61
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 simu-
lation 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 func-
tions, but also node voltages and branch currents which are 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 com-
mand 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 volt-
ages, 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
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.
62 CHAPTER 2. CIRCUIT DESCRIPTION
Expressions and scripting are powerful tools within ngspice, and we will enhance the examples
given in chapt. 21 continuously to describe these features.
Chapter 3
Circuit Elements and Models
Data fields that are enclosed in less-than and greater-than signs (’< >’) are optional. All indi-
cated punctuation (parentheses, equal signs, etc.) is optional but indicate the presence of any
delimiter. Further, future implementations may require the punctuation as stated. A consis-
tent 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 con-
vention (current flows in the direction of voltage drop).
3.1 General options and information
3.1.1 Simulating more devices in parallel
If you need to simulate more devices of the same kind in parallel, you can use the “m” (often
called parallel multiplier) option which is available for all instances except transmission lines
and sources (both independent and controlled). The parallel multiplier is implemented by mul-
tiplying the value of mthe element’s matrix stamp, thus it cannot be used to accurately simulate
larger devices in integrated circuits. The netlist below show 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 parallel d01-d10 con-
nected between 1 and 0.
63
64 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS
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 parame-
ters 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.9) and BSIM4 (11.2.10) models.
3.1.4 Multiplier m, initial conditions
The area factor “m” (often called parallel multiplier) used on the diode, BJT, JFET, and MES-
FET devices determines the number of equivalent parallel devices of a specified model. The
affected parameters are marked with an asterisk under the heading “area” in the model descrip-
tions (see the various chapters on models below). Several geometric factors associated with the
channel and the drain and source diffusions can be specified on the MOSFET device line.
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.
3.2. ELEMENTARY DEVICES 65
3.2 Elementary Devices
3.2.1 Resistors
General form:
RXXXXXXX n+ nv a l u e < ac = va l > <m= va l > < s c a l e = v al > <temp= v al >
+ <dtemp = val > < t c 1 = va l > < t c 2 = va l > < n o i s y =0|1 >
Examples:
R1 1 2 100
RC1 12 17 1K
R2 5 7 1K ac =2K
RL 1 4 2K m=2
Ngspice has a fairly complex model for resistors. It can simulate both discrete and semicon-
ductor 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
negative1but not zero.
Simulating small valued resistors: If you need to simulate very small resis-
tors (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 (not Pole-Zero nor noise). If you do not specify the ac parameter, it is defaulted
to value. If you want to simulate temperature dependence of a resistor, you need to specify its
temperature coefficients, using a .model line, like in the example below:
Example:
RE1 1 2 800 n ew re s dtemp =5
.MODEL ne wr es R t c 1 =0 .00 1
The temperature coefficients tc1 and tc2 describe a quadratic temperature dependence (see
equation17.12) 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). 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 noise2source 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 keyword and assigning zero to it, as in
the following example:
Example:
Rmd 134 57 1 . 5 k n o i s y =0
1A negative resistor modeling an active element can cause convergence problems, please avoid it.
2Flicker noise can be used to model carbon resistors.
66 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS
Ngspice calculates the nominal resistance as described below:
Rnom =VALUEscale
m
Racnom =acscale
m
(3.1)
If you are interested in temperature effects or noise equations, read the next section on semi-
conductor resistors.
3.2.2 Semiconductor Resistors
General form:
RXXXXXXX n+ n< v alu e > <mname> < l = l e n g t h > <w= wid th > <temp= v al >
+ <dtemp = val > <m= v al > < ac = val > < s c a l e = va l > < n o i s y = 0|1 >
Examples:
RLOAD 2 10 10K
RMOD 3 7 RMODEL L=10 u W=1u
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 geo-
metric 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 calcu-
lated from geometric information and to be corrected for temperature. The parameters available
are:
Name Parameter Units Default Example
TC1 first order temperature coeff.
/C0.0 -
TC2 second order temperature coeff.
/C20.0 -
RSH sheet resistance
/- 50
DEFW default width m1e-6 2e-6
NARROW narrowing due to side etching m0.0 1e-7
SHORT shortening due to side etching m0.0 1e-7
TNOM parameter measurement temperature C27 50
KF flicker noise coefficient 0.0 1e-25
AF flicker noise exponent 0.0 1.0
R (RES) default value if element value not given - 1000
The sheet resistance is used with the narrowing parameter and land wfrom the resistor device
to determine the nominal resistance by the formula:
3.2. ELEMENTARY DEVICES 67
Rnom =rsh lSHORT
wNARROW (3.2)
DEFW is used to supply a default value for wif one is not specified for the device. If either rsh
or lis 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(TTNOM) + TC2(TTNOM)2(3.3)
where R(TNOM) = Rnom|Racnom. In the above formula, T” represents the instance tempera-
ture, which can be explicitly set using the temp keyword or calculated using the circuit tem-
perature and dtemp, if present. If both temp and dtemp are specified, the latter is ignored.
Ngspice improves spice’s resistors noise model, adding flicker noise (1
/f) to it and the noisy
keyword to simulate noiseless resistors. The thermal noise in resistors is modeled according to
the equation:
¯
i2
R=4kT
R
f(3.4)
where "k" is the Boltzmann’s constant, and "T" the instance temperature.
Flicker noise model is:
¯
i2
R f n =KFIAF
R
f
f(3.5)
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 Min. Typ. Max.
Inter-metal (metal1 - metal2) 0.005 0.007 0.1
Top-metal (metal3) 0.003 0.004 0.05
Polysilicon (poly) 15 20 30
Silicide 2 3 6
Diffusion (n+, p+) 10 25 100
Silicided diffusion 2 4 10
n-well 1000 2000 5000
68 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS
3.2.4 Resistors, dependent on expressions (behavioral resistor)
General form:
RXXXXXXX n+ nR = e x p r e s s i o n < t c 1 = v a l u e > < t c 2 = v a l u e >
RXXXXXXX n+ n e x p r e s s i o n < t c 1 = va lu e > < t c 2 = v al ue >
Examples:
R1 r r 0 r = V( r r ) < { Vt } ? {R0} : {2*R0} t c 1 =2e 03 t c 2 =3 .3 e06
R2 r 2 r r r = {5 k + 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 chapter
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.
Example input file for non-linear resistor:
Nonl i n e a r r e s i s t o r
. param R0=1k Vi=1 Vt = 0. 5
*r e s i s t o r d ep e nd i ng on c o n t r o l v o l t a g e V( r r )
R1 r r 0 r = V( r r ) < { Vt } ? {R0} : {2*R0} ’
*c o n t r o l v o l t a g e
V1 r r 0 PWL( 0 0 100 u { Vi } )
. control
set noaskquit
t r a n 100 n 100 u u i c
p l o t i ( V1 )
. endc
. end
3.2.5 Capacitors
General form:
CXXXXXXX n+ n< v alu e > <mname> <m= v al > < s c a l e = v al > <temp= v al >
+ <dtemp= v al > < t c 1 = v al > < t c 2 = va l > < i c = i n i t _ c o n d i t i o 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:
3.2. ELEMENTARY DEVICES 69
C1 15 5 c s t d
C2 2 7 c s t d
. model c s t d C ca p =3n
Both capacitors have a capacitance of 3nF.
If you want to simulate temperature dependence of a capacitor, you need to specify its temper-
ature coefficients, using a .model line, like in the example below:
CEB 1 2 1 u cap 1 dtemp =5
.MODEL cap1 C t c 1 =0 .00 1
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.6)
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< v alu e > <mname> < l = l e n g t h > <w= wid th > <m= va l >
+ < s c a l e = va l > <temp= va l > <dtemp= v al > < i c = i n i t _ c o n d i t i o n >
Examples:
CLOAD 2 10 10P
CMOD 3 7 CMODEL L=10 u 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 speci-
fications 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,wkeywords, re-
spectively).
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.
70 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS
Name Parameter Units Default Example
CAP model capacitance F0.0 1e-6
CJ junction bottom capacitance F/m2- 5e-5
CJSW junction sidewall capacitance F/m- 2e-11
DEFW default device width m1e-6 2e-6
DEFL default device length m0.0 1e-6
NARROW narrowing due to side etching m0.0 1e-7
SHORT shortening due to side etching m0.0 1e-7
TC1 first order temperature coeff. F/C0.0 0.001
TC2 second order temperature coeff. F/C20.0 0.0001
TNOM parameter measurement temperature C27 50
DI relative dielectric constant F/m- 1
THICK insulator thickness m0.0 1e-9
The capacitor has a capacitance computed as:
If value is specified on the instance line then
Cnom =value scale m(3.7)
If model capacitance is specified then
Cnom =CAP scale m(3.8)
If neither value nor CAP are specified, then geometrical and physical parameters are take into
account:
C0=CJ(lSHORT)(wNARROW) + 2CJSW(lSHORT +wNARROW)(3.9)
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 if DI is specified,
CJ =εSiO2
THICK otherwise.(3.10)
If the relative dielectric constant is not specified the one for SiO2 is used. The values of the
constants are: ε0=8.854214871e12F
mand εSiO2=3.4531479969e11F
m. The nominal
capacitance is then computed as:
Cnom =C0scale m(3.11)
After the nominal capacitance is calculated, it is adjusted for temperature by the formula:
C(T) = C(TNOM)1+TC1(TTNOM) + TC2(TTNOM)2(3.12)
3.2. ELEMENTARY DEVICES 71
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+ nC = e x p r e s s i o n < t c 1 = v a l u e > < t c 2 = v a l u e >
CXXXXXXX n+ n e x p r e s s i o n < t c 1 = va lu e > < t c 2 = v al ue >
Examples:
C1 cc 0 c = V( c c ) < { Vt } ? {C1} : {Ch } t c 1 =1e 03 t c 2 =1 .3 e05
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 chapter
5.1. It may contain parameters (2.8.1) and the special variables time, temper, and hertz (5.1.2).
Example input file:
B e h a v i o r a l C a p a c i t o r
. param Cl =5n Ch=1n Vt =1m I l =100 n
. i c v ( cc ) = 0 v ( cc 2 ) = 0
*c a p a c i t o r d ep en din g on c o n t r o l v o l t a g e V( cc )
C1 cc 0 c = V( c c ) < { Vt } ? { Cl } : {Ch }
*C1 cc 0 c ={Ch}
I 1 0 1 { I l }
Exxx n1copy n2 n2 cc2 1
Cxxx n1copy n2 1
Bxxx cc 2 n2 I = ’ (V( c c2 ) < { Vt } ? { Cl } : {Ch } ) *i ( Exxx )
I 2 n2 22 { I l }
vn2 n2 0 DC 0
*me as ure c h a r g e by i n t e g r a t i n g c u r r e n t
a i n t 1 %i d ( 1 cc ) 2 t i m e _ c o u n t
a i n t 2 %i d (2 2 cc 2 ) 3 t i m e _ c o u n t
. model t i m e _ c o u n t i n t ( i n _ o f f s e t = 0. 0 g a i n = 1. 0
+ out_lower_limit=1e12 o u t _ u p p e r _ l i m i t =1 e12
+ l i m i t _ r a n g e =1e9 o u t _ i c = 0 . 0 )
. control
set noaskquit
t r a n 100 n 100 u
p l o t v ( 2 )
p l o t v ( cc ) v ( cc2 )
. endc
. end
72 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS
3.2.9 Inductors
General form:
LYYYYYYY n+ n<v al u e > <mname> < n t = v al > <m= v al > < s c a l e = v al > <temp= v al >
+ <dtemp= v al > < t c 1 = v al > < t c 2 = va l > <m= v al > < i c = i n i t _ c o n d i t i o n >
Examples:
LLINK 42 69 1UH
LSHUNT 23 51 10U IC = 15 .7MA
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 i n d =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:
L lo ad 1 2 1u i n d 1 dtemp =5
.MODEL i n d 1 L t c 1 = 0. 0 0 1
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 =value scale
m(3.13)
3.2.10 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 73
Name Parameter Units Default Example
IND model inductance H0.0 1e-3
CSECT cross section m20.0 1e-3
LENGTH length m0.0 1e-2
TC1 first order temperature coeff. H/C0.0 0.001
TC2 second order temperature coeff. H/C20.0 0.0001
TNOM parameter measurement temperature C27 50
NT number of turns - 0.0 10
MU relative magnetic permeability H/m0.0 -
The inductor has an inductance computed as:
If value is specified on the instance line then
Lnom =value scale
m(3.14)
If model inductance is specified then
Lnom =IND scale
m(3.15)
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 =MUµ0NT2CSECT
LENGTH if MU is specified,
Lnom =µ0NT2CSECT
LENGTH otherwise.(3.16)
with:µ0=1.25663706143592e6H
m. After the nominal inductance is calculated, it is adjusted
for temperature by the formula:
L(T) = L(TNOM)1+TC1(TTNOM) + TC2(TTNOM)2(3.17)
where L(TNOM) = Lnom. In the above formula, “T” represents the instance temperature, which
can be explicitly using the temp keyword or calculated using the circuit temperature and dtemp,
if present.
3.2.11 Coupled (Mutual) Inductors
General form:
KXXXXXXX LYYYYYYY LZZZZZZZ v a l u e
Examples:
K43 LAA LBB 0 . 9 9 9
KXFRMR L1 L2 0 . 8 7
74 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS
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+ nL = e x p r e s s i o n < t c 1 = v a l u e > < t c 2 = v a l u e >
LXXXXXXX n+ n e x p r e s s i o n < t c 1 = v al ue > < t c 2 = va lu e >
Examples:
L1 l 2 l l l L = i (Vm) < { I t } ? { Ll } : {Lh } t c 1 =4e03 t c 2 =6e05
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 chapter
5.1. It may contain parameters (2.8.1) and the special variables time, temper, and hertz (5.1.2).
3.2. ELEMENTARY DEVICES 75
Example input file:
V a r i a b l e i n d u c t o r
. param Ll = 0 .5m Lh=5m I t =50 u Vi=2m
. i c v ( i n t 2 1 ) = 0
*v a r i a b l e i n d u c t o r d e pe n di n g on c o n t r o l c u r r e n t i (Vm)
L1 l 2 l l l L = i (Vm) < { I t } ? { Ll } : {Lh }
*me as ure c u r r e n t t h r o u g h i n d u c t o r
vm l l l 0 dc 0
*v o l t a g e on i n d u c t o r
V1 l 2 0 { Vi }
*f i x e d i n d u c t o r
L3 33 331 { Ll }
*me as ure c u r r e n t t h r o u g h i n d u c t o r
vm33 331 0 dc 0
*v o l t a g e on i n d u c t o r
V3 33 0 { Vi }
*non l i n e a r i n d u c t o r ( d i s c r e t e s e t u p )
F21 i n t 2 1 0 B21 1
L21 i n t 2 1 0 1
B21 n1 n2 V = ( i (Vm21 ) < { I t } ? { L l } : {Lh } ) *v ( i n t 2 1 )
*me as ure c u r r e n t t h r o u g h i n d u c t o r
vm21 n2 0 dc 0
V21 n1 0 { Vi }
. control
set noaskquit
t r a n 1u 100 u u i c
p l o t i (Vm) i ( vm33 )
p l o t i ( vm21 ) i ( vm33 )
p l o t 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 which can be substituted for the SPICE models when
realistic initial conditions are required. For details please refer to chapt. 12. A XSPICE deck
example using these models is shown below:
*
* This circuit contains a capacitor and an inductor with
* initial conditions on them. Each of the components
76 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS
* 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+ NNC+ NCMODEL <ON><OFF>
WYYYYYYY N+ NVNAM MODEL <ON><OFF>
Examples:
s1 1 2 3 4 s w i t c h 1 ON
s2 5 6 3 0 sm2 o f f
Sw it ch 1 1 2 10 0 sm ode l1
w1 1 2 v c l o c k sw it ch mod 1
W2 3 0 vramp sm1 ON
w r e s e t 5 6 v c l c k l o s s y s w i t c h 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 77
3.2.15 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 Parameter Units Default Switch model
VT threshold voltage V 0.0 SW
IT threshold current A 0.0 CSW
VH hysteresis voltage V 0.0 SW
IH hysteresis current A 0.0 CSW
RON on resistance 1.0 SW,CSW
ROFF off resistance 1.0e+12 (*) 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 discontinu-
ities 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 ideal switch impedances 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 real-
istic 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 de-
creased 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 re-
duced. 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.
78 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS
Example input file:
Swi tc h t e s t
. t r a n 2 us 5ms
*s w i t c h c o n t r o l v o l t a g e
v1 1 0 DC 0. 0 PWL( 0 0 2e3 2 4e3 0 )
*s w i t c h c o n t r o l v o l t a g e s t a r t i n g i n s i d e h y s t e r e s i s window
*p l e a s e n ote i n f l u e n c e of i n s t a n c e p a r a m e t e r s ON, OFF
v2 2 0 DC 0 . 0 PWL( 0 0 . 9 2e3 2 4e3 0 . 4 )
*switch control current
i 3 3 0 DC 0 . 0 PWL( 0 0 2e3 2m 4e3 0 ) $ <switch control current
*load voltage
v4 4 0 DC 2 . 0
*i n p u t l o a d f o r c u r r e n t s o u r c e i 3
r 3 3 33 10 k
vm3 33 0 dc 0 $ <mea su re t h e c u r r e n t
*o up ut l o a d r e s i s t o r s
r10 4 10 10 k
r20 4 20 10 k
r30 4 30 10 k
r40 4 40 10 k
*
s1 10 0 1 0 s w i t c h 1 OFF
s2 20 0 2 0 s w i t c h 1 OFF
s3 30 0 2 0 s w i t c h 1 ON
. model s w i t c h 1 sw v t =1 vh = 0. 2 r on =1 r o f f =10 k
*
w1 40 0 vm3 w swi tc h1 o f f
. model w switc h1 csw i t =1m i h = 0. 2m ro n =1 r o f f =10k
*
. control
run
p l o t v ( 1 ) v ( 1 0 )
p l o t v ( 1 0 ) vs v ( 1 ) $ <get hysteresis loop
p l o t v ( 2 ) v ( 2 0 ) $ <d i f f e r e n t i n i t i a l v a l u e s
p l o t v ( 2 0 ) vs v ( 2 ) $ <get hysteresis loop
p l o t v ( 2 ) v ( 3 0 ) $ <d i f f e r e n t i n i t i a l v a l u e s
p l o t v ( 3 0 ) vs v ( 2 ) $ <get hysteresis loop
p l o t v ( 4 0 ) vs vm3# b r a n c h $ <c u r r e n t c o n t r o l l e d s w i t c h h y s t e r e s i s
. endc
. end
Chapter 4
Voltage and Current Sources
4.1 Independent Sources for Voltage or Current
General form:
VXXXXXXX N+ N<<DC> DC/TRAN VALUE> <AC <ACMAG <ACPHASE>>>
+ <DISTOF1 <F1MAG <F1PHASE>>> <DISTOF2 <F2MAG <F2PHASE>>>
IYYYYYYY N+ N<<DC> DC/TRAN VALUE> <AC <ACMAG <ACPHASE>>>
+ <DISTOF1 <F1MAG <F1PHASE>>> <DISTOF2 <F2MAG <F2PHASE>>>
Examples:
VCC 10 0 DC 6
VIN 13 2 0 . 0 0 1 AC 1 SIN ( 0 1 1MEG)
ISRC 23 21 AC 0 . 3 3 3 4 5 . 0 SFFM( 0 1 10K 5 1K)
VMEAS 12 9
VCARRIER 1 0 DISTOF1 0 . 1 90.0
VMODULATOR 2 0 DISTOF2 0 . 0 1
II N1 1 5 AC 1 DISTOF1 DISTOF2 0 . 0 0 1
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.
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).
79
80 CHAPTER 4. VOLTAGE AND CURRENT SOURCES
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 explanation)).
4.1.1 Pulse
General form:
PULSE( V1 V2 TD TR TF PW PER )
Examples:
VIN 3 0 PULSE(1 1 2NS 2NS 2NS 50NS 100NS)
Name Parameter Default Value Units
V1 Initial value - V,A
V2 Pulsed value - V,A
TD Delay time 0.0 sec
TR Rise time TSTEP sec
TF Fall time TSTEP sec
PW Pulse width TSTOP sec
PER Period TSTOP sec
A single pulse so specified is described by the following table:
4.1. INDEPENDENT SOURCES FOR VOLTAGE OR CURRENT 81
Time Value
0 V1
TD V1
TD+TR V2
TD+TR+PW V2
TD+TR+PW+TF V1
TSTOP V1
Intermediate points are determined by linear interpolation.
4.1.2 Sinusoidal
General form:
SIN (VO VA FREQ TD THETA)
Examples:
VIN 3 0 SIN ( 0 1 100MEG 1NS 1E10 )
Name Parameter Default Value Units
VO Offset - V,A
VA Amplitude - V,A
FREQ Frequency 1
/T ST OP Hz
TD Delay 0.0 sec
THETA Damping factor 0.0 1
/sec
The shape of the waveform is described by the following formula:
V(t) = (V0 if 0 t<T D
V0+VAe(tT D)T HETA sin(2πFREQ (tT D)) if T D t<T STOP (4.1)
4.1.3 Exponential
General Form:
EXP( V1 V2 TD1 TAU1 TD2 TAU2)
Examples:
VIN 3 0 EXP(41 2NS 30NS 60NS 40NS)
Name Parameter Default Value Units
V1 Initial value - V,A
V2 pulsed value - V,A
TD1 rise delay time 0.0 sec
TAU1 rise time constant TSTEP sec
TD2 fall delay time TD1+TSTEP sec
TAU2 fall time constant TSTEP sec
The shape of the waveform is described by the following formula:
82 CHAPTER 4. VOLTAGE AND CURRENT SOURCES
Let V21 =V2V1V12 =V1V2:
V(t) =
V1 if 0 t<T D1,
V1+V211e(tT D1)
TAU1if T D1t<T D2,
V1+V211e