1NUTMEG(1)                   General Commands Manual                  NUTMEG(1)
2
3
4

NAME

6       nutmeg - spice post-processor
7

SYNOPSIS

9       nutmeg [ - ] [ -n ] [ -t term ] [ datafile ... ]
10

DESCRIPTION

12       Nutmeg  is  a  post  processor for SPICE - it takes the raw output file
13       created by spice -r and plots the data on  a  graphics  terminal  or  a
14       workstation  display.   Note that the raw output file is different from
15       the data that SPICE writes to the standard output.
16
17       Arguments are:
18
19       -      Don't try to load the default data file ("rawspice") if no other
20              files are given.
21
22       -n (or --no-spiceinit)
23              Don't try to source the file ".spiceinit" upon startup. Normally
24              nutmeg tries to find the file in the current directory,  and  if
25              it is not found then in the user's home directory.
26
27       -t term (or --term=term)
28              The program is being run on a terminal with mfb name term.
29
30       -h (or --help)
31              Display  a  verbose  help on the arguments available to the pro‐
32              gram.
33
34       -v (or --version)
35              Display a version number and copyright information of  the  pro‐
36              gram.
37
38       Further  arguments are taken to be data files in binary or ascii format
39       (see sconvert(1)) which are loaded into  nutmeg.  If  the  file  is  in
40       binary format, it may be only partially completed (useful for examining
41       SPICE ouput before the simulation is finished). One  file  may  contain
42       any number of data sets from different analyses.
43
44       Nutmeg  data is in the form of vectors: time, voltage, etc. Each vector
45       has a type, and vectors can be operated on and combined algebraicly  in
46       ways  consistent  with their types. Vectors are normally created when a
47       data file is read in (see the load command below), and when the initial
48       datafile is loaded. They can also be created with the let command.
49
50       An  expression is an algebraic formula involving vectors and scalars (a
51       scalar is a vector of length 1), and the following operations:
52
53              +, -, *, %, /, ^, and ,.
54
55       % is the modulo operator, and the comma operator has two  meanings:  if
56       it  is  present  in  the argument list of a user-definable function, it
57       serves to seperate the arguments. Otherwise, the term x , y is  synony‐
58       mous with x + j(y).
59
60       Also available are the logical operations & (and), | (or), ! (not), and
61       the relational operations <, >, >=, <=, =, and <> (not equal).  If used
62       in  an  algebraic  expression they work like they would in C, producing
63       values of 0 or 1.  The relational operators  have  the  following  syn‐
64       onyms:  "gt"  is >, "lt" is <, "ge" is >=, "le" is <=, "ne" is <>, "eq"
65       is =, "and" is &, "or" is |, and "not" is !.  These are useful  when  <
66       and > might be confused with IO redirection (which is almost always).
67
68       The following functions are available:
69
70              mag(vector) - The magnitude of vector.
71
72              ph(vector) - The phase of vector.
73
74              j(vector) - i (sqrt(-1)) times vector.
75
76              real(vector) - The real component of vector.
77
78              imag(vector) - The imaginary part of vector.
79
80              db(vector) - 20 * log10(mag(vector)).
81
82              log(vector) - The logarithm (base 10) of the vector.
83
84              ln(vector) - The natural logarithm (base e) of vector.
85
86              exp(vector) - e to the vector power.
87
88              abs(vector) - The absolute value of vector.
89
90              sqrt(vector) - The square root of vector.
91
92              sin(vector) - The sin of vector.
93
94              cos(vector) - The cosine of vector.
95
96              tan(vector) - The tangent of vector.
97
98              atan(vector) - The inverse tangent of vector.
99
100              norm(vector) - The vector normalized to 1 (i.e, the largest mag‐
101              nitude of any component will be 1).
102
103              rnd(vector) - A vector with  each  component  a  random  integer
104              between  0 and the absolute value of the vectors's corresponding
105              component.
106
107              mean(vector) - The result is a scalar (a length 1  vector)  that
108              is the mean of the elements of vector.
109
110              vector(number)  -  The result is a vector of length number, with
111              elements 0, 1, ...  number - 1. If number is a vector then  just
112              the  first element is taken, and if it isn't an integer then the
113              floor of the magnitude is used.
114
115              length(vector) - The length of vector.
116
117              interpolate(plot.vector) - The result of interpolating the named
118              vector  onto  the scale of the current plot.  This function uses
119              the variable polydegree to determine the  degree  of  interpola‐
120              tion.
121
122       A  vector  may be either the name of a vector already defined, a float‐
123       ing- point number (a scalar), or a list  like  [elt1  elt2  ...  eltn],
124       which  is  a vector of length n.  A number may be written in any format
125       acceptable to SPICE, such as 14.6MEG or -1.231E-4. Note  that  you  can
126       either  use scientific notation or one of the abbreviations like MEG or
127       G, but not both.  As with SPICE, a number may have trailing  alphabetic
128       characters after it.
129
130       The  notation  expr  [lower  upper], where lower and upper are numbers,
131       denotes the range of elements from expr between lower and  upper.   The
132       notation  expr  [num]  denotes the num'th element of expr.  If upper is
133       lower than lower, the order of the elements in the vector is  reversed.
134       In  all  other  cases,  [  and  ]  serve to surround literal vectors as
135       described above.  (You may have to use a lot  of  parentheses  to  make
136       sure  that you get what you want.  For instance, you have to type print
137       (foo) ([1 2]) to print the two vectors.  Otherwise it  will  be  inter‐
138       preted  as  a  function call or a vector with an index.)  Note that the
139       expression foo[10 20][5] will not yield the 15th element  of  foo,  but
140       rather the 5th.  In general only the last index suffix on an expression
141       will take effect.
142
143       To reference vectors in a plot that is not the current  plot  (see  the
144       setplot command, below), the notation plotname.vecname can be used.
145
146       Either  a  plotname  or  a vector name may be the wildcard all.  If the
147       plotname is all, matching vectors from all plots are specified, and  if
148       the  vector  name is all, all vectors in the specified plots are refer‐
149       enced.  Note that you may not  use  binary  operations  on  expressions
150       involving  wildcards  - it is not obvious what all + all should denote,
151       for instance.
152
153       Thus some (contrived) examples of expressions are:
154
155              cos(TIME) + db(v(3))
156
157              sin(cos(log([1 2 3 4 5 6 7 8 9 10])))
158
159              TIME * rnd(v(9)) - 15 * cos(vin#branch) ^ [7.9e5 8]
160
161              not ((ac3.FREQ[32] & tran1.TIME[10]) gt 3)
162
163       Nutmeg commands are as follows:
164
165       plot exprs [ylimit ylo yhi] [xlimit xlo xhi] [xindices xilo xihi]
166              [xcompress comp] [xdelta xdel] [ydelta ydel] [xlog] [ylog] [vs xname]
167                      [xlabel word] [ylabel word] [title word] [samep]
168              Plot the given exprs on the screen (if you  are  on  a  graphics
169              terminal).  The  xlimit  and ylimit arguments determine the high
170              and low x- and y-limits of the axes, respectively. The  xindices
171              arguments  determine  what  range  of points are to be plotted -
172              everything between the xilo'th point and the  xihi'th  point  is
173              plotted.   The xcompress argument specifies that only one out of
174              every comp points should be plotted. If an xdelta  or  a  ydelta
175              parameter  is  present,  it  specifies  the spacing between grid
176              lines on the X- and Y-axis.  These parameter names may be abbre‐
177              viated to xl, yl, xind, xcomp, xdel, and ydel respectively.  The
178              xname argument is an expression to use as the scale  on  the  x-
179              axis.   If  xlog  or  ylog are present, the X or Y scale respec‐
180              tively will be logarithmic.  The  xlabel  and  ylabel  arguments
181              cause  the  specified  labels  to  be used for the X and Y axes,
182              respectively.  If samep is given, the values of the other param‐
183              eters  (other  than  xname) from the previous plot, hardcopy, or
184              asciiplot command will be used unless re-defined on the  command
185              line.   Finally, the title argument will be used in the place of
186              the plot name at the bottom of the graph.
187
188       hardcopy file plotargs
189              Just like plot, except creates a file called file containing the
190              plot.   The  file  is  an  image  in  plot(5) format, and can be
191              printed by either the plot(1) program or lpr with the -g flag.
192
193       asciiplot plotargs
194              Produce a line printer plot of the vectors.  The plot is sent to
195              the  standard  output,  so you can put it into a file with asci‐
196              iplot args ... > file.   The  set  options  width,  height,  and
197              nobreak  determine the width and height of the plot, and whether
198              there are page breaks, respectively. Note  that  you  will  have
199              problems  if you try to asciiplot something with an X-scale that
200              isn't monotonic (i.e, something like sin(TIME) ), because  asci‐
201              iplot uses a simple-minded sort of linear interpolation.
202
203       define function(arg1, arg2, ...) expression
204              Define  the  user-definable  function with the name function and
205              arguments arg1, arg2, ... to be expression,  which  may  involve
206              the arguments. When the function is later used, the arguments it
207              is given are substituted for the formal  arguments  when  it  is
208              parsed.   If expression is not present, any definition for func‐
209              tion is printed, and if there are no arguments  to  define  then
210              all  currently active definitions are printed. Note that you may
211              have different functions defined with the same name but  differ‐
212              ent arities.  Some useful definitions are:
213
214              define max(x,y) (x > y) * x + (x <= y) * y
215              define min(x,y) (x < y) * x + (x >= y) * y
216
217       undefine function ...
218              Definitions for the named user-defined functions are deleted.
219
220       let name = expr
221              Creates  a  new  vector  called name with the value specified by
222              expr, an expression as described above. If expr is []  (a  zero-
223              length  vector) then the vector becomes undefined.  If there are
224              no arguments, let is the same as display.
225
226       print [col] [line] expr ...
227              Prints the vector described by the expression expr.  If the  col
228              argument  is  present,  print the vectors named side by side. If
229              line is given, the vectors are printed horizontally.  col is the
230              default,  unless  all the vectors named have a length of one, in
231              which case line is the default.  The options width, length,  and
232              nobreak  are  effective for this command (see asciiplot). If the
233              expression is all, all of the  vectors  available  are  printed.
234              Thus  print  col all > file will print everything in the file in
235              SPICE2 format.  The scale vector (time, frequency)  will  always
236              be in the first column unless the variable noprintscale is true.
237
238       load [filename] ...
239              Loads  the  raw  data  in either binary or ascii format from the
240              files named. The default filename is rawspice, or  the  argument
241              to the -r flag if there was one.
242
243       source filename
244              Reads commands from the file filename.  Lines beginning with the
245              character * are considered comments and ignored.
246
247       help [all] [command ...]
248              Prints help.  If the argument all is given, a short  description
249              of  everything  you could possibly type is printed.  If commands
250              are given, descriptions of those commands are  printed.   Other‐
251              wise help for only a few major commands is printed.
252
253       display [varname ...]
254              Prints  a  summary of currently defined vectors, or of the names
255              specified.  The vectors are sorted by name unless  the  variable
256              nosort is set.  The information given is the name of the vector,
257              the length, the type of the vector, and whether it  is  real  or
258              complex  data. Additionally, one vector will be labeled [scale].
259              When a command such as plot is given without a vs argument, this
260              scale is used for the X-axis. It is always the first vector in a
261              rawfile, or the first vector defined in a new plot. If you unde‐
262              fine  the  scale (i.e, let TIME = []), a random remaining vector
263              will become the scale.
264
265       setplot [plotname]
266              Set the current plot to the plot with the given name, or  if  no
267              name  is  given,  prompt  the  user with a menu.  (Note that the
268              plots are named as they are loaded, with  names  like  tran1  or
269              op2.  These  names are shown by the setplot and display commands
270              and are used by  diff,  below.)   If  the  "New  plot"  item  is
271              selected,  the  current  plot  will  become  one with no vectors
272              defined.  Note that here the word "plot" refers to  a  group  of
273              vectors  that  are  the result of one SPICE run.  When more than
274              one file is loaded in, or more than one plot is present  in  one
275              file,  nutmeg keeps them seperate and only shows you the vectors
276              in the current plot.
277
278       settype type vector ...
279              Change the type of the named vectors to type.  Type names can be
280              found in the manual page for sconvert.
281
282       diff plot1 plot2 [vec ...]
283              Compare  all  the  vectors  in  the specified plots, or only the
284              named vectors if any are given. There are different  vectors  in
285              the two plots, or any values in the vectors differ significantly
286              the difference is reported. The variables  abstol,  reltol,  and
287              vntol  are used to determine what "significantly" means (see the
288              SPICE3 User's Manual).
289
290       quit   Quit nutmeg.
291
292       bug    Send a bug report. (If you have defined BUGADDR, the  mail  will
293              go there.)
294
295       write [file] [exprs]
296              Writes  out  the  expr's  to  file.   First  vectors are grouped
297              together by plots, and  written  out  as  such.   (I.e,  if  the
298              expression  list  contained  three vectors from one plot and two
299              from another, then two plots will be  written,  one  with  three
300              vectors  and  one  with  two.)  Additionally, if the scale for a
301              vector isn't present, it is automatically written out  as  well.
302              The  default  format  is ascii, but this can be changed with the
303              set filetype command.  The default filename is rawspice, or  the
304              argument  to  the -r flag on the command line, if there was one,
305              and the default expression list is all.
306
307       shell [args ...]
308              Fork a shell, or execute the  arguments  as  a  command  to  the
309              shell.
310
311       alias [word] [text ...]
312              Causes word to be aliased to text.  History substitutions may be
313              used, as in C-shell aliases.
314
315       unalias [word ...]
316              Removes any aliases present for the words.
317
318       history [number]
319              Print out the history, or the last number commands typed at  the
320              keyboard.   Note:  in   version  3a7  and  earlier, all commands
321              (including ones read from files) were saved.
322
323       set [word] [word = value] ...
324              Set the value of word to be value, if it is  present.   You  can
325              set any word to be any value, numeric or string.  If no value is
326              given then the value is the boolean 'true'.   The value of  word
327              may  be inserted into a command by writing $word.  If a variable
328              is set to a list of values  that  are  enclosed  in  parentheses
329              (which  must be seperated from their values by white space), the
330              value of the variable is the list.  The variables meaningful  to
331              nutmeg (of which there are too many) are:
332
333                       abstol
334                       The absolute tolerance used by the diff command.
335
336                       appendwrite
337                       Append  to  the file when a write command is issued, if
338                       one already exists.
339
340                       colorN
341                       These variables determine the  colors  used,  if  X  is
342                       being  run  on a color display.  N may be between 0 and
343                       15.  Color 0 is the background, color 1 is the grid and
344                       text  color,  and colors 2 through 15 are used in order
345                       for vectors plotted.  The value of the color  variables
346                       should  be  names  of colors, which may be found in the
347                       file /usr/lib/rgb.txt.
348
349                       combplot
350                       Plot vectors by drawing a vertical line from each point
351                       to  the X-axis, as opposed to joining the points.  Note
352                       that this option is subsumed in  the  plottype  option,
353                       below.
354
355                       cpdebug
356                       Print  cshpar  debugging information. (Must be complied
357                       with the -DCPDEBUG flag.)
358
359                       debug
360                       If set then a lot of debugging information is  printed.
361                       (Must be compiled with the -DFTEDEBUG flag.)
362
363                       device
364                       The  name  (/dev/tty??) of the graphics device. If this
365                       variable isn't set then the user's terminal is used. To
366                       do  plotting  on another monitor you will probably have
367                       to set both the device and term variables.  (If  device
368                       is  set  to  the  name  of a file, nutmeg will dump the
369                       graphics control codes into this file -- this is useful
370                       for saving plots.)
371
372                       echo
373                       Print out each command before it is executed.
374
375                       filetype
376                       This can be either ascii or binary, and determines what
377                       the format of rawfiles will be. The default is ascii.
378
379                       fourgridsize
380                       How many points to  use  for  interpolating  into  when
381                       doing fourier analysis.
382
383                       gridsize
384                       If this variable is set to an integer, this number will
385                       be used as the number of equally spaced points  to  use
386                       for  the  Y-axis  when plotting.  Otherwise the current
387                       scale will be used (which may not have  equally  spaced
388                       points).   If  the  current  scale isn't strictly mono‐
389                       tonic, then this option will have no effect.
390
391                       hcopydev
392                       If this is set, when the hardcopy command  is  run  the
393                       resulting  file is automatically printed on the printer
394                       named hcopydev with the command lpr -Phcopydev -g file.
395
396                       hcopydevtype
397                       This variable specifies the type of the printer  output
398                       to use in the hardcopy command.  If hcopydevtype is not
399                       set, plot (5) format is assumed.  The standard  distri‐
400                       bution  currently  recognizes postscript as an alterna‐
401                       tive output format.   When  used  in  conjunction  with
402                       hcopydev,  hcopydevtype  should  specify  a format sup‐
403                       ported by the printer.
404
405                       height
406                       The length of the page for asciiplot and print col.
407
408                       history
409                       The number of events to save in the history list.
410
411                       nfreqs
412                       The number of frequencies to  compute  in  the  fourier
413                       command. (Defaults to 10.)
414
415                       nobreak
416                       Don't have asciiplot and print col break between pages.
417
418                       noasciiplotvalue
419                       Don't  print  the first vector plotted to the left when
420                       doing an asciiplot.
421
422                       noclobber
423                       Don't overwrite existing files when doing IO  redirect‐
424                       ion.
425
426                       noglob
427                       Don't  expand  the global characters `*', `?', `[', and
428                       `]'. This is the default.
429
430                       nogrid
431                       Don't plot a grid when graphing curves  (but  do  label
432                       the axes).
433
434                       nomoremode
435                       If  nomoremode  is  not set, whenever a large amount of
436                       data is being printed to the screen (e.g, the print  or
437                       asciiplot  commands),  the output will be stopped every
438                       screenful and will continue when a carriage  return  is
439                       typed.  If  nomoremode is set then data will scroll off
440                       the screen without hesitation.
441
442                       nonomatch
443                       If noglob is unset and a global  expression  cannot  be
444                       matched, use the global characters literally instead of
445                       complaining.
446
447                       nosort
448                       Don't have display sort the variable names.
449
450                       noprintscale
451                       Don't print the scale in the  leftmost  column  when  a
452                       print col command is given.
453
454                       numdgt
455                       The  number  of digits to print when printing tables of
456                       data (fourier, print col).  The default precision is  6
457                       digits.   On  the  VAX, approximately 16 decimal digits
458                       are available using double precision, so numdgt  should
459                       not  be  more  than 16.  If the number is negative, one
460                       fewer digit is printed to  ensure  constant  widths  in
461                       tables.
462
463                       plottype
464                       This  should  be  one  of normal, comb, or point:chars.
465                       normal, the  default, causes points to  be  plotted  as
466                       parts  of  connected lines.  comb causes a comb plot to
467                       be done (see the description of the  combplot  variable
468                       above).   point  causes each point to be plotted seper‐
469                       ately - the chars are a list of characters that will be
470                       used for each vector plotted.  If they are omitted then
471                       a default set is used.
472
473                       polydegree
474                       The degree of the  polynomial  that  the  plot  command
475                       should fit to the data. If polydegree is N, then nutmeg
476                       will fit a degree N polynomial to every set of N points
477                       and  draw  10  intermediate points in between each end‐
478                       point. If the points aren't monotonic, then it will try
479                       rotating  the curve and reducing the degree until a fit
480                       is achieved.
481
482                       polysteps
483                       The number of points to interpolate between every  pair
484                       of  points  available  when  doing  curve  fitting. The
485                       default is 10. (This should really  be  done  automati‐
486                       cally.)
487
488                       program
489                       The name of the current program (argv[0]).
490
491                       prompt
492                       The prompt, with the character `!' replaced by the cur‐
493                       rent event number.
494
495                       rawfile
496                       The default name for rawfiles created.
497
498                       reltol
499                       The relative tolerance used by the diff command.
500
501                       rhost
502                       The machine to use for remote SPICE-3 runs, instead  of
503                       the  default  one.  (See  the description of the rspice
504                       command, below.)
505
506                       rprogram
507                       The name of the remote program to  use  in  the  rspice
508                       command.
509
510                       slowplot
511                       Stop  between  each graph plotted and wait for the user
512                       to type return before continuing.
513
514                       sourcepath
515                       A list of the directories to search when a source  com‐
516                       mand  is  given.   The default is the current directory
517                       and the standard spice  library  (/usr/local/lib/spice,
518                       or whatever LIBPATH is #defined to in the  source.
519
520                       spicepath
521                       The  program to use for the aspice command. The default
522                       is /cad/bin/spice.
523
524                       term
525                       The mfb name of the current terminal.
526
527                       units
528                       If this is degrees, then all the  trig  functions  will
529                       use degrees instead of radians.
530
531                       unixcom
532                       If a command isn't defined, try to execute it as a UNIX
533                       command.  Setting this option has the effect of  giving
534                       a rehash command, below.  This is useful for people who
535                       want to use nutmeg as a login shell.
536
537                       verbose
538                       Be verbose. This is midway between  echo  and  debug  /
539                       cpdebug.
540
541                       vntol
542                       The  absolute  voltage  tolerance used by the diff com‐
543                       mand.
544
545                       width
546                       The width of the page for asciiplot and print col.
547
548                       xbrushheight
549                       The height of the brush to use if X is being run.
550
551                       xbrushwidth
552                       The width of the brush to use if X is being run.
553
554                       xfont
555                       The name of the X font to use when  plotting  data  and
556                       entering  labels.  The plot may not look entirely great
557                       if this is a variable-width font.
558
559       unset [word] ...
560              Unset the variables word.
561
562       shift [varname] [number]
563              If varname is the name of a list variable, it is shifted to  the
564              left  by number elements. (I.e, the number leftmost elements are
565              removed.)  The default varname is argv, and the  default  number
566              is 1.
567
568       rusage [resource ...]
569              Print  resource  usage  statistics.  If any resources are given,
570              just  print  the  usage  of  that  resource.   Currently   valid
571              resources are:
572
573                       elapsed
574                       The amount of time elapsed since the last rusage elaped
575                       call.
576
577                       faults
578                       Number of page faults and context switches (BSD only).
579
580                       space
581                       Data space used.
582
583                       time
584                       CPU time used so far.
585
586                       everything
587                       All of the above.
588
589       cd [directory]  Change the current working directory to  directory,  or
590                       to the user's home directory if none is given.
591
592       aspice [output-file]
593                       Start  a  SPICE-3 run, and when it is finished load the
594                       data. The raw data is kept in a temporary file. If out‐
595                       put-file  is  specified  then  the diagnostic output is
596                       directed into that file, otherwise it is thrown away.
597
598       jobs            Report on the asynchronous SPICE-3 jobs currently  run‐
599                       ning.   Nutmeg  checks  to see if the jobs are finished
600                       every time you execute a command.  If it is  done  then
601                       the data is loaded and becomes available.
602
603       rspice [input file]
604                       Runs  a  SPICE-3  remotely  taking  the input file as a
605                       SPICE-3 input deck, or the current circuit if no  argu‐
606                       ment  is  given.  Nutmeg waits for the job to complete,
607                       and passes output from the remote  job  to  the  user's
608                       standard  output.  When the job is finished the data is
609                       loaded in as with aspice. If the variable rhost is set,
610                       nutmeg will connect to this host instead of the default
611                       remote SPICE-3 server machine. Note that  this  command
612                       will  only work if your system administrator is running
613                       a SPICE-3 daemon on the remote host.  If  the  variable
614                       rprogram is set, then rspice will use this as the path‐
615                       name to the program to run.
616
617       echo [stuff...] Echos the arguments.
618
619       fourier fundamental_frequency [value ...]
620                       Does a fourier analysis of each of  the  given  values,
621                       using  the  first  10 multiples of the fundamental fre‐
622                       quency (or the first nfreqs, if that variable is set  -
623                       see below). The output is like that of the .four  card.
624                       The values may be any valid expression.  The values are
625                       interpolated onto a fixed-space grid with the number of
626                       points given by the fourgridsize variable, or 200 if it
627                       is  not set.  The interpolation will be of degree poly‐
628                       degree if that variable is set, or 1.  If polydegree is
629                       0,  then no interpolation will be done.  This is likely
630                       to give erroneous results if  the  time  scale  is  not
631                       monotonic, though.
632
633       version [version id]
634                       Print  out  the  version of nutmeg that is running.  If
635                       there are arguments, it checks to make  sure  that  the
636                       arguments  match the current version of SPICE. (This is
637                       mainly used as a Command: line in rawfiles.)
638
639       rehash          Recalculate the internal hash tables used when  looking
640                       up  UNIX  commands,  and  make all UNIX commands in the
641                       user's PATH available for command completion.  This  is
642                       useless unless you have set unixcom first (see above).
643
644       The following control structures are available:
645
646              while condition
647                   statement
648                   ...
649              end
650
651       While  condition,  an  arbitrary algebraic expression, is true, execute
652       the statements.
653
654              repeat [number]
655                   statement
656                   ...
657              end
658
659       Execute the statements number times,  or  forever  if  no  argument  is
660       given.
661
662              dowhile condition
663                   statement
664                   ...
665              end
666
667       The same as while, except that the condition is tested after the state‐
668       ments are executed.
669
670              foreach var value ...
671                   statement
672                   ...
673              end
674
675       The statements are executed once for each of the values, each time with
676       the  variable  var set to the current one.  (var can be accessed by the
677       $var notation - see below).
678
679              if condition
680                   statement
681                   ...
682              else
683                   statement
684                   ...
685              end
686
687       If the condition is non-zero then the first set of statements are  exe‐
688       cuted, otherwise the second set.  The else and the second set of state‐
689       ments may be omitted.
690
691              label word
692
693       If a statement of the form goto word is encountered, control is  trans‐
694       fered to this point, otherwise this is a no-op.
695
696              goto word
697
698       If  a  statement  of  the form label word is present in the block or an
699       enclosing block, control is transfered there.  Note that if  the  label
700       is  at the top level, it must be before the goto statement (i.e, a for‐
701       ward goto may occur only within a block).
702
703              continue
704
705       If there is a while, dowhile, or foreach block  enclosing  this  state‐
706       ment,  control  passes to the test, or in the case of foreach, the next
707       value is taken.  Otherwise an error results.
708
709              break
710
711       If there is a while, dowhile, or foreach block  enclosing  this  state‐
712       ment, control passes out of the block. Otherwise an error results.
713
714       Of  course,  control structures may be nested.  When a block is entered
715       and the input is the terminal, the  prompt  becomes  a  number  of  >'s
716       equalling  the  number of blocks the user has entered. The current con‐
717       trol structures may be examined with the debugging command cdump.
718
719       If a word is typed as a command, and there is no built-in command  with
720       that name, the directories in the sourcepath list are searched in order
721       for the file.  If it is found, it is read in as a command file  (as  if
722       it  were  sourced).  Before it is read, however, the variables argc and
723       argv are set to the number of words following the filename on the  com‐
724       mand  line,  and a list of those words respectively.  After the file is
725       finished, these variables are unset.  Note that if a command file calls
726       another,  it  must  save its argv and argc since they will get altered.
727       Also, command files may not be re-entrant  since  there  are  no  local
728       variables.   (Of  course,  the  procedures  may explicitly manipulate a
729       stack...)  This way one can write scripts analogous  to  shell  scripts
730       for nutmeg and .  Note that for the script to work with , it must begin
731       with a blank line (or whatever you like, since it will be thrown  away)
732       and  then a line with .control on it.  This is an unfortunate result of
733       the source command being used for both circuit input and  command  file
734       execution.  Note also that this allows the user to merely type the name
735       of a circuit file as a command, and it will be automatically run.
736
737       There     are     various     command     scripts     installed      in
738       /usr/local/lib/spice/scripts (or whatever the path is on your machine),
739       and the default sourcepath includes this  directory,  so  you  can  use
740       these command files (almost) like builtin commands.
741
742       Nutmeg  will  use  either  X  or MFB, depending on whether it finds the
743       variable DISPLAY in the environment.  If you are using X on a  worksta‐
744       tion, it should already be present, but if you want to display graphics
745       on a different machine than the one you are running nutmeg on,  DISPLAY
746       should be of the form machine:0.
747
748       If  X  is  being used, the cursor may be positioned at any point on the
749       screen when the window is up and characters typed at the keyboard  will
750       be added to the window at that point.  The window may then be sent to a
751       printer using the xpr(1) program.
752
753       There are a number of pre-defined constants in nutmeg. They are:
754            pi        pi
755            e         The base of natural logarithms
756            c         The speed of light
757            i         The square root of -1
758            kelvin         Absolute 0 in Centigrade
759            echarge        The charge on an electron
760            boltz          Boltzman's constant
761            planck         Planck's constant (h)
762
763
764       These are all in MKS units. If you have another variable  with  a  name
765       that conflicts with one of these then it takes precedence.
766
767       Nutmeg occasionally checks to see if it is getting close to running out
768       of space, and warns the user if this is the case. (This is more  likely
769       to be useful with the SPICE front end.)
770
771       C-shell  type quoting with "" and '', and backquote substitution may be
772       used. Within single quotes, no further substitution (like history  sub‐
773       stitution)  is  done,  and  within  double  quotes,  the words are kept
774       together but further substitution is done. Any text between  backquotes
775       is  replaced  by  the  result of executing the text as a command to the
776       shell.
777
778       Tenex-style ('set filec' in the 4.3  C-shell)  command,  filename,  and
779       keyword  completion  is possible: If EOF (control-D) is typed after the
780       first character on the line, a list of the commands or  possible  argu‐
781       ments  is printed. (If it is alone on the line it will exit nutmeg.) If
782       escape is typed, then nutmeg will try to complete  what  the  user  has
783       already  typed.   To  get  a list of all commands, the user should type
784       <space> ^D.
785
786       The values of variables may be used in  commands  by  writing  $varname
787       where the value of the variable is to appear.  The special variables $$
788       and $< refer to the process ID of the program and a line of input which
789       is read from the terminal when the variable is evaluated, respectively.
790       If a variable has a name of the form $&word, then word is considered  a
791       vector (see above), and its value is taken to be the value of the vari‐
792       able.  If $foo is a valid variable, and  is  of  type  list,  then  the
793       expression  $foo[low-high]  represents a range of elements.  Either the
794       upper index or the lower may be left out, and the reverse of a list may
795       be  obtained with $foo[len-0].  Also, the notation $?foo evaluates to 1
796       if the variable foo is defined, 0 otherwise, and $#foo evaluates to the
797       number  of  elements  in  foo  if  it is a list, 1 if it is a number or
798       string, and 0 if it is a boolean variable.
799
800       History substitutions, similar to C-shell  history  substitutions,  are
801       also available - see the C-shell manual page for all of the details.
802
803       The  characters  ~, {, and } have the same effects as they do in the C-
804       Shell, i.e., home directory and alternative expansion. It  is  possible
805       to  use  the  wildcard  characters *, ?, [, and ] also, but only if you
806       unset noglob first. This makes them rather useless for typing algebraic
807       expressions,  so  you  should  set noglob again after you are done with
808       wildcard expansion. Note that the pattern [^abc] will match all charac‐
809       ters except a, b, and c.
810
811       IO  redirection  is  available - the symbols >, >>, >&, >>&, and < have
812       the same effects as in the C-shell.
813
814       You may type multiple commands on one line, seperated by semicolons.
815
816       If you want to use a different mfbcap file than  the  default  (usually
817       ~cad/lib/mfbcap),  you  have  to  set  the  environment variable MFBCAP
818       before you start nutmeg.  The -m option  and  the  mfbcap  variable  no
819       longer work.
820

VMS NOTES

822       Nutmeg  can  be run under VAX/VMS. Some features like command, etc com‐
823       pletion, expansion of *, ?, and [], backquote substitution,  the  shell
824       command,  and  so  forth  do not work. (In fact command completion only
825       works on 4.2 or 4.3 BSD.)
826
827       Nutmeg will look for start-up commands in the file spice.rc in the cur‐
828       rent directory.
829
830       The standard suffix for rawspice files in VMS is ".raw".
831
832       You  will  have to respond to the -more- prompt during plot with a car‐
833       riage return instead of any key as you can do on UNIX.
834

SEE ALSO

836       sconvert(1), spice(1), mfb(3), writedata(3)
837

AUTHOR

839       Wayne Christopher (faustus@cad.berkeley.edu)
840

BUGS

842       The label entry facilities are very primitive - after all, nutmeg isn't
843       a  graphics editor (yet).  You must be careful to type very slowly when
844       entering labels -- nutmeg checks the X event queue once  every  second,
845       and can get very confused if characters arrive faster than that.
846
847       If  you  redefine  colors after creating a plot window with X, and then
848       cause the window to be redrawn, it will not to the right thing.
849
850       When defining aliases like
851
852              alias pdb plot db( '!:1' - '!:2' )
853
854       you must be careful to quote the argument list  substitutions  in  this
855       manner. If you quote the whole argument it might not work properly.
856
857       In a user-defined function, the arguments cannot be part of a name that
858       uses the plot.vec syntax.  I.e,
859
860              define poke(duck) cos(tran1.duck)
861
862       won't do the right thing.
863
864       If you type plot all all, or otherwise use a wildcard reference for one
865       plot twice in a command, bad things will happen.
866
867       The  asciiplot  command  doesn't deal with log scales or the delta key‐
868       words.
869
870       There are probably some features that nutmeg doesn't have yet.
871

CAVEATS

873       Often the names of terminals recognised by MFB are different from those
874       in /etc/termcap. Thus you may have to reset your terminal type with the
875       command
876
877              set term = termname
878
879       where termname is the name in the mfbcap file.
880
881       The hardcopy command is useless on VMS and other  systems  without  the
882       plot  command,  unless  the user has a program that understands plot(5)
883       format.
884
885
886
887
8884th Berkeley Distribution        27 April 1987                       NUTMEG(1)
Impressum