Complex Math Functions for ACE
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 - For your enjoyment, I present four functions providing complex number
manipulation in ACE.  These four functions are accessed by linking in
the complex module and including a complex header file, more on this in
a bit.  Currently the only math functions are add, divide, multiply and
divide.  I would very much like to add to this meager list, but I am at
the limit of my mathematical knowledge. :(    I would welcome any and
all hints and suggestions!

 - Usage:

     - You must include 'complex.h' in your program, i.e.
          #include "complex.h"

     - This header file links your program to some math libraries and
     declares a structure called Complex.  The structure has two
     elements; 'real' and 'imag', and must be used to declare your
     complex variables, e.g.
          DECLARE STRUCT Complex z,c,r,*d

     - Variables declared as above are then passed to the functions as
     described below.  Each part of the complex number can be directly
     manipulated through the structure, e.g.
          z->real = 2.75 : z->imag = -3.0

     - All four functions require three variables of type 'Complex'
    to be passed to them.  The four functions are as follows:

     AddComp(first,second,result)
          result = first + second
          
     SubComp(first,second,result)
          result = first - second

     MulComp(first,second,result)
          result = first * second

     DivComp(first,second,result)
          result = first / second

     - Each function can be used by itself, as in:
          DivComp(c,z,r)
          AddComp(r,c,z)

     as part of an expression, as in:
          d = MulComp(z,z,r)

     and as part of an imbedded expression, as in:
          z = AddComp(MulComp(z,z,r),c,r)
       
     (which is the same as z = z^2 + c).

     - You must link 'complex.o' with your program when you compile
     or you will get errors!  A small program, 'make', was written
     by David Benn to allow easy compilation, just type 
          make filename.b
     and everything is taken care of for you (as long as complex.o and
     complex.h are in the same directory!).
 

 - I have included two sample program that make use of these functions.
     'mandel.b' will open a 400x400 window on your wookbench and draw the
standard mandelbrot, with a bit of a twist in the color selection.
     'fractal.b' also opens a 400x400 window, but this one draw an inverted
mandelbrot, defined by the complex iteration of z = z^2 + 1/c.  This program
also illustrates how to mix complex and real data types, you cheat!  I may
add a function that will accept one complex and one real and return the
complex answer, but who knows?
     To try it out, just type 'make mandel' and then run 'mandel' after it's
been compiled.  You can break out of the program at any time with a CTRL-C.
When the program finishes drawing the fractal, it waits for you to press
return, then cleans up and exits.  'fractal' works exactly the same, but
it takes a bit longer to render.  Fair warning!

 - Wish list...  I'd really love to be able to add a PowComp() function that
would return the result of one complex number raised to the power of a second
complex number, but as I said, that's beyond my mathematical experience.  If
anyone knows how to accomplish this and/or other useful complex number
manipulations, please send them on to me along with your comments.

 - Thanx goes to David Benn: as always for his great ACE compiler, and also
for his help in converting these functions to sub and object modules.
 

 - Rich Allen (rico@wsnet.com)
21 Sep 1995