ARM Club 1/ARM_CLUB_CD.iso/contents/education/n/spice/docs/Nutmeg_STD

Text File | 1993-01-03 | 92KB | 2,296 lines

=== ARCHIMEDES NUTMEG MANUAL VERSION 1.00 (03 Jan 1993) ===

written by F.K.W. van de Pol and E.T.J. van de Pol.

Note:

This is a development version of the Nutmeg manual. This manual has
not yet been finished, a few chapters are not present. If you wish
you could send us a corrected version of this document.

This document has been generated by a text compiler, so don't bother
converting this document to !Impression; we can easily generate an
!Impression text story.

** Please report any stylistic or grammatical faults! **

0       RELEASE NOTES
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Berkeley SPICE 3A6 - Archimedes version by FKW and ETJ van de Pol.

This product is public domain, which means that you can give these
programs to anyone you like, if and only if it is distributed with
all original files, and with no changes made to it. If you want to
put it on a bulletin board or include it in your public domain
library, you can do so, taking this notice in account. You may not
charge any money for it, apart from duplication and postage costs.
This should not exceed 10 dutch guilders.

If you find this program useful to you in any way, and you wish to
express your feelings of gratitude towards us, a small fee (say 50
dutch guilders, or £20) would very much be appreciated. If you want
to transfer some money, you can do so:

      * using the giro account (5944516) of ETJ van de Pol

      * using the giro account (5826066) of FKW van de Pol

      * sending a stamp and (self-addressed) envelope containing a
        3.5 inch floppy disc and a giro cheque to us (the address is
        listed below). Please state which version of BSpice, Nutmeg
        or any other application you are using. If you are smart, you
        include your list of bugs, notes, wishes and complaints as
        well. (Wonders never cease!). A newer version of Spice will
        be sent to you (as soon as it is available).

CONTACT US AT THE FOLLOWING ADDRESS:

                Frank & Erik van de Pol
                Mgr.Nelislaan 10
                4741 AB Hoeven
                The Netherlands
                (tel. [phone])
                email: [e-mail] or
                [e-mail]


======================================================================
1       INTRODUCTION
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
This chapter explains the basics of Nutmeg in conjunction with Spice.
If you are familiar with Spice, Nutmeg and the use of rawfiles, you
can skip this chapter.

1.1 What is it?
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Nutmeg is a so called graphic post-processor. It is part of the Spice
3A6 distribution. This chapter will provide some global information
concerning Spice in general and Nutmeg in particular.

1.1.1 History of Spice and Nutmeg

Spice was first released in May 1972 at the University of California,
Berkeley. It became a very popular program among students, but they
were not the only users: manufacturers of semi conductor devices used
it a lot.

Three years later, Spice 2 was released, with numerous enhancements
to the first version. It became the standard for analog electronic
circuit simulation. You can say that many semiconductors owe their
existence and success to Spice.

In october 1985, this version of Spice was released. We have enhanced
and debugged this release in many ways, and it is a much more
reliable product than the original Spice 3A6 distribution. However,
as we have used the original Berkeley Spice sources, we will continue
to call it Spice 3A6.

Nutmeg was part of this Spice 3A6 distribution. It is a fully
interactive graphic post-processor. The distribution consisted of
basically two programs: BSpice (the analog simulator) and Nutmeg.

1.1.2 What Nutmeg is good at

Nutmeg is, as you may have read, used to create diagrams. It uses the
data that has been calculated by the simulator BSpice and creates
diagrams using this data.

In order to do so, Nutmeg has a useful set of functions that can
operate on the calculated results. You could for instance plot the
difference of two voltages versus time, or you could plot 20 times
the log of a voltage (db(voltage)) versus frequency, in logarithmic
or linear grid. Nutmeg allows you to create very fancy graphics that
are compatible with most Archimedes programs.

You may have noticed that these examples concern electronic circuits,
and that is basically what Spice has been designed for. Therefore
most operations and functions in Nutmeg have an electrical
engineering background.

1.1.3 Main objectives

The main objectives of Nutmeg are:

      * Cooperation with BSpice.
      * Easy operation for users (electrical engineers).
      * Nice front-end.
      * Ability to use scripts for automating purposes.
      * full control over plotting.
      * Extended set of operations and functions.
      * Fancy output in Archimedes Draw format.
      * Extendibility.
      * Reasonable memory usage.
      * As bug free as possible.

1.1.4 Port information

The port of this package was done by Frank KW van de Pol and Erik TJ
van de Pol. If you want to redistribute it, you should read chapter 0
first.

We have to admit that the original (public) version of this program
is written at the Berkeley University of Technology. All authors are
credited for their program. The things we have done are numerous,
though. To mention a few: We restyled it to allow it to be used in
the desktop, added Draw diagrams, rewrote all plot routines,
eliminated numerous bugs and added several commands new to this Spice
3A6. You can imagine that this is a hell of a job, as this project
currently consists of over 2500 files in over 250 directories. This
includes all sources, documentation, object files, executables etc.
Anyway, this project chews up a massive 25 Megabytes of valuable hard
disk space. Since we are poor, you may send us a bigger SCSI hard
disk too if you like (this is serious).

Commercial versions of this program are available (most of them are
very expensive), so try to forgive us when you are frustrated in some
way by it. This project is done entirely in the spare time of two
students, and as you can imagine, rewriting and testing such a large
program with so few people in so little time, will almost inevitably
result in bugs or small irritating things we didn't get to. If you
notice them, you are strongly recommended to take a pencil,
typewriter or word-processor and write them down to report, as this
is the only way we can possibly eliminate all bugs.

We advise to use the following scheme:

        COMMENT NO.     a continuously numbered field, for references
        RECORD DATE     the date when you recorded this in the list
        RECORD INITIAL  the name of the person that recorded it
        STATUS          comment type: bug/improvement/cosmetic/etc.
        DESCRIPTION     the comment itself
        HINT            a hint that may lead to a solution

We can merge comments in our data base in a simple way if you do so.
Bug reports like 'my machine sometimes crashes when I run Spice' are
not very useful. At least include:

      * Your machine's configuration.
      * Installed software/modules.
      * Version numbers of the Spice applications.
      * What did you do to cause the problem.
      * Anything that you think is relevant.

Please remember:

      * A lot of effort has gone into this (very time consuming)
        project so far, so don't try to abuse it in any way, and
        please respect the people who wrote it, and that includes us
        too!

      * If you don't like it at all, don't use it.

      * If you have some complaints or wishes, find out what you
        would like to have added or changed in order to make these
        programs useful to you, and maybe we can sort it out.

      * If you like it a lot, we would very much like to hear that
        from you too. Humans do like compliments (like dogs do), so
        if you want to, you can send a nice colourful post card to
        our home address.

      * If you use it regularly or professionally, send us some money
        to encourage further development. The amount of money donated
        should be proportional with the size of your wallet.

      * If you don't like our english, send us an english dictionary!
        (You are also welcome to send us a corrected/ rewritten
        version of this manual.)

Our address has been included in chapter 0.

1.2 Limitations and Hardware Requirements
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Read this if you want to find out if your system meets the minimal
operating system and hardware requirements.

1.2.1 Operating system

Nutmeg and BSpice have been developed and tested under RISC OS 2.00.
Both programs should work under RISC OS 3.00 and RISC OS 3.10, but it
has not been altered to inhibit all special RISC OS 3 features.
However, these programs should operate without a problem with any
version of RISC OS higher than 2.00.

1.2.2 Hardware

Nutmeg and BSpice have been developed on an Archimedes 310 with an
Oak SCSI host adapter, a Seagate ST-177N hard disk and 4 megabytes of
memory. Our machine still has a standard ARM2 processor and original
MEMC1 memory controller.

Spice and Nutmeg have been tested on newer machines (Acorn A3000,
Acorn A5000, Archimedes 540 and Acorn R260) with positive results.

The following is an absolute minimum when you want to use this
product, so don't blame us when things get slow:

      * 2 megabytes of main memory.
      * 1 floppy disk with double density (800k archimedes).
      * any kind of monitor.
      * ARM2 processor.

