NUTMEG(1) NUTMEG(1)
NAME
nutmeg - spice post-processor
SYNOPSIS
nutmeg [ - ] [ -n ] [ -t term ] [ datafile ... ]
DESCRIPTION
Nutmeg is a post processor for SPICE - it takes the raw output file
created by spice -r and plots the data on a graphics terminal or a
workstation display. Note that the raw output file is different from
the data that SPICE writes to the standard output.
Arguments are:
- Don’t try to load the default data file ("rawspice") if no other
files are given.
-n (or --no-spiceinit)
Don’t try to source the file ".spiceinit" upon startup. Normally
nutmeg tries to find the file in the current directory, and if
it is not found then in the user’s home directory.
-t term (or --term=term)
The program is being run on a terminal with mfb name term.
-h (or --help)
Display a verbose help on the arguments available to the pro-
gram.
-v (or --version)
Display a version number and copyright information of the pro-
gram.
Further arguments are taken to be data files in binary or ascii format
(see sconvert(1)) which are loaded into nutmeg. If the file is in
binary format, it may be only partially completed (useful for examining
SPICE ouput before the simulation is finished). One file may contain
any number of data sets from different analyses.
Nutmeg data is in the form of vectors: time, voltage, etc. Each vector
has a type, and vectors can be operated on and combined algebraicly 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:
+, -, *, %, /, ^, and ,.
% 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 seperate the arguments. Otherwise, the term x , y is synony-
mous 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 syn-
onyms: "gt" is >, "lt" is <, "ge" is >=, "le" is <=, "ne" is <>, "eq"
is =, "and" is &, "or" is |, and "not" is !. 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 the 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 sin 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 mag-
nitude of any component will be 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 vector) 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 interpola-
tion.
A vector may be either the name of a vector already defined, a float-
ing- point number (a scalar), or a list like [elt1 elt2 ... eltn],
which is a vector of length n. A number may be written in any format
acceptable to SPICE, 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 SPICE, a number may have trailing alphabetic
characters after it.
The notation expr [lower upper], where lower and upper are numbers,
denotes the range of elements from expr between lower and upper. The
notation expr [num] denotes the num’th element of expr. If upper is
lower than lower, the order of the elements in the vector is reversed.
In all other cases, [ and ] serve to surround literal vectors as
described above. (You may have to use a lot of parentheses to make
sure that you get what you want. For instance, you have to type print
(foo) ([1 2]) to print the two vectors. Otherwise it will be inter-
preted as a function call or a vector with an index.) Note that the
expression foo[10 20][5] will not yield the 15th element of foo, but
rather the 5th. In general only the last index suffix on an expression
will take effect.
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 refer-
enced. 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)
Nutmeg commands are as follows:
plot exprs [ylimit ylo yhi] [xlimit xlo xhi] [xindices xilo xihi]
[xcompress comp] [xdelta xdel] [ydelta ydel] [xlog] [ylog] [vs xname]
[xlabel word] [ylabel word] [title word] [samep]
Plot the given exprs on the screen (if you are on a graphics
terminal). The xlimit and ylimit arguments determine the high
and low x- and y-limits of the axes, respectively. The xindices
arguments determine what range of points are to be plotted -
everything between the xilo’th point and the xihi’th point is
plotted. The xcompress argument specifies that only one out of
every comp points should be plotted. If an xdelta or a ydelta
parameter is present, it specifies the spacing between grid
lines on the X- and Y-axis. These parameter names may be abbre-
viated to xl, yl, xind, xcomp, xdel, and ydel respectively. The
xname argument is an expression to use as the scale on the x-
axis. If xlog or ylog are present, the X or Y scale respec-
tively will be logarithmic. The xlabel and ylabel arguments
cause the specified labels to be used for the X and Y axes,
respectively. If samep is given, the values of the other param-
eters (other than xname) from the previous plot, hardcopy, or
asciiplot command will be used unless re-defined on the command
line. Finally, the title argument will be used in the place of
the plot name at the bottom of the graph.
hardcopy file plotargs
Just like plot, except creates a file called file containing the
plot. The file is an image in plot(5) format, and can be
printed by either the plot(1) program or lpr with the -g flag.
asciiplot plotargs
Produce a line printer plot of the vectors. The plot is sent to
the standard output, so you can put it into a file with asci-
iplot args ... > file. The set options width, height, and
nobreak determine the width and height of the plot, and whether
there are page breaks, respectively. Note that you will have
problems if you try to asciiplot something with an X-scale that
isn’t monotonic (i.e, something like sin(TIME) ), because asci-
iplot uses a simple-minded sort of linear interpolation.
define function(arg1, arg2, ...) expression
Define the user-definable function with the name function and
arguments arg1, arg2, ... to be expression, which may involve
the arguments. When the function is later used, the arguments it
is given are substituted for the formal arguments when it is
parsed. If expression is not present, any definition for func-
tion is printed, and if there are no arguments to define then
all currently active definitions are printed. Note that you may
have different functions defined with the same name but differ-
ent arities. Some useful definitions are:
define max(x,y) (x > y) * x + (x <= y) * y
define min(x,y) (x < y) * x + (x >= y) * y
undefine function ...
Definitions for the named user-defined functions are deleted.
let name = expr
Creates a new vector called name with the value specified by
expr, an expression as described above. If expr is [] (a zero-
length vector) then the vector becomes undefined. If there are
no arguments, let is the same as display.
print [col] [line] expr ...
Prints the vector described by the expression expr. If the col
argument is present, print the vectors named side by side. If
line is given, the vectors are printed horizontally. col is the
default, unless all the vectors named have a length of one, in
which case line is the default. The options width, length, and
nobreak are effective for this command (see asciiplot). If the
expression is all, all of the vectors available are printed.
Thus print col all > file will print everything in the file in
SPICE2 format. The scale vector (time, frequency) will always
be in the first column unless the variable noprintscale is true.
load [filename] ...
Loads the raw data in either binary or ascii format from the
files named. The default filename is rawspice, or the argument
to the -r flag if there was one.
source filename
Reads commands from the file filename. Lines beginning with the
character * are considered comments and ignored.
help [all] [command ...]
Prints help. If the argument all is given, a short description
of everything you could possibly type is printed. If commands
are given, descriptions of those commands are printed. Other-
wise help for only a few major commands is printed.
display [varname ...]
Prints a summary of currently defined vectors, or of the names
specified. The vectors are sorted by name unless the variable
nosort is set. The information given is the name of the vector,
the length, the type of the vector, and whether it is real or
complex data. Additionally, one vector will be labeled [scale].
When a command such as plot is given without a vs argument, this
scale is used for the X-axis. It is always the first vector in a
rawfile, or the first vector defined in a new plot. If you unde-
fine the scale (i.e, let TIME = []), a random remaining vector
will become the scale.
setplot [plotname]
Set the current plot to the plot with the given name, or if no
name is given, prompt the user with a menu. (Note that the
plots are named as they are loaded, with names like tran1 or
op2. These names are shown by the setplot and display commands
and are used by diff, below.) If the "New plot" item is
selected, the current plot will become one with no vectors
defined. Note that here the word "plot" refers to a group of
vectors that are the result of one SPICE run. When more than
one file is loaded in, or more than one plot is present in one
file, nutmeg keeps them seperate and only shows you the vectors
in the current plot.
settype type vector ...
Change the type of the named vectors to type. Type names can be
found in the manual page for sconvert.
diff plot1 plot2 [vec ...]
Compare all the vectors in the specified plots, or only the
named vectors if any are given. There are different vectors in
the two plots, or any values in the vectors differ significantly
the difference is reported. The variables abstol, reltol, and
vntol are used to determine what "significantly" means (see the
SPICE3 User’s Manual).
quit Quit nutmeg.
bug Send a bug report. (If you have defined BUGADDR, the mail will
go there.)
write [file] [exprs]
Writes out the expr’s to file. First vectors are grouped
together by plots, and written out as such. (I.e, if the
expression list contained three vectors from one plot and two
from another, then two plots will be written, one with three
vectors and one with two.) Additionally, if the scale for a
vector isn’t present, it is automatically written out as well.
The default format is ascii, but this can be changed with the
set filetype command. The default filename is rawspice, or the
argument to the -r flag on the command line, if there was one,
and the default expression list is all.
shell [args ...]
Fork a shell, or execute the arguments as a command to the
shell.
alias [word] [text ...]
Causes word to be aliased to text. History substitutions may be
used, as in C-shell aliases.
unalias [word ...]
Removes any aliases present for the words.
history [number]
Print out the history, or the last number commands typed at the
keyboard. Note: in version 3a7 and earlier, all commands
(including ones read from files) were saved.
set [word] [word = value] ...
Set the value of word to be value, if it is present. You can
set any word to be any value, numeric or string. If no value is
given then the value is the boolean ’true’. The value of word
may be inserted into a command by writing $word. If a variable
is set to a list of values that are enclosed in parentheses
(which must be seperated from their values by white space), the
value of the variable is the list. The variables meaningful to
nutmeg (of which there are too many) are:
abstol
The absolute tolerance used by the diff command.
appendwrite
Append to the file when a write command is issued, if
one already exists.
colorN
These variables determine the colors used, if X is
being run on a color display. N may be between 0 and
15. Color 0 is the background, color 1 is the grid and
text color, and colors 2 through 15 are used in order
for vectors plotted. The value of the color variables
should be names of colors, which may be found in the
file /usr