Next: , Previous: Interactive Interpreter, Up: Interactive Interpreter


10.1 Expressions, Functions, and Constants

Ngspice and Nutmeg data is in the form of vectors: time, voltage, etc. Each vector has a type, and vectors can be operated on and combined algebraically in ways consistent with their types. Vectors are normally created when a data file is read in (see the load command below), and when the initial datafile is loaded. They can also be created with the let command.

An expression is an algebraic formula involving vectors and scalars (a scalar is a vector of length 1) and the following operations:

                  +   -    *    /    ^   %

% is the modulo operator, and the comma operator has two meanings: if it is present in the argument list of a user definable function, it serves to separate the arguments. Otherwise, the term x , y is synonymous with x + j(y).

Also available are the logical operations & (and), | (or), ! (not), and the relational operations <, >, >=, <=, =, and <> (not equal). If used in an algebraic expression they work like they would in C, producing values of 0 or 1. The relational operators have the following synonyms:

                            gt    >
                            lt    <
                            ge    >=
                            le    <=
                            ne    <>
                            eq    =
                            and   &
                            or    |
                            not   !

These are useful when < and > might be confused with IO redirection (which is almost always).

The following functions are available:

mag(vector)
The magnitude of vector
ph(vector)
The phase of vector
j(vector)
i (sqrt(-1)) times vector
real(vector)
The real component of vector
imag(vector)
The imaginary part of vector
db(vector)
20 log10(mag(vector))
log(vector)
The logarithm (base 10) of vector
ln(vector)
The natural logarithm (base e) of vector
exp(vector)
e to the vector power
abs(vector)
The absolute value of vector.
sqrt(vector)
The square root of vector.
sin(vector)
The sine of vector.
cos(vector)
The cosine of vector.
tan(vector)
The tangent of vector.
atan(vector)
The inverse tangent of vector.
norm(vector)
The vector normalized to 1 (i.e, the largest magnitude of any component is 1).
rnd(vector)
A vector with each component a random integer between 0 and the absolute value of the vectors's corresponding component.
mean(vector)
The result is a scalar (a length 1 vec tor) that is the mean of the elements of vector.
vector(number)
The result is a vector of length number, with elements 0, 1, ... number - 1. If number is a vector then just the first element is taken, and if it isn't an integer then the floor of the magnitude is used.
length(vector)
The length of vector.
interpolate(plot.vector)
The result of interpolating the named vector onto the scale of the current plot. This function uses the variable polydegree to determine the degree of interpolation.
deriv(vector)
Calculates the derivative of the given vector. This uses numeric differentiation by interpolating a polynomial and may not produce satisfactory results (particularly with iterated differentiation). The implementation only calculates the derivative with respect to the real component of that vector's scale.

A vector may be either the name of a vector already defined or a floating-point number (a scalar). A number may be written in any format acceptable to NGSPICE, such as 14.6Meg or -1.231e-4. Note that you can either use scientific notation or one of the abbreviations like MEG or G, but not both. As with NGSPICE, a number may have trailing alphabetic characters after it.

The notation expr [num] denotes the num'th element of expr. For multi-dimensional vectors, a vector of one less dimension is returned. Also for multi-dimensional vectors, the notation expr[m][n] will return the nth element of the mth subvector. To get a subrange of a vector, use the form expr[lower, upper].

To reference vectors in a plot that is not the current plot (see the setplot command, below), the notation plotname.vecname can be used.

Either a plotname or a vector name may be the wildcard all. If the plotname is all, matching vectors from all plots are specified, and if the vector name is all, all vectors in the specified plots are referenced. Note that you may not use binary operations on expressions involving wildcards - it is not obvious what all + all should denote, for instance. Thus some (contrived) examples of expressions are:

          cos(TIME) + db(v(3))
          sin(cos(log([1 2 3 4 5 6 7 8 9 10])))
          TIME * rnd(v(9)) - 15 * cos(vin#branch) ^ [7.9e5 8]
          not ((ac3.FREQ[32] & tran1.TIME[10]) gt 3)

Vector names in ngspice may have a name such as @name[param], where name is either the name of a device instance or model. This denotes the value of the param parameter of the device or model. See Appendix B for details of what parameters are available. The value is a vector of length 1. This function is also available with the show command, and is available with variables for convenience for command scripts.

There are a number of pre-defined constants in nutmeg. They are:

pi
J (3.14159...)
e
The base of natural logarithms (2.71828...)
c
The speed of light (299,792,500 m/sec)
i
The square root of -1
kelvin
Absolute 0 in Centigrade (-273.15 ^oC)
echarge
The charge on an electron (1.6021918e-19 C)
boltz
Boltzman's constant (1.3806226e-23)
planck
Planck's constant (h = 6.626200e-34)

These are all in MKS units. If you have another variable with a name that conflicts with one of these then it takes precedence.