Power-Programmierung/CD2.mdf/c/library/dos/math/anum/anum.txt

Text File | 1991-11-26 | 16.2 KB | 472 lines

           DISCLAIMER - LICENCING AND SUPPORT POLICY



   This documentation is dated as of November 26, 1991.


      ** PLEASE DO NOT SEND MONEY FOR THIS PACKAGE **


   This is  NOT shareware! ANUM is good old fashioned Public
Domain Software.  Source code,  totally written with Borland
C++ 2.0  is not  included with  this archive for the reasons
developped in the next section.


   With release  5 here  are the Borland C++ 2.0 and Turbo C
1.5 ANUM  library files.  Actually, tests  have shown so far
the application  code could  link with no major problem with
TC++ standard  libraries. However,  for an  unknown  reason,
execution time seems to be increased by nearly 10%.


   Turbo C  2.0 version is again delivered back with release
4 of ANUM. I had to remove TC 2.0 from my previous hard disk
to gain space. But as I have also changed of disk since them
(from 40 Mbyte  to 334 Mbyte)  I am  able  to  support  both
versions. I  have not  forgotten the  (not so  far ago) time
when I was a student not earning a single coin, and for whom
the buying  of a  compiler meant months of restrictions. The
TC 1.5  version is  planned to be supported until the end of
the year  while the TC 2.0 is until the end of 1993 and TC++
version until  the end  of 1995.  (I presume that after five
years of  existence, these  products may  be  considered  as
obsolete).


   While the  provided  functions  have  been  passed  to  a
minimal test,  I will  have no liability or responsibilty to
the user  or any  other person or entity with respect to any
liability, loss  or damage  caused, or  alleged to be caused
directly or  indirectly by  this library, including, but not
limited to,  any interruption  of service, loss of business,
anticipatory profits or consequential damages resulting from
the use of this program.


   Furthermore, although  this program  has been placed into
the public  domain, I  retain all copyrights to this library
around the  world. Pursuant to this, this library MAY NOT BE
SOLD BY  ANY PARTY  unless specifically  authorized  by  the
author, Jean-Marie  de Montarby,  in writing  prior  to  the
first copy  being sold.  As well,  this program  MAY NOT  BE
INCLUDED IN  OR USED  TO PRODUCE  ANY OTHER PACKAGE FOR SALE
even if  this program  is indicated  as being 'in the public
domain'. All  of the  above applies  to both the original as
well as  derived or  modified copies  of the  original.  Any
modified  copies   of  this   library  MUST  NOT  have  this
documentation -including  its  copyright  notice-  violated,
changed or altered.


   Occasionally, if you want to use ANUM, or a port of it to
some other  computers, in a commercial product, take contact
with me first. We will perhaps find a deal.


   Thus this  library, as  delivered here,  may only be used
for personal and/or research and/or educational purposes.


   Comments, bug  reports and  improvement  suggestions  are
welcome and  should be adressed only to me. I can be reached
at the following adresses:

Electronic mail: JMMàFRESTP11.BITNET (until... ?)

Normal mail : M. Jean-Marie de Montarby
               40 avenue des Tilleuls
               75016 PARIS
               FRANCE


   Do not  try to  phone me  at home. I am not registered in
the phone listings and due to the possible jet lags I am not
much happy when waked up in the middle of the night.


   However during  working hours in France (UTC+1, UTC+2), I
might be reached at my employer's:


   DATAID Systèmes Techniques et Industriels
Voice : +33 (1) 40.99.19.19.


   Better use FAX, however : +33 (1) 40.99.06.85.


   If you  wish to  do so,  you may  send me  in case  of  a
presumed  bug,  a  copy  of  your  code.  However  I  cannot
guarantee neither  a quick  response nor  the return of your
media if a postal shipment.
   Anum is  a yet (see next section) non-profitable piece of
software and  I prefer  to work  harder on a paid job rather
than on Anum.


   As I  work since  Nov 5  1990, besides  my  current  very
partial time job as teacher in the E.S.T.P, I cannot foresee
yet any availability delays for the next release of Anum.
                       GENERAL OVERVIEW



   I  have   since  July  1990  the  diploma  of  "Ingénieur
Géomètre" from  the "Ecole  Spéciale des Travaux Publics, du
Bâtiment et  de l'Industrie"  (E.S.T.P.). I  have planned to
release in  three years  a major piece of software for micro
computers which  will be  a commercial product. Do'nt ask me
neither what  it is nor why this software will be, according
to me,  somewhat revolutionnary. It could be compared to the
introduction  of   Turbo Pascal  on   the  micro   computers
programming  languages   market,  either   by  its   planned
efficiency and financial impact.


   This major  piece of  software requires several different
