Power-Programmierung/CD1.mdf/basic/library/qb_pds/math/mathlib/manual.txt

Text File | 1991-06-01 | 10.3 KB | 236 lines

         RealFun:  Real & Complex Math Libraries for QuickBASIC

         MANUAL.TXT



           RealFun & CompFun:  Mathematics Libraries for QuickBASIC

                       Copyright 1991, L. Kerry Mitchell





         Contents: I.   Introduction

                   II.  RealFun Libraries

                   III. CompFun Libraries

                   IV.  Support Policy

                   V.   General Comments

                   VI.  Revision History





         I.   Introduction



         One of the nice things about BASIC is that it's an easy

         language to learn and use, especially in the QuickBASIC

         environment.  However, this ease of use comes at the expense

         of programming power.  As it is packaged, QuickBASIC just

         doesn't have the same number-crunching capability as

         FORTRAN, for example.  In much of my personal programming, I

         wanted to use functions, like hyperbolic trigonometric

         functions, that were available in FORTRAN.  The essential

         pieces were there (arithmetic operators and the EXP

         function), but not in the forms I wanted.  So I set out to

         create a set of libraries that would contain all the

         functions I'd ever want to use, and then some.



         Along the way, I realized that some of the intrinsic

         functions in QuickBASIC don't quite function the way I'd

         like.  For example, the modulo function (MOD) only returns

         integers, which is not helpful if you're trying to find 1000

         mod 3.14159.  The arctangent function (ATN) only takes one

         argument, so you can't tell what quadrant your angle is in.

         Specifically, if the sides of your angle are x and y, with x

         = -1 and y = -1, ATN(y/x) will give you the same result as

         it would if x and y were both 1.  And of course, QuickBASIC

         does not handle complex numbers (as such).



         This package is a compilation of my efforts to make

         QuickBASIC more powerful and more productive.  I hope you

         find it useful.





         II.  RealFun Libraries



         The RealFun library is actually two libraries, a Quick

         library (REALFUN.QLB) that is used during your interactive


         programming session, and a stand-alone library (REALFUN.LIB)

         that is used to create stand-alone programs.  To use them,

         initiate QuickBASIC with the "/l" option:



              C> qb/l realfun



         This assumes that you keep RealFun in the same directory as

         your QuickBASIC executable files.  For additional

         information on loading libraries, see your QuickBASIC

         manuals.



         Once you've gotten the library loaded, you need to tell your

         program about it.  For each function that you use, you need

         a declaration statement at the beginning of your code.  For

         example, to use the sind (sine of an angle in degrees)

         function, you would need a



              DECLARE FUNCTION sind (x)



         at the beginning of your program.  Then, if you wanted to

         find the sine of 35 degrees somewhere later, call the sind

         function just as you would the intrinsic SIN function:



              .

              .

              .

              s35 = sind(35)

              .

              .

              .



         All the other functions are similarly available for your

         use.



         RealFun is composed of 38 functions.  A full list of them by

         general topic area (sine, hyperbolic tangent, modulo, etc.)

         can be found in the file REALTOP.TXT.  An alphabetic listing

         by function name (sind, tanh, dmod, etc.) can be found in

         the file REALLIST.TXT.  That's all there is to it!





         III. CompFun Libraries



         The CompFun libraries are also two libraries, a Quick

         library (COMPFUN.QLB) that is used during your interactive

         programming session, and a stand-alone library (COMPFUN.LIB)

         that is used to create stand-alone programs.  To use them,

         initiate QuickBASIC with the "/l" option:



              C> qb/l compfun




         just like intializing the RealFun libraries.



         The CompFun library is a superset of the functions included

         in RealFun, and is composed of FUNCTIONS and SUBprograms.

         To use the FUNCTIONs, you need to let your program know

         about them, with the appropriate declaration(s).  For

         example, to use the amax and amin functions (maximum and

         minimum of 2 items in a list), you would need



              DECLARE FUNCTION amax (x, y)

              DECLARE FUNCTION amin (x, y)



         at the beginning of your program.



         The strength of CompFun lies in its ability to manipulate

         complex numbers via their real and imaginary parts.  (In

         brief, complex numbers have 2 parts, that are known as the

         "real" and "imaginary" parts.  QuickBASIC can only handle

         "real" numbers, that is, numbers with 1 part.  See

         REGISTER.TXT for information regarding a tutorial on complex

         numbers and using them with the CompFun library.)  Since

         FUNCTIONs only return 1 number, the complex routines are

         executed using SUBprograms, which support parameter lists.

         Each SUBprogram you want to use requires its own declaration

         statement.  For example, to convert the real and imaginary

         parts of a complex number to its magnitude and phase, use



              DECLARE SUB cpolar (x, y, r, t)



         at the beginning of your program, and



              CALL cpolar (a, b, mag, phase)



         in the body of your code.  Of course, you don't have to use

         these same variables names, as long as they are of the

         proper type.  In this example, the inputs are a (the real

         part of the complex number) and b (the imaginary part).  The

         outputs are mag (the magnitude) and phase (the phase, in

         radians).  The file COMPTOP.TXT lists all the FUNCTIONs and

         SUBprograms in CompFun, arranged by topic.  Also listed are

         the input and output types (single- or double-precision,

         integer or long), and the number of arguments.  An

         alphabetic listing of all the routines can be found in

         COMPLIST.TXT.



         A bit of warning about dealing with complex numbers:  Any

         function involving the trigonometric functions (sin, cos,

         tan, sinh, cosh, tanh) or the exponentials (exp, log), the

         so-called "transcendental" functions, will be multi-valued.


         That is to say, there is an infinity of numbers that give

         the same answer.  This is not really a problem, but

         something of which you need to be aware.  For example, if

         you computed the cosine and arccosine of (-1, -3):



              DECLARE SUB ccos(a, b, c, d)

              DECLARE SUB cacos(a, b, c, d)

              CALL ccos(-1, -3, u, v)

              CALL cacos(u, v, x, y)

              PRINT x, y



         you'd find that x = 1 and y = 3, rather than -1 and -3.  So

         computing the inverse of a function does not necessarily get

         you right back where you started.





         IV.  General Comments



         The limits of these libraries are the same as the limits of

         QuickBASIC, as far as precision, overflow, underflow, etc.



         It is assumed that the user has some idea of what he/she is

         doing, or doesn't mind crashing his/her program often.  That

         is to say that there is no error-checking in the routines.

         If you try to compute cdacos(145%), your program will

         probably die.  I decided that QuickBASIC's error-checking

         facilities were good enough to keep your machine from

         hanging up, and that checking for the more common errors

         would amount to excessive overhead and adversely affect the

         routines' performance.



         Some of the calculations, especially the inverse

         trigonometric functions, are a bit involved.  A lot of

         effort has gone into optimizing the algorithms, but it can

         still take a long time to do a massive calculation (like a

         640 x 480, several thousand iteration fractal).  There's not

         much that can be done about that; it's the nature of the

         system.





         V.   Support Policy



         It is expected that the user of this package will have at

         least a passing familiarity with QuickBASIC and the

         mathematics used in the libraries.  For a tutorial on

         complex numbers and usage of the libraries, please see

         REGISTER.TXT and order the enhanced package.



         These libraries have been tested thoroughly, but on only one

         installation.  The modules are believed to be fully


         compatible with MS-DOS 3.3 and QuickBASIC 4.5.

         Compatibility with earlier versions is an open question,

         although no "tricks" or dirty programming have been used, so

         it should be safe.  To report bugs and problems, please send

         a short note to me at the address below.



         Support in working with the package can be obtained in two

         ways.  For 90 days after registration, you are entitled to a

         total of 1 hour telephone support, free of charge (except

         normal long-distance charges).  Support by mail (postal or

         electronic) is available free of charge for 180 days after

         registration.  To obtain help or report a bug, write or

         call:



              Kerry Mitchell

              Creative Imagery

              1454 Todds Lane #A-25

              Hampton, VA 23666

              804-827-7034

              CompuServe:  [70152,1444]

              Internet:  [e-mail]

              Delphi:  lkmitch





         VI.  Revision History



         This is officially version 1.0 of the RealFun package.  A

         preliminary version was released in 1990, primarily as an

         exercise for myself.