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

Contents

Prefaces

Preface to the first edition

This manual has been assembled from different sources:

1. The spice3f5 manual,
2. the XSPICE user’s manual,
3. the CIDER user’s manual

and some original material needed to describe the new features and the newly implemented models. This cut and paste approach, while not being orthodox, allowed ngspice to have a full manual in a fraction of the time that writing a completely new text would have required. The use of LaTex and Lyx instead of TeXinfo, which was the original encoding for the manual, further helped to reduce the writing effort and improved the quality of the result, at the expense of an on-line version of the manual but, due to the complexity of the software I hardly think that users will ever want to read an on-line text version.

In writing this text I followed the 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 TE 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

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 LY 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,

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,

Charles D.H. Williams,

Antony Wilson,

and many others...

If someone helped in the development and has not been inserted in this list then this omission was unintentional. If you feel you should be on this list then please write to <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 California at Berkeley. The authors of XSPICE gratefully acknowledge UC Berkeley’s development and distribution of this software, and their licensing policies which promote further improvements to simulation technology.

We also gratefully acknowledge the participation and support of our U.S. Air Force sponsors, the Aeronautical Systems Center and the Warner Robins Air Logistics Command, without which the development of XSPICE would not have been possible.

Chapter 1
Introduction

Ngspice is a general-purpose circuit simulation program for nonlinear and linear analyses. Circuits may contain resistors, capacitors, inductors, mutual inductors, independent or dependent voltage and current sources, loss-less and lossy transmission lines, switches, uniform distributed RC lines, and the five most common semiconductor devices: diodes, BJTs, JFETs, MESFETs, and MOSFETs.

Some introductory remarks on how to use ngspice may be found in 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 parameters are not specified, the basic model (BJT) reduces to the simpler Ebers-Moll model. In either case and in either models, charge storage effects, ohmic resistances, and a current-dependent output conductance may be included. The second bipolar model BJT2 adds dc current computation in the substrate diode. The third model (VBIC) contains further enhancements for advanced bipolar devices.

The semiconductor diode model can be used for either junction diodes or Schottky barrier diodes. There are two models for JFET: the first (JFET) is based on the model of Shichman and Hodges, the second (JFET2) is based on the Parker-Skellern model. All the original six MOSFET models are implemented: MOS1 is described by a square-law I-V characteristic, MOS2 [1] is an analytical model, while MOS3 [1] is a semi-empirical model; MOS6 [2] is a simple analytic model accurate in the short channel region; MOS9, is a slightly modified Level 3 MOSFET model - not to confuse with Philips level 9; BSIM 1 [3, 4]; BSIM2 [5] are the old BSIM (Berkeley Short-channel IGFET Model) models. MOS2, MOS3, and BSIM include second-order effects such as channel-length modulation, subthreshold conduction, scattering-limited velocity saturation, small-size effects, and charge controlled capacitances. The recent MOS models for submicron devices are the BSIM3 (Berkeley BSIM3 web page) and BSIM4 (Berkeley BSIM4 web page) models. Silicon-on-insulator MOS transistors are described by the SOI models from the BSIMSOI family (Berkeley BSIMSOI web page) and the STAG [18] one. There is partial support for a couple of HFET models and one model for MESA devices.

Ngspice supports mixed-level simulation and provides a direct link between technology parameters and circuit performance. A mixed-level circuit and device simulator can provide greater simulation accuracy than a stand-alone circuit or device simulator by numerically modeling the critical devices in a circuit. Compact models can be used for 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 Kirchhoff’s Laws for the circuit at time steps selected to ensure the solution has converged to a stable value and that numerical approximations of integrations are sufficiently accurate. Since Kirchhoff’s laws form a set of simultaneous equations, the simulator operates by solving a matrix of equations at each time point. This matrix processing generally results in slower simulation times when compared to digital circuit simulators.

The response of a circuit is a function of the applied sources. Ngspice offers a variety of source types including DC, sine-wave, and pulse. In addition to specifying sources, the user must define the type of simulation to be run. This is termed the “mode of analysis”. Analysis modes include DC analysis, AC analysis, and transient analysis. For DC analysis, the 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 Kirchhoff’s laws is not required. Instead, the simulator must only determine whether a change in the logic state of a node has occurred and propagate this change to connected elements. Such a change is called an “event”.

When an event occurs, the simulator examines only those circuit elements that are affected by the event. As a result, matrix analysis is not required in digital simulators. By comparison, analog simulators must iteratively solve for the behavior of the entire circuit because of the forward and reverse transmission properties of analog components. This difference results in a considerable computational advantage for digital circuit simulators, which is reflected in the significantly greater speed of digital simulations.

