Summary of newton, a code to
                     ----------------------------
                       implement Newton's method
                       -------------------------

Created by two sections of the
course Programming with C++
January 2005

Abstract
--------
    Newton's method is implemented in a code called newton.  The
program reads a starting vector (x) from a data file.  The function
(F) whose zero-point is sought is defined in a subroutine as is its
Jacobian (DF) in a separate subroutine.  The arrays storing the
starting vector, the function and its Jacobian are defined globally
and dynamically.  Since the dimension (n) of these arrays is also a
global variable, the code can readily be adapted to other functions.
The starting vector is overwritten with an update in the Newton
iteration, and thus this vector is used also for the final solution to
the zero-point problem.  The Newton iteration is terminated when a
relative error criterion is met or when the number of iterations
exceeds a limit.  The relative error theshold (tol) and the maximum
number of iterations (imax) are read from a data file as input.  Once
the solution is found within the specified accuracy, the result is
written to a data file, and the number of iterations (maxi) required
to find it is written to a separate data file.

MyProgram from a User's Perspective.
-----------------------------------
    There are two input files for newton: data.in, which contains the
initial vector, x[i], i=0,(n-1), and newton.in, which contains the
input parameters tol and imax.  There are also two output files for
newton: data.out, which contains the solution vector, x[i], i=0,(n-1),
and newton.out, which contains maxi.  The format of the input and the
output can be altered in init and in term.  All data files are text
files and can be written or read with a usual text editor.

Input File:  data.in
--------------------
    The input file data.in is a text file with the following format
which can be seen in init:

          x[0]
          x[1]
          ...
          x[n-1]

where x is a pointer to double, and its elements are established
dynamically.  Note that n and x are global variables.

Input File:  newton.in
----------------------
    The input file newton.in is a text file with the following format
which can be seen in init:

          tol
          imax

where tol is double and imax is unsigned long.  Note that tol and
imax are global variables.  tol is used in the stopping criterion:
          ||dx|| <= tol * ||x||
where the Newton iteration involves the solution to the linear
system:
          DF dx = -F,     x = x + dx
imax is used in the stopping criterion:
          (maxi+1) > imax
where (maxi+1) would be the number of the next iteration.

Output File:  data.out
----------------------
    The output file data.out is a text file with the following format
which can be seen in term:

          x[0]
          x[1]
          ...
          x[n-1]

where x is a pointer to double, and its elements are established
dynamically.  Note that n and x are global variables.  Since data.out
and data.in have the same format, data.out can be copied to data.in
to restart the code and to perform further iterations.  If the values
in data.out are excessively large it is likely that the Newton iteration
with the specified initial vector is divergent.  In this case another
starting vector should be selected.

Output File:  newton.out
----------------------
    The output file newton.out is a text file with the following format
which can be seen in term:

          Number of iterations performed: maxi

where maxi is unsigned long.  Note that maxi is a global variable.
If maxi = imax holds, then the following warning is written to
newton.out:
          WARNING:  The number of iterations performed
          has reached the maximum allowed.  Increase imax
          or tol or seek a nearer starting vector.

Standard Output:
----------------
    Only error messages are reported on the screen, and these may occur
when files are not correctly handled.

Compilation
-----------
    The makefile groups the (object-oriented) functions together in
SCR1 which do not depend upon the global variables but rather only on
their local constructions.  All other functions are grouped together
in SRC2 as they all depend upon the include file INC = newton.hpp
which contains the prototypes and extern statements.  Note that all
global variables are declared, and established dynamically as
necessary, in newton.cpp.  The object files of SCR1 are grouped
together in OBJ1 and the object files of SCR2 are grouped together in
OBJ2, so only OBJ2 depends upon INC.  The executable file newton.exe
depends upon the OBJ1 and OBJ2 files.  The executable is built by
typing "make all".  The directory can be cleaned by typing "make
clean".