nutmeg.1

spice中支持多层次元件模型仿真的可单独运行的插件源码

.\" RCS Info: $Revision: 1.4 $ on $Date: 86/01/07 06:12:19 $
.\"           $Source: /cad4/faustus/spice/doc/RCS/nutmeg.1,v $
.\" Copyright (c) 1985 Wayne A. Christopher, U. C. Berkeley CAD Group
.TH NUTMEG 1 "27 April 1987"
.UC 4
.SH NAME
nutmeg \- spice post-processor
.SH SYNOPSIS
\fBnutmeg [ - ] [ -n ] [ -t term ] [ datafile ... ]\fR
.SH DESCRIPTION
.B Nutmeg
is a post processor for \s-2SPICE\s+2 \- it takes the raw 
output file created 
by \fBspice -r\fR
and plots the data on a graphics terminal or a workstation display.
Note that the raw output file is different from the
data that \s-2SPICE\s+2 writes to the standard output.
.PP
Arguments are:
.TP
\fB-\fR
Don't try to load the default data file ("rawspice") if no other files
are given.
.TP
\fB-n\fR (or \fB-N\fR)
Don't try to source the file ".spiceinit" upon startup. Normally \fBnutmeg\fR
tries to find the file in the current directory, and if it is not found then
in the user's home directory.
.TP
\fB-t term\fR (or \fB-T term\fR)
The program is being run on a terminal with \fImfb\fR name \fBterm\fR.
.PP
Further arguments are taken to be data files in binary or ascii format
(see \fBsconvert\fR(1)) which are loaded into nutmeg. If the file
is in binary format, it may be only partially completed (useful for
examining \s-2SPICE\s+2 ouput before the simulation is finished). One
file may contain any number of data sets from different analyses.
.PP
\fBNutmeg\fR
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
.B load
command below), and when the initial datafile is loaded. They can
also be created with the
.B let
command.
.PP
An expression 
is an algebraic
formula involving vectors and scalars (a scalar is a vector of
length 1), and the following operations:
.IP
+, -, *, %, /, ^, and ,.
.PP
% 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 \fBx , y\fR is
synonymous with \fBx + j(y)\fR.
.PP
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: 
\fB"gt"\fR is >,
\fB"lt"\fR is <, 
\fB"ge"\fR is >=,
\fB"le"\fR is <=,
\fB"ne"\fR is <>,
\fB"eq"\fR is =,
\fB"and"\fR is &,
\fB"or"\fR is |,
and
\fB"not"\fR is !.
These are useful when < and > might be confused with IO redirection
(which is almost always).
.PP
The following functions are available:
.IP
\fBmag(vector) \-\fR
The magnitude of vector.
.IP
\fBph(vector) \-\fR
The phase of vector.
.IP
\fBj(vector) \-\fR
\fIi\fR (sqrt(-1)) times vector.
.IP
\fBreal(vector) \-\fR
The real component of vector.
.IP
\fBimag(vector) \-\fR
The imaginary part of vector.
.IP
\fBdb(vector) \-\fR
20 * log10(mag(vector)).
.IP
\fBlog(vector) \-\fR
The logarithm (base 10) of the vector.
.IP
\fBln(vector) \-\fR
The natural logarithm (base e) of vector.
.IP
\fBexp(vector) \-\fR
e to the vector power.
.IP
\fBabs(vector) \-\fR
The absolute value of vector.
.IP
\fBsqrt(vector) \-\fR
The square root of vector.
.IP
\fBsin(vector) \-\fR
The sin of vector.
.IP
\fBcos(vector) \-\fR
The cosine of vector.
.IP
\fBtan(vector) \-\fR
The tangent of vector.
.IP
\fBatan(vector) \-\fR
The inverse tangent of vector.
.IP
\fBnorm(vector) \-\fR
The \fBvector\fR normalized to 1 (i.e, the largest magnitude of any component
will be 1).
.IP
\fBrnd(vector) \-\fR
A vector with each component a random integer between 0 and the absolute
value of the vectors's corresponding component.
.IP
\fBmean(vector) \-\fR
The result is a scalar (a length 1 vector) that is the mean of the elements
of \fBvector\fR.
.IP
\fBvector(number) \-\fR
The result is a vector of length \fBnumber\fR, with elements 0, 1, ... 
\fBnumber - 1\fR. If \fBnumber\fR 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.
.IP
\fBlength(vector) \-\fR
The length of \fBvector\fR.
.IP
\fBinterpolate(plot.vector) \-\fR
The result of interpolating the named vector onto the scale of the current
plot.  This function uses the variable \fBpolydegree\fR to determine
the degree of interpolation.
.PP
A vector may be either the name of a vector already defined, a floating-
point number (a scalar), or a list like \fB[elt1 elt2 ... eltn]\fR, which
is a vector of length n.
A number may be written in any format acceptable to \s-2SPICE\s+2, such
as \fB14.6MEG\fR or \fB-1.231E-4\fR. Note that you can either use
scientific notation or one of the abbreviations like \fIMEG\fR or \fIG\fR,
but not both.  As with \s-2SPICE\s+2, a number may have trailing 
alphabetic characters after it.
.PP
The notation \fBexpr [lower upper]\fR, where \fBlower\fR and \fBupper\fR
are numbers, denotes the range of elements from \fBexpr\fR between
\fBlower\fR and \fBupper\fR.  The notation \fBexpr [num]\fR denotes
the \fBnum\fR'th element of \fBexpr\fR.  If \fBupper\fR
is lower than \fBlower\fR, the order of the elements in the vector
is reversed.  In all other cases, \fB[\fR and \fB]\fR 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 \fBprint (foo) ([1 2])\fR to print the two vectors.
Otherwise it will be interpreted as a function call or a vector with an
index.)  Note that the expression \fBfoo[10 20][5]\fR will \fInot\fR 
yield the 15th element of \fBfoo\fR, but rather the 5th.  In general only
the last index suffix on an expression will take effect.
.PP
To reference vectors in a plot that is not the
\fIcurrent plot\fR (see the \fBsetplot\fR command, below), the
notation \fBplotname.vecname\fR can be used.
.PP
Either a plotname or a vector name may be the wildcard \fBall\fR.  If the
plotname is \fBall\fR, matching vectors from all plots are specified, and
if the vector name is \fBall\fR, 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 \fBall + all\fR should
denote, for instance.
.PP
Thus some (contrived) examples of expressions are:
.IP
\fBcos(TIME) + db(v(3))\fR
.IP
\fBsin(cos(log([1 2 3 4 5 6 7 8 9 10])))\fR
.IP
\fBTIME * rnd(v(9)) - 15 * cos(vin#branch) ^ [7.9e5 8]\fR
.IP
\fBnot ((ac3.FREQ[32] & tran1.TIME[10]) gt 3)\fR
.PP
.B Nutmeg
commands are as follows:
.TP
\fBplot exprs [ylimit ylo yhi] [xlimit xlo xhi] [xindices xilo xihi]\fR
.ce
\fB[xcompress comp] [xdelta xdel] [ydelta ydel] [xlog] [ylog] [vs xname]\fR
.ce
\fB[xlabel word] [ylabel word] [title word] [samep]\fR
Plot the given
.B exprs
on the screen (if you are on a graphics terminal). The
.B xlimit
and
.B ylimit
arguments determine the high and low x- and y-limits of the axes,
respectively. The
.B xindices
arguments determine what range of points are to be plotted \- everything
between the \fBxilo\fR'th point and the \fBxihi\fR'th point is plotted.
The
.B xcompress
argument specifies that only one out of every \fBcomp\fR points should
be plotted. If an \fBxdelta\fR or a \fBydelta\fR parameter is present,
it specifies the spacing between grid lines on the X- and Y-axis.
These parameter names may be abbreviated to
.B xl,
.B yl,
.B xind,
.B xcomp,
.B xdel,
and
.B ydel
respectively.
The
.B xname
argument is an expression to use as the scale on the x-axis. 
If \fBxlog\fR or \fBylog\fR are present, the X or Y scale respectively
will be logarithmic.
The \fBxlabel\fR and \fBylabel\fR arguments cause the specified
labels to be used for the X and Y axes, respectively.
If \fBsamep\fR is given, the values of the other parameters (other than
\fBxname\fR) from the previous \fBplot, hardcopy,\fR or \fBasciiplot\fR
command will be used unless re-defined on the command line.
Finally, the \fBtitle\fR argument will be used in the place of the plot
name at the bottom of the graph.
.TP
\fBhardcopy file \fIplotargs\fR
Just like \fBplot\fR, except creates a file called
.B file
containing the plot.  The file is an image in \fIplot(5)\fR format,
and can be printed by either the \fBplot(1)\fR program or \fBlpr\fR
with the \fB-g\fR flag.
.TP
\fBasciiplot \fIplotargs\fR
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 \fIasciiplot args ... > file\fR.
The \fBset\fR options \fBwidth, height,\fR and \fBnobreak\fR 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 \fBasciiplot\fR
something with an X-scale that isn't monotonic (i.e, something
like \fIsin(TIME)\fR ), because \fBasciiplot\fR uses a simple-minded sort
of linear interpolation.
.TP
\fBdefine function(arg1, arg2, ...) expression\fR
Define the \fIuser-definable function\fR with the name \fIfunction\fR
and arguments \fIarg1, arg2, ...\fR to be \fIexpression\fR, 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 \fIexpression\fR is not present, any definition for \fIfunction\fR
is printed, and if there are no arguments to \fIdefine\fR then all
currently active definitions are printed. Note that you may have different
functions defined with the same name but different arities.
Some useful definitions are:
.IP
define max(x,y) (x > y) * x + (x <= y) * y
.br
define min(x,y) (x < y) * x + (x >= y) * y
.TP
\fBundefine function ...\fR
Definitions for the named user-defined functions are deleted.
.TP
\fBlet name = expr\fR
Creates a new vector called
.B name
with the value specified by
.B expr,
an expression as described above. If \fBexpr\fR is [] (a zero-length vector)
then the vector becomes undefined.
If there are no arguments, \fBlet\fR is the same as \fBdisplay\fR.
.TP
\fBprint [col] [line] expr ... \fR
Prints the vector described by the expression
.B expr.
If the 
.B col
argument is present, print the vectors named side by side. If \fBline\fR
is given, the vectors are printed horizontally.  \fBcol\fR is the default,
unless all the vectors named have a length of one, in which case \fBline\fR
is the default.
The options
\fBwidth, length,\fR and \fBnobreak\fR are effective for this
command (see \fBasciiplot\fR). If the expression is \fBall\fR,
all of the vectors available are printed. Thus \fBprint col all > file\fR
will print everything in the file in \s-2SPICE\s+2\&2 format.
The scale vector (time, frequency) will always be in the first column
unless the variable \fBnoprintscale\fR is true.
.TP
\fBload [filename] ... \fR
Loads the raw data in either binary or ascii format
from the files named. The default filename is \fBrawspice\fR, or the argument
to the \fB-r\fR flag if there was one.
.TP
\fBsource filename\fR
Reads commands from the file
.B filename.
Lines beginning with the character \fB*\fR are considered comments and
ignored.
.TP
\fBhelp [all] [command ...]\fR
Prints help.  If the argument \fBall\fR is given, a short description
of everything you could possibly type is printed.  If \fBcommand\fRs are
given, descriptions of those commands are printed.  Otherwise help for
only a few major commands is printed.
.TP
\fBdisplay [varname ...]\fR
Prints a summary of currently defined vectors, or of the names specified.
The vectors are sorted by name unless the variable \fBnosort\fR 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 \fB[scale]\fR. When a command such as
\fIplot\fR is given without a \fIvs\fR 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 undefine the scale
(i.e, \fIlet TIME = []\fR), a random remaining
vector will become the scale.
.TP
\fBsetplot [plotname]\fR
Set the \fBcurrent plot\fR 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 \fBtran1\fR or \fBop2\fR. These names are shown by the
\fBsetplot\fR and \fBdisplay\fR commands and are used by \fBdiff\fR,
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 \s-2SPICE\s+2 run.
When
more than one file is loaded in, or more than one plot is present
in one file, \fBnutmeg\fR keeps them seperate and only shows you the
vectors in the current plot.
.TP
\fBsettype type vector ...\fR