1.1.3 Mixed-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 algorithm and a digital algorithm in the same executable. Glued mode simulators actually use two simulators, one of which is analog and the other digital. This type of simulator must define an input/output protocol so that the two executables can communicate with each other effectively. The communication constraints tend to reduce the speed, and sometimes the accuracy, of the complete simulator. On the other hand, the use of a glued mode simulator allows the component models developed for the separate executables to be used without modification.

Ngspice is a native mode simulator providing both analog and event-based simulation in the same executable. The underlying algorithms of ngspice (coming from XSPICE and its Code Model Subsystem) allow use of all the standard SPICE models, provide a pre-defined collection of the most common analog and digital functions, and provide an extensible base on which to build additional models.

1.1.3.1 User-Defined Nodes

Ngspice supports creation of “User-Defined Node” types. User-Defined Node types allow you to specify nodes that propagate data other than voltages, currents, and digital states. Like digital 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 solution of Poisson’s equation, and the electron and hole current-continuity equations. DSIM incorporates many of the same basic physical models found in the Stanford two-dimensional device simulator PISCES. Input to CIDER consists of a SPICE-like description of the circuit and its compact models, and PISCES-like descriptions of the structures of numerically modeled devices. As a result, CIDER should seem familiar to designers already accustomed to these two tools. 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 transverse field mobility degradation important in scaled-down MOSFETs and a polysilicon model for poly-emitter bipolar transistors. Temperature dependence has been included over the range from -50C to 150C. The numerical models can be used to simulate all the basic types of semiconductor devices: resistors, MOS capacitors, diodes, BJTs, JFETs and MOSFETs. BJTs and JFETs can be modeled with or without a substrate contact. Support has been added for the management of device internal states. Post-processing of device states can be performed using the ngnutmeg user interface.

1.1.4.2 GSS TCAD

GSS is a TCAD software which enables two-dimensional numerical simulation of semiconductor device with well-known drift-diffusion and hydrodynamic method. GSS has Basic DDM (drift-diffusion method) solver, Lattice Temperature Corrected DDM solver, EBM (energy balance method) solver and Quantum corrected DDM solver which based on density-gradient theory. The GSS program is directed via input statements by a user specified disk file. Supports triangle mesh generation and adaptive mesh refinement. Employs PMI (physical model interface) to support various materials, including compound semiconductor materials such as SiGe and AlGaAs. Supports DC sweep, transient and AC sweep calculations. The device can be stimulated by voltage or current source(s).

GSS is no longer updated, but is still available as open source as a limited edition of the commercial 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.

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 temperature¹ is 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 begins by obtaining a DC solution to provide a point of departure for simulating time-varying behavior. Once the DC solution is obtained, the time-dependent aspects of the system are reintroduced, and the two simulator algorithms incrementally solve for the time varying behavior of the entire system. Inconsistencies in node values are resolved by the two simulation algorithms such that the time-dependent waveforms created by the analysis are consistent across the entire simulated time interval. Resulting time-varying descriptions of node behavior for the specified time interval are accessible to you.

All sources 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 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 sensitivity of an output variable with respect to all circuit variables, including model parameters. Ngspice calculates the difference in an output variable (either a node voltage or a branch current) by perturbing each parameter of each device independently. Since the method is a numerical approximation, the results may demonstrate second order 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).

1.2.7 Noise Analysis

