NUTMEG

NAME

SYNOPSIS

DESCRIPTION

Arguments are:

-

Don't try to load the default data file ("rawspice") if no other files are given.

-n (or -N)

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 -T term)

The program is being run on a terminal with mfb name term.

-m mfbcap (or -M mfbcap)

Use mfbcap as the file containing terminal descriptions, instead of the default (~cad/lib/mfbcap). This option and the -m option may also be used with the set command (see below). Note that is the environment variable MFBCAP is set then it becomes the default mfbcap file, instead of ~cad/lib/mfbcap.

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

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 1, 2, ... number. 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.

A vector may be either the name of a vector already defined, a floating- 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. Unlike SPICE, a number may not have trailing characters after it. Additionally, the notation vec[number] denotes the number'th element of vec. To reference vectors in a plot that is not the current plot (see the setplot command, below), the notation plotname.vecname can be used.

Thus some examples of expressions are:

cos(TIME) + db(t1)

sin(cos(log([1 2 3 4 5 6 7 8 9 10])))

TIME * rnd(cap5) - 15 * cos(res3) ^ [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] [vs xname]
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. These parameter names may be abbreviated to xl, yl, xind, and xcomp. The xname argument is an expression to use as the scale on the x-axis.

hardcopy device file plotargs

Just like plot, except creates a file called file containing the plot. (This is currently unimplemented.)

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 asciiplot 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 asciiplot 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 function 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 different 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.

print [col] expr ...

Prints the vector described by the expression expr. If the col argument is present, print the vectors named side by side. 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.

load filename ...

Loads the raw data in either binary or ascii format from the files named.

source filename

Reads commands from the file filename. Lines beginning with the character * are considered comments and ignored.

help [command ...]

Prints help, either on the specified commands or for all commands available.

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

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. The plot name and title will be that associated with the first expression given. The default format is ascii, but this can be changed with the set filetype command.

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

set [word] [word = value] ...

Set the value of word to be value, if it is present. The variables meaningful to nutmeg are:

abstol
The absolute tolerance used by the diff command.

combplot
Plot vectors by drawing a vertical line from each point to the X-axis, as opposed to joining the points.

cpdebug
Print cshpar debugging information. (Must be complied with the -DCPDEBUG flag.)

debug
If set then a lot of debugging information is printed. (Must be compiled with the -DFTEDEBUG flag.)

device
The name (/dev/tty??) of the graphics device. If this variable isn't set then the user's terminal is used. To do plotting on another monitor you will probably have to set both the device and term variables. (If device is set to the name of a file, nutmeg will dump the graphics control codes into this file -- this is useful for saving plots.)

dontplot
No graphics control codes are actually sent. (Useful for debugging on non-graphics terminals.)

echo
Print out each command before it is executed.

filetype
This can be either ascii or binary, and determines what the format of rawfiles will be. The default is ascii.

height
The length of the page for asciiplot and print col.

history
The number of events to save in the history list.

mfbcap
The mfbcap to use instead of the standard one (see mfb(3)).

nfreqs
The number of frequencies to compute in the fourier command. (Defaults to 10.)

nobreak
Don't have asciiplot and print col break between pages.

noclobber
Don't overwrite existing files when doing IO redirection.

