home *** CD-ROM | disk | FTP | other *** search
/ SDN¹ Plus / SDN1_.cdr / sdn / lang / realfun.sdn / MANUAL.TXT < prev    next >
Text File  |  1991-06-01  |  11KB  |  236 lines
  1.  
  2.  
  3.          RealFun:  Real & Complex Math Libraries for QuickBASIC
  4.          MANUAL.TXT
  5.  
  6.            RealFun & CompFun:  Mathematics Libraries for QuickBASIC
  7.                        Copyright 1991, L. Kerry Mitchell
  8.  
  9.  
  10.          Contents: I.   Introduction
  11.                    II.  RealFun Libraries
  12.                    III. CompFun Libraries
  13.                    IV.  Support Policy
  14.                    V.   General Comments
  15.                    VI.  Revision History
  16.  
  17.  
  18.          I.   Introduction
  19.  
  20.          One of the nice things about BASIC is that it's an easy
  21.          language to learn and use, especially in the QuickBASIC
  22.          environment.  However, this ease of use comes at the expense
  23.          of programming power.  As it is packaged, QuickBASIC just
  24.          doesn't have the same number-crunching capability as
  25.          FORTRAN, for example.  In much of my personal programming, I
  26.          wanted to use functions, like hyperbolic trigonometric
  27.          functions, that were available in FORTRAN.  The essential
  28.          pieces were there (arithmetic operators and the EXP
  29.          function), but not in the forms I wanted.  So I set out to
  30.          create a set of libraries that would contain all the
  31.          functions I'd ever want to use, and then some.
  32.  
  33.          Along the way, I realized that some of the intrinsic
  34.          functions in QuickBASIC don't quite function the way I'd
  35.          like.  For example, the modulo function (MOD) only returns
  36.          integers, which is not helpful if you're trying to find 1000
  37.          mod 3.14159.  The arctangent function (ATN) only takes one
  38.          argument, so you can't tell what quadrant your angle is in. 
  39.          Specifically, if the sides of your angle are x and y, with x
  40.          = -1 and y = -1, ATN(y/x) will give you the same result as
  41.          it would if x and y were both 1.  And of course, QuickBASIC
  42.          does not handle complex numbers (as such).
  43.  
  44.          This package is a compilation of my efforts to make
  45.          QuickBASIC more powerful and more productive.  I hope you
  46.          find it useful.
  47.  
  48.  
  49.          II.  RealFun Libraries
  50.  
  51.          The RealFun library is actually two libraries, a Quick
  52.          library (REALFUN.QLB) that is used during your interactive
  53.  
  54.          programming session, and a stand-alone library (REALFUN.LIB)
  55.          that is used to create stand-alone programs.  To use them,
  56.          initiate QuickBASIC with the "/l" option:
  57.  
  58.               C> qb/l realfun
  59.  
  60.          This assumes that you keep RealFun in the same directory as
  61.          your QuickBASIC executable files.  For additional
  62.          information on loading libraries, see your QuickBASIC
  63.          manuals.
  64.  
  65.          Once you've gotten the library loaded, you need to tell your
  66.          program about it.  For each function that you use, you need
  67.          a declaration statement at the beginning of your code.  For
  68.          example, to use the sind (sine of an angle in degrees)
  69.          function, you would need a
  70.  
  71.               DECLARE FUNCTION sind (x)
  72.  
  73.          at the beginning of your program.  Then, if you wanted to
  74.          find the sine of 35 degrees somewhere later, call the sind
  75.          function just as you would the intrinsic SIN function:
  76.  
  77.               .
  78.               .
  79.               .
  80.               s35 = sind(35)
  81.               .
  82.               .
  83.               .
  84.  
  85.          All the other functions are similarly available for your
  86.          use.
  87.  
  88.          RealFun is composed of 38 functions.  A full list of them by
  89.          general topic area (sine, hyperbolic tangent, modulo, etc.)
  90.          can be found in the file REALTOP.TXT.  An alphabetic listing
  91.          by function name (sind, tanh, dmod, etc.) can be found in
  92.          the file REALLIST.TXT.  That's all there is to it!
  93.  
  94.  
  95.          III. CompFun Libraries
  96.  
  97.          The CompFun libraries are also two libraries, a Quick
  98.          library (COMPFUN.QLB) that is used during your interactive
  99.          programming session, and a stand-alone library (COMPFUN.LIB)
  100.          that is used to create stand-alone programs.  To use them,
  101.          initiate QuickBASIC with the "/l" option:
  102.  
  103.               C> qb/l compfun
  104.  
  105.  
  106.          just like intializing the RealFun libraries.
  107.  
  108.          The CompFun library is a superset of the functions included
  109.          in RealFun, and is composed of FUNCTIONS and SUBprograms. 
  110.          To use the FUNCTIONs, you need to let your program know
  111.          about them, with the appropriate declaration(s).  For
  112.          example, to use the amax and amin functions (maximum and
  113.          minimum of 2 items in a list), you would need
  114.  
  115.               DECLARE FUNCTION amax (x, y)
  116.               DECLARE FUNCTION amin (x, y)
  117.  
  118.          at the beginning of your program.
  119.  
  120.          The strength of CompFun lies in its ability to manipulate
  121.          complex numbers via their real and imaginary parts.  (In
  122.          brief, complex numbers have 2 parts, that are known as the
  123.          "real" and "imaginary" parts.  QuickBASIC can only handle
  124.          "real" numbers, that is, numbers with 1 part.  See
  125.          REGISTER.TXT for information regarding a tutorial on complex
  126.          numbers and using them with the CompFun library.)  Since
  127.          FUNCTIONs only return 1 number, the complex routines are
  128.          executed using SUBprograms, which support parameter lists. 
  129.          Each SUBprogram you want to use requires its own declaration
  130.          statement.  For example, to convert the real and imaginary
  131.          parts of a complex number to its magnitude and phase, use
  132.  
  133.               DECLARE SUB cpolar (x, y, r, t)
  134.  
  135.          at the beginning of your program, and
  136.  
  137.               CALL cpolar (a, b, mag, phase)
  138.  
  139.          in the body of your code.  Of course, you don't have to use
  140.          these same variables names, as long as they are of the
  141.          proper type.  In this example, the inputs are a (the real
  142.          part of the complex number) and b (the imaginary part).  The
  143.          outputs are mag (the magnitude) and phase (the phase, in
  144.          radians).  The file COMPTOP.TXT lists all the FUNCTIONs and
  145.          SUBprograms in CompFun, arranged by topic.  Also listed are
  146.          the input and output types (single- or double-precision,
  147.          integer or long), and the number of arguments.  An
  148.          alphabetic listing of all the routines can be found in
  149.          COMPLIST.TXT.
  150.  
  151.          A bit of warning about dealing with complex numbers:  Any
  152.          function involving the trigonometric functions (sin, cos,
  153.          tan, sinh, cosh, tanh) or the exponentials (exp, log), the
  154.          so-called "transcendental" functions, will be multi-valued. 
  155.  
  156.          That is to say, there is an infinity of numbers that give
  157.          the same answer.  This is not really a problem, but
  158.          something of which you need to be aware.  For example, if
  159.          you computed the cosine and arccosine of (-1, -3):
  160.  
  161.               DECLARE SUB ccos(a, b, c, d)
  162.               DECLARE SUB cacos(a, b, c, d)
  163.               CALL ccos(-1, -3, u, v)
  164.               CALL cacos(u, v, x, y)
  165.               PRINT x, y
  166.  
  167.          you'd find that x = 1 and y = 3, rather than -1 and -3.  So
  168.          computing the inverse of a function does not necessarily get
  169.          you right back where you started.
  170.  
  171.  
  172.          IV.  General Comments
  173.  
  174.          The limits of these libraries are the same as the limits of
  175.          QuickBASIC, as far as precision, overflow, underflow, etc.
  176.  
  177.          It is assumed that the user has some idea of what he/she is
  178.          doing, or doesn't mind crashing his/her program often.  That
  179.          is to say that there is no error-checking in the routines. 
  180.          If you try to compute cdacos(145%), your program will
  181.          probably die.  I decided that QuickBASIC's error-checking
  182.          facilities were good enough to keep your machine from
  183.          hanging up, and that checking for the more common errors
  184.          would amount to excessive overhead and adversely affect the
  185.          routines' performance.
  186.  
  187.          Some of the calculations, especially the inverse
  188.          trigonometric functions, are a bit involved.  A lot of
  189.          effort has gone into optimizing the algorithms, but it can
  190.          still take a long time to do a massive calculation (like a
  191.          640 x 480, several thousand iteration fractal).  There's not
  192.          much that can be done about that; it's the nature of the
  193.          system.
  194.  
  195.  
  196.          V.   Support Policy
  197.  
  198.          It is expected that the user of this package will have at
  199.          least a passing familiarity with QuickBASIC and the
  200.          mathematics used in the libraries.  For a tutorial on
  201.          complex numbers and usage of the libraries, please see
  202.          REGISTER.TXT and order the enhanced package.
  203.  
  204.          These libraries have been tested thoroughly, but on only one
  205.          installation.  The modules are believed to be fully
  206.  
  207.          compatible with MS-DOS 3.3 and QuickBASIC 4.5. 
  208.          Compatibility with earlier versions is an open question,
  209.          although no "tricks" or dirty programming have been used, so
  210.          it should be safe.  To report bugs and problems, please send
  211.          a short note to me at the address below.
  212.  
  213.          Support in working with the package can be obtained in two
  214.          ways.  For 90 days after registration, you are entitled to a
  215.          total of 1 hour telephone support, free of charge (except
  216.          normal long-distance charges).  Support by mail (postal or
  217.          electronic) is available free of charge for 180 days after
  218.          registration.  To obtain help or report a bug, write or
  219.          call:
  220.  
  221.               Kerry Mitchell
  222.               Creative Imagery
  223.               1454 Todds Lane #A-25
  224.               Hampton, VA 23666
  225.               804-827-7034
  226.               CompuServe:  [70152,1444]
  227.               Internet:  70152.1444@compuserve.com
  228.               Delphi:  lkmitch
  229.  
  230.  
  231.          VI.  Revision History
  232.  
  233.          This is officially version 1.0 of the RealFun package.  A
  234.          preliminary version was released in 1990, primarily as an
  235.          exercise for myself.
  236.