The noise analysis portion of Ngspice does analysis device-generated noise for the given circuit. When provided with an input source and an output port, the analysis calculates the noise contributions of each device (and each noise generator within the device) to the output port voltage. It also calculates the 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/current (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 option. Circuit temperature has a default (nominal) value of 27°C (300.15 K) that can be changed using the TEMP option in an .option control line (see 15.1.1) or by the .TEMP line (see 2.11), which has precedence over the .option TEMP line. All analyses are, thus, performed at circuit temperature, and if you want to simulate circuit behavior at different temperatures you should prepare a netlist for each temperature.

All input data for ngspice is assumed to have been measured at the circuit nominal temperature. This value can further be overridden for any device 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:

Temperature dependent support is provided for all devices except voltage and current sources (either independent and controlled) and BSIM models. BSIM MOSFETs have an alternate temperature dependency scheme 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:

(1.1)

where k is Boltzmann’s constant, q is the electronic charge, E_g is the energy gap which is a model parameter, and XT I is the saturation current temperature exponent (also a model parameter, and usually equal to 3).

The temperature dependence of forward and reverse beta is according to the formula:

(1.2)

where T ₀ and T ₁ are in degrees Kelvin, and XT B is a user-supplied model parameter. Temperature effects on beta are carried out by appropriate adjustment to the values of B_F , I_SE, B_R, and I_SC (spice model parameters BF, ISE, BR, and ISC, respectively).

Temperature dependence of the saturation current in the junction diode model is determined by:

(1.3)

where N is 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:

(1.4)

where k is Boltzmann’s constant, q is the electronic charge, N_a is the acceptor impurity density, N_d is the donor impurity density, N_i is the intrinsic carrier concentration, and E_g is the energy gap. Temperature appears explicitly in the value of surface mobility, M₀(or U₀), for the MOSFET model.

The temperature dependence is determined by:

(1.5)

The effects of temperature on resistors, capacitor and inductors is modeled by the formula:

(1.6)

where T is the circuit temperature, T ₀ is the nominal temperature, and T C₁ and T C₂ are the first and second order temperature coefficients.

1.4 Convergence

Ngspice uses the Newton-Raphson algorithm to solve nonlinear equations arising from circuit description. The NR algorithm is interactive and terminates when both of the following conditions hold:

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 k and the current one (k+1):

(1.7)

where

(1.8)

The RELTOL (RELative TOLerance) parameter, which default value is 10^-3, specifies how small the solution update must be, relative to the node voltage, to consider the solution to have converged. The VNTOL (absolute convergence) parameter, which has 1μV as default becomes important when node voltages have near zero values. The relative parameter alone, in such case, would need too strict tolerances, perhaps lower than computer round-off error, and thus convergence would never be achieved. VNTOL forces the algorithm to consider as converged any node whose solution update is lower than its value.

1.4.2 Current convergence criterion

Ngspice checks the convergence on the non-linear functions that describe the non-linear branches in circuit elements. In semiconductor devices the functions defines currents through the device and thus the name of the criterion.

Ngspice computes the difference between the value of the nonlinear function computed for last voltage and the linear approximation of the same current computed with the actual voltage:

(1.9)

where

(1.10)

In the two expressions above, the 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.

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 frequently 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 element.

The first letter of the element instance name specifies the element type. The format for the ngspice element types is given in the following manual chapters. In the rest of the manual, the strings XXXXXXX, YYYYYYY, and ZZZZZZZ denote arbitrary alphanumeric strings.

For example, a resistor instance name must begin with the letter R and can contain one or more characters. Hence, R, R1, RSE, ROUT, and R3AC2ZY are valid resistor names. Details of each type of device are supplied in a following section 3. Table 2.1 lists the element types which are available in ngspice, sorted by the first letter.

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:

Letters immediately following a number that are not scale factors are ignored, and letters immediately following a scale factor are ignored. Hence, 10, 10V, 10Volts, and 10Hz all represent the same number, and M, MA, MSec, and MMhos all represent the same scale factor. Note that 1000, 1000.0, 1000Hz, 1e3, 1.0e3, 1kHz, and 1k all represent the same number. Note that M or m denote ’milli’, i.e. 10^-3. Suffix meg has to be used for 10⁶.

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).

2.2 Basic lines

2.2.1 .TITLE line

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.

will internally be replaced by

2.2.2 .END Line

The ".End" line must always be the last in the input file. Note that the period is an integral part of the name.

2.2.3 Comments

The asterisk in the first column indicates that this line is a comment line. Comment lines may be placed anywhere in the circuit description.

2.2.4 End-of-line comments

General Form:

Examples:

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

Most simple circuit elements typically require only a few parameter values. However, some devices (semiconductor devices in particular) that are included in ngspice require many parameter values. Often, many devices in a circuit are defined by the same set of device model parameters. For these reasons, a set of device model parameters is defined on a separate .model line and assigned a unique model name. The device element lines in ngspice then refer to the model name.

For these more complex device types, each device element line contains the device name, the nodes 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 (8 to 11) and Diodes (7) for more details). mname in the above is the model name, and type is one of the following fifteen types:

Parameter values are defined by appending the parameter name followed by an equal sign and the parameter value. Model parameters that are not given a value are assigned the default values given below for each model type. Models are listed in the section on each device along with the description of device element lines. Model parameters and their default values are given in 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:

Example:

* The following is the instance card: 
* 
xdiv1 10 7 0 vdivide 
 
* The following are the subcircuit definition cards: 
* 
.subckt vdivide 1 2 3 
r1 1 2 10K 
r2 2 3 5K 
.ends

The above specifies a subcircuit with ports numbered “1”, “2” and “3”:

• Resistor ”R1” is connected from port “1” to port “2”, and has value 10 kOhms.
• Resistor “R2” is connected from port “2” to port “3”, and has value 5 kOhms.

