/*****************************************************************************
*                                                                            *
*   GHAVERSIN.SPL Copyright (C) 2020 DSP Development Corporation             *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:       Randy Race                                                 *
*                                                                            *
*   Synopsis:     Generates a haversin function                              *
*                                                                            *
*   Revisions:    12 May 2020  RRR  Creation                                 *
*                                                                            *
*****************************************************************************/

#if @HELP_GHAVERSIN

    GHAVERSIN

    Purpose: Generates a haversin function in accordance with the specified
             parameters.

    Syntax:  GHAVERSIN(length, spacing, frequency, phase)

                 length - An integer, the length of the output series.

                spacing - A real, the spacing (delta X) between each point
                          on the X axis.

              frequency - Optional. A real, the frequency in cycles per
                          second (Hertz). Defaults to 1.0.

                  phase - Optional. A real, the phase in radians. Defaults
                          to 0.

    Returns: A series.

    Example:
             W1: ghaversin(1000, 1/1000)

             Generates 1000 samples of a 1 Hz haversin sampled at 1000 Hz.
 
    Example:
             W2: ghaversin(1000, 1/1000, 2.0, pi/3)

             Same as above except the frequency is 2 Hz and the phase is
             pi/3 radians.
 
    Remarks:
             The haversin function is defined as:

               haversin(theta) = sin(theta/2)^2 = (1 - cos(theta)) / 2

             
             The formula used to generate each point, n, in the series
             is as follows:

             h[n] = 0.5 * (1 - cos(2*pi*frequency*spacing * (n-1) * phase))

    See Also:
             Gsin
             Haversin
             Sin
#endif


/* generate a haversin function */
ghaversin(len, dx, f, phase)
{
        local h;

        if (argc < 4)
        {
                if (argc < 3)
                {
                        if (argc < 2)
                        {
                                error(sprintf("%s - input length and delta x required", __FUNC__));
                        }

                        f = 1.0;
                }

                phase = 0;
        }

        return(0.5 * (1 - gcos(len, dx, f, phase)));
}