home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 24 / CD_ASCQ_24_0995.iso / dos / educ / cf515 / cf515.doc next >
Text File  |  1995-07-07  |  22KB  |  589 lines
  1. July 7, 1995                     (C) Copyright 1993,1995  John P. Arkins
  2.  
  3.  
  4.                          CurveFits v5.15
  5.              ---------------
  6.  
  7.             LIMIT OF LIABILITY
  8.  
  9.  CurveFits v5.15 is distributed as-is. Although effort has been taken
  10.  to insure accurate answers are obtained when using this program, the
  11.  author disclaims all warranties, expressed or implied.  The author will
  12.  assume no liability for damages either from the direct use of this product
  13.  or as a consequence of the use of this product.
  14.  
  15.                REVISION HISTORY
  16.                ----------------
  17.  
  18.  CF101  -- January 1992 (Never Released)
  19.        5 Fits, Maximum of 20 data pairs. Graphics screen was fixed.
  20.        Written using Turbo Pascal 6.0
  21.  CF251  -- August  27 1992
  22.        6 Fits, Graphics screen now movable and zoomable.
  23.        Written using Turbo Pascal 6.0
  24.  CF315  -- January 30 1993
  25.        16 fits, Data point limit now increased to 250.
  26.        Written using Turbo Pascal 6.0
  27.  CF427  -- February 6 1994
  28.        26 fits, External utility for converting text files added.
  29.        Written using Turbo Pascal 7.0
  30.  CF502  -- February 4 1995
  31.        26 fits. Program re-written using Borland's Turbo
  32.        vision interface. External program CONVERT.EXE written
  33.        using Turbo C++ 3.1 for greatly enhanced text file
  34.        conversion, and program can be called from within the
  35.        CurveFits program. Number of data points limited only by
  36.        FPU and size of hard disk.
  37.            Written using Borland Pascal 7.0
  38.  CF515 --  July 7 1995
  39.            28 Fits.  Program revision due mainly to confusion over
  40.            whether an option to print graphs existed, it did and
  41.            does exist.  Added Beta and Gamma Fits.  Network
  42.            printing capabilites added.  Epson printout changed
  43.            from portrait to landscape, quality is much improved.
  44.            Added some command line options to facilitate batch
  45.            operations.  Floating point emulation support returns in
  46.            this version.
  47.            Written using Borland Pascal 7.0
  48.  
  49.  
  50.                   FOREWORD
  51.                   --------
  52.  
  53.  CurveFits v5.xx is a signifigant revision of the CurveFits program.
  54.  The program was re-designed and rebuilt using Borland Pascal's Turbo
  55.  Vision interface.  The program also no longer has a 250 data point
  56.  limit, and the size of data files are only limited by the amount of
  57.  hard disk space, and the 80 bit registers on a 80286+ PC's floating
  58.  point unit (FPU).
  59.  
  60.  
  61.               USING THE PROGRAM
  62.               -----------------
  63.  
  64.  MENU BAR
  65.  --------
  66.    The menu bar is the white bar across the top of the screen with the
  67.    words 'File' 'Data' 'Fits' 'Window' 'Help' and 'Exit' written on it.
  68.    Each word contains a unique red letter.  To access a selection on the
  69.    menu bar, press Alt and hilighted letter or click on the word with the
  70.    mouse.
  71.  
  72.  Here are the subfunctions of the menu bar, listed in order :
  73.  
  74.  File|Create
  75.  -----------
  76.   This option allows a user to create a new data file.  You will be prompted
  77.   for a filename, and then the program will loop through the data entry
  78.   process until the user selects the Cancel button on the data entry
  79.   dialog.
  80.  
  81.  File|Load
  82.  ---------
  83.   This option allows the loading of a pre-existing curvefits data file.
  84.  
  85.  File|Load&Fit
  86.  -------------
  87.  This is an 'express' option. It will load a pre-existing curve fits
  88.  file, run it through the curve fitting process and then take you to
  89.  the fit selection dialog. It, in effect, performs File|Load,
  90.  Fits|Perform Fits, and Fits|View Fits in sequence.
  91.  
  92.  File|Change Dir
  93.  ---------------
  94.  Use this to change the current directory of Curvefits.
  95.  
  96.  File|View Text
  97.  --------------
  98.  Use this option to use the internal file viewer to examine text
  99.  files.  This is useful for examining text data files that you may
  100.  want to import.  Note that the viewer can only display 64K.
  101.  
  102.  File|Dos Shell
  103.  --------------
  104.  This option will shell you to the DOS command line.
  105.  
  106.  File|Set Printer
  107.  ----------------
  108.  This option lets you select either a LaserJet or Epson compatible
  109.  printer, and allows printing on LPTx where x ranges from 1 to 9.
  110.  
  111.  Data|Add Pair
  112.  -------------
  113.  This option allows you to add a data pair to the currently loaded
  114.  data file.
  115.  
  116.  Data|Delete Pair
  117.  ----------------
  118.  This option allows you to delete the highlighted data pair from
  119.  the currently loaded data file.
  120.  
  121.  Data|Modify Pair
  122.  ----------------
  123.  This option allows you to modify the values of the highlighted data pair.
  124.  
  125.  Data|Add Loop
  126.  -------------
  127.  This allows the addition of multiple data points to data file.  The
  128.  program will loop through the data pair addition process until either the
  129.  Cancel button is selected or the Esc key is pressed.
  130.  
  131.  Data|Reduce
  132.  -----------
  133.  This allows you to multiply all the data pairs in a data file by
  134.  two constants. One for the X value and another for the Y value.
  135.  This is good for reducing the magnitude of data files that have
  136.  large values, ( or should I say large exponents, positive or negative)
  137.  which tend to overflow the exponential function, and the fits that 
  138.  depend upon it.  The range of values the 80x87's 80-bit register can 
  139.  hold is approximately 3.4e-4932 to 1.1e4932.  This translates roughly 
  140.  to exp(-11000) to exp(11000).  If these limits are exceeded during the 
  141.  calculation of an equation's coefficients, the fit will become unavailable.
  142.  
  143.  Data|Import Text
  144.  ----------------
  145.  You will be asked for the name of the data file you wish to convert,
  146.  and a formating string for the text file data.
  147.  
  148.  For numbers you wish to use you will specify the code '%Le'
  149.  in the format while numbers that are to be ignored will be specified with
  150.  '%*Le'.  The format string will tell the program what each
  151.  line in your text file looks like, and therefore how it should be processed.
  152.  
  153.  For example, if your text data file looked like this :
  154.   1.01232 12.8373
  155.   2.98210 4.87371
  156.  
  157.  You would use this format string :
  158.   %Le %Le
  159.  
  160.  If there are more than two numbers per line, you can specify which
  161.  numbers you want to use (realizing of course that CurveFits can only
  162.  use TWO data points).
  163.  
  164.  For a text data file that looks like this :
  165.  
  166.  16.9872E+02  16020202020.2  -1928.34E-02
  167.  123.32323   1.32233  22332.2
  168.  
  169.  If you wanted to use columns one and three use this format string :
  170.   %Le %*Le %Le
  171.  
  172.  or If your data appears like this :
  173.   1.4, 2.11
  174.   6.1, 12.32
  175.  
  176.  Use this format string :
  177.   %Le, %Le
  178.  
  179.  Compare this with the previous :
  180.   1.22982 ,    12121
  181.  
  182.  Format string :
  183.   %Le , %Le
  184.  
  185.  Any amount of consecutive spaces can be reduced to one space
  186.  but any spacing between commas, numbers etc MUST be noted. You
  187.  must also use an %Le or %*Le for EVERY number appearing on a line.
  188.  
  189.  One last more complex example:
  190.  
  191.  Text File:
  192.   time = 1, velocity = 3, acceleration =         6.82287
  193.   time = 2, velocity = 4, acceleration =         5.28701
  194.  the appropriate format string is :
  195.   time = %Le, velocity = %*Le, acceleration = %Le
  196.  
  197.  IMPORTANT!:
  198.  Keep in mind that THE FORMAT STRING IS CASE SENSITIVE!
  199.  If the conversion program fails immediately upon being called
  200.  it is most likely due to a incorrect format string.
  201.  The program shells to DOS and executes the program convert.exe.
  202.  Convert.exe MUST reside in the same directory as the file
  203.  CF515.EXE
  204.  
  205.  For further experimentation, load a sample data file.  Convert
  206.  it to a text file using the Data|Output Text option.  
  207.  Clear the desktop.  Now import the text file using the format string 
  208.  ' %Le %Le' (minus the quotes of course).  Note the leading space.
  209.  
  210.  If the format string is wrong the conversion fails almost immediately. 
  211.  You will the get a message 'Error:empty file' because CurveFits is
  212.  trying to load the converted file which is empty.
  213.  
  214.  If the format string is nearly correct, but not quite, the conversion
  215.  process make work for the first few lines and then fail.
  216.  
  217.  Data|Output Text
  218.  ----------------
  219.  This will convert the currently loaded data file into a text file.
  220.  The file with have the same name, but will have an extension of
  221.  '.out'
  222.  
  223.  Fits|Perform Fits
  224.  -----------------
  225.  This will perform the curve fits on the currently loaded data file.
  226.  The length of this process depends on the size of the data files.
  227.  On a PC with 80386/20Mhz CPU, a data file with 100,000 points will take
  228.  about 17.5 minutes, 1000 points about 8 seconds. Note that this process is
  229.  two phased, the first phase involves calculating the coefficients, the second
  230.  determining the correlation coefficient and the maximum and standard errors.
  231.  Note that this process does NOT calculate the correlation coefficient,
  232.  maximum error or standard error for the polynomial fit. If those values are
  233.  desired, press 'C' while viewing a graph of a particular polynomial fit.
  234.  
  235.  Fits|Best Correlation
  236.  ---------------------
  237.  This will display, in sorted order, the available fits by best correlation.
  238.  Pressing enter will display the highlighted fit.
  239.  
  240.  Fits|Best Standard Error
  241.  ------------------------
  242.  This will display, in sorted order, the available fits by standard error.
  243.  Pressing enter will display the highlighted fit.
  244.  
  245.  Fits|View Fits
  246.  --------------
  247.  This will bring up the fit selection menu.  Fits that are unavailable will
  248.  be marked with 'N/A' (Not Available).  This can happen for three reasons:
  249.  
  250.  (1) Data has values which would cause calculations to have undefined
  251.      results (division by zero, logarithms of zero and below etc.)
  252.  
  253.  (2) Data has caused FPU registers to overflow/underflow
  254.  
  255.  (3) Polynomial fit & less than 4 data points
  256.      (Use quadratic or linear fit)
  257.  
  258.  Help|Help
  259.  ---------
  260.  Help can be obtained anywhere in the application by pressing F1
  261.  
  262.  
  263.               EDITING A DATA FILE
  264.               -------------------
  265.  
  266.  Once a data file has been loaded, it can be edited.  Pressing enter
  267.  will allow changing the values of the hilighted pair.  Pressing the Insert
  268.  key will allow a the addition of a data point, while pressing Delete will
  269.  delete the hilighted data pair.  All modifications are written directly
  270.  to the data file.
  271.  
  272.               THE FITS
  273.               ---------
  274.  
  275.  CurveFits presently supports 28 types of fits, 19 of which are more or
  276.  less 'distinct'.  The fits which are identical in some or all cases are:
  277.  
  278.   Linear, Quadratic and Polynomial Fits
  279.   Exponential and Modified Power Fit
  280.   Root, Modified Hoerl and Modified Exponential Fit
  281.   Cauchy and Reciprocal Quadratic Fit
  282.   Inverse and Hyperbolic Fit
  283.   Reciprocal line and Reciprocal Quadratic Fits.
  284.   Hoerl and Gamma Fit
  285.  
  286.  For some fits the LN or the inverse of input data is used in the program's
  287.  calculations.  For this reason these fits cannot support data containing
  288.  zeros and negatives or data containing zeros respectively.  Other fits
  289.  will also may not be available if during the curve fitting calculations
  290.  their coefficients are determined to have values which will cause infinite
  291.  or undefined results, such as c = 0 for the Gaussian Fit.  When a fit is
  292.  unavailable it will appear with an N/A next to it in the fit selection
  293.  box (the box that appears when Fits|View Fits is selected).
  294.  
  295.  The 28 Fits and limitations are:
  296.  
  297.    Name                    Equation             Limitations
  298.  --------------------------------------------------------------------------
  299.   1 Linear                : Y=A+B*X
  300.   2 Quadratic             : Y=A+B*X+C*X^2
  301.   3 Power                 : Y=A*X^B              X and Y greater than zero
  302.   4 Exponential           : Y=A*EXP(B*X)         X greater than zero
  303.   5 Logarithm             : Y=A+B*LN(X)          X greater than zero
  304.   6 Hyperbolic            : Y=A+B/X              Non-zero X
  305.   7 Super Geometric       : Y=A*X^(B*X)          X and Y greater than zero
  306.   8 Root                  : Y=A*B^(1/X)          Non-zero X and Y > 0
  307.   9 Polynomial            : Y=A+B*X+C*X^2        Will not accept repeated
  308.                                                  X Values for divided diff.
  309.  10 Reciprocal Line       : Y=1/(A+B*X)          Non-zero Y
  310.  11 Reciprocal Quadratic  : Y=1/(A+B*X+C*X^2)    Non-zero Y
  311.  12 Modified Power        : Y=A*B^X              Y greater than zero
  312.  13 Modified Exponential  : Y=A*EXP(B/X)         Non-zero X and Y > 0
  313.  14 Reciprocal Logarithm  : Y=1/(A+B*LN(X))      Non-zero Y and Y > 0
  314.  15 Reciprocal Hyperbolic : Y=X/(A+B*X)          Non-zero X and Y
  315.  16 Modified Geometric    : Y=A*X^(B*X)          X and Y greater than zero
  316.  17 Heat Capacity         : Y=A+B*X+C/X^2        Non-zero X
  317.  18 Vapor Pressure        : Y=EXP(A+B/X+C*LN(X)) Non-zero X and Y > 0
  318.  19 Exponential Step      : Y=A*(1-B*EXP(-X))
  319.  20 Sinusoidal            : Y=A+B*SIN(X+C)
  320.  21 Gaussian              : Y=A*EXP(-(X-B)^2/(2*C^2))
  321.                          Y greater than zero
  322.  22 Inverse               : Y=A+B/X+C/X^2        Non-zero X
  323.  23 Hoerl                 : Y=A*B^X*X^C          X and Y greater than zero
  324.  24 Cauchy                : Y=1/(A*(X+B)^2+C)    Non-zero Y
  325.  25 Modified Hoerl        : Y=A*B^(1/X)*X^C      X and Y greater than zero
  326.  26 Log Normal            : Y=A*EXP((LN(X)-B)^2/C)
  327.                          X and Y greater than zero
  328.  27 Gamma                 : Y=(A*(X/B)^C)*EXP(A/B)
  329.  29 Beta                  : Y=(A*(X^B)*(1-X)^C)
  330.                                                  X must be a value from 0 to 1
  331.  ---------------------------------------------------------------------------
  332.  
  333.  
  334.               POLYNOMIAL FIT
  335.               --------------
  336.  This fit requires at least four data points.  If there are less than four
  337.  data points it will be unselectable.  When this fit is chosen the user is
  338.  prompted for the order of the fit desired, the order referring to the
  339.  number of coefficients in the desired polynomial fit.  If there are more
  340.  than twenty data points the user will be be asked for a value between four
  341.  to twenty, if there are less than twenty data points, say seventeen, the user
  342.  will be asked for a value between four and seventeen.  If the order chosen
  343.  is equal to the number of data points, (seventeen in this case) the user
  344.  will then be given the option of doing the fit using either Newton's forward
  345.  divided difference or by the usual matrix method. Newton's forward divided
  346.  difference is more accurate than the matrix method however it cannot accept
  347.  repeated x values and it's order is not adjustable as is the case with the
  348.  matrix method.  Note: if two or more X values are the same, Newton's
  349.  divided difference will fail.
  350.  
  351.                 GRAPH SCREEN
  352.                 ------------
  353.  
  354.                DESCRIPTION OF HOTKEYS:
  355.                -----------------------
  356.  
  357.    When the graphing screen is active these hot-keys support
  358.    the described actions:
  359.  
  360.    F1 or H      -  HELP SCREEN (THIS SCREEN)
  361.  
  362.    Alt-F1       -  TOGGLE GRID
  363.            Pressing this will toggle the grid on and off.
  364.  
  365.    F2           -  TOGGLES GRID LABELING
  366.            Pressing this will toggle grid labeling on and off.
  367.  
  368.    F3           -  TOGGLES CIRCLING OF DATA POINTS
  369.            Loops through a sequence of data point marking
  370.            options.  The first is nothing, the second is a
  371.            point, the third is a point with the addition
  372.            of a circle with a radius of one pixel, in essence
  373.            a larger dot.  Pressing F3 again will increase
  374.            the radius of the circles by one pixel.  After
  375.            a radius of 5 pixels, the marking then returns to
  376.            nothing again.
  377.  
  378.   F4            -  TOGGLES ZOOM WINDOW
  379.            This key will turn on/off the zoom window which
  380.            graphically highlights the area which will be
  381.            zoomed to when 'z' is pressed.
  382.  
  383.   F5            -  TOGGLES TITLING OF GRAPH
  384.            This key will turn on/off all text display on the graph
  385.            screen.
  386.  
  387.   F6            -  TOGGLES LINE THICKNESS
  388.            Allows you to choose either a thin or thick
  389.            line for drawing the fitted curve.
  390.  
  391.   F7            -  MARK DISCONTINUITIES
  392.            For fitted equations that have undefined points
  393.            (where there is division by zero), this option
  394.            will place a vertical blue line to denote that
  395.            position.
  396.  
  397.   F8            -  SET XSCALE = YSCALE
  398.            Sets the x and y axes to the same scale.  The
  399.            scale used is the larger, which will still
  400.            show all data points.
  401.  
  402.   F9            -  CHANGES LINE COLOR
  403.            Allows you to choose your own color for the line
  404.            used for drawing the fitted equation.
  405.  
  406.   F10           -  MANUALLY CHANGE VIEWING AREA
  407.            Allows you to manually enter the coordinates
  408.            of the viewing area.
  409.  
  410.   CURSOR
  411.   KEYS          - MOVE VIEWPOINT OF GRAPH
  412.           The cursor keys move the viewpoint area on the graph.
  413.           For larger moves (3x), use Ctrl-Arrow Up, Ctrl-Arrow
  414.           Down, Ctrl-PgUp, Ctrl-PgDn
  415.  
  416.   z   Z        -  ZOOM IN,ZOOM OUT
  417.  
  418.   [   ]        -  DECREASE / INCREASE X SCALE
  419.           This will increase/decrease the X distance between the
  420.           dislpayed ends of the graph.
  421.  
  422.   {   }        -  DECREASE / INCREASE Y SCALE
  423.           This will increase/decrease the X distance between the
  424.           dislpayed ends of the graph.
  425.  
  426.   /   ?        -  TOGGLES DIVISION OF GRID SPACING BY 2
  427.           Divides grid spacing by two. / for Y axes, ? for X axes
  428.  
  429.   C            -  DISPLAYS EQUATION COEFF. / GET POLY R,σ,MaxErr
  430.           This displays the coefficients of the currently displayed
  431.           equation.  It will also calculate the correlation
  432.           coefficient, standard error and maximum error of a
  433.           polynomial fit if it has not done so already.
  434.  
  435.   D            -  DISPLAYS DATA COMPARISON
  436.           Will display a comparison between the original data
  437.           and the calculated values.  The arrow keys will allow
  438.           the user to scroll up and down through the data.
  439.  
  440.   R            -  RESETS GRAPH SETTINGS
  441.           Resets zoom and grid parameters and centers plot.
  442.  
  443.   V            -  CALCULATE VALUE FROM FITTED EQUATION
  444.           Allows user to calculate a value using the fitted equation.
  445.  
  446.   E            -  OUTPUT GRAPH TO PRINTER
  447.                   This will dump the graphics screen to the
  448.                   selected printer.  In the registered version,
  449.                   'PRESS F1 FOR HOTKEYS' will disappear.  In the
  450.                   unregistered version it is replaced by the
  451.                   message 'UNREGISTERED SHAREWARE'.  Both versions
  452.                   then send a copy of the screen to the printer.
  453.  
  454.   M            -  CALCULATE MOMENTS OF DATA
  455.  
  456.   Q            -  PLOT RESIDUALS
  457.  
  458.   P            -  CREATE DOS TEXT FILE
  459.           Creates DOS text file containing Equation type,
  460.           coefficients, input data, data from displayed equation
  461.           and the standard error, maximum error and correlation
  462.           coefficient.
  463.  
  464.   S            -  SAVE CONFIGURATION
  465.           Saves the current state (line color, thickness,
  466.           data circling, data marking, grid labeling etc) to
  467.                   disk in file 'CF515.CFG'.
  468.  
  469.   ESC          -  Pressing the ESC will break any loop, including drawing
  470.           the curve and circling data.
  471.  
  472.  
  473.                           COMMAND LINE
  474.                           ------------
  475.  
  476.  CurveFits can send fit results to standard output via the
  477.  following options:
  478.  
  479.  cf515 # /brief filename
  480.  
  481.  This will output a brief description of the fit results to stdout.
  482.  This output is redirectable.
  483.  
  484.  A longer description (the default) can be output this way:
  485.  
  486.  cf515 # filename
  487.  
  488.  Finally, to skip the intro screen and go directly to the graph
  489.  use this option:
  490.  
  491.  cf515 # /view filename
  492.  
  493.  In the above examples, 'filename' is of course the name of the
  494.  file, and # is a number which corresponds to the desired fit,
  495.  defined by the following table:
  496.  
  497.  #      Fit
  498.  ---------------------
  499.  1      Linear
  500.  2      Quadratic
  501.  3      Power
  502.  4      Exponential
  503.  5      Logarithm
  504.  6      Hyperbolic
  505.  7      Super Geometric
  506.  8      Root
  507.  9      Polynomial
  508.  10     Reciprocal Line
  509.  11     Reciprocal Quadratic
  510.  12     Modified Power
  511.  13     Modified Exponential
  512.  14     Reciprocal Logarithm
  513.  15     Reciprocal Hyperbolic
  514.  16     Modified Geometric
  515.  17     Heat Capacity
  516.  18     Vapor Pressure
  517.  19     Exponential Step
  518.  20     Sinusoidal
  519.  21     Gaussiam
  520.  22     Inverse
  521.  23     Hoerl
  522.  24     Cauchy
  523.  25     Modified Hoerl
  524.  26     Log Normal
  525.  27     Gamma
  526.  28     Beta
  527.  
  528.               COMPUTATIONS
  529.               ------------
  530.  
  531.  Standard Error:
  532.  ---------------
  533.  
  534.  StErr = SquareRoot(SumErrSqr/(N-2))
  535.  
  536.  Correlation Coefficient:
  537.  ------------------------
  538.  R = SquareRoot(1-SumErrSqr/(Sum(Y*Y)-SQR(Sum(Y)*Sum(Y))/N))
  539.  
  540.  where:
  541.  
  542.  SumErrSq is the sum of the sum of the squared difference between
  543.       the calculated values and actual data.
  544.  Sum(Y*Y) is the sum of the squares of the Y data
  545.  N        is the number of data points
  546.  Sum(Y)   is the sum of the Y data
  547.  
  548.  This formula will sometimes return a correlation greater than one.  This
  549.  is usually indicative of a poor fit. If a value above one is generated, it
  550.  is set to zero for the Fits|Best Correlation option.
  551.  
  552.                 PROGRAM
  553.                 -------
  554.  CF515 uses Turbo Pascal's extended real data type.  This data type allows
  555.  for 18-19 digit accuracy in computations.  However, this data type requires
  556.  a math coprocessor.  The program runs at a very acceptable speed on my
  557.  computer which is an 80486DX2/66MHz.
  558.  
  559.  
  560.                  DATA FILE FORMAT
  561.                  ----------------
  562.  
  563.  For those who wish to know the format of a CurveFits data file it is
  564.  a simple binary file whose record structure (in Pascal) is
  565.  
  566.    type          DataPair = record
  567.                 x : extended;
  568.                 y : extended;
  569.                 end;
  570.  
  571.  in C this translates to :
  572.  
  573.         struct DataPair {
  574.                 long double x;
  575.                 long double y;
  576.                 };
  577.  
  578.  
  579.  
  580.                 SHAREWARE NOTICE:
  581.                 -----------------
  582.  The program Curvefits v5.15 and this text file are not in the public
  583.  domain, they are shareware.  Please register your copy by sending $25
  584.  to the below address.
  585.  
  586.              John P. Arkins
  587.              54 Pearl Street
  588.              NHP, NY 11040-3814
  589.