The instance card, when placed in an ngspice deck, will cause subcircuit port “1” to be equated to circuit node “10”, while port “2” will be equated to node “7” and port “3” will equated to node “0”.

There is no limit on the size or complexity of subcircuits, and subcircuits may contain other subcircuits. An example of subcircuit usage is given in chapter 21.6.

2.4.1 .SUBCKT Line

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).

2.4.2 .ENDS Line

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

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

Nodes defined in the .GLOBAL statement are available to all circuit and subcircuit blocks independently from any circuit hierarchy. After parsing the circuit, these nodes are accessible from top level.

2.6 .INCLUDE

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

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

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 characters. 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.

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:

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

<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:

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 X line must exactly match the number and the order of formal parameters of the subcircuit.

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 [ ...] ):

As expected, atoms, built-in function calls and stuff within parentheses are evaluated before the other operators. The operators are evaluated following a list of precedence close to the one of the C language. For equal precedence binary ops, evaluation goes left to right. Functions operate on real values only!

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:

The scaling suffixes (any decorative alphanumeric string may follow):

Note: there are intentional redundancies in expression syntax, e.g. x^y , x**y and pwr(x,y) all have nearly the same result.

2.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 precedence 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).

.func will initiate a replacement operation. After reading the input files, and before parameters are evaluated, all occurrences of the icos(x) function will be replaced by cos(x)-1. All occurrences of f(x,y) will be replaced by x*y. Function statements may be nested to a depth of t.b.d..

2.10 .CSPARAM

Create a constant vector (see 17.8.2) from a parameter in plot (17.3) “const”.

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.

This card overrides the circuit temperature given in an .option line (15.1.1).

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.

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

In ngspice there are several ways to describe functional dependencies. In fact there are three independent function parsers, being active before, during, and after the simulation. So it might be due to have a few words on their interdependence.

2.13.1 Parameters

Parameters (chapt. 2.8.1) and functions, either defined within the .param statement or with the .func statement (chapt. 2.9) are evaluated before any simulation is started, that is during the setup of the input and the circuit. Therefore these statements may not contain any simulation output (voltage or current vectors), because it is simply not yet available. The syntax is described in chapt. 2.8.5. During the circuit setup all functions are evaluated, all parameters are replaced by their resulting numerical values. Thus it will not be possible to get feedback from a later stage (during or after simulation) to change any of the parameters.

2.13.2 Nonlinear sources

During the simulation, the B source (chapt. 5) and their associated E and G sources, as well as some devices (R, C, L) may contain expressions. These expressions may contain parameters from above (evaluated immediately upon ngspice start up), numerical data, predefined functions, but also node voltages and branch currents 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 command script enclosed in .control ... .endc lines. The scripts may contain expressions (see chapt. 17.2). The expressions may work upon simulation output vectors (of node voltages, branch currents), as well as upon predefined or user defined vectors and variables, and are invoked after the simulation. Parameters from 2.8.1 defined by the .param statement are not allowed in these expressions. However you may define such parameters with .csparam (2.10). Again the expression syntax (see chapt. 17.2) will deviate from the one for parameters or B sources listed in 2.8.1 and 5.1.

If you want to use parameters from 2.8.1 inside your control script, you may use .csparam (2.10) or apply a trick by defining a voltage source with the parameter as its value, and then have it available as a vector (e.g. after a transient simulation) with a then constant output (the parameter). A feedback from here back into parameters (2.13.1) is never possible. Also you cannot access non-linear sources of the preceding simulation. However you may start a first simulation inside your control script, then evaluate its output using expressions, change some of the element or model parameters with the alter and altermod statements (see chapt. 17.5.3) and then automatically start a new simulation.

Expressions and scripting are powerful tools within ngspice, and we will enhance the examples given in chapt. 21 continuously to describe these features.

Chapter 3
Circuit Elements and Models

Data fields that are enclosed in less-than and greater-than signs (’< >’) are optional. All indicated punctuation (parentheses, equal signs, etc.) is optional but indicate the presence of any delimiter. Further, future implementations may require the punctuation as stated. A consistent style adhering to the punctuation shown here makes the input easier to understand. With respect to branch voltages and currents, ngspice uniformly uses the associated reference convention (current flows in the direction of voltage drop).

3.1 General options and information

3.1.1 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 multiplying the value of m the 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:

3.1.2 Technology scaling

Still to be implemented and written.

3.1.3 Model binning