fields of  the so-called  "art of  programming". One  of its
aspect is  that it  will  extensively  use  mathematics  and
scientific  number  crunching  algorithms.  I  am  currently
developping  the   corresponding  functions   on  a  IBM  PC
compatible under  MS-DOS which allows low-cost developpement
at home.  For the  reasons  explained  at  the  end  of  the
disclaimer section  I  cannot  spend  much  time  thoroughly
testing those  functions. This  is why  I  decided  to  make
public the  first functions  already  done.  More  functions
should come  in the  future as this mathematical subroutines
package is not yet complete.


   ANUM is  a library  for use  with one  of the following C
compilers:  Turbo C 2.0,  Turbo C++ 1.0  or  Borland C++ 2.0
from Borland International. It provides several routines for
use by  any programmer  interested  in  Numerical  Analysis.
These routines  are thoroughly  explained further  in one of
the following sections of this documentation.


   A few  of these  routines are only of interest for Anum's
own routines  but have  been left  as public as their use is
shared by several functions in several modules. However they
will remain  marked as  reserved  in  this  file.  Usage  of
functions  with  similar  names  can  be  of  some  problem,
especially if  the "warn duplicate symbol" toggle is not set
active at link edit time.


   To use the ANUM.LIB file, you should either.
- specify its name in one of the line of your project file.
- append it at the end of the command line if you use TCC or
   BCC or  BCCX. Do not forget then to include the MATHL.LIB
   file and  the coprocessor  chip or  emulator library file
   depending on your system configuration.
   Please refer  to Turbo  C manuals for more information on
that topic.


   ANUM code  is compiled  with word  data alignement  and a
default signed  char type.  Consequently you  should  ensure
your compiler  settings will  correspond to  this. Otherwise
the result could be undefined.


   ANUM  code   is  compiled   without  the   VROOM  overlay
facilities (for  the TC++  and BC++ versions, of course). If
you want a special copy of ANUM with them, send me a notice.


   The ANUM.LIB file was created using Borland International
library utility  TLIB. Its  version number  is 4.0  for BC++
version, 3.0 for TC++ version and 2.0 for TC 2.0 version.


   It is highly recommended ANSI prototyping be used in your
programs making  use of  Anum. This is why, two header files
are also  provided to  include in  your  own  routines.  The
SYSIO.H file contains declarations for the error and warning
messages interface,  whilst the  ANUM.H file  contains those
relevant to  numerical codification  of errors  and warnings
and of the other routines.


   A special  effort has been made to keep the interface for
parameters  passings   quite  close   to  the  one  used  by
Borland International Turbo Pascal Numerical Toolbox to help
those of  you who  would like to port their already existing
applications from  Pascal to  C. In  fact, most  of the high
level functions  of Anum  use the  same algorithm  than  the
Numerical Toolbox.  This is  due to the fact that they offer
quite a  wide coverage  of usual  numerical analysis  within
quite a  few routines,  and it  is quite  important when one
starts writing its own numerical toolbox.
                          CONVENTIONS



   The following conventions are applied:
All of  the functions  present in  the  library,  which  are
   documented  here,   follow  the   C   parameter   calling
   conventions and have been provided for use with the LARGE
   memory  model   exclusively.  The   only  near  functions
   provided here  are of  the static  class and then totally
   hidden to the application programmer.
No function  returns any  pointers allocated. Some functions
   may allocate  space for  temporary  items.  But  this  is
   hidden to  the application  programmer and space is freed
   at the  end of  the routine.  It  is  hereby  up  to  the
   programmer to  allocate the  necessary amount of space by
   using the  farcalloc function before calling any function
   of the  present library.  Rows and  columns are  numbered
   from 1 unless explicitely stated.
Polynomial indexation  strictly follows  the following rule:
   The degree  is always  increasing i.e.  *poly  points  to
   poly[0], *(poly+1) points to poly[1] and so on.
Matrices are  indexed as follows: the first index is the row
   index, the second is the column one just as the classical
   way C handles arrays.
The typedef'ed  COMPLEX type  is required to use some of the
   provided routines  dealing with complex arithmetic. It is
   defined in the ANUM.H header file.
All real values in the Anum library are of the type double.
All Anum  error codes  take negative  values. A  zero  value
   indicates there is no error.
                       PROVIDED ROUTINES



   For each provided routine, you will find:
the function prototype,
a short description of what it performs,
its input and output parameters,
a list of its possible error code values,
its value on return if any.


   To ensure  coherence and  because prior releases suffered
poor documentation,  this part of the documentation has been
transferred to the header files (ANUM.H and SYSIO.H).
                    ERROR AND WARNING CODES



   Here are  a few  of the  possible returnes error codes. A
more complete  list is given in the "anum.h" file. I promise
I will  include it in the next release of ANUM documentation
:-). It  is sometimes  no joke working until 2 a.m. on a non
paid job ;-).



 ETOLLE0

Class : Error
Cause :  The called  routine was  given a  nil  or  negative
   tolerance value.
User's Response  : Correct the 'tol' parameter to a strictly
   positive value.


 EOVERMAXITER

Class : Error
Cause :  An iterative  function could  not find the solution
   within 'maxiter' iterations.
