/*****************************************************************************
*                                                                            *
*   TRAPZ.SPL    Copyright (C) 2000-2015 DSP Development Corporation         *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Integration using the trapezoidal rule                      *
*                                                                            *
*   Revisions:    3 Jan 2000  RRR  Creation                                  *
*                27 Mar 2003  RRR  zero first output point                   *
*                24 Apr 2003  RRR  vertical units                            *
*                14 May 2003  RRR  xy series support                         *
*                14 Nov 2003  RRR  ITERATE to iterate through input array    *
*                17 Nov 2009  RRR  difference equation for speed             *
*                29 Sep 2015  RRR  defer to cumtrapz                         *
*                                                                            *
*****************************************************************************/


#if @HELP_TRAPZ

    TRAPZ

    Purpose: Calculates the total area of a series using the trapezoidal rule.

    Syntax:  TRAPZ(series)

              series - An interval or XY series, the input data.


    Alternative Syntax:  

              TRAPZ(xseries, yseries)

              xseries - A series, the X values.

              yseries - A series, the Y values.

    Returns: A scalar, the total area.

    Example:

             trapz(gsin(1000, 1/1000, 0.5))

             returns 0.636618.  For a sinusoid, the result of the
             analytic computation is:

               1
              /
              | sin(pi * t) dt = (1/pi) * (1 - cos(pi)) = 2/pi
              /
             0

    Example:
             y1 = gnorm(1000, .001);
             a1 = cumtrapz(y1);
             a2 = trapz(y1);

             Series a1 contains the cumulative area of y1 and scalar a2
             contains the value of the total area of y1.  Note that
             a1[end] == a2, the last point of the cumulative area
             equals the total area.

    Remarks:
             For series S, the trapezoidal rule calulates the running sum
             of:
                        deltax * (S[i+1] + S[i]) / 2.

             See AREA to compute the total area using Simpson's rule.

             See CUMTRAPZ to compute the cumulative area using the
             trapezoidal rule.

    See Also:
             Area
             Cumtrapz
             Integ
#endif


/* trapezoidal rule */
ITERATE trapz(x, y)
{
        local t;

        /* last point of cumulative trapz sum is the result */
        t = cumtrapz(x, y);
        t = t[end];

        return(t);
}