noglob
Don't expand the global characters `*', `?', `[', and `]'. This is the default.

nogrid
Don't plot a grid when graphing curves (but do label the axes).

nonomatch
If noglob is unset and a global expression cannot be matched, use the global characters literally instead of complaining.

nosort
Don't have display sort the variable names.

polydegree
The degree of the polynomial that the plot command should fit to the data. If polydegree is N, then nutmeg will fit a degree N polynomial to every set of N points and draw 10 intermediate points in between each endpoint. If the points aren't monotonic, then it will try rotating the curve and reducing the degree until a fit is achieved.

polysteps
The number of points to interpolate between every pair of points available when doing curve fitting. The default is 10. (This should really be done automatically.)

program
The name of the current program (argv[0]).

prompt
The prompt, with the character `!' replaced by the current event number.

rawfile
The default name for rawfiles created.

reltol
The relative tolerance used by the diff command.

rhost
The machine to use for remote SPICE-3 runs, instead of the default one. (See the description of the rspice command, below.)

rprogram
The name of the remote program to use in the rspice command.

slowplot
Stop between each graph plotted and wait for the user to type return before continuing.

spicepath
The program to use for the aspice command. The default is /cad/bin/spice.

term
The mfb name of the current terminal.

units
If this is degrees, then all the trig functions will use degrees instead of radians.

unixcom
If a command isn't defined, try to execute it as a UNIX command. Setting this option has the effect of giving a rehash command, below. This is useful for people who want to use nutmeg as a login shell.

verbose
Be verbose. This is midway between echo and debug / cpdebug.

vntol
The absolute voltage tolerance used by the diff command.

width
The width of the page for asciiplot and print col.

unset [word] ...

Unset the variables word.

rusage [resource ...]

Print resource usage statistics. If any resources are given, just print the usage of that resource. Currently valid resources are:

elapsed
The amount of time elapsed since the last rusage elaped call.

faults
Number of page faults and context switches (BSD only).

space
Data space used.

time
CPU time used so far.

cd [directory]

Change the current working directory to directory, or to the user's home directory if none is given.

aspice [output-file]

Start a SPICE-3 run, and when it is finished load the data. The raw data is kept in a temporary file. If output-file is specified then the diagnostic output is directed into that file, otherwise it is thrown away.

jobs

Report on the asynchronous SPICE-3 jobs currently running. Nutmeg checks to see if the jobs are finished every time you execute a command. If it is done then the data is loaded and becomes available.

rspice [input file]

Runs a SPICE-3 remotely taking the input file as a SPICE-3 input deck, or the current circuit if no argument is given. Nutmeg waits for the job to complete, and passes output from the remote job to the user's standard output. When the job is finished the data is loaded in as with aspice. If the variable rhost is set, nutmeg will connect to this host instead of the default remote SPICE-3 server machine. Note that this command will only work if your system administrator is running a SPICE-3 daemon on the remote host. If the variable rprogram is set, then rspice will use this as the pathname to the program to run.

echo [stuff...]

Echos the arguments.

fourier fundamental_frequency [value ...]

Does a fourier analysis of each of the given values, using the first 10 multiples of the fundamental frequency (or the first nfreqs, if that variable is set - see below). The output is like that of the .four card. The values may be any valid expression.

version [version id]

Print out the version of nutmeg that is running. If there are arguments, it checks to make sure that the arguments match the current version of SPICE. (This is mainly used as a Command: line in rawfiles.)

rehash

Recalculate the internal hash tables used when looking up UNIX commands, and make all UNIX commands in the user's PATH available for command completion. This is useless unless you have set unixcom first (see above).

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

        pi              pi
        e               The base of natural logarithms
        c               The speed of light
        i               The square root of -1
        kelvin          Absolute 0 in Centigrade
        echarge         The charge on an electron
        boltz           Boltzman's constant
        planck          Planck's constant (h)

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

Nutmeg occasionally checks to see if it is getting close to running out of space, and warns the user if this is the case. (This is more likely to be useful with the SPICE front end.)

C-shell type quoting with "" and '', and backquote substitution may be used. Within single quotes, no further substitution (like history substitution) is done, and within double quotes, the words are kept together but further substitution is done. Any text between backquotes is replaced by the result of executing the text as a command to the shell.

Tenex-style ('set filec' in the 4.3 C-shell) command, filename, and keyword completion is possible: If EOF (control-D) is typed after the first character on the line, a list of the commands or possible arguments is printed. (If it is alone on the line it will exit nutmeg.) If escape is typed, then nutmeg will try to complete what the user has already typed. To get a list of all commands, the user should type <space> ^D.

The values of variables may be used in commands by writing $varname where the value of the variable is to appear.

History substitutions, similar to C-shell history substitutions, are also available - see the C-shell manual page for all of the details.

The characters ~, {, and } have the same effects as they do in the C-Shell, i.e., home directory and alternative expansion. It is possible to use the wildcard characters *, ?, [, and ] also, but only if you unset noglob first. This makes them rather useless for typing algebraic expressions, so you should set noglob again after you are done with wildcard expansion. Note that the pattern [^abc] will match all characters except a, b, and c.

IO redirection is available - the symbols >, >>, >&, >>&, and < have the same effects as in the C-shell.  

VMS NOTES

Nutmeg will look for start-up commands in the file spice.rc in the current directory.

The standard suffix for rawspice files in VMS is ".raw".

You will have to respond to the -more- prompt during plot with a carriage return instead of any key as you can do on UNIX.  

SEE ALSO

AUTHOR

BUGS

When something is plotted on log scales, the numbering on the scales is not in the original units and the grid lines are linearly spaced.

Hitting ^C at the wrong times can sometimes cause the database to get mangled.

When defining aliases like

alias pdb plot db( '!:1' - '!:2' )

you must be careful to quote the argument list substitutions in this manner. If you quote the whole argument it might not work properly.

Lists written as [ ... ] cannot be longer than 128 elements.

History (and aliases that use history symbols) doesn't work properly.

The hardcopy command doesn't work (and probably won't at least until nutmeg is converted to use X).

An expression like v(5)[1] won't work - the [] notation only works when there are no ()'s in the name. Enclosing the name with double quotes ("v(5)[1]") will work, however.

In commands like plot, all vectors mentioned must be in the same plot. Otherwise strange things may happen.

There are probably some features that nutmeg doesn't have yet.  

CAVEATS

set term = termname

where termname is the name in the mfbcap file.

Index

NAME

SYNOPSIS

DESCRIPTION

VMS NOTES

SEE ALSO

AUTHOR

BUGS

CAVEATS