home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / misc / integra1_0a.lha / Integra / doc / integra_lib.autodoc next >
Encoding:
Text File  |  1995-02-06  |  15.0 KB  |  483 lines
  1.  
  2.     NAME
  3.         Integra.lib v1.0a
  4.  
  5.     COPYRIGHT
  6.         (C) Copyright 1994,95 Daniele Finocchiaro, Gianluca Marcoccia
  7.  
  8.     FUNCTION
  9.         Integra.lib is a library package for the numerical
  10.         computation of definite one-dimensional integrals.
  11.  
  12.     AUTHORS
  13.         Daniele Finocchiaro, Gianluca Marcoccia
  14.                              (marcocci@cli.di.unipi.it)
  15.  
  16.     CREATION DATE
  17.         24-Oct-1994
  18.  
  19.     MODIFICATION HISTORY
  20.         v1.0  - (24-10-94) initial release at IPISA 1994
  21.  
  22.         v1.0a - (06-02-95) nearly complete rewriting of the documentation
  23.                            added english docs and rearranged distribution
  24.  
  25. TABLE OF CONTENTS
  26.  
  27. Integra.lib/Int_function
  28. Integra.lib/Int_string
  29. Integra.lib/Int_points
  30. Integra.lib/Int_eq_points
  31. Integra.lib/Int_points_p
  32. Integra.lib/Int_eq_points_p
  33. Integra.lib/Parse_addfunction
  34. Integra.lib/Parse_eval
  35. Integra.lib/Parse_evalx
  36. Integra.lib/Int_function                              Integra.lib/Int_function
  37.  
  38.     NAME
  39.         Int_functions -- calculate integral on supplied f(x)
  40.  
  41.     SYNOPSIS
  42.         result = Int_function( &foobar, 0.0, 1.0, &pr )
  43.  
  44.         double Int_function( double (*f)(double),
  45.                                 double from, double to, int *prec);
  46.  
  47.                 /* Function e^(-x^2)    */
  48.         double foobar(double x) { return exp(-x*x); }
  49.  
  50.     int pr = 15;
  51.  
  52.     FUNCTION
  53.         The algorithm will evaluate the C function f() passed as an argument.
  54.         At exit, (*prec) is usually bigger(or equal to) than the value passed
  55.         to the function. This might not happen if the integration routined
  56.         met particular difficulties with the provided function.
  57.         (if prec=0 or (*prec) is out of 0..18 range,
  58.         default value of 15 is used)
  59.  
  60.     INPUTS
  61.         f       - pointer to a C function that requires a double
  62.                   and returns a double
  63.         from    - lower limit of the range of integration
  64.         to      - upper limit
  65.         prec    - pointer to an integer containing the number of
  66.                   precision digits required (default=15)
  67.  
  68.     RESULT
  69.         result  - value of the integral. When this value is returned
  70.                   in (*prec) you can find the number of digits exstimated
  71.                   to be exact.
  72.  
  73.     EXAMPLE
  74.  
  75.     NOTES
  76.  
  77.     BUGS
  78.  
  79.     SEE ALSO
  80.         Integra.lib/Int_string
  81.  
  82. Integra.lib/Int_string                                 Integra.lib/Int_string
  83.  
  84.     NAME
  85.         Int_string -- calculate integral on supplied string function
  86.  
  87.     SYNOPSIS
  88.         result = Int_string( "e^(-x*x)", 0., 1., &pr );
  89.  
  90.         double Int_string( char *expr, double from, double to, int *prec);
  91.  
  92.     int pr = 15;
  93.  
  94.     FUNCTION
  95.         The algorithm will evaluate the function f() passing the string to
  96.             Parse_evalx( expr, x ).
  97.         This is a parser function that evaluates a string containing a
  98.         function. Read the documentation about the parser function for the
  99.         format used in the string.
  100.         About `prec' see previous function.
  101.  
  102.  
  103.     INPUTS
  104.         expr    - string containing expression for f(x)
  105.         from    - lower limit of the range of integration
  106.         to      - upper limit
  107.         prec    - pointer to an integer containing the number of precision
  108.                   digits required (default=15)
  109.  
  110.     RESULT
  111.         result  - value of the integral. When this value is returned
  112.                   in (*prec) you can find the number of figures exstimated
  113.                   to be exact.
  114.  
  115.     EXAMPLE
  116.  
  117.     NOTES
  118.  
  119.     BUGS
  120.  
  121.     SEE ALSO
  122.         Integra.lib/Int_function
  123.         Integra.lib/Parse_addfunction
  124.         Integra.lib/Parse_eval
  125.         Integra.lib/Parse_evalx
  126.  
  127. Integra.lib/Int_points                                 Integra.lib/Int_points
  128.  
  129.     NAME
  130.         Int_points - calculate integral of function already known
  131.                      in some points
  132.  
  133.     SYNOPSIS
  134.         result = Int_points(100,x,fx);
  135.  
  136.         double Int_points(int n, double x[n], double fx[n])
  137.  
  138.         double  x[100] = { .. , .. , .. ... .. };
  139.         double fx[100] = { .. , .. , .. ... .. };
  140.  
  141.     FUNCTION
  142.         This function is used to integrate functions that are
  143.         already known on a assigned set of point. This means, for example,
  144.         that the values of x and f(x) have been previously obtained by some
  145.         kind of measurements, and now we need to evaluate an approximation
  146.         of the integral of f(x). This problem shows up often in practical
  147.         applications.
  148.         In this version we have implemented an interpolatory formula on 5
  149.         points. On an intuitive basis this means that every 5 points we
  150.         create the interpolation polinomial of fifth degree that passes
  151.         thru these 5 points, and we calculate the integral of this one.
  152.  
  153.     INPUTS
  154.         n       - number of points (>=2)
  155.         x[]     - array containing x points where we know f(x)
  156.         fx[]    - array containing values of f(x[i])
  157.  
  158.     RESULT
  159.         result  - evaluation of the integral.
  160.  
  161.     EXAMPLE
  162.  
  163.     NOTES
  164.         BEWARE: utilization of this routine is to be avoided as it implements
  165.         a much simpler integration method. (it is very fast anyway)
  166.  
  167.     BUGS
  168.  
  169.     SEE ALSO
  170.         Integra.lib/Int_points_p
  171.  
  172. Integra.lib/Int_eq_points                           Integra.lib/Int_eq_points
  173.  
  174.     NAME
  175.         Int_eq_points - calculate the integral of function already known
  176.                         in equidistribuited points
  177.  
  178.     SYNOPSIS
  179.         result = Int_eq_points(100,0.1,fx);
  180.  
  181.         double Int_eq_points(int n, double h, double fx[n])
  182.  
  183.         double fx[100] = { .. , .. , .. ... .. };
  184.  
  185.     FUNCTION
  186.         In this function we assume x points to be equidistribuited at a
  187.         distance of 'h' each other. In general:
  188.  
  189.             x[i] = x[0] + i*h
  190.  
  191.         Assuming this we can implement a much more efficient version of the
  192.         previous function, as far as the weights of the integration formula
  193.         are predefined. This algorithm is an extension to 5 points of the
  194.         Cavalieri-Simpson procedure. (which works with 3 points)
  195.  
  196.     INPUTS
  197.         n       - number of points (>=2)
  198.         h       - offset between x(es)
  199.         fx[]    - array containing values of f(x[i])
  200.  
  201.     RESULT
  202.         result  - evaluation of the integral.
  203.  
  204.     EXAMPLE
  205.  
  206.     NOTES
  207.         BEWARE: utilization of this routine is to be avoided as it implements
  208.         a much simpler integration method. (it is very fast anyway)
  209.  
  210.     BUGS
  211.  
  212.     SEE ALSO
  213.         Integra.lib/Int_eq_points_p
  214.  
  215. Integra.lib/Int_points_p                             Integra.lib/Int_points_p
  216.  
  217.     NAME
  218.         Int_points_p -- calculate integral of function already known in some
  219.                         points, also returns partial results of the
  220.                         computation
  221.  
  222.     SYNOPSIS
  223.         result = Int_points_p(100,x,fx,part);
  224.  
  225.         double Int_points_p(int n, double x[n],
  226.                             double fx[n], double partial[n-1]);
  227.  
  228.         double  x[100] = { .. , .. , .. ... .. };
  229.         double fx[100] = { .. , .. , .. ... .. };
  230.         double *part;
  231.  
  232.     FUNCTION
  233.         This function returns also intermediate approximations,
  234.         this is to say that it will return the evaluation of the integral
  235.         every time it adds a point to the solution.
  236.         This function is the same as Int_points, but returns in the partial[]
  237.         array all the intermediate values of the integral this is to say:
  238.  
  239.             partial[i] = integral of f(x) between x[0] and x[i+1]
  240.  
  241.         In particular partial[n-2] is the value returned by the function.
  242.  
  243.     INPUTS
  244.         n           - number of points (>=2)
  245.         x[]         - array containing x points where we know f(x)
  246.         fx[]        - array containing values of f(x[i])
  247.         partial[]   - array to be filled with partial integral values
  248.  
  249.     RESULT
  250.         result      - evaluation of the integral.
  251.  
  252.     EXAMPLE
  253.  
  254.     NOTES
  255.         CAVEAT: if partial==NULL Int_points() gets called instead.
  256.  
  257.         BEWARE: utilization of this routine is to be avoided as it implements
  258.         a much simpler integration method. (it is very fast anyway)
  259.  
  260.     BUGS
  261.  
  262.     SEE ALSO
  263.         Integra.lib/Int_points
  264.  
  265. Integra.lib/Int_eq_points_p                       Integra.lib/Int_eq_points_p
  266.  
  267.     NAME
  268.         Int_eq_points_p -- calculate the integral of function already known
  269.                            in equidistribuited points, also returns
  270.                            partial results of the computation
  271.  
  272.     SYNOPSIS
  273.         result = Int_eq_points_p(100,0.1,fx,part);
  274.  
  275.         double Int_eq_points_p(int n, double h,
  276.                                 double fx[n], double partial[n-1]);
  277.  
  278.         double fx[100] = { .. , .. , .. ... .. };
  279.         double *part;
  280.  
  281.     FUNCTION
  282.         Same as previous function, but x points are equidistributed.
  283.  
  284.     INPUTS
  285.         n           - number of points (>=2)
  286.         h           - offset between x(es)
  287.         fx[]        - array containing values of f(x[i])
  288.         partial[]   - array to be filled with partial integral values
  289.  
  290.     RESULT
  291.         result      - evaluation of the integral.
  292.  
  293.     EXAMPLE
  294.  
  295.     NOTES
  296.         CAVEAT: if partial==NULL Int_eq_points() gets called instead.
  297.  
  298.         BEWARE: utilization of this routine is to be avoided as it implements
  299.         a much simpler integration method. (it is very fast anyway)
  300.  
  301.     BUGS
  302.  
  303.     SEE ALSO
  304.         Integra.lib/Int_eq_points
  305.  
  306. Integra.lib/Parse_addfunction                   Integra.lib/Parse_addfunction
  307.  
  308.     NAME
  309.         Parse_addfunction -- add a function to the directory
  310.                              of known functions
  311.  
  312.     SYNOPSIS
  313.         result = Parse_addfunction("foo",&foobar);
  314.  
  315.         int Parse_addfunction(char *name, double (*f)(double) );
  316.  
  317.         double foobar(double x) { return cos(x)*(x+1); }
  318.  
  319.     FUNCTION
  320.         The function Parse_addfunction adds the specified function to the
  321.         directory of acknowledged functions.
  322.         This way of operation is useful when a certain function is known at
  323.         compilation time, and you can write explicitely the code that
  324.         calculates it. In this way we can implement further functions which
  325.         are not supplied (yet).
  326.  
  327.     INPUTS
  328.         name    - a name to be used as reference to the function
  329.         f       - pointer to the function to be added and associated to
  330.                   the 'name'.
  331.  
  332.     RESULT
  333.         This function returns 0 if everything is ok, -1 if it was not
  334.         possible to add the function (actually the only possible reason
  335.         for this it is that the directory is full).
  336.  
  337.     EXAMPLE
  338.         if ( Parse_addfunction("foo",&foobar) )
  339.             { exit(1); }
  340.         else
  341.             { ... }
  342.  
  343.     NOTES
  344.         Actually you can only use unary functions
  345.         (that need only one argument).
  346.  
  347.     BUGS
  348.  
  349.     SEE ALSO
  350.         Integra.lib/Parse_eval
  351.         Integra.lib/Parse_evalx
  352.  
  353. Integra.lib/Parse_eval                                 Integra.lib/Parse_eval
  354.  
  355.     NAME
  356.         Parse_eval - evaluate a string which contains a function
  357.  
  358.     SYNOPSIS
  359.         result = Parse_eval("2+2");
  360.  
  361.         double Parse_eval(char *expr);
  362.  
  363.     FUNCTION
  364.         Evaluates a string which contains the ascii definition of a function.
  365.  
  366.     INPUTS
  367.         Expression String Sintax
  368.  
  369.         More or less the sintax is the one used to insert expression on
  370.         a calculator. For example:
  371.  
  372.                 3*5+(2+sin(4))^2
  373.  
  374.         Operators as *, +, -, /, ^ (power), % (remaining of integer division)
  375.         and functions as
  376.  
  377.                 cos                             cosin
  378.                 sin                             sin
  379.                 tan, tg                         tangente
  380.                 arccos, acos                    arc-cosin
  381.                 arcsin, asin                    arc-sin
  382.                 arctan, arctg, atn, atan        arc-tangente
  383.                 cosh                            iperbolic cosin
  384.                 sinh                            iperbolic sin
  385.                 tanh                            iperbolic tangente
  386.                 ln                              natural logarithm
  387.                 log, log10                      10-base logarithm
  388.                 sqrt                            square root
  389.                 abs                             absolute value
  390.                 exp                             exponent (natural base)
  391.                 int                             integer part
  392.  
  393.         Moreover there are these predefined values:
  394.                 p                               pigreco
  395.                 e                               Nepero's number
  396.  
  397.         As said above, using Parse_addfunction() it is possible to add more
  398.         unary functions.
  399.  
  400.         The order used when evaluating is the usual one (unary function
  401.         first, multiplications, addition) but can be arranged using brackets.
  402.  
  403.         Assignments to variables are supported. In this version these
  404.         operations are limited to constant values or other variables.
  405.         The assignment is followed by a comma and the expression to be
  406.         evaluated.
  407.         For example:
  408.  
  409.                 z=2,z^2+z^3
  410.  
  411.         evaluates "2^2+2^3" giving 12 as result. This kind of operation will
  412.         probably be extended in future releases.
  413.  
  414.     RESULT
  415.         result  - evaluation of string
  416.  
  417.         At exit, variable Parse_error indicates whether there were errors
  418.         (0 all is ok). The result is to be taken in consideration only
  419.         if Parse_error=0.
  420.  
  421.     EXAMPLE
  422.  
  423.     NOTES
  424.         CAVEAT: beware of unary minus. String "-1^2" gets evaluated
  425.         as "(-1)^2", thus giving 1 as result. Instead, "5-1^2" is considered
  426.         as "5-(1^2)" and its result is 4.
  427.         As this behaviour is NOT STANDARD, this will probably be changed in
  428.         future releases. Always use brackets when in doubt.
  429.  
  430.     BUGS
  431.         Actually there are some cases in which the parser is unable
  432.         to certify the string. (these, anyway, are not relevant)
  433.  
  434.     SEE ALSO
  435.         Integra.lib/Parse_addfunction
  436.         Integra.lib/Parse_evalx
  437.  
  438. Integra.lib/Parse_evalx                               Integra.lib/Parse_evalx
  439.  
  440.     NAME
  441.         Parse_evalx -- evaluates a string which contains indeterminate x
  442.  
  443.     SYNOPSIS
  444.         result = Parse_evalx("x+x",valx);
  445.  
  446.         double Parse_evalx(char *expr, double x);
  447.  
  448.         double valx = 2;
  449.  
  450.     FUNCTION
  451.         Evaluates a string inside which there is the indeterminate 'x'.
  452.  
  453.     INPUTS
  454.         See Parse_eval() for the syntax of the expression string.
  455.  
  456.         x   - This value will bereplaced in the expression for every
  457.               occurrence of the x indeterminate.
  458.  
  459.     RESULT
  460.         result  - evaluation of string
  461.  
  462.         At exit, variable Parse_error indicates wether there were errors
  463.         (0 all is ok). The result is to be taken in consideration only
  464.         if Parse_error=0.
  465.  
  466.     EXAMPLE
  467.  
  468.     NOTES
  469.         CAVEAT: beware of unary minus. String "-1^2" gets evaluated
  470.         as "(-1)^2", thus giving 1 as result. Instead, "5-1^2" is considered
  471.         as "5-(1^2)" and its result is 4.
  472.         As this behaviour is NOT STANDARD, this will probably be changed in
  473.         future releases. Always use brackets when in doubt.
  474.  
  475.     BUGS
  476.         Actually there are some cases in which the parser is unable
  477.         to certify the string. (these anyway are not relevant)
  478.  
  479.     SEE ALSO
  480.         Integra.lib/Parse_addfunction
  481.         Integra.lib/Parse_eval
  482.  
  483.