Binning is a kind of range partitioning for geometry dependent models like MOSFET’s. The purpose is to cover larger geometry ranges (Width and Length) with higher accuracy then the model built-in geometry formulas. Each size range described by the additional model parameters LMIN, LMAX, WMIN and WMAX has its own model parameter set. These model cards are defined by a number extension, like “nch.1”. NGSPICE has a algorithm to choose the right model card by the requested W and L.

This is implemented for BSIM3 (11.2.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 MESFET 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 descriptions (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

3.2.1 Resistors

Ngspice has a fairly complex model for resistors. It can simulate both discrete and semiconductor resistors. Semiconductor resistors in ngspice means: resistors described by geometrical parameters. So, do not expect detailed modeling of semiconductor effects.

n+ and n- are the two element nodes, value is the resistance (in ohms) and may be positive or negative¹ but not zero.

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:

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 noise² source you have to add a .model card defining the flicker noise parameters. It is possible to simulate resistors that do not generate any kind of noise using the noisy keyword and assigning zero to it, as in the following example:

Ngspice calculates the nominal resistance as described below:

(3.1)

If you are interested in temperature effects or noise equations, read the next section on semiconductor resistors.

3.2.2 Semiconductor Resistors

This is the more general form of the resistor presented before (3.2.1) and allows the modeling of temperature effects and for the calculation of the actual resistance value from strictly geometric information and the specifications of the process. If value is specified, it overrides the geometric information and defines the resistance. If mname is specified, then the resistance may be calculated from the process information in the model mname and the given length and width. If value is not specified, then mname and length must be specified. If width is not specified, then it is taken from the default width given in the model.

The (optional) temp value is the temperature at which this device is to operate, and overrides the temperature specification on the .option control line and the value specified in dtemp.

3.2.3 Semiconductor Resistor Model (R)

The resistor model consists of process-related device data that allow the resistance to be calculated from geometric information and to be corrected for temperature. The parameters available are:

The sheet resistance is used with the narrowing parameter and l and w from the resistor device to determine the nominal resistance by the formula:

(3.2)

DEFW is used to supply a default value for w if one is not specified for the device. If either rsh or l is not specified, then the standard default resistance value of 1 mOhm is used. TNOM is used to override the circuit-wide value given on the .options control line where the parameters of this model have been measured at a different temperature. After the nominal resistance is calculated, it is adjusted for temperature by the formula:

(3.3)

where R(T NOM) = R_nom|R_acnom. In the above formula, “T ” represents the instance temperature, which can be explicitly set using the temp keyword or calculated using the circuit temperature and dtemp, if present. If both temp and dtemp are specified, the latter is ignored. Ngspice improves spice’s resistors noise model, adding flicker noise (¹∕_f) to it and the noisy keyword to simulate noiseless resistors. The thermal noise in resistors is modeled according to the equation:

(3.4)

where "k" is the Boltzmann’s constant, and "T " the instance temperature.

Flicker noise model is:

(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.

3.2.4 Resistors, dependent on expressions (behavioral resistor)

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.

3.2.5 Capacitors

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:

If you want to simulate temperature dependence of a capacitor, you need to specify its temperature coefficients, using a .model line, like in the example below:

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:

(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

This is the more general form of the Capacitor presented in section (3.2.5), and allows for the calculation of the actual capacitance value from strictly geometric information and the specifications of the process. If value is specified, it defines the capacitance and both process and geometrical information are discarded. If value is not specified, the capacitance is calculated from information contained model mname and the given length and width (l, w keywords, respectively).

It is possible to specify mname only, without geometrical dimensions and set the capacitance in the .model line (3.2.5).

3.2.7 Semiconductor Capacitor Model (C)

The capacitor model contains process information that may be used to compute the capacitance from strictly geometric information.

The capacitor has a capacitance computed as:

If value is specified on the instance line then

(3.7)

If model capacitance is specified then

(3.8)

If neither value nor CAP are specified, then geometrical and physical parameters are take into account:

(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:

(3.10)

If the relative dielectric constant is not specified the one for SiO2 is used. The values of the constants are: ϵ₀ = 8.854214871e-12 and ϵ_SiO2 = 3.4531479969e-11. The nominal capacitance is then computed as:

(3.11)

After the nominal capacitance is calculated, it is adjusted for temperature by the formula:

(3.12)

where C(T NOM) = C_nom.

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)

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.9 Inductors

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:

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:

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:

(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.

The inductor has an inductance computed as:

If value is specified on the instance line then

(3.14)

If model inductance is specified then

(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:

(3.16)

with:μ₀ = 1.25663706143592e-6. After the nominal inductance is calculated, it is adjusted for temperature by the formula:

(3.17)

where L(T NOM) = L_nom. 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

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)

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.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 

* 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 < ∞).

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.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: