Chapter 1

Introduction

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

Some introductory remarks on how to use ngspice may be found in Chapt. 21.

Ngspice is an update of Spice3f5, the last Berkeley’s release of Spice3 simulator family.
Ngspice is being developed to include new features to existing Spice3f5 and to fix its bugs.
Improving a complex software like a circuit simulator is a very hard task and, while some
improvements have been made, most of the work has been done on bug fixing and code
refactoring.

Ngspice has built-in models for the semiconductor devices, and the user need specify only
the pertinent model parameter values.

Ngspice supports mixed-level simulation and provides a direct link between technology pa-
rameters and circuit performance. A mixed-level circuit and device simulator can provide
greater simulation accuracy than a stand-alone circuit or device simulator by numerically
modeling the critical devices in a circuit. Compact models can be used for all other de-
vices. The mixed-level extensions to ngspice is CIDER, a mixed-level circuit and device
simulator integrated into ngspice code.

Ngspice supports mixed-signal simulation through the integration of XSPICE code. XSPICE
software, developed as an extension to Spice3C1 by GeorgiaTech, has been enhanced and
ported to ngspice to provide ‘board’ level and mixed-signal simulation.

The XSPICE extension enables pure digital simulation as well.

New devices can be added to ngspice by several means: behavioral B-, E- or G-sources,
the XSPICE code-model interface for C-like device coding, and the ADMS interface based
on Verilog-A and XML.

Finally, numerous small bugs have been discovered and fixed, and the program has been
ported to a wider variety of computing platforms.

35
36 CHAPTER 1. INTRODUCTION

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 ele-
ments 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 con-
tinuous 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 accu-
rate. 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 Device Models for Analog Simulation

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 model, charge storage effects, ohmic resistances, and a current-dependent output
conductance may be included. The second bipolar model BJT2 adds dc current compu-
tation in the substrate diode. The third model (VBIC) contains further enhancements
for advanced bipolar devices.
1.1. SIMULATION ALGORITHMS 37

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.

1.1.3 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.4 Mixed-Signal Simulation

Modern circuits often contain a mix of analog and digital circuits. To simulate such circuits
efficiently and accurately, a mix of analog and digital simulation techniques is required.
When analog simulation algorithms are combined with digital simulation algorithms, the
result is termed ‘mixed-mode simulation’.
Two basic methods of implementing mixed-mode simulation used in practice are the ‘na-
tive 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 com-
municate 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
38 CHAPTER 1. INTRODUCTION

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.4.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.5 Mixed-Level Simulation (Electronic and TCAD)

Ngspice implements mixed-level simulation through the merging of its code with CIDER
(details see Chapt. 30).
CIDER is a mixed-level circuit and device simulator that provides a direct link between
technology parameters and circuit performance. A mixed-level circuit and device simula-
tor can provide greater simulation accuracy than a stand-alone circuit or device simulator
by numerically modeling the critical devices in a circuit. Compact models can be used
for noncritical devices.
CIDER couples ngspice to a internal C-based device simulator, thus providing circuit
analyses, compact models for semiconductor devices, and an interactive user interface.
CIDER provides accurate, one- and two-dimensional numerical device models based on
the solution of Poisson’s equation, and the electron and hole current-continuity equa-
tions. CIDER incorporates many of the same basic physical models found in the the
Stanford two-dimensional device simulator PISCES [PINT85]. Input to CIDER consists
of a SPICE-like description of the circuit and its compact models, and PISCES-like de-
scriptions of the structures of numerically modeled devices. As a result, CIDER should
seem familiar to designers already accustomed to these two tools.
The CIDER input format has great flexibility and allows increased access to physical
model parameters. New physical models have been added to allow simulation of state-
of-the-art devices. These include transverse field mobility degradation [GATE90] that
is important in scaled-down MOSFETs and a polysilicon model for poly-emitter bipolar
transistors. Temperature dependence has been included for most physical models over
the range from -50°C to 150°C. The numerical models can be used to simulate all the
basic types of semiconductor devices: resistors, MOS capacitors, diodes, BJTs, JFETs
and MOSFETs. BJTs and JFETs can be modeled with or without a substrate contact.
Support has been added for the management of device internal states. Post-processing
of device states can be performed using the control language user interface of ngspice.
1.2. SUPPORTED ANALYSES 39

Previously computed states can be loaded into the program to provide accurate initial
guesses for subsequent analyses.
Details of the basic semiconductor equations and the physical models used by CIDER are
not provided in this manual. Unfortunately, no other single source exists that describes
all of the relevant background material. Comprehensive reviews of device simulation can
be found in [PINT90] and the book [SELB84]. CODECS (predecessor to CIDER) and its
inversion-layer mobility model are described in [MAYA88] and [LGATE90], respectively.
PISCES and its models are described in [PINT85]. Temperature dependencies for the
PISCES models used by CIDER are available in [SOLL90].
For Linux users the cooperation of the TCAD software GSS with ngspice might be of
interest, see https://ngspice.sourceforge.io/gss.html. This project is no longer maintained
however, but has moved into the Genius simulator, still available as open source cogenda
genius.

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, Sensi-
tivity 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 un-
derlying simulation algorithms of ngspice, it is important to understand what is meant
by each analysis type. This is detailed below.

1.2.1 DC Analysis
The DC analysis portion of ngspice determines the dc operating point of the circuit with
inductors shorted and capacitors opened. DC analysis options are specified on the .DC,
.TF, and .OP control lines.
DC analysis does not consider any time dependence on any of the sources within the sys-
tem description. The simulator algorithm subdivides the circuit into those portions that
40 CHAPTER 1. INTRODUCTION

require the analog simulator algorithm and those that require the event-driven algorithm.
Each subsystem block is then iterated to solution, with the interfaces between analog
nodes and event-driven nodes iterated for consistency across the entire system.
Once stable values are obtained for all nodes in the system, the analysis halts and the
results may be displayed or printed out as you request them.
A dc analysis is automatically performed prior to a transient analysis to determine the
transient initial conditions, and prior to an ac small-signal analysis to determine the
linearized, 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. 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
first obtains a DC solution to provide a point of departure for simulating time-varying
behavior. Once the DC solution is obtained, the time-dependent aspects of the system are
reintroduced, and the two simulator algorithms incrementally solve for the time varying
behavior of the entire system. Inconsistencies in node values are resolved by the two
simulation algorithms such that the time-dependent waveforms created by the analysis are
consistent across the entire simulated time interval. Resulting time-varying descriptions
of node behavior for the specified time interval are accessible to you.
All sources that are not time dependent (for example, power supplies) are set to their dc
value. The transient time interval is specified on a .TRAN control line.

1.2.4 Pole-Zero Analysis

Pole-zero analysis in ngspice computes the poles and/or zeros in the small-signal ac trans-
fer function. Ngspice first computes the dc operating point and then determines the lin-
earized, small-signal models for all the nonlinear devices in the circuit. The small-signal
1.2. SUPPORTED ANALYSES 41

circuit model 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 func-
tions 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. Please note, that for some
circuits, the method becomes “lost” and may find an excessive number of poles or zeros.

1.2.5 Small-Signal Distortion Analysis

Distortion analysis in ngspice computes steady-state harmonic and intermodulation prod-
ucts 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 deter-
mined at every point in the circuit. If there are signals of two frequencies input to the
circuit, the analysis finds out the complex values of the circuit variables at the sum and
difference of the input frequencies, and at the difference of the smaller frequency from the
second harmonic of the larger frequency. Distortion analysis is supported for the following
nonlinear devices:

• Diodes (DIO),
• BJT,
• JFET (level 1),
• MOSFETs (levels 1, 2, 3, 9, and BSIM1),
• MESFET (level 1).

All linear devices are automatically supported by distortion analysis. If there are switches
present in the circuit, the analysis continues to be accurate provided the switches do not
change state under the small excitations used for distortion calculations.
If a device model does not support direct small signal distortion analysis, please use the
Fourier of FFT statements and evaluate the output per scripting.

1.2.6 Sensitivity Analysis

Ngspice can calculate either the DC operating-point sensitivity or the AC small-signal
sensitivity of an output variable with respect to all circuit variables, including model
parameters. Ngspice calculates the difference in an output variable (either a node voltage
or a branch current) by perturbing each parameter of each device independently. Since the
method is a numerical approximation, the results may demonstrate second order effects
in highly sensitive parameters, or may fail to show very low but non-zero sensitivity.
Since each variable is perturbed by a small fraction of its value, zero-valued parameters
are not analyzed, reducing what is usually a very large amount of data.
42 CHAPTER 1. INTRODUCTION

1.2.7 Noise Analysis

Noise analysis in ngspice measures the device-generated noise for a given circuit. When
provided with an input source and an output port, the analysis calculates the noise con-
tributions of each device, and each noise generator within each device, as measured as a
voltage at the output port. Noise analysis also calculates the equivalent input noise of
the circuit, based on the output noise. This is done for every frequency point in a spec-
ified range - the calculated value of the noise corresponds to the spectral density of the
circuit variable viewed as a stationary Gaussian stochastic process. After calculating the
spectral densities, noise analysis integrates these values over the specified frequency range
to arrive at the total noise voltage and current over this frequency range. The calculated
values correspond to the variance of the circuit variables viewed as stationary Gaussian
processes.

1.2.8 Periodic Steady State Analysis

Experimental code.
PSS is a radio frequency periodical large-signal dedicated analysis. The implementation
is based on a time domain shooting method that make use of transient analysis. As
it is in early development stage, PSS performs analysis only on autonomous circuits,
meaning that it is able to predict fundamental frequency and (harmonic) amplitude(s)
for oscillators, VCOs, etc.. The algorithm is based on a search of the minimum error
vector defined as the difference of RHS vectors between two occurrences of an estimated
period. Convergence is reached when the mean of this error vector decreases below a given
threshold parameter. Results of PSS are the basis of periodical large-signal analyses like
PAC or PNoise.

1.3 Analysis at Different Temperatures

1.3.1 Introduction

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.12), which has precedence over the .option TEMP line. All analyses
are, thus, performed at circuit temperature, and if you want to simulate circuit behavior
at different temperatures you should prepare a netlist for each temperature.
All input data for ngspice is assumed to have been measured at the circuit nominal
temperature. This value can further be overridden for any device that models temperature
effects by specifying the TNOM parameter on the .model itself. Individual instances may
further override the circuit temperature through the specification of TEMP and DTEMP
parameters on the instance. The two options are not independent even if you can specify
both on the instance line, the TEMP option overrides DTEMP. The algorithm to compute
instance temperature is described below:
1.3. ANALYSIS AT DIFFERENT TEMPERATURES 43

Algorithm 1.1 Instance temperature computation

IF TEMP is specified THEN
instance_temperature = TEMP
ELSE
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 temperature dependency scheme that adjusts all of the model parameters before
input to ngspice.
For details of the BSIM temperature adjustment, see [6] and [7]. Temperature appears
explicitly in the exponential terms of the BJT and diode model equations. In addition,
saturation currents have a built-in temperature dependence. The temperature dependence
of the saturation current in the BJT models is determined by:

 XT I  
T1 Eg q (T1 − T0 )
IS (T1 ) = IS (T0 ) exp (1.1)
T0 k (T1 T0 )

where k is Boltzmann’s constant, q is the electronic charge, Eg is the energy gap model
parameter, and XT I is the saturation current temperature exponent (also a model pa-
rameter, and usually equal to 3).
The temperature dependence of forward and reverse beta is according to the formula:

 XT B
T1
B (T1 ) = B (T0 ) (1.2)
T0

where T0 and T1 are in degrees Kelvin, and XT B is a user-supplied model parameter.

Temperature effects on beta are carried out by appropriate adjustment to the values of
BF , ISE , BR , and ISC (SPICE model parameters BF, ISE, BR, and ISC, respectively).
Temperature dependence of the saturation current in the junction diode model is deter-
mined by:

  XT I  
T1 N Eg q (T1 − T0 )
IS (T1 ) = IS (T0 ) exp (1.3)
T0 N k (T1 T0 )

where N is the emission coefficient model parameter, and the other symbols have the
same meaning as above. Note that for Schottky barrier diodes, the value of the saturation
current temperature exponent, XT I, is usually 2. Temperature appears explicitly in the
value of junction potential, U (in Ngspice PHI), for all the device models.
The temperature dependence is determined by:
 
kT Na Nd
U (T ) = ln (1.4)
q Ni (T )2
44 CHAPTER 1. INTRODUCTION

where k is Boltzmann’s constant, q is the electronic charge, Na is the acceptor impurity

density, Nd is the donor impurity density, Ni is the intrinsic carrier concentration, and Eg
is the energy gap. Temperature appears explicitly in the value of surface mobility, M0 (or
U0 ), for the MOSFET model.
The temperature dependence is determined by:

M0 (T0 )
M0 (T ) =  1.5 (1.5)
T
T0

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

 
R (T ) = R (T0 ) 1 + T C1 (T − T0 ) + T C2 (T − T0 )2 (1.6)

where T is the circuit temperature, T0 is the nominal temperature, and T C1 and T C2 are
the first and second order temperature coefficients.

1.3.2 Controlling the temperature

The default temperature is set to 27 °C.

.temp 40

will set the overall temperature to 40 °C (2.12). The command

.options temp=60

will set the overall temperature to 60 °C (15.1.1). Both commands are equivalent, however
.temp will override .options temp.
The temperature of an individual device may be determined by the instance parameters
temp or dtemp.

M1 d g s b MOSN temp=35

will set the temperature of the specific MOS device to 35 °C.

M2 d g s b MOSN dtemp=20

will set the temperature of device M2 at a delta of 20° above the overall temperature.
The temperatures thus set are static throughout the simulation. It is possible, however,
to sweep the temperature by a command like

.dc temp 25 49 2
1.4. CONVERGENCE 45

starting at 25 °C, stopping at 49 °C with a step of 2° (see 15.3.2).

The current overall temperature may be assessed by the variable TEMPER, which can be
used as part of an equation in B sources (5.1.2) or behavioral E, G, R, L, C sources (e.g.
5.2). A typical example may look like

Bt1 1 2 V=’5 + TEMPER*TEMPER’

The nominal temperature, a reference temperature where device model parameters have
been measured, is called tnom.

.options tnom=25

will set the nominal temperature for all devices to 25 °C (15.1.1). Tnom sometimes may
be set as a model parameter in a .model line (3.2.2), depending on the specific class of
devices and its model parameter set.

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 when the difference between the last iteration k
and the current one (k + 1)

vn(k+1) − vn(k) ≤ RELTOL vnmax + VNTOL, (1.7)

where

vnmax = max vn(k+1) , vn(k) . (1.8)

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

1.4.2 Current convergence criterion

Ngspice checks the convergence on the non-linear functions that describe the non-linear
branches in circuit elements. In semiconductor devices the functions defines currents
through the device and thus the name of the criterion.
Ngspice computes the difference between the value of the nonlinear function computed
for the last voltage and the linear approximation of the same current computed with the
actual voltage

\(k+1) (k)
ibranch − ibranch ≤ RELTOL ibrmax + ABSTOL, (1.9)

where
 
\
(k+1) (k)
ibrmax = max ibranch , ibranch . (1.10)

In the two expressions above, the i\

branch 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, plus a newline delimiter.

The order of the remaining lines is alomost arbitrary (except, of course, that continuation
lines must immediately follow the line being continued, .subckt ... .ends, .if ... .endif,
or .control ... .endc have to enclose their specific lines). Leading white spaces in a
line are ignored, as well as empty lines.
The lines described in sections 2.1 to 2.12 are typically used in the core of the input file,
outside of a .control section (see 16.4.3). An exception is the .include includefile
line (2.7) that may be placed anywhere in the input file. The contents of includefile
will be inserted exactly in place of the .include line.

2.1.2 Syntax check

A very preliminary syntax check has been added to the input parser.

2.1.2.1 Valid utf-8 characters

The input file will be scanned for valid utf-8 characters. If non-valid characters are found,
reading the input is stopped.

47
48 CHAPTER 2. CIRCUIT DESCRIPTION

2.1.2.2 Special characters leading a line

If the first character in a netlist or .control line is one of =[]?()&%$§\"!:, then ngspice
replaces it by ’*’ and issues a warning. Command set strict_errorhandling will force
ngspice to exit.

2.1.2.3 Dot command couple completion

Check for .control ... .endc, .subckt ... .ends, .if ... .endif.

2.1.3 Circuit elements (device instances)

Each element in the circuit is a device instance specified by an instance line that con-
tains:

• 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 available in ngspice, sorted by their first letter.
2.1. GENERAL STRUCTURE AND CONVENTIONS 49

First letter Element description Comments, links

12
analog (12.2)
A XSPICE code model
digital (12.4)
mixed signal (12.3)
B Behavioral (arbitrary) source 5.1
C Capacitor 3.3.6
D Diode 7
linear (4.2.2),
E Voltage-controlled voltage source (VCVS)
non-linear (5.2)
F Current-controlled current source (CCCs) linear (4.2.3)
linear (4.2.1),
G Voltage-controlled current source (VCCS)
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.3.12
L Inductor 3.3.10
11
M Metal oxide field effect transistor (MOSFET) BSIM3 (11.2.10)
BSIM4 (11.2.11)
N Numerical device for GSS 14
O Lossy transmission line 6.2
P Coupled multiconductor line (CPL) 6.4.2
Q Bipolar junction transistor (BJT) 8
R Resistor 3.3.1
S Switch (voltage-controlled) 3.3.15
T Lossless transmission line 6.1
U Uniformly distributed RC line 6.3*
U Basic digital building blocks using XSPICE 14*
V Voltage source 4.1
W Switch (current-controlled) 3.3.15
X Subcircuit 2.5.3
Y Single lossy transmission line (TXL) 6.4.1
Z Metal semiconductor field effect transistor (MESFET) 10

Table 2.1: ngspice element types

*) For a disambiguation see chapter 14.1.3.

2.1.4 Some naming conventions

2.1.4.1 Lines

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
50 CHAPTER 2. CIRCUIT DESCRIPTION

column 2. Lines may also be continued in Unix shell style, when the final two characters
are backslashes. A device name field must begin with a letter (A through Z) and cannot
contain any delimiters.

2.1.4.2 Numbers

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 × 10−6
m milli 10−3
u micro 10−6
n nano 10−9
p pico 10−12
f femto 10−15
a atto 10−18

Table 2.2: Ngspice scale factors

2.1.4.3 Letters following a number

Letters immediately following a number that are not scale factors are ignored, and letters
immediately following a scale factor are ignored. Hence, 10, 10V, 10Volts, and 10Hz all
represent the same number, and M, MA, MSec, and MMhos all represent the same scale
factor. Note that 1000, 1000.0, 1000Hz, 1e3, 1.0e3, 1kHz, and 1k all represent the same
number. Note that ‘M’ or ‘m’ denote ‘milli’, i.e. 10−3 . Suffix meg has to be used for
106 . If compatibility mode LT (16.14.6) is set, ngspice will accept the RKM notation for
entering resistance or capacitance values, e.g. 2K7 or 100R.

2.1.4.4 Node names

Node names may be arbitrary character strings (exceptions see below) and are case in-
sensitive, 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 following characters = % ( ) , [ ] < > ~ are not allowed
in a node name, especially when XSPICE code models are used (they have their special
meanings then and act as string delimiters).

2.1.4.5 Ground node

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’. If
2.2. DOT COMMANDS 51

this is not feasible, you may switch the conversion off by setting set no_auto_gnd in one
of the configuration files spinit or .spiceinit. 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.

2.1.5 Topological constraints

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 Dot commands

This section summarizes all dot commands available in ngspice, with links to their detailed
presentation, in alphabetical order. Control section (or interactive) commands are listed
and explained in chapter 17.5.

.AC start an ac simulation (15.3.1).

.CONTROL start a .control section (16.4.3).

.CSPARAM define parameter(s) made available in a control section (2.11).

.DC start a dc simulation (15.3.2).

.DISTO start a distortion analysis simulation (15.3.3).

.ELSE conditional branching in the netlist (2.13).

.ELSEIF conditional branching in the netlist (2.13).

.END end of the netlist (2.3.2).

.ENDC end of the .control section (16.4.3).

.ENDIF conditional branching in the netlist (2.13).

.ENDS end of subcircuit definition (2.5.2).

.FOUR Fourier analysis of transient simulation output (15.6.4).

.FUNC define a function (2.10).

52 CHAPTER 2. CIRCUIT DESCRIPTION

.GLOBAL define global nodes (2.6).

.IC set initial conditions (15.2.2).

.IF conditional branching in the netlist (2.13).

.INCLUDE include part of the netlist (2.7).

.LIB include a library (2.8).

.MEAS measurements during the simulation (15.4).

.MODEL list of device model parameters (2.4).

.NODESET set initial conditions (15.2.1).

.NOISE start a noise simulation (15.3.4).

.OP start an operating point simulation (15.3.5).

.OPTIONS set simulator options (15.1).

.PARAM define parameter(s) (2.9).

.PLOT printer plot during batch simulation (15.6.3).

.PRINT tabular listing during batch simulation (15.6.2).

.PROBE save device currents, voltages and differential voltages (15.6.5).

.PSS start a periodic steady state analysis (15.3.12).

.PZ start a pole-zero analysis simulation (15.3.6).

.SAVE name simulation result vectors to be saved (15.6.1).

.SENS start a sensitivity analysis (15.3.7).

.SP S parameter analysis (15.3.8).

.SUBCKT start of subcircuit definitions (2.5).

.TEMP set the ciruit temperature (2.12).

.TF start a transfer function analysis (15.3.9).

.TITLE title of the netlist (2.3.1).

.TRAN start a transient simulation (15.3.10).

.WIDTH width of printer plot (15.6.7).

2.3. BASIC LINES 53

2.3 Basic lines

2.3.1 .TITLE line

Examples:

POWER AMPLIFIER CIRCUIT

* additional lines following
*...

Test of CAM cell

* additional lines following
*...

The title line must be the first in the input file. Its contents are printed verbatim as the
heading for each section of output.
As an alternative, you may place a .TITLE <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:

** ** ****************** ** ******
* additional lines following
*...
. TITLE Test of CAM cell
* additional lines following
*...

will internally be replaced by

Internal input deck:

Test of CAM cell

* additional lines following
*...
* TITLE Test of CAM cell
* additional lines following
*...

2.3.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.
54 CHAPTER 2. CIRCUIT DESCRIPTION

2.3.3 Comments
General Form:

* < any comment >

Examples:

* RF =1 K Gain should be 100

* Check open - loop gain and phase margin

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

2.3.4 End-of-line comments

General Form:

< any command > $ < any comment >

< any command > ; < any comment >

Examples:

RF2 =1 K $ Gain should be 100

C1 =10 p ; Check open - loop gain and phase margin
. param n1 =1 // new value

ngspice supports comments that begin with double characters ‘$ ’ (dollar plus space) or
‘//’. For readability you should precede each comment character with a space. ngspice
will accept the single character ‘$’.
Please note that the ‘$’ character is not a valid end-of-line comment delimiter, if the
PSPICE compatibility mode (16.14.5) has been chosen. Then ’$’ becomes an ordinary
character.

2.3.5 Continuation lines

General Form:

< any command >

+ < continuation of any command > ; some comment
+ < further continuation of any command >
2.4. .MODEL DEVICE MODELS 55

If input lines get overly long, they may be split into two or more lines (e.g. for better
readability). Internally they will be merged into a single line. Each follow-up line starts
with character ’+’ plus additional space. Follow-up lines have to follow immediately after
each other. End-of-line comments will be ignored. Lines may also be continued by ending
the line with two backslashes, as used in Unix shells. The following lines do not allow
using continuation lines: .title, .lib, and .include.

2.4 .MODEL Device Models

General form:

. model mname type ( pname1 = pval1 pname2 = pval2 ... )

Examples:

. model MOD1 npn ( bf =50 is =1 e -13 vbf =50)

Most simple circuit elements typically require only a few parameter values. However,
some devices (semiconductor devices in particular) that are included in ngspice require
many parameter values. Often, many devices in a circuit are defined by the same set of
device model parameters. For these reasons, a set of device model parameters is defined
on a separate .model line and assigned a unique model name. The device element lines
in ngspice then refer to the model name.
For these more complex device types, each device element line contains the device name,
the nodes the device is connected to, and the device model name. In addition, other
optional parameters may be specified for some devices: geometric factors and an initial
condition (see the following section on Transistors (8 to 11) and Diodes (7) for more
details). mname in the above is the model name, and type is one of the following fifteen
types:
Parameter values are defined by appending the parameter name followed by an equal sign
and the parameter value. Model parameters that are not given a value are assigned the
default values given below for each model type. Models are listed in the section on each
device along with the description of device element lines. Model parameters and their
default values are given in Chapt. 31.

2.5 .SUBCKT Subcircuits

Subcircuits consisting of ngspice elements can be defined and used similarly to device
models. Subcircuits are the way ngspice implements hierarchical modeling and make
circuits with repeated sections easier to represent. During parsing of a SPICE deck, each
subcircuit instance is replaced by its definition using text expansion and the hierarchy is
not present after input processing.
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
56 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
VDMOS Power MOS model

Table 2.3: Ngspice model types

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 that begins with the letter ‘X’. A complete
example of all three of these cards follows:
Example:

* The following is the instance card :

*
xdiv1 10 7 0 vdivide

* The following are the subcircuit definition cards :

*
. subckt vdivide 1 2 3
r1 1 2 10 K
r2 2 3 5 K
. 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’.
2.5. .SUBCKT SUBCIRCUITS 57

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

2.5.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
that immediately follow the .SUBCKT line define the subcircuit. The last line in a sub-
circuit 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 defi-
nition). Also, any element nodes not included on the .SUBCKT line are strictly local, with
the exception of 0 (ground) that is always global. If you use parameters, the .SUBCKT line
will be extended (see 2.9.3).

2.5.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 sub-
circuits being defined are terminated. The name is needed only when nested subcircuit
definitions are being made.
58 CHAPTER 2. CIRCUIT DESCRIPTION

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

2.6 .GLOBAL
General form:

. GLOBAL nodename1 [ nodename2 ... ]

Examples:

. GLOBAL gnd vcc

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 ac-
cessible from top level.

2.7 .INCLUDE
General form:

. INCLUDE filename

Examples:

. INCLUDE / users / spice / common / bsim3 - param . mod

Frequently, portions of circuit descriptions will be reused in several input files, particularly
with common models and subcircuits. In any ngspice input file, the .INCLUDE line may
be used to copy some other file as if that second file appeared in place of the .INCLUDE
line in the original file.
There is no restriction on the file name imposed by ngspice beyond those imposed by the
local operating system.
2.8. .LIB 59

2.8 .LIB
General form:

. LIB filename libname

Examples:

. LIB / users / spice / common / mosfets . lib mos1

The .LIB statement allows including 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.14) 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.7.

2.9 .PARAM Parametric netlists

Ngspice allows for the definition of parametric attributes in the netlists. This is an
enhancement of the ngspice front-end that adds arithmetic functionality to the circuit
description language.

2.9.1 .param line

General form:

. param < ident > = < expr > < ident > = < expr > ...

Examples:

. param pippo =5
. param po =6 pp =7.8 pap ={ AGAUSS ( pippo , 1 , 1.67)}
. param pippp ={ pippo + pp }
. param p ={ pp }
. param pop = ’ pp +p ’

This line assigns numerical values to identifiers. More than one assignment per line
is possible using a separating space. Parameter identifier names must begin with an
alphabetic character. The other characters must be either alphabetic, a number, or ! #
$ % [ ] _ as special characters. The variables time, temper, and hertz (see 5.1.1) are
not valid identifier names. Other restrictions on naming conventions apply as well, see
2.9.6.
60 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. Expressions defining a parameter should be put
within braces {p+p2}, or alternatively within single quotes ’AGAUSS(pippo, 1, 1.67)’.
An assignment cannot be self-referential, something like .param pip = ’pip+3’ will not
work.

The current ngspice version does not always need quotes or braces in expressions, es-
pecially when spaces are used sparingly. However, it is recommended to do so, as the
following examples demonstrate.

. param a = 123 * 3 b = sqrt (9) $ doesn ’ t work , a <= 123

. param a = ’123 * 3 ’ b = sqrt (9) $ ok .
. param c = a + 123 $ won ’ t work
. param c = ’a + 123 ’ $ ok .
. param c = a +123 $ ok .

Parameters may also have string values, but support is limited. String-valued parameters
can be defined by .param and used in the same ways as numeric parameters. The only
operation on string values is concatenation and that is possible only in top-level .param
assignments.

. param str1 =" first " str2 =" second "

. param both ={ str1 }" and " str2

2.9.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.9.5). Brace expressions ({..}) cannot be used to parameterize 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.9. .PARAM PARAMETRIC NETLISTS 61

2.9.3 Subcircuit parameters

General form:

. subckt < identn > node node ... < ident >= < value > < ident >= < value > ...

Examples:

. subckt myfilter in out rval =100 k cval =100 nF

<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 default values of the parameters.
The syntax of a subcircuit call (invocation) is:
General form:

X < name > node node ... < identn > < ident >= < value > < ident >= < value > ...

Examples:

X1 input output myfilter rval =1 k

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> } .
Subcircuit example with parameters:

* Param - example
. param amplitude = 1 V
*
. subckt myfilter in out rval =100 k cval =100 nF
Ra in p1 {2* rval }
Rb p1 out {2* rval }
C1 p1 0 {2* cval }
Ca in p2 { cval }
Cb p2 out { cval }
R1 p2 0 { rval }
. ends myfilter
*
X1 input output myfilter rval =1 k cval =1 n
V1 input 0 AC { amplitude }
. end
62 CHAPTER 2. CIRCUIT DESCRIPTION

2.9.4 Symbol scope

All subcircuit and model names are considered global and must be unique. The .param
symbols that are defined outside of any .subckt ... .ends section are global. Inside such
a section, the pertaining params: symbols and any .param assignments are considered
local: they mask any global identical names, until the .ends line is encountered. You
cannot reassign to a global number inside a .subckt, a local copy is created instead.
Scope nesting works up to a level of 10. For example, if the main circuit calls A that has
a formal parameter xx, A calls B that has a param. xx, and B calls C that also has a
formal param. xx, there will be three versions of ‘xx’ in the symbol table but only the
most local one - belonging to C - is visible.

2.9.5 Syntax of expressions

<expr> ( optional parts within [...] )

An expression may be one of:

< atom > where < atom > is either a spice number or an identifier
< unary - operator > < atom >
< function - name > ( < expr > [ , < expr > ...] )
< atom > < binary - operator > < expr >
( < expr > )

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!
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
2.9. .PARAM PARAMETRIC NETLISTS 63

The evaluation of the power functions ** or ^ depends on the compatibility mode (16.14.1)
chosen.

Power function source code implementation:

compatmode hs : x >0 pow (x , y ); x <0 pow (x , round ( y )); X =0 0

compatmode lt : x >0 pow (x , y ); x <0 pow (x , y ) if y is close to intege

The number zero is used to represent boolean False. Any other number represents boolean
True. The result of logical operators is 1 or 0. An example input file is shown below:

Example input file with logical operators:

* Logical operators

v1or 1 0 {1 || 0}
v1and 2 0 {1 && 0}
v1not 3 0 {! 1}
v1mod 4 0 {5 % 3}
v1div 5 0 {5 \ 3}
v0not 6 0 {! 0}

. control
op
print allv
. endc

. end
64 CHAPTER 2. CIRCUIT DESCRIPTION

Built-in function Notes

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.
2.10. .FUNC 65

2.9.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: or, defined,
sqr, sqrt, sin, cos, exp, ln, log, log10, arctan, abs, pwr, time, temper, hertz.

2.9.7 A word of caution on the three ngspice expression parsers

The historical parameter notation using & as the first character of a line as equivalence
to .param. is deprecated and will be removed in a coming release.
Confusion may arise in ngspice because of its multiple numerical expression features. The
.param lines and the brace expressions (see Chapt. 2.10) are evaluated in the front-
end, that is, just after the subcircuit expansion. (Technically, the X lines are kept as
comments in the expanded circuit so that the actual parameters can be correctly sub-
stituted). Therefore, after the netlist expansion and before the internal data setup, all
number attributes in the circuit are known constants. However, there are circuit elements
in Spice that accept arithmetic expressions not evaluated at this point, but only later
during circuit analysis. These are the arbitrary current and voltage sources (B-sources,
5), as well as E- and G-sources and R-, L-, or C-devices. The syntactic difference is that
‘compile-time’ expressions are within braces, but ‘run-time’ expressions have no braces.
To make things more complicated, the back-end ngspice scripting language accepts arith-
metic/logic expressions that operate only on its own scalar or vector data sets (17.2).
Please see Chapt. 2.14.
It would be desirable to have the same expression syntax, operator and function set,
and precedence rules, for the three contexts mentioned above. In the current Numparam
implementation, that goal is not achieved.

2.10 .FUNC
This keyword defines a function. The syntax of the expression is the same as for a .param
(2.9.5).
General form:

. func < ident > { < expr > }

. func < ident > = { < expr > }

Examples:

. func icos ( x ) { cos ( x ) - 1}

. func f (x , y ) { x * y }
. func foo (a , b ) = { a + b }

.func will initiate a replacement operation. After reading the input files, and before
parameters are evaluated, all occurrences of the icos(x) function will be replaced by
66 CHAPTER 2. CIRCUIT DESCRIPTION

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.11 .CSPARAM
Create a constant vector (see 17.8.2) from a parameter in plot (17.3) const.
General form:

. csparam < ident > = < expr >

Examples:

. param pippo =5
. param pp =6
. csparam pippp ={ pippo + pp }
. param p ={ pp }
. csparam pap = ’ pp +p ’
In the example shown, vectors pippp, and pap are added to the constants that already
reside in plot const, having length one and real values. These vectors are generated dur-
ing 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.12 .TEMP
Sets the circuit temperature in degrees Celsius.
General form:

. temp value

Examples:

. temp 27
2.13. .IF CONDITION-CONTROLLED NETLIST 67

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

2.13 .IF Condition-Controlled Netlist

A simple .IF-.ELSE(IF) block allows condition-controlling of the netlist. boolean expression

is any expression according to Chapt. 2.9.5 that evaluates parameters and returns a
boolean 1 or 0. The netlist block in between the .if ... .endif statements may contain
device instances or .model cards that are selected according to the logic condition.
68 CHAPTER 2. CIRCUIT DESCRIPTION

General form:

. if ( boolean expression )
...
. elseif ( boolean expression )
...
. else
...
. endif

Example 1:

* device instance in IF - ELSE block

. param ok =0 ok2 =1

v1 1 0 1
R1 1 0 2

. if ( ok && ok2 )
R11 1 0 2
. else
R11 1 0 0.5 $ <-- selected
. endif

Example 2:

* . model in IF - ELSE block

. param m0 =0 m1 =1

M1 1 2 3 4 N1 W =1 L =0.5

. if ( m0 ==1)
. model N1 NMOS level =49 Version =3.1
. elseif ( m1 ==1)
. model N1 NMOS level =49 Version =3.2.4 $ <-- selected
. else
. model N1 NMOS level =49 Version =3.3.0
. endif

Nesting of .IF-.ELSE(IF)-.ENDIF blocks is possible. Several .elseif (but of course

only one .else)are allowed per block (please see example ngspice/tests/regression/misc/if-
elseif.cir). However some restrictions apply, as the following netlist components are not
supported within the .IF-.ENDIF block: .SUBCKT, .INC, .LIB, and .PARAM.
2.14. PARAMETERS, FUNCTIONS, EXPRESSIONS, AND COMMAND SCRIPTS69

2.14 Parameters, functions, expressions, and com-

mand 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.14.1 Parameters
Parameters (Chapt. 2.9.1) and functions, either defined within the .param statement or
with the .func statement (Chapt. 2.10) 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.9.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.14.2 Nonlinear sources

During the simulation, the B source (Chapt. 5) and their associated E and G sources, as
well as some devices (R, C, L) may contain expressions. These expressions may contain
parameters from above (evaluated immediately upon ngspice start up), numerical data,
predefined functions, but also node voltages and branch currents resulting from the sim-
ulation. 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 cre-
ate 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.9.1.

2.14.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.9.1 defined by
the .param statement are not allowed in these expressions. However you may define such
parameters with .csparam (2.11). Again the expression syntax (see Chapt. 17.2) will
deviate from the one for parameters or B sources listed in 2.9.1 and 5.1.
If you want to use parameters from 2.9.1 inside your control script, you may use .csparam
(2.11) 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.14.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
70 CHAPTER 2. CIRCUIT DESCRIPTION

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 About netlists, device instances, models and model

parameters

The input to ngspice is a netlist, which lists all circuit elements, their interconnects and
model parameters.

71
72 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS

Netlist example of a simple bipolar amplifier:

bipolar amplifier

R3 vcc intc 10 k
R1 vcc intb 68 k
R2 intb 0 10 k
Cout out intc 10 u
Cin intb in 10 u
RLoad out 0 100 k
Q1 intc intb 0 BC546B

VCC vcc 0 5
Vin in 0 dc 0 ac 1 sin (0 1 m 500)

. model BC546B npn ( IS =7.59 E -15 VAF =73.4 BF =480 IKF =0.0962
+ NE =1.2665 ISE =3.278 E -15 IKR =0.03 ISC =2.00 E -13 NC =1.2 NR =1
+ BR =5 RC =0.25 CJC =6.33 E -12 FC =0.5 MJC =0.33 VJC =0.65
+ CJE =1.25 E -11 MJE =0.55 VJE =0.65 TF =4.26 E -10 ITF =0.6 VTF =3
+ XTF =20 RB =100 IRB =0.0001 RBM =10 RE =0.5 TR =1.50 E -07)
. end

After the first line, which is always a title line only, the netlist starts. Each line here is a
device instance (except for lines starting with a dot ’.’). We have simple circuit elements
that consist of a single line only, e.g. resistors like R3. In its simplest implementation,
the resistor model does not need any model parameters except for the resistance value
(same for capacitors like Cout). Netlist lines like R3 vcc intc 10k are called instance lines,
as each line is the representation of an instance of a generic model hard-coded into the
ngspice simulator (here: resistor). R3 denotes the device name. Its first character R
denotes a resistor. The next two tokens vcc intc are the two nodes of the resistor, 10k is
the resistance value. Equal node names on different devices denote a connection between
these nodes.

A more complex device is described by the instance line Q1 intc intb 0 BC546B. Q denotes
a bipolar transistor, intc intb 0 are the three nodes collector, base, and emitter. BC546B is
the name of a model parameter set, named after a real transistor and describing (together
with the implemented bipolar transistor model) its electrical behavior. The associated
model parameters are given in the line .model BC546B npn (IS=7.59E-15 ...). This is not an
instance line, because starting with a dot. It contains the model parameters as supplied by
the device manufacturer or by people having them extracted from the electrical behavior
and data sheet (to be found e.g. on his or her web pages). BC546B is the name of the
model parameter set and relates it to the device instance. npn is the type of the device.
The parameters (name=value) are given in brackets.

The instance Q1... requires model parameters. For a quick test one may do without
device maker’s model parameters.
3.2. GENERAL OPTIONS 73

Simplified bipolar transistor instance and model parameter set:

Q1 intc intb 0 defaultmod

. model defaultmod npn

If you enter the bipolar transistor instance as shown above, you make use of a default
model parameter set supplied by ngspice. defaultmod is an arbitrary name. This procedure
models a generic bipolar transistor, not resembling any commercial device. The default
parameter values may be assessed by the command showmod Q1.

You will get more information on devices, instances and models in the following chapters
3.3 to 12.

3.2 General options

3.2.1 Paralleling devices with multiplier m

When it is needed to simulate several devices of the same kind in parallel, use the ‘m’
(parallel multiplier) instance parameter available for the devices listed in Table 3.1. This
multiplies the value of the element’s matrix stamp with m’s value. The netlist below shows
how to correctly use the parallel multiplier:

Multiple device example:

d1 2 0 mydiode m =10
d01 1 0 mydiode
d02 1 0 mydiode
d03 1 0 mydiode
d04 1 0 mydiode
d05 1 0 mydiode
d06 1 0 mydiode
d07 1 0 mydiode
d08 1 0 mydiode
d09 1 0 mydiode
d10 1 0 mydiode
...

The d1 instance connected between nodes 2 and 0 is equivalent to the 10 parallel devices
d01-d10 connected between nodes 1 and 0.

The following devices support the multiplier m:

74 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS

First letter Element description

C Capacitor
D Diode
F Current-controlled current source (CCCs)
G Voltage-controlled current source (VCCS)
I Current source
J Junction field effect transistor (JFET)
L Inductor
M Metal oxide field effect transistor (MOSFET)
Q Bipolar junction transistor (BJT)
R Resistor
X Subcircuit (for details see below)
Z Metal semiconductor field effect transistor (MESFET)

Table 3.1: ngspice elements supporting multiplier ’m’

When the X line (e.g. x1 a b sub1 m=5) contains the token m=value (as shown) or
m=expression, subcircuit invocation is done in a special way. If an instance line of the
subcircuit sub1 contains any of the elements shown in table 3.1, then these elements are
instantiated with the additional parameter m (in this example having the value 5). If such
an element already has an m multiplier parameter, the element m is multiplied with the
m derived from the X line. This works recursively, meaning that if a subcircuit contains
another subcircuit (a nested X line), then the latter m parameter will be multiplied by the
former one, and so on.
Example 1:

. param madd = 6
X1 a b sub1 m =5
. subckt sub1 a1 b1
Cs1 a1 b1 C =5 p m = ’ madd -2 ’
. ends

In example 1, the capacitance between nodes a and b will be C = 5pF*(madd-2)*5 =

100pF.
Example 2:

. param madd = 4
X1 a b sub1 m =3
. subckt sub1 a1 b1
X2 a1 b1 sub2 m = ’ madd -2 ’
. ends
. subckt sub2 a2 b2
Cs2 a2 b2 3 p m =2
. ends

In example 2, the capacitance between nodes a and b is C = 3pF*2*(madd-2)*3 = 36pF.

3.2. GENERAL OPTIONS 75

Using m may fail to correctly describe geometrical properties for real devices like MOS
transistors.
M1 d g s nmos W=0.3u L=0.18u m=20
is probably not be the same as
M1 d g s nmos W=6u L=0.18u
because the former may suffer from small width (or edge) effects, whereas the latter is
simply a wide transistor.

3.2.2 Instance and model parameters

The simple device example below consists of two lines: The device is defined on the
instance line, starting with Lload ...: The first letter determines the device type (an
inductor in this example). Following the device name are two nodes 1 and 2, then the
inductance value 1u is set. The model name ind1 is a connection to the respective model
line. Finally we have a parameter on the instance line, together with its value dtemp=5.
Parameters on an instance line are called instance parameters.
The model line starts with the token .model, followed by the model name, the model type
and at least one model parameter, here tc1=0.001. There are complex models with more
than 100 model parameters.

Lload 1 2 1 u ind1 dtemp =5

. MODEL ind1 L tc1 =0.001

Instance parameters are listed in each of the following device descriptions. Model pa-
rameters sometimes are given below as well, for complex models like the BSIM transistor
models, they are available in the model makers documentation. Instance parameters may
also be placed in the .model line. Thus they are recognized by each device instance refer-
ring to that model. Their values may be overridden for a specific instance of a device by
placing them additionally onto its instance line.

3.2.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
than 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 an algo-
rithm to choose the right model card by the requested W and L.
This is implemented for BSIM3 (11.2.10) and BSIM4 (11.2.11) models.

3.2.4 Initial conditions

Two different forms of initial conditions may be specified for some devices. The first form
is included to improve the dc convergence for circuits that contain more than one stable
76 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS

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.10) for a
detailed explanation of initial conditions.

3.3 Elementary Devices

3.3.1 Resistors
General form:

RXXXXXXX n + n - < resistance | r = > value < ac = val > <m = val >
+ < scale = val > < temp = val > < dtemp = val > < tc1 = val > < tc2 = val >
+ < noisy =0|1 >

Examples:

R1 1 2 100
RC1 12 17 1 K
R2 5 7 1 K ac =2 K
RL 1 4 2 K m =2

Ngspice has a fairly complex model for resistors. It can simulate both discrete and semi-
conductor resistors. Semiconductor resistors in ngspice means: resistors described by
geometrical parameters. So, do not expect detailed modeling of semiconductor effects.
n+ and n- are the two element nodes, value is the resistance (in ohms) and may be
positive or negative1 but not zero.
Simulating small valued resistors: If you need to simulate very small
resistors (0.001 Ohm or less), you should use CCVS (transresistance).
It is less efficient but improves overall numerical accuracy. Consider a
small resistance as 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
1
A negative resistor modeling an active element can cause convergence problems, please avoid it.
3.3. ELEMENTARY DEVICES 77

in AC analysis only (neither Pole-Zero nor Noise). If you do not specify the ac parameter,
it is defaulted to value.
Ngspice calculates the nominal resistance as

VALUE scale
Rnom = m
(3.1)
ac scale
Racnom = m
.

If you want to simulate temperature dependence of a resistor, you need to specify its tem-
perature coefficients, using a .model line or as instance parameters, like in the examples
below:
Examples:

RE1 1 2 800 newres dtemp =5

. MODEL newres R tc1 =0.001

RE2 a b 1.4 k tc1 =2 m tc2 =1.4 u

RE3 n1 n2 1 Meg tce =700 m

The temperature coefficients tc1 and tc2 describe a quadratic temperature dependence
(see equation 1.6) of the resistance. If given in the instance line (the R... line) their
values will override the tc1 and tc2 of the .model line (3.3.3). Ngspice has an additional
temperature model equation 3.2 parameterized by tce given in model or instance line. If
all parameters are given (quadratic and exponential) the exponential temperature model
is chosen.

 
R (T ) = R (T0 ) 1.01T CE·(T −T0 ) (3.2)

where T is the circuit temperature, T0 is the nominal temperature, and T CE is the

exponential temperature coefficients.
Instance temperature is useful even if resistance does not vary with it, since the thermal
noise generated by a resistor depends on its absolute temperature. Resistors in ngspice
generates two different noises: thermal and flicker. While thermal noise is always gener-
ated in the resistor, to add a flicker noise2 source you have to add a .model card defining
the flicker noise parameters. It is possible to simulate resistors that do not generate any
kind of noise using the noisy (or noise) keyword and assigning zero to it, as in the
following example:
Example:

Rmd 134 57 1.5 k noisy =0

If you are interested in temperature effects or noise equations, read the next section on
semiconductor resistors.
2
Flicker noise can be used to model carbon resistors.
78 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS

3.3.2 Semiconductor Resistors

General form:

RXXXXXXX n + n - < value > < mname > <l = length > <w = width >
+ < temp = val > < dtemp = val > <m = val > < ac = val > < scale = val >
+ < noisy = 0|1 >

Examples:

RLOAD 2 10 10 K
RMOD 3 7 RMODEL L =10 u W =1 u

This is the more general form of the resistor presented before (3.3.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.3.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 as follows:
Name Parameter Units Default Example
TC1 first order temperature coeff. Ω/◦ C 0.0 -
TC2 second order temperature coeff. Ω/◦ C 2 0.0 -
RSH sheet resistance Ω/ - 50
DEFW default width m 1e-6 2e-6
NARROW narrowing due to side etching m 0.0 1e-7
SHORT shortening due to side etching m 0.0 1e-7
◦
TNOM parameter measurement temperature C 27 50
KF flicker noise coefficient 0.0 1e-25
AF flicker noise exponent 0.0 1.0
WF flicker noise width exponent 1.0
LF flicker noise length exponent 1.0
EF flicker noise frequency exponent 1.0
R (RES) default value if element value not given Ω - 1000
The sheet resistance is used with the narrowing parameter and l and w from the resistor
device to determine the nominal resistance by the formula:
3.3. ELEMENTARY DEVICES 79

l − SHORT
Rnom = rsh (3.3)
w − NARROW

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

 
R(T ) = R(TNOM) 1 + T C1 (T − TNOM) + T C2 (T − TNOM)2 (3.4)

where R(TNOM) = Rnom |Racnom . In the above formula, ‘T ’ represents the instance
temperature, which can be explicitly set using the temp keyword or calculated using the
circuit temperature and dtemp, if present. If both temp and dtemp are specified, the latter
is ignored. Ngspice improves SPICE’s resistors noise model, adding flicker noise (1/f ) to
it and the noisy (or noise) keyword to simulate noiseless resistors. The thermal noise
in resistors is modeled according to the equation:

4kT
i¯2R = ∆f (3.5)
R

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

Flicker noise model is:

¯ = KFIRAF
i2Rf n ∆f (3.6)
W W F LLF f EF

A small list of sheet resistances (in Ω/) for conductors is shown below. The table repre-
sents 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
80 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS

3.3.4 Resistors, dependent on expressions (behavioral resistor)

General form:

RXXXXXXX n + n - R = ’ expression ’ < tc1 = value > < tc2 = value > < noisy =0 >
RXXXXXXX n + n - ’ expression ’ < tc1 = value > < tc2 = value > < noisy =0 >

Examples:

R1 rr 0 r = ’V ( rr ) < { Vt } ? { R0 } : {2* R0 } ’ tc1 =2 e -03 tc2 =3.3 e -06

R2 r2 rr r = {5 k + 50* TEMPER }
. param rp1 = 20
R3 no1 no2 r = ’5 k * rp1 ’ noisy =1

Expression may be an equation or an expression containing node voltages or branch

currents (in the form of i(vm)) and any other terms as given for the B source and described
in Chapt. 5.1. It may contain parameters (2.9.1) and the special variables time, temper,
and hertz (5.1.2). An example file is given below. Small signal noise in the resistor
(15.3.4) may be evaluated as white noise, depending on resistance, temperature and tc1,
tc2. To enable noise calculation, add the flag noisy=1 to the instance line. As a default
the behavioral resistor is noiseless.
Example input file for non-linear resistor:

Non - linear resistor

. param R0 =1 k Vi =1 Vt =0.5
* resistor depending on control voltage V ( rr )
R1 rr 0 r = ’V ( rr ) < { Vt } ? { R0 } : {2* R0 } ’
* control voltage
V1 rr 0 PWL (0 0 100 u { Vi })
. control
unset askquit
tran 100 n 100 u uic
plot i ( V1 )
. endc
. end

3.3.5 Resistor with nonlinear r2_cmc model

In the adms version of ngspice, a resistor model r2_cmc is implemented. This is a 2-

terminal resistor model developed by the resistor subcommittee of the CMC. The goal
was to have a standard 2-terminal resistor model with standard parameter names and
a standard, numerically well behaved nonlinearity model. It may be selected by setting
level=2 in the .model line.
For now a detailed description is available in the Verilog A source code file to be found a
src/spicelib/devices/adms/r2_cmc/admsva/r2_cmc.va.
3.3. ELEMENTARY DEVICES 81

Example input file for non-linear resistor with r2_cmc model

r2_cmc
v1 1 0 10
Rr2_cmc 1 0 rmodel w =1 u l =20 u isnoisy =1
. model rmodel r ( level =2 rsh =200 xl =0.2 u xw = -0.05 u
+ p3 =0.12 q3 =1.6 p2 =0.015 q2 =3.8 tc1 =1.5 e -4 tc2 =7 e -7)
. control
op
let res = v (1) / - v1 # branch
print res . endc
. end

3.3.6 Capacitors
General form:

CXXXXXXX n + n - < value > < mname > <m = val > < scale = val > < temp = val >
+ < dtemp = val > < tc1 = val > < tc2 = val > < ic = init_condition >

Examples:

CBYP 13 0 1 UF
COSC 17 23 10 U IC =3 V

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 char-
acteristics are called ‘semiconductor capacitors’ and are described in the next section.
In this first form n+ and n- are the positive and negative element nodes, respectively and
value is the capacitance in Farads.
Capacitance can be specified in the instance line as in the examples above or in a .model
line, as in the example below:

C1 15 5 cstd
C2 2 7 cstd
. model cstd C cap =3 n

Both capacitors have a capacitance of 3nF.

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

CEB 1 2 1 u cap1 dtemp =5

. MODEL cap1 C tc1 =0.001
82 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS

The (optional) initial condition is the initial (time zero) value of capacitor voltage (in
Volts). Note that the initial conditions (if any) apply only if the uic option is specified
on the .tran control line.

Ngspice calculates the nominal capacitance as described below:

Cnom = value · scale · m (3.7)

The temperature coefficients tc1 and tc2 describe a quadratic temperature dependence
(see equation17.14) 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.3.8).

3.3.7 Semiconductor Capacitors

General form:

CXXXXXXX n + n - < value > < mname > <l = length > <w = width > <m = val >
+ < scale = val > < temp = val > < dtemp = val > < ic = init_condition >

Examples:

CLOAD 2 10 10 P
CMOD 3 7 CMODEL L =10 u W =1 u

This is the more general form of the Capacitor presented in section (3.3.6), 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 capaci-
tance in the .model line (3.3.6).

3.3.8 Semiconductor Capacitor Model (C)

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

Name Parameter Units Default Example

CAP model capacitance F 0.0 1e-6
CJ junction bottom capacitance F/m2 - 5e-5
CJSW junction sidewall capacitance F/m - 2e-11
DEFW default device width m 1e-6 2e-6
DEFL default device length m 0.0 1e-6
NARROW narrowing due to side etching m 0.0 1e-7
SHORT shortening due to side etching m 0.0 1e-7
TC1 first order temperature coeff. F/◦ C 0.0 0.001
TC2 second order temperature coeff. F/◦ C 2 0.0 0.0001
◦
TNOM parameter measurement temperature C 27 50
DI relative dielectric constant F/m - 1
THICK insulator thickness m 0.0 1e-9
The capacitor has a capacitance computed as:
If value is specified on the instance line then

Cnom = value · scale · m (3.8)

If model capacitance is specified then

Cnom = CAP · scale · m (3.9)

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

C0 = CJ(l − SHORT)(w − NARROW) + 2CJSW(l − SHORT + w − NARROW) (3.10)

CJ can be explicitly given on the .model line or calculated by physical parameters. When
CJ is not given, is calculated as:
If THICK is not zero:

DI ϵ0
CJ = THICK
if DI is specified,
(3.11)
ϵSiO2
CJ = THICK
otherwise.

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

Cnom = C0 scale m (3.12)

After the nominal capacitance is calculated, it is adjusted for temperature by the formula:
 
C(T ) = C(TNOM) 1 + T C1 (T − TNOM) + T C2 (T − TNOM)2 (3.13)
84 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS

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.3.9 Capacitors, dependent on expressions (behavioral capaci-

tor)

There are two forms for behavioral capacitors allowed:

1. Capacitance formulated expressions C = ’expression’

2. Charge formulated expressions Q = ’expression’

General form:

CXXXXXXX n + n - C = ’ expression ’ < tc1 = value > < tc2 = value >
CXXXXXXX n + n - ’ expression ’ < tc1 = value > < tc2 = value >

CXXXXXXX n + n - Q = ’ expression ’ < tc1 = value > < tc2 = value >

Examples:

C1 cc 0 c = ’V ( cc ) < { Vt } ? { C1 } : { Ch } ’ tc1 = -1e -03 tc2 =1.3 e -05

C1 a b q = ’1 u *(4* atan ( V (a , b )/4)*2+ V (a , b ))/3 ’

Expression may be an equation or an expression containing node voltages or branch

currents (in the form of i(vm)) and any other terms as given for the B source and described
in Chapt. 5.1. It may contain parameters (2.9.1) and the special variables time, temper,
and hertz (5.1.2).
3.3. ELEMENTARY DEVICES 85

Example input file:

Behavioral Capacitor
. param Cl =5 n Ch =1 n Vt =1 m Il =100 n
. ic v ( cc ) = 0 v ( cc2 ) = 0
* capacitor depending on control voltage V ( cc )
C1 cc 0 c = ’V ( cc ) < { Vt } ? { Cl } : { Ch } ’
I1 0 1 { Il }
Exxx n1 - copy n2 n2 cc2 1
Cxxx n1 - copy n2 1
Bxxx cc2 n2 I = ’( V ( cc2 ) < { Vt } ? { Cl } : { Ch }) ’ * i ( Exxx )
I2 n2 22 { Il }
vn2 n2 0 DC 0
* measure charge by integrating current
aint1 % id (1 cc ) 2 time_count
aint2 % id (22 cc2 ) 3 time_count
. model time_count int ( in_offset =0.0 gain =1.0
+ out_lower_limit = -1 e12 out_upper_limit =1 e12
+ limit_range =1 e -9 out_ic =0.0)
. control
unset askquit
tran 100 n 100 u
plot v (2)
plot v ( cc ) v ( cc2 )
. endc
. end

3.3.10 Inductors

General form:

LYYYYYYY n + n - < value > < mname > < nt = val > <m = val >
+ < scale = val > < temp = val > < dtemp = val > < tc1 = val >
+ < tc2 = val > < ic = init_condition >

Examples:

LLINK 42 69 1 UH
LSHUNT 23 51 10 U IC =15.7 MA

The inductor device implemented into ngspice has many enhancements over the original
one.n+ and n- are the positive and negative element nodes, respectively. value is the
inductance in Henry. The initial condition (a curremt through L) becomes effective when
the uic parameter is set on the .tran line. Inductance can be specified in the instance
line as in the examples above or in a .model line, as in the example below:
86 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS

L1 15 5 indmod1
L2 2 7 indmod1
. model indmod1 L ind =3 n

Both inductors have an inductance of 3nH.

The nt is used in conjunction with a .model line, and is used to specify the number of
turns of the inductor. If you want to simulate temperature dependence of an inductor,
you need to specify its temperature coefficients, using a .model line, like in the example
below:

Lload 1 2 1 u ind1 dtemp =5

. MODEL ind1 L tc1 =0.001

The (optional) initial condition is the initial (time zero) value of inductor current (in
Amps) that flows from n+, through the inductor, to n-. Note that the initial conditions
(if any) apply only if the UIC option is specified on the .tran analysis line.
Ngspice calculates the nominal inductance as described below:

value scale
Lnom = (3.14)
m

3.3.11 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.
Name Parameter Units Default Example
IND model inductance H 0.0 1e-3
CSECT cross section m2 0.0 1e-6
DIA coil diameter m 0.0 1e-3
LENGTH length m 0.0 1e-2
TC1 first order temperature coeff. H/◦ C 0.0 0.001
TC2 second order temperature coeff. H/◦ C 2 0.0 0.0001
◦
TNOM parameter measurement temperature C 27 50
NT number of turns - 0.0 10
MU relative magnetic permeability - 1.0 -
The inductor’s inductance is computed as follows:
If value is specified on the instance line then

value scale
Lnom = (3.15)
m
If model inductance is specified then

IND scale
Lnom = (3.16)
m
3.3. ELEMENTARY DEVICES 87

If neither value nor IND are specified, then geometrical and physical parameters are taken
into account. In the following formulas
NT refers to both instance and model parameter (instance parameter overrides model
parameter):
If LENGTH is not zero:
(
MU µ0 NT2 π DIA2
Lnom = 4 LENGTH
if DIA is specified,
MU µ0 NT2 CSECT (3.17)
Lnom = LENGTH
otherwise.

with µ0 = 1.25663706143592 µH m
. DIA takes preference over CSECT. kl is the geometry
correction factor according to Lundin (see D. W. Knight, pp. 35-36), which is important
when inductor length and diameter have the same order of magnitude. After the nominal
inductance is calculated, it is adjusted for temperature by the formula
 
L(T ) = L(TNOM) 1 + T C1 (T − TNOM) + T C2 (T − TNOM) , 2
(3.18)

where L(TNOM) = Lnom . In the above formula, ‘T ’ represents the instance tempera-
ture, which can be explicitly set using the temp keyword or calculated using the circuit
temperature and dtemp, if present.

3.3.12 Coupled (Mutual) Inductors

General form:

KXXXXXXX LYYYYYYY LZZZZZZZ value

Examples:

K43 LAA LBB 0.999

KXFRMR L1 L2 0.87

LYYYYYYY and LZZZZZZZ are the names of the two coupled inductors, and value is
the coefficient of coupling, K, which must be greater than 0 and less than or equal to 1.
Using the ‘dot’ convention for drawing the coupled inductors, place a ‘dot’ on the first
node of each inductor. If you have more than two inductors interacting, pairwise coupling
is supported.
Pairwise coupling of more than two inductors:

L1 1 0 10 u
L2 2 0 11 u
L3 3 0 10 u

K12 L1 L2 0.99
K23 L2 L3 0.99
K13 L1 L3 0.98
88 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS

When there are more than two inductors coupled for interaction, some combination of
coupling constants are not possible physically because the magnetic fields then would
violate energy conservation. ngspice checks the coupling matrix for such conditions and
issues a warning.

3.3.13 Inductors, dependent on expressions (behavioral induc-

tor)

General form:

LXXXXXXX n + n - L = ’ expression ’ < tc1 = value > < tc2 = value >
LXXXXXXX n + n - ’ expression ’ < tc1 = value > < tc2 = value >

Examples:

L1 l2 lll L = ’i ( Vm ) < { It } ? { Ll } : { Lh } ’ tc1 = -4e -03 tc2 =6 e -05

Expression may be an equation or an expression containing node voltages or branch

currents (in the form of i(vm)) and any other terms as given for the B source and described
in Chapt. 5.1. It may contain parameters (2.9.1) and the special variables time, temper,
and hertz (5.1.2).
3.3. ELEMENTARY DEVICES 89

Example input file:

Variable inductor
. param Ll =0.5 m Lh =5 m It =50 u Vi =2 m
. ic v ( int21 ) = 0

* variable inductor depending on control current i ( Vm )

L1 l2 lll L = ’i ( Vm ) < { It } ? { Ll } : { Lh } ’
* measure current through inductor
vm lll 0 dc 0
* voltage on inductor
V1 l2 0 { Vi }

* fixed inductor
L3 33 331 { Ll }
* measure current through inductor
vm33 331 0 dc 0
* voltage on inductor
V3 33 0 { Vi }

* non linear inductor ( discrete setup )

F21 int21 0 B21 -1
L21 int21 0 1
B21 n1 n2 V = ’( i ( Vm21 ) < { It } ? { Ll } : { Lh }) ’ * v ( int21 )
* measure current through inductor
vm21 n2 0 dc 0
V21 n1 0 { Vi }

. control
unset askquit
tran 1 u 100 u uic
plot i ( Vm ) i ( vm33 )
plot i ( vm21 ) i ( vm33 )
plot i ( vm ) - i ( vm21 )
. endc
. end

3.3.14 Capacitor or inductor with initial conditions

The simulator supports the specification of voltage and current initial conditions on capac-
itor and inductor models, respectively. These models are not the standard ones supplied
with SPICE3, but are in fact code models that can be substituted for the SPICE models
when realistic initial conditions are required. For details please refer to Chapter 12. A
XSPICE deck example using these models is shown below:

*
* This circuit contains a capacitor and an inductor with
90 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS

* initial conditions on them. Each of the components

* has a parallel resistor so that an exponential decay
* of the initial condition occurs with a time constant of
* 1 second.
*
a1 1 0 cap
.model cap capacitoric (c=1000uf ic=1)
r1 1 0 1k
*
a2 2 0 ind
.model ind inductoric (l=1H ic=1)
r2 2 0 1.0
*
.control
tran 0.01 3
plot v(1) v(2)
.endc
.end

3.3.15 Switches

Two types of switches are available: a voltage controlled switch (type SXXXXXX, model
SW) and a current controlled switch (type WXXXXXXX, model CSW). A switching
hysteresis may be defined, as well as on- and off-resistances (0 < R < ∞).
General form:

SXXXXXXX N + N - NC + NC - MODEL <ON > < OFF >

WYYYYYYY N + N - VNAM MODEL <ON > < OFF >

Examples:

s1 1 2 3 4 switch1 ON
s2 5 6 3 0 sm2 off
Switch1 1 2 10 0 smodel1
w1 1 2 vclock switchmod1
W2 3 0 vramp sm1 ON
wreset 5 6 vclck lossyswitch OFF

Nodes 1 and 2 are the nodes between which the switch terminals are connected. The model
name is mandatory while the initial conditions are optional. For the voltage controlled
switch, nodes 3 and 4 are the positive and negative controlling nodes respectively. For
the current controlled switch, the controlling current is that through the specified voltage
source. The direction of positive controlling current flow is from the positive node, through
the source, to the negative node.
The instance parameters ON or OFF are required, when the controlling voltage (cur-
rent) starts inside the range of the hysteresis loop (different outputs during forward vs.
3.3. ELEMENTARY DEVICES 91

backward voltage or current ramp). Then ON or OFF determine the initial state of the
switch.

3.3.16 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 shown below.
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/GM IN , if you have set GM IN to any other value, see the .OPTIONS control
line (15.1.2) for a description of GM IN , its default value results in an off-resistance of
1.0e+12 ohms.

The use of an ideal element that is highly nonlinear such as a switch can cause large
discontinuities to occur in the circuit node voltages. A rapid change such as that associated
with a switch changing state can cause numerical round-off or tolerance problems leading
to erroneous results or time step difficulties. The user of switches can improve the situation
by taking the following steps:

• First, it is wise to set the ideal switch impedance just high or low enough to be
negligible with respect to other circuit elements. Using switch impedances that
are close to ‘ideal’ in all cases aggravates the problem of discontinuities mentioned
above. Of course, when modeling real devices such as MOSFETS, the on resistance
should be adjusted to a realistic level depending on the size of the device being
modeled.

• If a wide range of ON to OFF resistance must be used in the switches (ROFF/RON

> 1e+12), then the tolerance on errors allowed during transient analysis should be
decreased by using the .OPTIONS control line and specifying TRTOL to be less than
the default value of 7.0.

• When switches are placed around capacitors, then the option CHGTOL should also
be reduced. Suggested values for these two options are 1.0 and 1e-16 respectively.
These changes inform ngspice to be more careful around the switch points so that
no errors are made due to the rapid change in the circuit.
92 CHAPTER 3. CIRCUIT ELEMENTS AND MODELS

Example input file:

Switch test
. tran 2 us 5 ms
* switch control voltage
v1 1 0 DC 0.0 PWL (0 0 2e -3 2 4e -3 0)
* switch control voltage starting inside hysteresis window
* please note influence of instance parameters ON , OFF
v2 2 0 DC 0.0 PWL (0 0.9 2e -3 2 4e -3 0.4)
* switch control current
i3 3 0 DC 0.0 PWL (0 0 2e -3 2 m 4e -3 0) $ <--- switch control current
* load voltage
v4 4 0 DC 2.0
* input load for current source i3
r3 3 33 10 k
vm3 33 0 dc 0 $ <--- measure the current
* ouput load resistors
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 switch1 OFF
s2 20 0 2 0 switch1 OFF
s3 30 0 2 0 switch1 ON
. model switch1 sw vt =1 vh =0.2 ron =1 roff =10 k
*
w1 40 0 vm3 wswitch1 off
. model wswitch1 csw it =1 m ih =0.2 m ron =1 roff =10 k
*
. control
run
plot v (1) v (10)
plot v (10) vs v (1) $ <-- get hysteresis loop
plot v (2) v (20) $ <--- different initial values
plot v (20) vs v (2) $ <-- get hysteresis loop
plot v (2) v (30) $ <--- different initial values
plot v (30) vs v (2) $ <-- get hysteresis loop
plot v (40) vs vm3 # branch $ <--- current controlled switch hysteresi
. 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.001 AC 1 SIN (0 1 1 MEG )
ISRC 23 21 AC 0.333 45.0 SFFM (0 1 10 K 5 1 K )
VMEAS 12 9
VCARRIER 1 0 DISTOF1 0.1 -90.0
VMODULATOR 2 0 DISTOF2 0.01
IIN1 1 5 AC 1 DISTOF1 DISTOF2 0.001

n+ and n- are the positive and negative nodes, respectively. Note that voltage sources
need not be grounded. Positive current is assumed to flow from the positive node, through
the source, to the negative node. A current source of positive value forces current to flow
out of the n+ node, through the source, and into the n- node. Voltage sources, in addition
to being used for circuit excitation, are the ‘ammeters’ for ngspice, that is, zero valued
voltage sources may be inserted into the circuit for the purpose of measuring current.
They of course have no effect on circuit operation since they represent short-circuits.
DC/TRAN is the dc and transient analysis value of the source. If the source value is zero
both for dc and transient analyses, this value may be omitted. If the source value is
time-invariant (e.g., a power supply), then the value may optionally be preceded by the
letters DC.
The keyword AC together with its value ACMAG (and optional value ACPHASE) are required
when the voltage or current source is intended to become the small signal source in an

93
94 CHAPTER 4. VOLTAGE AND CURRENT SOURCES

ac simulation. ACMAG is the ac magnitude and ACPHASE is the ac phase. The voltage or
current source then will become a reference for all nodes. All small signal node amplitude
values obtained after the simulation have been divided by the reference ACMAG. A typcal
ACMAG value thus may be unity. Any measured phase has been shifted by ACPHASE. 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 to be avoided.
DISTOF1 and DISTOF2 are the keywords that specify that the independent source has
distortion inputs at the frequencies F1 and F2 respectively (see the description of the
.DISTO control line). The keywords may be followed by an optional magnitude and
phase. The default values of the magnitude and phase are 1.0 and 0.0 respectively.
Any independent source can be assigned a time-dependent value for transient analysis. If
a source is assigned a time-dependent value, the time-zero value is used for dc analysis.
There are nine independent source functions:

• pulse,

• exponential,

• sinusoidal,

• piece-wise linear,

• single-frequency FM,

• AM,

• transient noise,

• random voltages or currents,

• external data (only with ngspice shared library),

• and RF port

If parameters other than source values are omitted or set to zero, the default values shown
are assumed. TSTEP is the printing increment and TSTOP is the final time – see the .TRAN
control line for an explanation.

4.1.1 Pulse

General form:

PULSE ( V1 V2 TD TR TF PW PER NP )

Examples:

VIN 3 0 PULSE ( -1 1 2 NS 2 NS 2 NS 50 NS 100 NS 5)

4.1. INDEPENDENT SOURCES FOR VOLTAGE OR CURRENT 95

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
NP Number of Pulses *) unlimited -
A single pulse, without repetition count or phase offset, is described by the following
table:
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.
*) NP set to 0 or omitted denotes unlimited pulses. If compatibility mode (see 16.14.1)
set ngbehavior=xs is set in .spiceinit, the 8th parameter is the phase of the pulse signal
(in degrees), which results in forward running (pos. value) or a delay (neg. value) of the
pulse sequence.

4.1.2 Sinusoidal

General form:

SIN ( VO VA FREQ TD THETA PHASE )

Examples:

VIN 3 0 SIN (0 1 100 MEG 1 NS 1 E10 )

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

PHASE Phase 0.0 degrees

The shape of the waveform is described by the following formula:
96 CHAPTER 4. VOLTAGE AND CURRENT SOURCES

(
V0 if 0 ≤ t < T D
V (t) =
V 0 + V A e−(t−T D)T HET A sin (2π · F REQ · (t − T D) + P HASE) if T D ≤ t < T ST OP.
(4.1)

4.1.3 Exponential

General form:

EXP ( V1 V2 TD1 TAU1 TD2 TAU2 )

Examples:

VIN 3 0 EXP ( -4 -1 2 NS 30 NS 60 NS 40 NS )

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:
Let V 21 = V 2 − V 1, V 12 = V 1 − V 2:


V 1
   if 0 ≤ t < T D1,
 (t−T D1)
− T AU 1
V (t) = V 1 + V 21 1 − e if T D1 ≤ t < T D2,

    
 (t−T D1) (t−T D2)
V 1 + V 21 1 − e− T AU 1 + V 12 1 − e− T AU 2 if T D2 ≤ t < T ST OP.
(4.2)

4.1.4 Piece-Wise Linear

General form:

PWL ( T1 V1 < T2 V2 T3 V3 T4 V4 ... >) <r = value > < td = value >

Examples:

VCLOCK 7 5 PWL (0 -7 10 NS -7 11 NS -3 17 NS -3 18 NS -7 50 NS -7)

+ r =0 td =15 NS
4.1. INDEPENDENT SOURCES FOR VOLTAGE OR CURRENT 97

Each pair of values (Ti , Vi ) specifies that the value of the source is Vi (in Volts or Amps)
at time = Ti . The value of the source at intermediate values of time is determined by
using linear interpolation on the input values. The parameter r determines a repeat time
point. If r is set to -1 or is not given, the whole sequence of values (Ti , Vi ) is issued once
only, then the output stays at its final value. If r = 0, the whole sequence from time 0 to
time Tn is repeated forever. If r = 10ns, the sequence between 10ns and 50ns is repeated
forever. The r value has to be one of the time points T1 to Tn of the PWL sequence. If
td is given, the whole PWL sequence is delayed by the value of td. Please note that for
now r and td are available only with the voltage source, not with the current source.

4.1.5 Single-Frequency FM

General Form:

SFFM ( VO VA FC MDI FS PHASEC PHASES )

Examples:

V1 12 0 SFFM (0 1 M 20 K 5 1 K )

Name Parameter Default value Units

VO Offset - V, A
VA Amplitude - V, A
FC Carrier frequency 1/T ST OP Hz
MDI Modulation index -
FS Signal frequency 1/T ST OP Hz
PHASEC carrier phase 0 degrees
PHASES signal phase 0 degrees
The shape of the waveform is described by the following equation:

V (t) = VO + VA sin (2π · F C · t + M DI sin (2π · F S · t + P HASES) + P HASEC)

(4.3)

4.1.6 Amplitude modulated source (AM)

General form:

AM ( VA VO MF FC TD PHASES )

Examples:

V1 12 0 AM (0.5 1 20 K 5 MEG 1 m )
98 CHAPTER 4. VOLTAGE AND CURRENT SOURCES

Name Parameter Default value Units

VA Amplitude - V, A
VO Offset - V, A
MF Modulating frequency - Hz
FC Carrier frequency 1/T ST OP Hz
TD Signal delay - s
PHASES Phase 0.0 degrees
The shape of the waveform is described by the following equation:

V (t) = VA (V O + sin (2π · M F · t) + P HASES) sin (2π · F C · t + P HASES) (4.4)

4.1.7 Transient noise source

General form:

TRNOISE ( NA NT NALPHA NAMP RTSAM RTSCAPT RTSEMT )

Examples:

VNoiw 1 0 DC 0 TRNOISE (20 n 0.5 n 0 0) $ white

VNoi1of 1 0 DC 0 TRNOISE (0 10 p 1.1 12 p ) $ 1/ f
VNoiw1of 1 0 DC 0 TRNOISE (20 10 p 1.1 12 p ) $ white and 1/ f
IALL 10 0 DC 0 trnoise (1 m 1 u 1.0 0.1 m 15 m 22 u 50 u )
$ white , 1/ f , RTS

Transient noise is an experimental feature allowing (low frequency) transient noise injec-
tion and analysis. See Chapt. 15.3.11 for a detailed description. NA is the Gaussian noise
rms voltage amplitude, NT is the time between sample values (breakpoints will be en-
forced on multiples of this value). NALPHA (exponent to the frequency dependency), NAMP
(rms voltage or current amplitude) are the parameters for 1/f noise, RTSAM the random
telegraph signal amplitude, RTSCAPT the mean of the exponential distribution of the trap
capture time, and RTSEMT its emission time mean. White Gaussian, 1/f, and RTS noise
may be combined into a single statement.
Name Parameter Default value Units
NA Rms noise amplitude (Gaussian) - V, A
NT Time step - sec
NALPHA 1/f exponent 0<α<2 -
NAMP Amplitude (1/f) - V, A
RTSAM Amplitude - V, A
RTSCAPT Trap capture time - sec
RTSEMT Trap emission time - sec
If you set NT and RTSAM to 0, the noise option TRNOISE ... is ignored. Thus you may
switch off the noise contribution of an individual voltage source VNOI by the command
alter @vnoi[trnoise] = [ 0 0 0 0 ] $ no noise
4.1. INDEPENDENT SOURCES FOR VOLTAGE OR CURRENT 99

alter @vrts[trnoise] = [ 0 0 0 0 0 0 0] $ no noise

See Chapt. 17.5.3 for the alter command.
You may switch off all TRNOISE noise sources by setting
set notrnoise
to your .spiceinit file (for all your simulations) or into your control section in front of the
next run or tran command (for this specific and all following simulations). The command
unset notrnoise
will reinstate all noise sources.
The noise generators are implemented into the independent voltage (vsrc) and current
(isrc) sources.

4.1.8 Random voltage source

The TRRANDOM option yields statistically distributed voltage values, derived from the
ngspice random number generator. These values may be used in the transient simula-
tion directly within a circuit, e.g. for generating a specific noise voltage, but especially
they may be used in the control of behavioral sources (B, E, G sources 5, voltage control-
lable A sources 12, capacitors 3.3.9, inductors 3.3.13, or resistors 3.3.4) to simulate the
circuit dependence on statistically varying device parameters. A Monte-Carlo simulation
may thus be handled in a single simulation run.
General form:

TRRANDOM ( TYPE TS < TD < PARAM1 < PARAM2 > > >)

Examples:

VR1 r1 0 dc 0 trrandom (2 10 m 0 1) $ Gaussian

TYPE determines the random variates generated: 1 is uniformly distributed, 2 Gaussian,

3 exponential, 4 Poisson. TS is the duration of an individual voltage value. TD is a time
delay with 0 V output before the random voltage values start up. PARAM1 and PARAM2
depend on the type selected.
TYPE description PARAM1 default PARAM2 default
1 Uniform Range 1 Offset 0
2 Gaussian Standard Dev. 1 Mean 0
3 Exponential Mean 1 Offset 0
4 Poisson Lambda 1 Offset 0
100 CHAPTER 4. VOLTAGE AND CURRENT SOURCES

4.1.9 External voltage or current input

General form:

EXTERNAL

Examples:

Vex 1 0 dc 0 external
Iex i1 i2 dc 0 external <m = xx >

Voltages or currents may be set from the calling process, if ngspice is compiled as a shared
library and loaded by the process. See Chapt. 19.6.3 for an explanation.

4.1.10 Arbitrary Phase Sources

ngspice supports arbitrary phase independent sources that output at TIME=0.0 a value
corresponding to some specified phase shift. Other versions of SPICE use the TD (delay
time) parameter to set phase-shifted sources to their time-zero value until the delay time
has elapsed. The ngspice phase parameter is specified in degrees and is included after the
SPICE3 parameters normally used to specify an independent source. Partial examples of
usage for pulse and sine waveforms are shown below:

* Phase shift is specified as final parameter

* on the independent source cards. Phase shift for both of the
* following is specified as +45 degrees
*
v1 1 0 0.0 sin(0 1 1k 0 0 45.0)
r1 1 0 1k
*
v2 2 0 0.0 pulse(-1 1 0 1e-5 1e-5 5e-4 1e-3 45.0)
r2 2 0 1k
*

4.1.11 RF Port
A voltage source VSRC may be defined as RF Port. To do so, there are at least two
more parameters required. The first is portnum (integer) which defines the VSRC as a
RF Port. Portnum of all VSRCs defined as RF ports must start from 1 and count up to
the number of RF ports. You cannot have duplicate portnums. Then you have Z0 (real)
which defines the internal impedance. If not provided, its default value is 50Ohm. When
declaring a RF ports, the VSRC now become a VSRC with Z0 Ohm in series. This extra
resistor affects all simulations.
General form:
4.2. LINEAR DEPENDENT SOURCES 101

DC 0 AC 1 portnum n1 < z0 n2 >

Examples:

V1 in 0 dc 0 ac 1 portnum 1 z0 100

At least two ports are required for the S-parameter simulation with the command .sp
(15.3.8). If portnum is not provided, the voltage source VRSC behaves as normal.

4.2 Linear Dependent Sources

Ngspice allows circuits to contain linear dependent sources characterized by any of the
four equations
i = gv v = ev i = fi v = hi
where g, e, f , and h are constants representing transconductance, voltage gain, current
gain, and transresistance, respectively. Non-linear dependent sources for voltages or cur-
rents (B, E, G) are described in Chapt. 5.

4.2.1 Gxxxx: Linear Voltage-Controlled Current Sources (VCCS)

General form:

GXXXXXXX N + N - NC + NC - VALUE <m = val >

Examples:

G1 2 0 5 0 0.1
n+ and n- are the positive and negative nodes, respectively. Current flow is from the
positive node, through the source, to the negative
node. nc+ and nc- are the positive and negative controlling nodes, respectively. value
is the transconductance (in mhos). m is an optional multiplier to the output current. val
may be a numerical value or an expression according to 2.9.5 containing references to
other parameters. Instance parameters are listed in chapt. 31.3.6.

4.2.2 Exxxx: Linear Voltage-Controlled Voltage Sources (VCVS)

General form:

EXXXXXXX N + N - NC + NC - VALUE

Examples:

E1 2 3 14 1 2.0
102 CHAPTER 4. VOLTAGE AND CURRENT SOURCES

n+ is the positive node, and n- is the negative node. nc+ and nc- are the positive and
negative controlling nodes, respectively. value is the voltage gain. Instance parameters
are listed in chapt. 31.3.7.

4.2.3 Fxxxx: Linear Current-Controlled Current Sources (CCCS)

General form:

FXXXXXXX N + N - VNAM VALUE <m = val >

Examples:

F1 13 5 VSENS 5 m =2

n+ and n- are the positive and negative nodes, respectively. Current flow is from the
positive node, through the source, to the negative node. vnam is the name of a voltage
source through which the controlling current flows. The direction of positive controlling
current flow is from the positive node, through the source, to the negative node of vnam.
value is the current gain. m is an optional multiplier to the output current. Instance
parameters are listed in chapt. 31.3.4.

4.2.4 Hxxxx: Linear Current-Controlled Voltage Sources (CCVS)

General form:

HXXXXXXX N + N - VNAM VALUE

Examples:

HX 5 17 VZ 0.5 K

n+ and n- are the positive and negative nodes, respectively. vnam is the name of a voltage
source through which the controlling current flows. The direction of positive controlling
current flow is from the positive node, through the source, to the negative node of vnam.
value is the transresistance (in ohms). Instance parameters are listed in chapt. 31.3.5.

4.2.5 Polynomial Source Compatibility

Dependent polynomial sources available in SPICE2G6 are fully supported in ngspice using
the XSPICE extension (25.1). The form used to specify these sources is shown in Table
4.1. For details on its usage please see Chapt. 5.5.
4.2. LINEAR DEPENDENT SOURCES 103

Dependent Polynomial Sources

Source Type Instance Card
POLYNOMIAL VCVS EXXXXXXX N+ N- POLY(ND) NC1+ NC1- P0 (P1...)
POLYNOMIAL VCCS GXXXXXXX N+ N- POLY(ND) NC1+ NC1- P0 (P1...)
POLYNOMIAL CCCS FXXXXXXX N+ N- POLY(ND) VNAM1 !VNAM2...? P0 (P1...)
POLYNOMIAL CCVS HXXXXXXX N+ N- POLY(ND) VNAM1 !VNAM2...? P0 (P1...)

Table 4.1: Dependent Polynomial Sources