--------------------------------------------------------------------------
                !Numeric (v1.04)  --   Graham Hick, 1995
--------------------------------------------------------------------------

=== 1. Introduction ======================================================

This program is a combination of my previous programs !Integrate (v1.03)
and !Diff (v1.01), which, as you might expect, allow you to calculate
integrals of functions on bounded intervals, and also derivatives of
functions, at a point. It also contains modules for solution of equations
(Newton-Raphson method) and summation of series.

To use the program, click Menu on the icon-bar icon, and select the part
of the program you want to use. Type the function and relevant value(s)
into the boxes, and then click on the "Calculate" button (or press Enter
when in the last writable icon) to do the calculation. All answers are
given to 5 significant figures.


=== 2. Expression syntax =================================================

Because the program uses BASICs EVAL function, the function and values
must be in a form that BASIC can understand, e.g.

			      3*x rather than 3x
			1/(cos x) rather than sec x
			(sin x)^2 rather than sinx

Upper or lower case can be used throughout. The constants 'Pi' and 'e' can
be used in the function or values - just type 'pi' or 'e' respectively.
Also, factorials can be calculated, by typing 'FNfact(n)' for n!. 


=== 3. Notes on calculation ==============================================

3.1 Integration

    Numerical integration is performed using "Simpson's Rule". The number
    of strips used is given in the options window (see later). Remember
    that if you want something sensible to happen, make sure your function
    is integrable. If you try and integrate 1/x from -1 to 1, you're
    asking for trouble. Trapping this kind of thing is inherently very
    difficult in a numerical system, since it's not possible to sample
    every point in the domain. If some sort of singularity happens, the
    program may or may not find it, depending on exactly where the sample
    points fall. Try integrating 1/x from -1 to 1.001, and you should see
    what I mean.

3.2 Differentiation

    The derivative at a point is found by calculating the slope of closer
    and closer interpolation lines. It is now pretty robust, and
    pathological things like the perennial favourite sin(1/x) should
    always be handled correctly. If "--" is given as the answer, the
    derivative doesn't exist - for example f'(0) where f(x)=abs(x).

3.3 Summation

    The sum is calulated how you might expect - by adding up all the
    terms. You can put "inf" as the upper limit, to calculate an infinite
    sum. As with differentiation, if "-" is given as the answer, the sum
    does not converge. Note the factorial function described in section 1.

3.4 Solution

    Given an initial "guess" the iterative Newton-Raphson method is one of
    the best ways of finding a solution to an equation of the form
    f(x)=0. For instance, to find the cube root of 7, give f(x) as
    x^3-7. Note that only real solutions are found - and you don't
    always get an answer when f(x)>0 around the expected root (for
    example, try f(x)=x^2).


=== 4. Options ===========================================================

The Options window allows you to customize some of the features of the
program:

4.1 Initial Windows

    Firstly, the windows to be opened on startup can be selected in the
    top section of the window.

4.2 Accuracy settings

    More usefully, perhaps, you can set various threshold values used in
    various bits of the program:

    4.2.1 "Snap to zero" exponent

        This number represents the smallest number not to be pulled to
        zero. Because of the way floating point works, you sometimes find
        (although not so much with BASIC64) that an expected answer of
        zero will actually come out as something like 1.27E-9, which you
        don't want. The default value of this parameter is -8, meaning
        that anything with absolute value less than 1E-8 will be shown as
        zero.

    4.2.2 Integration strips

        The number of strips to use when applying Simpson's Rule to find
        an integral. The default is 128. The value can be given in
        "scientific notation" (e.g. 1E5) if necessary.

    4.2.3 Derivative convergence exponent

        When calculating a derivative, the program stops when two
        successive approximations come within a certain distance of each
        other. The default value is 1E-10 - i.e. exponent -10.

    4.2.4 Summation convergence exponent

        Similarly, this is the distance that two successive approximations
        must come within, in order for an infinite sum calculation to
        stop. The default is -7.
        
    4.2.5 Summation iteration limit
    
        This is the maximum number of iterations to carry out in an
        infinite sum calculation, before giving up. The default is 8000.

    4.2.6 Solution convergence exponent

        Finally, the same as 4.2.3 and 4.2.4, for the Newton-Raphson
        calculation. The default is -8.

4.3 Saving or ignoring the changes

    Press the Cancel button to close the window and forget any changes
    made to the settings since it was opened. Press the Close button to
    update the settings, and press Save to also save them to disc (so they
    will be loaded next time).


=== 5. Misc program notes ================================================

