ARM Club 1

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 1 / ARM_CLUB_CD.iso / contents / education / n / spice / docs / FTE / LPR / NUTMEG < prev next >

Wrap

Text File | 1988-01-27 | 27.4 KB | 859 lines

NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) NAME nutmeg - spice post-processor SYNOPSIS nutmeg [ - ] [ -n ] [ -t term ] [ -m mfbcap ] [ datafile ... ] DESCRIPTION Nutmeg is a post processor for SPICE - it takes the raw out- put file created by spice -r and plots the data on a graph- ics terminal. (For types supported, see mfb(3).) 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 -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 descrip- tions, 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 vari- able 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 simu- lation 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. Printed 12/9/85 20 January 1985 1 NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) An expression is an algebraic formula involving vectors and scalars (a scalar is a vector of length 1), and the follow- ing 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 rela- tional 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. Printed 12/9/85 20 January 1985 2 NUTMEG(1) UNIX Programmer's Manual NUTMEG(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 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 scien- tific 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 com- mand, 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. Printed 12/9/85 20 January 1985 3 NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) hardcopy device file plotargs Just like plot, except creates a file called file con- taining 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 interpo- lation. define function(arg1, arg2, ...) expression Define the user-definable function with the name func- tion 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 expres- sion 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 speci- fied 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 every- thing in the file in SPICE2 format. load filename ... Printed 12/9/85 20 January 1985 4 NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) 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 deter- mine 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.) Printed 12/9/85 20 January 1985 5 NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) 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 substitu- tions 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 com- mand. 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 dev- ice. 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.) Printed 12/9/85 20 January 1985 6 NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) dontplot No graphics control codes are actually sent. (Useful for debugging on non-graphics termi- nals.) echo Print out each command before it is exe- cuted. 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 Printed 12/9/85 20 January 1985 7 NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) Don't have display sort the variable names. polydegree The degree of the polynomial that the plot command should fit to the data. If polyde- gree is N, then nutmeg will fit a degree N polynomial to every set of N points and draw 10 intermediate points in between each end- point. 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 com- mand. 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. Printed 12/9/85 20 January 1985 8 NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) units If this is degrees, then all the trig func- tions 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 Printed 12/9/85 20 January 1985 9 NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) 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 com- mand will only work if your system adminis- trator is running a SPICE-3 daemon on the remote host. If the variable rprogram is set, then rspice will use this as the path- name 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 run- ning. 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). Printed 12/9/85 20 January 1985 10 NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) 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 substitu- tion may be used. Within single quotes, no further substitu- tion (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 substitu- tions, 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 expan- sion. 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 char- acters except a, b, and c. Printed 12/9/85 20 January 1985 11 NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) IO redirection is available - the symbols >, >>, >&, >>&, and < have the same effects as in the C-shell. VMS NOTES Nutmeg can be run under VAX/VMS. Some features like command, etc completion, expansion of *, ?, and [], backquote substi- tution, the shell command, and so forth do not work. (In fact command completion only works on 4.2 or 4.3 BSD.) 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 sconvert(1), spice(1), mfb(3), spop(1), mfb2lpr(1), mhc(3) AUTHOR Wayne Christopher (faustus@cad.berkeley.edu) 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 data- base 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. Printed 12/9/85 20 January 1985 12 NUTMEG(1) UNIX Programmer's Manual NUTMEG(1) 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 Often the names of terminals recognised by MFB are different from those in /etc/termcap. Thus you may have to reset your terminal type with the command set term = termname where termname is the name in the mfbcap file. Printed 12/9/85 20 January 1985 13