User's Response  : Set  the 'maxiter' parameter to a greater
   value or check the algorithm will converge with the given
   approximate values  of the solution or assume there is no
   solution.


 ENULLSLOPE

Class : Error
Cause  :  The  user  function  attempted  to  use  a  Newton
   algorithm with a point, the slope of the function is zero
   at which.
User's  Response   :  Choose  another  parameter  value  for
   approximate value of the root.


 WCPLXROOTS

Class : Warning
Cause :  A function  solving real polynomes could not find a
   number of  real roots  equal to its degree. This polynome
   could possibly have one or more complex roots.
User's Response  : Use  a routine giving al so complex roots
   or set the 'maxiter' parameter to a greater value.


 EYSAMESIGN

Class : Error
Cause :  The bisection  algorithm was  given two  bounds the
   values of which are of the same sign.
User's Response  : Correct one of the bounds. Check if there
   is at  least one  root between the bounds or assume there
   is no solution.


 EMAXITERLT0

Class : Error
Cause :  An iterative routine was given a negative value for
   the maximum number of iterations as parameter.
User's Response  :  Input  a  positive  value  as  'maxiter'
   parameter. A  nil value will only be suitable if you want
   to treat  only cases  for  which  a  trivial  and  direct
   solution exists.


 ENOPXINTERSECT

Class : Error
Cause : The computed parabola does not intersect the X axis.


 EDIMLT0

Class : Error
Cause : A function attempted to use a negative length vector
   or a negative order square matrix.
User's Response  : Change  the dim  parameter or  check your
   polynome is not totally deflated.


 EMATSING

Class : Error
Cause : A routine attempted to invert a singular matrix.


 EDIMLE0

Class : Error
Cause :  A function  attempted to  use a  negative  or  zero
   length vector or a negative or zero order square matrix.
User's Response  : Change  the dim  parameter or  check your
   polynome is not totally deflated.


 E0DIVIDE

Class : Error
Cause : A function attempted to do a division by zero.

 EDEGLT2

Class : Error
Cause :  The selected  algorithm  requires  a  polynome  the
   degree of which is at least two.
User's Response  : Check your calling function for errors or
   try to use a direct solving method.


 ENOWCORE

Class : Error
Cause :  There is  not enough  working core  for one  of the
   routine to allocate its working arrays.
User's  Response   :  Try  to  free  some  main  storage  by
   eliminating  Terminate-and-Stay-Resident   programs.  Use
   overlays if  your compilers  allows them. Check your code
   for unused stuff.


 EDEGLE0

Class : Error
Cause :  A function  attempted to  use a  negative  or  zero
   degree polynomial.
User's Response  : Check passed arguments or try to directly
   solve a  trivial case  (if degree  is nil  or  polynomial
   equals 0).


 ENUMINTLE0

Class : Error
Cause : The given number of arguments passed to a routine is
   lower than or equal to 0.
                 HISTORY LOG - CHANGES TO COME

   From first to second release
Fixed a bug concerning a hardwire coded error in the Newton-
   Raphson algorithm.

Added :
   steffensen function
   laguerre function
   ena_beep function
   ena_warn function
   ena_err function
   ena_m_beep
   disa_m_beep


   The five  last functions allow or disable sytem generated
warning or messages and the audible tone associated to it.


   Not  to   cause  some   "vapourware"  announces   and  as
programming generates  unexpected delays,  no date  is given
for the next release of Anum.


   From second to third release
Fixed severe  bug in  swap_rows function  giving some random
   results with inverse and determinant functions.
Added : a whole bunch of new functions.


   From third to fourth release
Fixed severe  bug in  swap_rows function  giving some random
   results with inverse and determinant functions.
Added  :  (lsq,  eigen_vector,  householder_givens,  jacobi,
   le_verrier).
Added :  C/C++ support,  ANUM release 4 routines should link
   without problem  with C++  modules. This  is achieved  by
   suppressing automatically type checking at link edit time
   (See the  #ifdef compilation  directives  in  ANUM.H  and
   SYSIO.H).
In release  4.1, fixed  a bug affecting the inverse function
   and the jacobi method due to a wrong parameter passing in
   row_mat_div.  Solved   an  ambiguity  in  the  eigen_vect
   routine. fixed a (very minor) bug in testlib.bat.


   In the next release of this package:
Changes  of  the  interface  to  support  Turbo  Pascal  are
   considered. This  would primarily  affect  the  parameter
   calling conventions.
Microsoft compilers  are too slow, require too much space on
   the secondary  storage, are  too user  unfriendly and too
   expansive for me to forecast any support yet.
More functions are to come out, of course. Especially in the
   differential equations  solving and interpolation fields.
   A better  documentation will  also arise, especially from
   your comments.


   Thanks to :
CFGROP at WEIZMANN.BITNET
ROSSBACH at DMRHRZ11.BITNET
C3DOUTRE at FRECCL11.BITNET
m_rives at paris.paris.ingr.com
USERGB3W at UMICHUM.BITNET


   for support and/or suggestions.


                          Contents