5.1 3D templates

    This release only contains 3D-style templates, so it only works
    completely right in RISC OS 3.10 or later. It should, however, still
    work OK in RISC OS 2, but the writable icons may look too big. I'm
    sorry about this, but I found developing two sets of virtually
    identical templates too much of a pain. If you don't like this, then
    please tell me!

5.2 Hi-res sprites

    If you are in a high-res mode (i.e. 1:1 pixel aspect ratio) when the
    program starts, it will load high-resolution versions of the sprites
    which it uses. As I can't use all screen modes (I only have a VGA
    monitor) and I haven't tested it with third-party screen modes (such
    as those provided by whizzy graphics cards) I can't guarantee that
    this works with your set-up. If it doesn't, then please let me know,
    and tell me what screen mode(s) you are using, so I can figure
    something out.

5.3 BASIC64

    If the operating system version is >= 3, Numeric will attempt to use
    BASIC64, which should be in the System: path. This gives far higher
    accuracy than the usual BASIC.


=== 6. Version history ===================================================

1.00 (Date unknown)

  * First release version, with Integrate and Diff integrated (sorry...)
    into one package.

1.01 (15 Apr 1994)

  * Added Newton-Raphson solver, and summation.
  * Changed window layouts slightly.
  * Wrote better(?) documentation.
  * Added 3D templates and new sprites.

1.02 (21 Sep 1994)

  * Revised the templates (thanks to Colin Turnbull for some helpful(?)
    comments on this!).
  * Nicer icon-bar menu.
  * Fixed cursor up/down bugs.

1.03 (12 Apr 1995)

  * New app icon.
  * Added options window and file.
  * Added interactive help support.
  * Changed to BASIC64.
  * Improved differentiation routine.
  * Added infinite series capability.
  * Improved the error handlers.
  * Expanded and reformatted this help file.
  
1.04 (09 Oct 1995)

  * Proper message list passed to Wimp_Initialise
  * Added summation iteration limit to options window, for slowly-
    convergent sums such as a[n] = n^(-2).
  * Improved the error handlers slightly again.


=== 7. Future changes ====================================================

These are reasonably ambitious changes which may get done one day,
depending on time and motivation, and particularly dependent on whether
anyone uses this program at all at the moment...

  * I'd like to be able to do integration over unbounded intervals. This
    should be possible, by testing for convergence with repeated
    approximations.

  * Do a pre-parser, to take into account mathematical notation (as
    opposed to BASIC's more limited format). Alternatively I may abandon
    EVAL altogether, and write a completely new parser (It's a bit of a
    kludge at the moment, as you might notice...). But then again, I might
    not bother...


=== 8. Credits ===========================================================

I wrote this program, hence no-one else should get the blame for it.

However, I would like to thank various people for comments and advice:

  * Colin Turnbull for comments(!) about template design;

  * Peter Killworth for pointing out some series which didn't get the
    right answer (or any answer at all);

  * Michel Grimminck for letting me look at some interesting numerical
    analysis routines.

More generally, thanks to:

  * Dominic Symes, author of the extremely good editor Zap. If you have
    never used Zap, you really have missed out. It's free, it's fast, it's
    got syntax-colouring for BASIC, Assembler, C and Pascal, configurable
    keymaps, plus bucket-loads of other exciting features.

  * Dick Alstein for !TemplEd, a very good template editor (far better
    than Acorn's !FormEd ever was).

  * The various people of RISC User magazine who wrote the various series
    on WIMP programming - your code was extremely helpful, especially as I
    have no PRMs. Similarly the various readers of comp.sys.acorn.* who
    have answered my queries over the years.


=== 9. Copyright? ========================================================

This program is "Freeware". As far as I am concerned, this means that you
can distribute it to anyone and everyone, PROVIDING that all files within
the !Numeric directory are included in their original form, and you don't
make any profit from distribution.

If you feel that you could do better, please send your improvements or
suggestions to me (see below) rather than distributing them all over the
place, as this can lead to large amounts of confusion.


=== 10. Contact ==========================================================

Well done. You have found the interesting bit at the end of the
documentation - how to insult the author. Seriously, software developers,
whether professional or unpaid, always desperately need feedback from
users. So if you have ANY comments, suggestions, improvements or bugs to
report, then PLEASE PLEASE PLEASE do not hesitate to get in touch with me:

Paper-mail: 38 Rocks Lane
            Barnes
            London SW13 0DA
            United Kingdom

E-mail:     gjmh@doc.ic.ac.uk (until September 1996)

All communication WILL be replied to. Thank you for your attention.


--------------------------------------------------------------------------
                !Numeric (v1.04)  --   Graham Hick, 1995
--------------------------------------------------------------------------