For average use, the following outfit is recommended:

      * 4 megabytes of memory.
      * a hard disk with enough storage left on it.
      * any kind of monitor.
      * an ARM2 processor.

For extensive use, the following system configuration is recommended:

      * more than 4 megabytes of memory.
      * a hard disk with enough storage left on it.
      * a multisync or monochrome hires monitor.
      * an ARM3 processor.
      * a floating point coprocessor.

As Spice and Nutmeg have to perform lots of floating point operations
the addition of a floating point coprocessor will give you a
significant (read: amazing) improvement of processing and simulation
speed.

1.3 Where does Nutmeg fit in?
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Nutmeg is the part that reads in and operates on the raw files
created by BSpice. Nutmeg and BSpice are a couple that can't be
split. Using BSpice without using Nutmeg isn't very likely to be
useful, and using Nutmeg without using BSpice isn't very handy
either. Therefore, Nutmeg and BSpice can't be separated.

It is possible to create your own raw files (the format is described
in appendix C), thus allowing you to use Nutmeg for other purposes,
but Nutmeg should be considered to be used for electronic purposes
only because of the specialised set of commands and functions.

1.3.1 Accompanying tools

The Spice package has some extra tools. These are not essential when
you want to work with Spice, but they allow you to do more.

1.3.1.1 Manager

The Manager can be used to create work directories. If you follow
this approach, you can have several work directories, depending on
your needs. You could, for instance, have a work directory for each
project you are working on, allowing you to keep things separate and
store them on separate floppies.

1.3.1.2 Resources

The Resources application does not have an executable. It is more or
less comparable with the !System application that has been provided
by Acorn. The resources directory should be a central place in your
Spice system. It is meant to be the place where you can store include
files for in Spice circuit sources (for the simulator), universal or
common script files (for Nutmeg) and universal or common Query box
definitions (for use with Nutmeg).

The last two are probably superfluous, but the first purpose is
essential when you have models describing several different standard
components.

1.3.2 Schematic overview

The set-up is globally as follows:

(fig. 1-1)


======================================================================
2       OPERATING NUTMEG
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
2.1 Installation
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
This chapter describes how to install Nutmeg and Spice on your
system.

2.1.1 Nutmeg on a hard disk system

Running Nutmeg from a hard disk system should not cause any problems.
Just place it somewhere in your directory structure. You are
recommended to place Nutmeg, BSpice, Resource and your work directory
in the same directory level. You can place the work directories in a
different directory if you like, but remember to explicitely select
the work directory you would like to use.

2.1.2 Nutmeg on a floppy system

You should create a fresh floppy containing Nutmeg and BSpice, and
another floppy disk that holds the work directory. This really is a
must, as BSpice is very good at creating large rawfiles. Place the
Resources on a separate floppy too as this directory will grow in
size when you add resource files. If the size of your resource
directory is small enough, you can put it together with BSpice on one
floppy.

2.2 Resources
¯¯¯¯¯¯¯¯¯¯¯¯¯
This section is meant to give you an idea of the resources Nutmeg
uses. Simple examples are provided, and you are recommended to
experiment with some settings. For more information read the
appropriate sections in the chapter 'Advanced Operation'.

2.2.1 SpiceInit file

The SpiceInit is behind directory !Nutmeg.Script, and it contains a
set of commands (as you would type them on the input line of the
window) that set up the behaviour of Nutmeg on start-up. You can set
various variables and preferences in order to customize Nutmeg. In
fact, SpiceInit is a normal script file that can be run with Nutmeg's
script command.

When Nutmeg is started, each line in this file is treated as if it
had been typed in from the window's input line. After that, Nutmeg
returns control to you, and you can enter commands yourself. Start
make changes to the existing SpiceInit file and study the results.

Due to this approach, you are highly recommended to edit the
SpiceInit file and make it as short as possible. This prevents long
parsing times of the script file.

2.2.2 Query boxes

Query boxes are created from description files and can perform
various actions. Their basic use is communication with the user in a
natural (RISC OS compliant) way. On start up, there are several
query-boxes available.

Try for example clicking on the 'plot' icon beneath the input line.
As you can see, a dialogue box will be opened that has the look and
feel of a normal dialogue box. The power of query boxes is, that you
can provide them yourselves for various actions: you could have some
for setting different variables, executing different commands or
launching applications.

2.2.3 Smart icons

Smart Icons are meant for quick access to regularly used commands.
The order in which they appear is described in a configuration file,
and the icons associated with them reside in a separate sprite file.

Clicking on them can have different effects, but they basically send
a command to Nutmeg. This can be any valid Nutmeg command.

2.2.4 System paths

There are several system and program paths you can reference to. Here
is a list of the available paths:

BSpice3A6$Dir   points to the directory where the actual Spice
                simulator can be found. When you want to call BSpice,
                run <BSpice3A6$Dir>.BSpice <input> [-q] [-b]. Note
                that omitting a run command in front of the
                environment variable may cause problems, especially
                when you have selected an other filing system than
                the one Spice has been put on. This run command
                refers to the RISC OS operating system command.

Nutmeg$Dir      is the application directory of the post processor.
                Do not explicitely use this variable unless you
                really need to.

SpiceResource:  contains various models for use in Spice netlists and
                may be used to store scripts and query boxes too.

SpiceWork$Dir   points to the current work directory. It contains
                several sub directories, for example 'In', 'Raw',
                'Script' and 'Query'.

2.2.5 !Resources directory

This directory contains models and sub circuits for inclusion in
Spice simulation files, but is also a central place where Scripts and
Query boxes can be stored.

2.2.6 Work directories

Work directories enable you to keep things separate. For example,
when you are working on several projects, you can have several sub
directories where you store all things that are specific for this
project (eg. scripts and query boxes). You select a work directory by
double-clicking on it.

2.3 Starting up
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Starting Nutmeg is just like starting any RISC OS application: you
double click on the !Nutmeg icon in a directory viewer, and Nutmeg
will install on the icon bar, with one window opened. This window is
the central input and output window. There are several items of
interest:

(fig. 2-1)

The window behaves just like any other RISC OS window. You can type
any command on the input line and press return to pass it to the
command parser.

After you press return, a fresh line appears and you can enter a new
command while the command you just entered is being executed.

The icon that contains 'Zzz' is called the sleep icon. You can click
on it to pause the currently executing Nutmeg command. Nutmeg
multitasks happily with other RISC OS applications, and has been
designed to execute all commands without having long delays. If
execution is paused, the icon on the icon bar will change. The key
short-cut for this function is CTRL-S (if the Nutmeg window has the
input focus).

2.4 Nutmeg Terminology
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
When you load in a simulation result file (a rawfile), you will
notice that Nutmeg orders them in a hierarchical manner, as follows:

      * The type of simulation in which the data vectors are stored
        is called a plot.

      * The simulation values of the nodes in a plot are called
        vectors.

Vectors are the key to manipulate your results. If you want to
calculate with the data, you can work on an entire vector in stead of
making calculations for each point in the vector. This provides a
very quick and flexible way of working.

Card            This is a Spice term. It is a word in a Spice circuit
                file that starts with a dot. It tells BSpice what to
                do.

Circuit         This is a Spice term. It is part of a simulation file
                and describes what the circuit looks like and what
                components are used.

CLI window      This is the main Nutmeg window.

Commands        tell Nutmeg what to do next.

Constants       can be used as constants in calculations, just like
                any number you typed in. Standard constants include
                pi, planck's constant and the speed of light.

Deck

Diagrams        are the Draw graphics that Nutmeg produces. There are
                sometimes referred to as plots, but that should not
                be confused with the plots described above.

Diagram viewer  is the window that contains the generated Draw
                graphics. A viewer is a standard way of dealing with
                Diagrams.

Expression      is an algebraic formula involving vectors and scalars
                (a scalar is a vector of length 1), and several
                operations.

Functions       have one or more vector or scalars as input, operate
                on them and return the result of the calculation.

History         is the list of commands that has been typed in since
                program start-up. You can save this list to replay a
                session.

Input line      is this icon in the CLI window that you can use to
                enter text in.

Operations      Basic arithmetic operations to operate on vectors and
                scalars.

Plot            is a structure in the Nutmeg database where the
                results of a certain simulation are stored. A plot
                contains vectors.

Preferences     allow you to fully control the behaviour of Nutmeg.

Query box       is a dialogue box that allow you to set variables and
                execute commands. Query boxes are constructed using
                description files.

Scripts         are files that contain sequences of valid Nutmeg
                commands.

Smart Icons     provide a nice way of interfacing with the user. You
                can found them under the input line.

Variables       control the behaviour of various commands and are of
                help when interfacing to scripts and saving states.

Vector          is an array in plot that contains simulation results.
                Voltage versus time is an example of a vector.

Work directory  Is a directory where you store circuits, scripts,
                models and query boxes. You can have several
                different projects, but you have to choose one. This
                is called the current work directory.

2.5 CLI input
¯¯¯¯¯¯¯¯¯¯¯¯¯
When a command is given, it is interpreted as one of several things.
First, it may be an alias, in which case the line is replaced with
the result after alias substitution, and the line is parsed again.
Second, it may be a predefined command, in which case it is executed
(see chapter 9 for a list of available commands). Third, it may be an
assignment statement, which consists of a vector name, an = symbol,
and an expression (see the syntax for the let command in section
9.1.10), in which case it is executed as if it were preceded by the
word let. Finally, it may be a RISC OS * command (not the comment
card used in Spice simulation files), in which case (if the variable
unixcom is set) it is executed as if it were entered in the input
line.

There are a number of ways in which you can tell Nutmeg what to do.
Here follows a short description of the two most commonly used:

2.5.1 Typing

The simplest way to give commands to Nutmeg is typing a line in the
input line in the CLI window. You can edit the line and page through
previous commands using the up and down arrow keys. When you press
return, the command will be parsed.

2.5.2 Drag

Another way to execute commands is dragging files to the command line
window. Nutmeg will look at the parent name of the file, and decide
what to do depending on that name.

      * If the name is 'Script', Nutmeg will load the script in, as
        if you typed script <name>, and execute the script file.

      * If the name is 'Raw', Nutmeg will issue a load command, and
        thus tries to load in the rawfile.

      * If the name is 'In', and the BSpice shell has been started,
        then Nutmeg will issue a BSpice command. This command sends a
        message to BSpice with instructions to read the circuit and
        simulate it. Output will go to the currently selected work
        directory.

2.6 Diagram viewers
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
2.6.1 Purpose

Nutmeg has extensive abilities to create Draw figures from vectors.
In fact, this is what Nutmeg has been designed for (although not for
Draw figures).

When Nutmeg creates a diagram, a window will be opened containing
that diagram. These so called diagram viewers provide a uniform way
of dealing with generated draw figures. You can save the draw file or
discard it, whatever you want. They also provided information on the
created diagram, and allow you to zoom in or out.

2.6.2 The menu

Open a diagram menu as follows: position the mouse over the diagram
viewer and press the menu button of your mouse. A menu will open,
which is as simple as it looks:

      * Follow the info arrow to get some information about the
        diagram.

      * Follow the zoom arrow to set zoom factors using a standard
        dialogue box.

      * Follow the save arrow to put you diagram somewhere safe or
        insert it in any other program.

Clicking on the close box of the window will prompt you if you
haven't saved the diagram yet, and will then remove the picture from
memory.

2.7 Scripts
¯¯¯¯¯¯¯¯¯¯¯
2.7.1 Introduction

Scripts are the key to flexible and automated operation. They can
contain all valid Nutmeg commands, even conditionally. Scripts can
also call other scripts (only limited). Writing a script file can be
tricky: read the special 'advanced' chapter below for more
information.

2.7.2 Usage

Scripts can be executed using script <name>, where Nutmeg tries to
load them in, looking in various directories in a specified order
allowing you to override certain script files when you want something
a little different for a project:

      * It scans <SpiceWork$Dir>.Script first (to add project
        specific scripts), then SpiceResource:Script (for general and
        standard scripts), and finally <Nutmeg$Dir>.Script, which
        contains default and system scripts.

This approach gives you full control over what script should be
executed, as you can supersede a 'standard' script when you need to.

2.8 Smart icons
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
2.8.1 Introduction

Smart icons have been designed for those commands that are used very
frequently. Each smart icon can have a neat icon, that will be
positioned below the input line. Definitions (which are very simple)
are stored inside a description file.

2.8.2 Operating them

Clicking on such an icon will cause the command that is associated
with an icon to be passed to the command interpreter, where it is
treated as just any other command.

2.8.3 Adding yourself

Open the !Nutmeg directory by clicking on it while holding shift.
Locate the file called 'Icons' and load it into a text editor (eg.
!Edit). You can add lines to add new icons or to create some space:

      * 'command' followed by the name of the sprite you want to use,
        and finally the command itself, which could be any number of
        words.

      * A special keyword 'gap' is provided to add some distance
        between two icons.

See appendix C for more information about this file format.

Save the file and edit the sprite file called 'IconPicts'. This
contains the sprites Nutmeg uses when displaying the smart icon.
Define a nice sprite matching the name you typed in, and save the
sprite file.

Note that the new smart icons will not be in effect until you start
Nutmeg again.

2.9 Query boxes
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
2.9.1 Introduction

Query boxes are designed to make Nutmeg look real nice, and to
communicate with the user in an intuitive way. Query boxes basically
consist of a number of objects in order to do so. They are:

Static text     for accompanying text.

Static pictures for descriptive graphics.

Booleans        for switching options on and off.

Writable icons  for entering values and names.

Hotbuttons      for action buttons.

Query boxes have a number of commands to control them. You can use
querylist, queryclose, queryopen, querykill and queryload, each of
which has it's straightforward meaning. See chapters 3 and 9 for more
information.

You can define query boxes by providing a description file containing
the box definitions.

2.9.2 Examining a query box definition

Writing query boxes can be tricky. If you want to have some examples,
you can have a look on the definitions of the currently available
(and standard) query boxes.

In order to do so, open the Nutmeg directory, locate directory
'Query' and open it. Inside will be a file named 'Std'. This file
contains various box descriptions. Somewhere at the top will be a
line beginning with 'defbox'. This tells Nutmeg that this is the
start of a new definition. it has two arguments: the identifier you
use for reference purposes and the name of the box (notice the
quotes!) that should appear as the title of the box.

Underneath are lines starting with 'static' followed by the
coordinates of the bottom left corner of the text and the (quoted)
text itself. Notice that you cannot have text containing quotes.

There are several lines starting with 'staticpict'. This defines a
static picture. Most of them are used to stress key short-cuts.

Then, some lines appear starting with 'string' and followed by (in
that order) the variable identifier to store the names in, the type
of the string, the two coordinates making up the left corner of the
box, and finally the width and height of the box.

After this section appears a number of lines starting with 'boolean',
followed by the variable identifier it is associated with, the
coordinates of the left corner of the button, and the keycode that
toggles the command.

Finally, the text 'hotbutton' appears with the command to execute,
coordinate pairs, the keycode that causes this button to be hit, and
the text inside the button. The last word of a definition is
'endbox', which concludes the definition of the query box.

2.10 Preferences
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
2.10.1 Introduction

Preferences are the key to customize most features of Nutmeg. Those
most used can, in many cases, be controlled by Nutmeg environment
variables. However, there is a number of options you are not likely
to alter much, so these are not controlled by a variable. Instead, a
special keyword has been included: pref. With this keyword you can
set your preferences to tell Nutmeg to operate the way you want
Nutmeg to behave.

2.10.2 Preference window

Setting preferences from a script file can be a tedious job,
involving lots of looking up keywords and more of that. There is an
alternative to that, and it is the preferences window.

You can open it by clicking on the item 'Preferences...' on the icon
bar menu of Nutmeg. It contains all options you can set in a RISC OS
compliant way. You can alter options easily to match your taste. You
can then save those preferences to an editor to customize them and
make it into a start-up script for Nutmeg. You are highly recommended
to delete all lines that contain the default values, as this will
speed up loading.

2.10.3 Editing you prefs

If you are satisfied with the current settings, you will have to save
them. The best thing you can do is save them somewhere in a
directory, and then delete all lines from the saved preferences file
that you did not edit. Omitting these lines will force Nutmeg to take
some default value for it, and since you didn't edit it, the result
will be the same. An extra advantage is that the preferences file
will be a lot shorter and as a consequent will be parsed a lot
faster.

You are recommended to save the preferences with a different name and
compare each line carefully to corresponding lines in
<Nutmeg$Dir>.Script.SpiceInit. Only alter or add the lines that have
been changed to the SpiceInit file.


======================================================================
3       ADVANCED OPERATION
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
This chapter contains more detailed information of what is mentioned
in chapter 2. It is therefore possible that some of the information
has been included in other sections of this manual too. This chapter
tries to explain things in full. For normal use you should not need
this chapter, but if you want to customize Nutmeg, you will
inevitably need to.

3.1 Internal database
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Nutmeg has an internal database where it keeps track of vectors and
plots. There are many commands that need information from this
database. For example, if you want to plot something, you have to
specify what vectors you want to appear on the screen.

3.1.1 Referencing

Each vector is contained in a plot. Normally you will select a plot
using setplot, and if you need to reference a vector, you will use
that name directly.

Now imagine that you want to plot vectors from several different
plots. You would have to specify the name of the plot that is
associated with each vector. Fortunately, Nutmeg allows you to do so:
if you want to refer to a vector that is not in the currently
selected plot, you can refer to it with plotname.vecname.

3.1.2 Maintenance

It is easy to maintain the database: Nutmeg does it for you. You may
however find it useful to destroy vectors and plots that are not
needed in case memory is low. You can use the killvect and destroy
commands for that purpose.

Just remember that:

      * vectors are stored inside plots,

      * you can list the vectors of the currently selected plot with
        display,

      * that you can list all plots using listplots,

      * you set the currently selected plot using setplot.

3.1.3 Summary

Refer to vectors in an other then the currently selected plot
explicitely using plotname.vecname. listplots will list all plots,
setplot is used to set the current plot, and display will list all
vectors in the current plot. destroy and killvect will destroy plots
and vectors. Use with care.

3.2 Writing Scripts
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
If you use start using scripts you can automate some simple
operations in Nutmeg that would otherwise involve lots of typing
standard commands. A script file can take action depending on
variables or on the evaluation of expressions.

3.2.1 Advanced Scripts

3.2.2 Script writing Hints

Try loading in an existing script. You can find several in
!Nutmeg.Script. Try to predict what the script should do and why.

3.2.3 Quotation

3.2.4 Variable substitution

If you want to substitute a variable in an expression, you have to
specify it explicitely. If you have a variable named offset, you can
add it to the contents of a vector and output the result in columns
using:

        print col V(1) + $(offset)

The $() construct substitutes the value of the variable for the name
of the variable on the command line, and tries again. A substitution
could result in other $() sequences to appear. Nutmeg will continue
with substitution until all $() have disappeared. Nutmeg will trap
infinite substitutions. If no more substitution needs to be done,
then Nutmeg will try to evaluate the expression.

You can 'construct' a command line depending on certain variables and
substitute appropriate values in order to construct a command string.
The default query boxes that can be accessed by clicking on the smart
icons below the input line have several writable icons where you can
enter strings. In most cases, such a query box will start a script
(because each action button can have only one command associated with
it) which will test several variables and will construct a command
line for a specific command. When construction has been finished, a
command will be executed with this constructed tail using plain
variable substitution.

3.2.5 Summary

3.3 Advanced CLI input
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
3.3.1 Wimp messages

Please notice that this Wimp message is not allocated by Acorn.

3.3.2 Example program

3.3.3 Summary

3.4 Advanced query boxes
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
3.4.1 Key short cuts

The hotbuttons and booleans allow you to assign a key short-cut to
them. Pressing the key will simulate a click on the button. The key
code should be the standard wimp code.

3.4.2 Writing scripts

3.4.3 Standard constructions

3.4.4 Box layout tips

Make sure that you design the box so that using it is intuitive and
logical. If you want to make it real professional, create a box with
a template editor and use it to create a similar box with. You can
then easily figure out what the layout of your query box will be.
Alternatively, you can draw the layout on a piece of paper, and build
the description of the query box using that piece of paper.

Try not to include too much options in one single query box. If you
want to build a very large box it will probably be too large to fit
on the screen, or it may be confusing and hard to use.

There is a trick to make large boxes: they can be hierarchically
ordered by making a 'top level' menu with a number of action buttons
and descriptive text. Clicking on an action button can then open a
second query box (and close the first) to contain the interface to
the user for that 'menu' item. Such a submenu can contain a special
action button to open the root box again.

Make sure you use a grid which you use to align your items on in
order to make the appearance neat. You will have to know the size of
the different items. They are as follows (in OS units):

boolean         width is 44, height is 48.

hotbutton       width is 20 + (16 * the length of the text), height
                is 48.

static          width is 16 * the length of the text, height is 48.

staticpict      width and height depend on the size of the sprite and
                the screen mode it has been designed for.

string          width has been include in the definition, height is
                48.

Do not put your own boxes in 'Query.Std'. Instead use your own file
(eg. 'Query.Custom' or 'Query.MyBox') and load them in with queryload
. You can put that command in the SpiceInit script file that is
executed each time Nutmeg is started.

Each action button and each Boolean button can have a special key
code associated with it. Generating this keycode (by pressing the
key) will simulate a click on the button. Choose logical
abbreviations for these keycodes and, if possible, show it using some
descriptive text and/or using static pictures to underline
appropriate letters in descriptive text. You can for example use text
in lower case for each boolean or hotbutton, and highlight one
character (using upper case) that represents the key that responds to
this button.

To make things real clear, the standard query boxes use a static
picture (a small grey line) to underline the appropriate letter, and
place a small 'return' symbol next to the hot button that reacts on
the return key.

3.4.5 Summary

3.5 Directory structures
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
3.5.1 What paths are available

3.5.1 Where to put what?

3.5.2 Search path order

The order in which various Nutmeg commands try to open resource files
are:

      *         The current work directory. Access explicitely with
        <SpiceWork$Dir>.

      *         The resources directory. Access explicitely with
        SpiceResource:.

      *         The Nutmeg home directory. Access explicitely with
        <Nutmeg$Dir>.

      3.5.3 Making use of search paths

      Place standard resources in the Resources directory. Try not to
        put too many things in the Nutmeg application directory: this
        directory should contain 'system' resources only.

      Use the sub-directories in the work directories for project
        specific resources. These should contain all scripts and
        query boxes that are not likely to be useful for other
        projects. You can keeps things separate in this way.

      You can make use of search paths in an other way. If you are
        not satisfied with some 'standard' query box (eg. it is too
        extended or not extended enough), you can easily copy and
        alter it, and save it in the Resources or work directory to
        overrule the default definitions. The same goes for script
        files.

      3.5.4 Summary

      3.6 Customization
      ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
      This section tries to give some hints where you can start when
        you want to customize Nutmeg.

      3.6.1 Change prefs

      The preferences are used for settings that are not likely to be
        altered much. To obtain maximum flexibility, you can save and
        edit these preferences. Chapter 8 provides a list of
        preference keywords that you can alter.

      3.6.2 Change smart icons

      There is only one way you can edit the smart icons. In order to
        do so you will have to load the file !Nutmeg.Icons in a text
        editor. Then edit the description of the icons, following the
        format rules that are laid out in appendix C.

      Note that if you want to add a smart icon, you will have to
        create a sprite too with the same name as you used to
        reference to the icon. These icons are in file
        !Nutmeg.IconPicts and can be loaded in and edited with Paint.

      Changes to the smart icons description file will not take
        effect until you start Nutmeg again.

      3.6.3 Aliases

      If you use some commands or sequences of command regularly, you
        might consider defining an alias for them. This alias can
        abbreviate a longer command with various options, or it can
        be used to start a command script. The last method allows you
        to define an alias for sequences of more than one command.

      Modify the Init script file you can find in directory
        !Nutmeg.Script. Place your own alias definitions in this
        script file or call a script file from Init that contains
        your custom settings. You can even place this custom script
        file in a work directory, and have Nutmeg configured
        differently depending on what project directory you selected
        before starting Nutmeg.

      3.6.4 System variables

      There is a number of system variables that influence the
        behaviour of Nutmeg. You can alter, set or unset these
        variables inside some start-up script to set certain
        defaults. See chapter 4 for more information. Note that some
        of the standard query boxes make use of system variables too,
        and enable you to alter the setting of these variables by
        clicking on them.

      3.6.5 Summary

      You can customize Nutmeg in several ways. The smart icons
        should be altered before you start-up Nutmeg. They allow you
        to make Nutmeg friendly and nice to deal with. Aliases can be
        used to abbreviate long commands or make new ones. System
        variables allow you to manipulate commonly altered features.
        Prefs are useful if you want to alter system specific
        features. Note that smart use of a query box and accompanying
        script file can eliminate the difference between these two
        when dealing with them.


======================================================================
4       NUTMEG ENVIRONMENT VARIABLES
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Variables in Nutmeg differ from vectors. A variable can be used to
set or disable a specific feature, or to pass parameters to other
functions. This chapter is meant to shed light on what variables are
available and what they are used for. Below is a list of variable
names who are reserved for use in Nutmeg, so if you want to make use
of variables for your own purposes, make sure you don't get any name
clashes with these predefined variables.

4.1 Variables for CLI handling
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
abstol          The absolute tolerance used by the diff command.

cpdebug         Print cshellparse debugging information.

debug           If set then a lot of debugging information printed.

echo            Echo each command to the screen before it is
                executed.

filetype        Can be ascii (default) or binary. It is the rawfile
                format. Rawfiles in ascii format are in a readable
                form, but rawfiles in binary form will take up less
                memory. BSpice produces ascii format rawfiles.

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

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

nfreqs          The number of frequencies for fourier. The default is
                10, but higher values will result in more accurate
                fourier transforms.

noaskquit       Don't ask the user if he really wants to quit when he
                has unsaved data.

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
                ']'.

nonomatch       If an expression can't be matched, use global chars
                literally.

nosort          Don't have display sort the variable names.

polydegree      The degree of the polynomial used for curve fitting.

polysteps       The number of points to interpolate when doing curve
                fitting.

program         The name of the current program.

rawfile         The default name for rawfiles created.

reltol          The relative tolerance used by the diff command.

showtype        Display the variable type when all variables are
                listed.

units           If this is 'deg' (degrees), then all trigonometric
                functions will use degrees.

unixcom         Send unrecognised commands to the operating system,
                who will try to execute them. If you enter an unknown
                command and this variable has not been set, then
                Nutmeg will report an error.

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.

4.2 Variables dealing with plots
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
combplot        Plot vectors by drawing a line from the point to the
                X-axis. If you use it with large datasets, plotting
                and displaying the diagram will be slow.

dontplot        No graphics control codes are actually sent, so no
                diagram will be build.

monochrome      Create monochrome diagrams when plotting. Useful if
                you want to output the diagram to a printer.

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

nologscale      Force not to use log scale when plotting. Note that
                this differs from the subgrid variable. The subgrid
                instructs Nutmeg to create a logarithmic grid in a
                diagram if appropriate, and nologscale tells nutmeg
                not to map the data points on a logarithmic grid.

redrawplot      Redraw the plot each time a vector has been added.

subgrid         Plot a logarithmic sub division grid if appropriate.

xprecision      The decimal precision when labelling the x axis. If
                you create a diagram and the resolution of the x axis
                labelling is not high enough, increase this value.

yprecision      The decimal precision for the y axis. If you omit
                this value, Nutmeg assumes that you want to use the
                same resolution as used for x axis labelling.

4.3 Default query box variables
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
There are 6 standard query boxes defined that use nutmeg variables to
pass results and store temporary values. For more information about
how to create a query box see chapter 2 and 3 in the appropriate
sections.

These variables are defined for use by the qb_plot box ('Plot
Options'):

                plot_vecs
                plot_vecvs
                plot_xmin
                plot_xmax
                plot_ymin
                plot_ymax
                plot_indlo
                plot_indhi
                plot_xprec
                plot_yprec
                plot_dash
                plot_cols
                plot_xrang
                plot_yrang
                plot_indic
                plot_vs

The following are defined in query box qb_help ('Help items'):

                qbhelp_comm
                qbhelp_func
                qbhelp_oper
                qbhelp_vars
                qbhelp_cons
                qbhelp_auth
                qbhelp_anyc
                qbhelp_hstr

These variable are defined in query box qb_fourier ('Fourier
analysis'):

                four_vecs
                four_freq
                four_tovect
                four_all

The following variables are reserved for use in three other boxes
('Shell command', 'Batch Spice', 'Type file'):

                qbsh_comm
                qbbspice_in
                qbtype_in


======================================================================
5       NUTMEG OPERATIONS
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Nutmeg has a set of arithmetic operations like addition and division.
These operations can be used to calculate with vectors and scalars. A
scalar is a vector of length 1, and can be a scale factor, for
example.

You can mix operations and functions in an algebraic expression. For
a full description of available functions, see chapter 6.

There are 6 basic arithmetic operations available in Nutmeg. These
operations work on real data and complex data, either vector or
scalar. If vectors of different types are used, for example real and
complex, then the values will be converted so that the types match.
In this example, the output will contain complex results. Output can
be converted back to real using appropriate functions.

5.1 List of operations
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Here is a list of arithmetic operations on vectors and scalars:

+               Addition of two terms.

-               Subtraction of two terms.

*               Multiplication of two terms

/               Division of two terms.

%               This is the modulo operator. This represents the rest
                term when doing a division.

^               The term 'a ^ b' represents 'a to the power of b'.

,               This operator has two meanings: it can be part of an
                argument list of a user-definable function where it
                separates the arguments, or it separates the real and
                complex argument of a complex number. The term 'x ,
                y' is synonymous with 'x + j(y)'.

There is a number of logical operations available in Nutmeg. They can
be used in various plot commands, where they return the values 0 (if
the expression was false) and 1 (if the expression was true). Logical
operators use zero or non-zero. You can also use the set of
conditional commands (notably 'if') to make decisions in scripts. See
chapter 9 for more information.

Here is a list of logical operations:

Sym Synonym     Description.

&   and         Logical and. The result of a and b is 1 if both a and
                b are 1.

|   or          Logical or. The result of a or b is 1 if either a or
                b is 1.

!   not         Logical not. The result of not a is 1 if a was 0 and
                vice versa.

There is a number of relational operations. They belong to the group
of logical operations because they return either zero or non-zero,
depending on the validation of the relation. For example, 5 < 8 is
true, and therefore returns 1. Here is a list of operators with their
textual synonyms:

<   lt          Lower than.

<=  le          Lower or equal.

>   gt          Greater than.

>=  ge          Greater or equal.

=   eq          Equal.

<>  ne          Not equal.

Note that it is not possible to compare two complex numbers (either
vector or scalar). Nutmeg will return strange values if you try to do
so. If you want to compare the real or imaginary part of complex
scalars or vectors, use the real() or imag() functions described in
chapter 6.

Textual synonyms are useful if you don't want an expression
containing '<' and '>' characters to be confused with I/O redirection
(which is almost always).


======================================================================
6       NUTMEG FUNCTIONS
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
6.1 List of functions
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
This section describes the functions available in nutmeg. You can use
functions in expressions for calculations on plots, so they are very
important in this respect. These functions have been designed to
operate on vectors of values (data structures containing more values)
and will, in most cases, return a vector of the same length
containing the result.

Here is the list:

mag(vect)       This function returns a vector containing the
                magnitude of each of it's complex values. The
                magnitude is sometimes called the modulus of a
                vector, or in other words, the length of a complex
                vector.

ph(vect)        This function returns the phase for for each element
                of the input vector. The returned argument can be in
                degrees or in radians, depending on the value of
                variable 'units'.

j(vect)         This function multiplies the input vector with i
                (where i has been defined as the number for which i^2
                equals -1).

real(vect)      This function returns the real component of a complex
                vector.

imag(vect)      This function returns the imaginary part of a complex
                vector.

db(vect)        20 * log10(mag(vect)).

log(vect)       The logarithm (base 10) of the vect.

ln(vect)        The natural logarithm (base e) of vect.

exp(vect)       e to the vect power.

abs(vect)       The absolute value of vect.

sqrt(vect)      The square root of vect.

sin(vect)       The sin of vect.

cos(vect)       The cosine of vect.

tan(vect)       The tangent of vect.

atan(vect)      The inverse tangent of vect.

rnd(vect)       Random integer between 0 and the abs(elements) of
                vect.

mean(vect)      The result is the mean of the elements of vect.

vmin(vect)      Returns the minimum of the elements of vect. If the
                input is a complex vector, the results cannot be
                relied upon (as complex vectors cannot be ordered
                like real numbers).

vmax(vect)      Returns the maximum of the elements of vect. If the
                input is a complex vector, the same comment is made
                as for vmin().

vector(num)     This generates a vector of length num. The elements
                of this vector have value 0 to num-1.

length(vect)    The length of a vector is the number of elements that
                is contained in a vector.

timer(dummy)    Returns the number of centiseconds passed since
                program start. It can be used for timing purposes:
                measure the starting time, do what you have to do and
                calculate and output the difference in time.


======================================================================
7       NUTMEG CONSTANTS
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
7.1 List of constants
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
pi              pi.
e               The base of natural logarithms.
c               The speed of light.
kelvin          Absolute 0 in centigrade.
echarge         The charge of an electron.
boltz           Boltzman's constant.
planck          Planck's constant (h).
true            Logical true. This is defined as 1.
false           Logical false. This is defined as 0.

7.2 Using constants
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
You can use constants in any place where you would normally type a
numeric value. Nutmeg will replace the name of the constant with it's
value. Be careful if you want to use true or false in expression.
Minor calculation errors that occur when rounding down numbers can
cause problems when comparing these with true or false.


======================================================================
8       PREFERENCE KEYWORDS
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
These are the keywords that the Nutmeg command pref recognizes.

8.1 List of keywords
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Nutmeg provides a number of text styles when creating diagrams. You
can control font name, horizontal and vertical size, shift horizontal
or vertical, and foreground and background colour.

You can control the text appearance of the text styles used in Nutmeg
diagrams. The text styles you can edit are legend, label and unit.
There are several item for each style you can edit. The style items
can be recognized by the last part of the keyword, and are obvious.

Colour information must be given as three numerical values: one for
red, one for blue and one for green (in that order). Each of them
must be in the range 0 to 255. If you want to calculate the colour
values, use a program like Draw or Paint to find out what colour you
like.

8.1.1 Text styles

Shift factors are in millimetres. They allow you to shift all items
that are created using that style in either x or y direction.

The colour information for text styles can be supplied for either
background or foreground colour.

Font names must not be included in brackets, and parsing is not case
sensitive.

                pref text_legend_fontname fontname
                pref text_legend_sizex pts
                pref text_legend_sizey pts
                pref text_legend_shiftx mm
                pref text_legend_shifty mm
                pref text_legend_fore R G B
                pref text_legend_back R G B
                pref text_label_fontname fontname
                pref text_label_sizex pts
                pref text_label_sizey pts
                pref text_label_shiftx mm
                pref text_label_shifty mm
                pref text_label_fore R G B
                pref text_label_back R G B
                pref text_units_fontname fontname
                pref text_units_sizex pts
                pref text_units_sizey pts
                pref text_units_shiftx mm
                pref text_units_shifty mm
                pref text_units_fore R G B
                pref text_units_back R G B

8.1.2 Grid appearance

You can supply colour information for either the grid, the
subdivision grid and the axes of the plot. You can alter the line
thickness for the axes, the grid and the vectors that are plot on the
grid.

                pref line_grid_width pts
                pref line_axes_width pts
                pref line_plot_width pts
                pref line_grid_col R G B
                pref line_subgrid_col R G B
                pref line_axes_col R G B

8.1.3 Line style information

The line styles are used for vectors. There are only used if pref
nodash is not defined. you must supply 4 values for each dash style.
The first is the style number in the range 0 to 11 (there are 12
styles). The second is the so called 'used' flag which can be
non-zero or zero, depending on if you would like to use the style or
not. The last two items are the multiplication and division factors.
They are currently unimplemented, and should therefore be set to 1.

                pref dash_style stylenum usedflg mul div

8.1.4 Line colour information

The line colour information is used for vectors. It only has effect
if variable monochrome is not defined. The format is pretty much the
same as for dash styles. You have to supply the style number in the
range 0 to 13, a 'used' flag, and the Red Green and Blue factors for
the colour. You can customize the set of colours you would like to
use if the default values don't match your taste.

                pref cols_style stylenum usedflg R G B

8.1.5 Miscellaneous preferences.

This list contains a number of preferences that control the size of
the time slices, the number of poll cycles per time slice,
information whether or not the nutmeg window should force itself on
top, whether or not to read the news file, whether or not the window
should open on start-up, the size and position of the nutmeg window,
whether or not to use dash patterns, and the size of the diagrams.

                pref timeslice centisecs
                pref cycles cyclenum
                pref keepontop flag
                pref readnews flag
                pref autoopen flag
                pref clipos xpos ypos
                pref clisize xsize ysize
                pref nodash flag
                pref graphsize xmm ymm


======================================================================
9       NUTMEG COMMANDS
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
9.1 List of commands
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
9.1.1 Input commands

load filename ...

                This command loads the raw data in either binary or
                ascii format into the internal Nutmeg database.
                Simulation results will be stored in plots, and the
                simulated results for each node in the circuit will
                be stored in vectors. You can supply more than one
                filename, which will cause Nutmeg to load in all
                named files. Files should be stored in
                <Spicework$Dir>.raw.

source filename

                Reads commands from the file filename. Lines
                beginning with the character * are considered
                comments and are ignored. This command is a remainder
                of ASpice, and should be considered redundant in
                Nutmeg. Instead, use the load and script commands to
                either load in raw files or execute a script.

script file     Run a Nutmeg script file. Script files should be
                located in one of the script directories mentioned in
                chapter 2.7.2. Script files can contain any valid
                Nutmeg command, so you can use them to automate
                certain operations or change the settings of some
                variables.

9.1.2 Output commands

9.1.2.1 File

write file exprs

                Writes out the expressions to the 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.

9.1.2.2 Tables

print [col | csv] 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.

                If the csv argument is present, data is output in
                comma separated values format. The first value will
                be de index into the vector. Complex data will be
                output as 'real , imag'. This output mode enables you
                to export Spice data to foreign data analysis
                packages, spreadsheets and graphics software.

9.1.2.3 Draw graphics

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.

9.1.2.4 Ascii graphics

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 or output device with output redirection
                i.e, 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 simpleminded sort of linear
                interpolation.

9.1.3 Database manipulation commands

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. In addition, one vector will be labelled
                '[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 separate and only shows you the vectors in
                the currently selected plot.

destroy[plotname ... ] [ all ]

                Throw away the data in the named plot and reclaim the
                storage space. This can be necessary if a lot of
                large simulations are being done. If the argument to
                destroy is all, all plots except the constant plot
                will be thrown away. It is not possible to destroy
                the constant plot. If no argument is given the
                current plot is destroyed. Use with care.

killvect vector [ ... ]

                Kill the specified vector. You should type the name
                of the vector explicitely. It is possible to specify
                more than 1 vector. You cannot use the
                plotname.vecname construction, and Nutmeg will not
                complain if a vector does not exist. Use with care.

9.1.4 Environment commands

echo [stuff]    Print stuff directly to the output window. It is
                useful if you want to output descriptive text in a
                nutmeg script.

cd [directory]  This command changes the working directory. You will
                probably never need it, as almost everything in
                Nutmeg works with the currently selected working
                directory.

cat [leaf name] Catalogue the contents of the current work dir. If
                you do not specify a leaf name, Nutmeg will display
                all files in the .In directory together with
                information on similar named files in the .Raw
                directory. You can enter any leaf name after the cat
                command. For example, cat Script will cause Nutmeg to
                display all files behind directory
                <SpiceWork$Dir>.Script, provided that one exists.

shell [args]    Fork a shell, or execute the command. It will simply
                call the supervisor using *Gos. If you want to know
                more about he *Gos command, then see the RISC OS user
                guide.

type file       Type the specified file. If you want to include a
                RISC OS variable containing a path (e.g. type
                <SpiceWork$Dir>.In.RTLinv) you should use single
                quotes around the file specification to avoid
                confusion with I/O redirection.

9.1.5 Calculation commands

diff plot1 plot2 [vector ...]

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

fourier [vect] fund_freq 'all' | vector ...

                Do 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 variables). The output is like that of the
                .four card. The values may be any valid expression.
                If the keyword vect is supplied, output will be
                stored in a plot. This allows you to do calculations
                on it, and plot it.

9.1.6 Conditional commands

if <expression> then <command>

                execute a command if the result of the expression is
                greater than 0. In other words, this expression is
                true. If you want to execute more than 1 command
                depending on the result, you can either repeat the if
                command several times, or execute a script that
                contains the commands.

ifdef '<var>' '<command> [tail ...]'

                execute command if var has been defined. Note that
                the quotes must be actually typed to avoid problems
                with non-existing variables.

ifundef '<var>' '<command> [tail ...]'

                execute command if var has not been defined. Note
                that the quotes must be actually typed to avoid
                problems with non-existing variables.

9.1.7 Query commands

queryload file

                This command parses a query file. Queries can be used
                to alleviate interacting with the user and to provide
                a nice looking front end for nutmeg commands. A query
                description file contains the query box identifier
                and a number of definitions for static text, boolean
                buttons, writable icons and hot buttons (action
                buttons). When an identifier is found that already is
                being used, the old definition is killed and the new
                box loaded.

                The file is first searched for in
                <SpiceWork$Dir>.Query, then in SpiceResource:Query
                and finally in <Nutmeg$Dir>.Query.

queryopen id

                Open the specified query box at the current mouse
                pointer position. This will also close all other
                query boxes. The id is the name found in the header
                of the query box definition (e.g. 'query_plot').

querykill id

                Remove the specified query box from memory. If you
                reference a query box that has previously been
                deleted from memory or that never has been defined
                before, nothing will happen.

querylist

                Output a list of currently loaded query boxes. The
                information includes the identifier of the query box,
                whether it has been opened or close, and the text
                that would appear in the title bar of the window.

queryclose

                Close the opened query box. If no query box is open,
                nothing will happen.

9.1.8 'Set' command

set [option] [option = value] ...

                Set a variable. There are several possible variable
                types, each of which can be set using a different
                syntax. Typing just plain set without any parameters
                will output a list of all defined options to the
                screen. If you would like to set a boolean variable,
                then use the set option syntax. This will create a
                variable of type bool with name option. If you use
                the set option = value syntax, then Nutmeg will
                create a string or real variable with value value.
                You will have to use single quotes in order to assign
                a string value to a variable. If a variable does not
                exist, then the variable will be created. If the
                variable does exist, then the old value and type will
                be discarded and set to the new value.

unset varname ...

                Unset a variable. You can unset more than one
                variable using one single command. Variables can be
                of any type.

9.1.9 'Pref' command

pref item <opt1> [opt2 .. opt5]

                Set various nutmeg preferences that cannot be set
                with the set command, typically settings that are not
                likely to change very often. See chapter 8 for
                further information.

9.1.10 Miscellaneous commands

bspice [input file]

                Start a remote batch Spice job. !BSpice must be
                active, or nothing will happen at all. The generated
                raw file will not be loaded in automatically, so you
                will have to do so yourself using the load command.

help [item] ...

                Print help on a subject. The subject can be any valid
                command, or one of the following keywords: commands,
                functions, operations, variables, constants, authors.
                These special keywords will give you short
                information, just to remind you of their syntax or
                functional use. For full documentation you should
                refer to this document.

history [number]

                This will print the history of commands (last number
                events).

version [number]

                With no arguments, this command prints out the
                current version of spice. If there are arguments, it
                compares the current version with the given version
                and prints a warning if they differ. A version
                command is usually included in the rawfile.

define function(arg, ...) expression

                Define the macro with the name function and with
                arguments arg, ... 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 definitions for function are
                printed, and if there are 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 gt y) * x + (x le y) * y

                define min(x,y) (x lt y) * x + (x ge y) * y

undefine [word ...]

                Remove all the macro functions defined for the words.
                If the argument is "*", then all macro functions are
                deleted. Note that all functions with the given names
                are removed, so there is no way to delete a function
                with a particular arity without deleting all
                functions with that name.

let vecname = expr

                Create a vector with name vecname and value given by
                the expression expr. None of the vector options such
                as default scale and colour that are read from the
                rawfile are preserved when a vector is created in
                this manner.

quit            This command quits Nutmeg. Note that you will not be
                asked for confirmation, so use it only if you are
                certain you saved all diagrams.

rusage          Print current resource usage. This includes memory
                available and execution time.

9.2 Aliases
¯¯¯¯¯¯¯¯¯¯¯
You can set up an alias for a command if you are not happy with the
name of the present command or if you want to include some default
parameters. You could for example introduce an alias 'ff' for the
fourier command, and an alias 'ffv' for the fourier command with
redirection to a vector. All this can be done using the 'alias'
command:

alias [[word] alias]

                Define an alias. If you given no arguments to alias,
                a list of currently defined aliases will be output.
                If you specify one argument, then Nutmeg will look up
                that argument in the alias list, and if it exists,
                the alias definition will be printed. If more than 1
                arguments are specified, the first one is treated as
                the name of the new alias that is being defined.
                Every time you enter a command that is known as an
                alias, the rest of the arguments you have given is
                substituted, and normal command parsing of the
                command execution continues. Note that you can use
                another alias inside an alias definition. If your
                alias definition is badly formed, you can get
                infinite loops. Nutmeg catches these and reports an
                error if this happens.

unalias word

                undefines the alias that can be identified using the
                specified argument. If no such alias exists, nothing
                happens.


======================================================================
10      'HOW TO..' SECTION
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
This chapter contains various tips and suggestions for dealing with
standard problems.

10.1 Scripts
¯¯¯¯¯¯¯¯¯¯¯¯
10.2 Query boxes
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
10.3 Calculation
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
10.4 Conditional execution
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

======================================================================
A       KNOWN PROBLEMS AND BUGS
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
A.1 Limitations
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Nutmeg does not feature a full programming language. You can create
simple command scripts using the internal commands, but you can not
create repeating constructions.

Nutmeg can not print directly. We will include this facility in the
future (using some routines written by Peter Roozemaal).

A.2 Annoyances
¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Nutmeg does not complain if you have unsaved data and you want to
quit. You will simply lose all unsaved results and diagrams. However,
you can reconstruct a session using the file !Nutmeg.Script.Logfile.
Rename this log file and start Nutmeg. Then execute the log file
using the script command. Note that this will not work properly if
you have changed the current work directory during a Nutmeg session.

A.3 Real bugs
¯¯¯¯¯¯¯¯¯¯¯¯¯
Sometimes, when you mix complex and real vectors, Nutmeg will crash
displaying the error 'free failed'. This is a real bug.

Loading binary raw files does not work reliable. Do not use it for
the moment.

The 'insert' item in the CLI window menu tree has been shaded due to
dome serious problems with the RISC OS libraries.


======================================================================
B       WORK DIRECTORIES
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
B.1 Usage
¯¯¯¯¯¯¯¯¯
B.2 Creating
¯¯¯¯¯¯¯¯¯¯¯¯
B.3 Maintenance
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

======================================================================
C       FILE FORMATS
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
C.1 Ascii raw files
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
The ascii output file format is provided to make it easy to modify
data files and transfer them between machines with different
floating-point formats ie. other than the Archimedes' floating point
format. You can transfer raw files in ascii format from one
architecture to another without any trouble.

The format is as follows:

        Title: Title Card String
        Date: Date
        [ Plotname: Plot Name
            Flags: complex or real
            No. Variables: numoutputs
            No. Points: numpoints
            Command: nutmeg command
            Variables:  0 varname1 typename1
                        1 varname2 typename2
                        etc...
            Values:
                0 n n n n ...
                1 n n n n ...
            And so forth...
        ] repeated one or more times

If one of the flags is complex, the points look like r,i where r and
i are floating point (in %e format, that is, in scientific notation).
Otherwise they are in %e format. Only one of real and complex should
appear.

The lines are guaranteed to be less than 80 columns wide (unless the
plot title or variable names are very long), so this format is safe
to transfer between systems like VAX/VMS, IBM OS/2, UNIX etc. using
ftp, e-mail, kermit or simply swapping floppies or streamer tapes.

Any number of Command: lines may appear between the No. Points: and
the Variables: lines, and whenever the plot is loaded into nutmeg
they will be executed.

C.2 Binary raw files
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Binary format is the preferred output format for general use, as it
is the most economical in terms of space and speed of access. The
format is as follows:

        Title Card                      (a NULL terminated string)
        Date, Time                      (a NULL terminated string)
        [
            Plot title                  (a NULL terminated string)
            Number of variables         (an integer)
            Number of data points       (an integer)
            flags                       (a short integer)
            variable header struct      (repeated numoutputs times)
                variable name           (a NULL terminated string)
                variable type           (an integer)
            set of outputs              (repeated numpoints times)
        ] repeated one or more times.

A set of outputs is a vector of doubles of length numoutputs, or a
vector of real and imaginary pairs of doubles if the data is complex.

Note that such files can hardly be created them using a text editor.
Format is very strict and can best be handled by specialised
programs.

C.3 Scripts
¯¯¯¯¯¯¯¯¯¯¯
Scripts are normal text files. You can enter valid Nutmeg commands
(on separate lines) or use the comment character * or |. Blank lines
are stripped. Any command that you can enter from the Nutmeg command
line may be used inside Nutmeg script files. You can execute a script
using the script command.

C.4 Query boxes
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Query boxes can be created using a normal text file. There is a set
of 6 keywords that control the creation of query boxes. Note that all
keywords should start in column 1. This means that you should not
leave any spaces in front of a keyword.

C.4.1 Box definition

You can define several query boxes in one file. Each query box
consists of a box definition and number of items inside the body of
the box definition. A box definition is as follows:

        defbox box_identifier 'Title string'

        item description

        endbox

C.4.2 Box items

Inside a box definition can be a number of items. The query box is
created using these items. In fact, each items will represent an icon
in the query box.

All identifiers are case sensitive.

The items are:

boolean varname xpos ypos keycode

                Create on/off switches. varname is the name of the
                variable that will be set or unset depending on the
                state of the button. xpos and ypos are the
                coordinates of the bottom left corner of the button.
                keycode is the wimp keycode that can be used to
                toggle this switch. If you do not want to use any key
                short-cut, you should supply -1 as a value.

hotbutton 'command string' xpos ypos keycode 'text'

                Create action buttons, that will cause a command to
                be executed and the box to be closed. 'command
                string' is the string of the command that should be
                executed when this button is activated, enclosed in
                single quotes. xpos and ypos are the coordinates of
                the bottom left corner of the button. keycode is the
                wimp keycode that can be used to activate this
                button. If you do not want to use any key short-cut,
                you should supply -1 as a value. 'text' is the Text
                you would like to appear in the icon, enclosed in
                single quotes. The length of this text should not
                exceed 11 characters!

static xpos ypos 'text'

                Create static text for informational purpose only.
                xpos and ypos are the coordinates of the bottom left
                corner of the text field. 'text' is the text you
                would like to display on screen. The length of this
                text is restricted to 250 characters, which should be
                more than enough.

staticpict xpos ypos 'name'

                This will put a sprite (that should be in the
                'IconPicts' sprite file) with it's left bottom corner
                at position xpos,ypos. It can be used to make the
                query box look nicer, or to underline the character
                that corresponds to a hot key. See the standard query
                box description file for more information.

string varname R/C/P/V/S/I xpos ypos width length

                Create a writable icon where you can enter text.
                varname is the name of the variable where you would
                like to keep the contents of the icon in. xpos and
                ypos are the coordinates of the bottom left corner of
                the writable icon. width is the width of the writable
                icon. length is the size of the buffer. The meaning
                of the characters after varname is as follows:

                R   This writable icon can contain a real number.

                C   This writable icon can contain a complex number.

                P   The writable icon can contain the name of a plot.

                V   The writable icon can contain the name of vector.

                S   The writable number can contain any string.

                I   The writable icon can contain an integer.

C.5 Smart Icon description file
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
This file format is very straightforward. There can at most be one
Smart Icon description file, which is read in when Nutmeg starts.
This is the !Nutmeg.Icons file.

There is a number of keywords that you can use to describe the icon
bar. Here is the list:

        |   comment
        command spritename commandstring
        gap distance

The order in which the icons are created is the order in which they
appear in the description file. The special keyword gap allows you to
create some space between groups of icons that belong to each other.
The distance units are OS units.

Note that all keywords are case sensitive.


======================================================================
D       TUTORIAL
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
This is a simple tutorial, which should be seen as an introduction to
working with the Spice environment we have made for the Archimedes.

The reader is assumed to be familiar with the Spice netlist format,
and the process of generating this netlist.

It will be shown how to generate plots and do calculations from
within Nutmeg. We will use some example circuits that can be found in
the !General work directory.

D.1 Starting up
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Double-click on the !BSpice and !Nutmeg icon in the filer window to
start these applications. The Nutmeg window will open. Make sure the
!Resources application has been seen by the filer. If !Resources
resides in the same directory as !BSpice and/or !Nutmeg this is not a
problem.

Activate the work directory, in our case !General, by double-clicking
on it. A window with the directory contents of the in directory
together with a information box will be opened.

If you want a hardcopy of a generated plot on you printer: a RISC OS
printer driver must be installed, and Draw should have been seen by
the filer.

D.2.1 Example 1:MOS output characteristics

In this example will make a plot of the output characteristics of a
MOS-FET device. We will use the 'MOSoutput' file in the !General work
directory.

If you type 'cat' or click on the floppy icon in the !Nutmeg window,
a directory catalogue will be printed. As we expected, out circuit is
present.

Start now the simulation. There are multiple methods for starting the
simulation.

      * Type 'bspice MOSoutput' in the Nutmeg input line

      * Click on the 'S' icon in Nutmeg. A query box will be opened.
        Type 'MOSoutput' in the 'Input file' field. Click 'Go!' or
        press return to start the simulation.

      * Drag the MOSoutput file onto the !BSpice icon on the icon
        bar.

      * Click on the !BSpice icon on the icon bar, a dialog box will
        open. Type 'MOSoutput' in the 'Input file' field, or drag the
        MOSoutput file onto the dialog box. You can also set runtime
        options for BSpice in this box. Toggle the 'Log file' button
        to enable or disable saving of runtime messages to the log
        directory (which resides in the work directory). Toggle the
        'Quiet' button to disable status display while running.

The results of the simulation are stored in the raw directory behind
the work directory. After the simulation is finished you are prompted
to press space to continue.

If you type 'cat', you will see that Nutmeg has detected the presence
of the simulation results.

Type 'load MOSoutput' to load the results.

Type 'display' to find out what vectors are available for further
processing.

We will use vector 'vids#branch' (current flowing through 'vids') for
our output characteristic.

Generate the plot of the output characteristic: type 'plot
vids#branch', or click on the plot icon (the pencil) and substitute
the desired vector, 'vids#branch' in the vectors field. Click on the
'plot' button start plotting.

A window with a draw diagram within it will open. In it are 6 curves,
the one at the bottom displays the drain source current versus drain
source voltage, with a gate source voltage of 0 volt. The one at the
top displays the drain source current versus drain source voltage,
with a gate source voltage of 6 volt.

You can magnify the trace with the zoom box in the viewer menu. Use
the save box to save the diagram to ArcDraw, DrawPlus or Vector for
further placing annotations. You can also drag it into your DTP
program, a filer window to save it, or the printer driver to print
it.

Type or click quit to exit nutmeg of you want to exit.

Enjoy!


======================================================================
E       Table of figures
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
fig.    Name    Description

1-1     ?       schematic overview Spice and Nutmeg environment
2-1     ?       picture of Nutmeg main window