/*****************************************************************************
*                                                                            *
*   GSWEEP.SPL   Copyright (C) 2005-2023 DSP Development Corporation         *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Generates a swept sinewave                                  *
*                                                                            *
*   Revisions:   18 Jan 2005  RRR  Creation                                  *
*                13 Jun 2019  RRR  support for negative and constant freq    *
*                23 Feb 2023  RRR  support for PHI, initial phase            *
*                                                                            *
*****************************************************************************/


#if @HELP_GSWEEP

    GSWEEP

    Purpose:
             Generates a linearly swept sinewave.

    Syntax:
             GSWEEP(len, dx, start, end, phi)

             (s, f) = GSWEEP(len, dx, start, end, phi)

                  len  - An integer, the number of points to generate.

                    dx - A real, the spacing (deltax) between points.

                 start - Optional. A real, the starting frequency in Hertz.
                         Defaults to 10 Hz.

                   end - Optional. A real, the ending frequency in Hertz.
                         Defaults to 100 Hz.

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

    Returns:
             A series, a linearly swept sinewave.

             (s, f) = GSWEEP(len, dx, start, end, phi) returns both the
             swept sinewave and the instantaneous frequency series.

    Example:
             W1: gsweep(1000, .001, 2, 200)

             Creates a 1000 point linear swept sinewave with points spaced at
             an interval of 0.001 seconds (a sample rate of (1/.001 = 1000 Hz)
             starting at 2 Hz and ending at 200 Hz

    Example:
             W1: gsweep(1000, .001, -200, 200)

             Creates a 1000 point linear swept sinewave with points spaced at
             an interval of 0.001 seconds (a sample rate of (1/.001 = 1000 Hz)
             starting at 200 Hz, decreasing to 0 and then increasing to 200 Hz.

    Example:
             W2: spectrum(W1, 1024)
             W3: specgram(W1, 128, 120, 512)
             W4: demodfm(W1)

             W2 displays the normalized FFT showing frequency information from
             2 to 200 Hz. W3 displays the joint time-frequency plot of W1,
             clearly displaying the linear frequency ramp. W4 demodulates
             W1 to approximately recover the linear frequency ramp.

    Example:
             W1: gsweep(1000, .001, 2, 200, pi/2)

             Creates a 1000 point linear swept sinewave with points spaced at
             an interval of 0.001 seconds (a sample rate of (1/.001 = 1000 Hz)
             starting at 2 Hz and ending at 200 Hz. The starting phase is pi/2
             radians resulting in a swept cosine.

    Example:
             (s, f) = gsweep(1000, .001, 2, 200)

             Same as the first example except variable s contains the swept
             sinewave and variable f contains the instantaneous frequency
             values.

    Remarks:
             GSWEEP returns a series that is a linear frequency sweep from
             the starting frequency to the ending frequency. To prevent
             aliasing,  both the starting and ending frequencies must be
             less than 1 / (2 * dx), the Nyquist frequency.

             The sweep is created by calculating the sine of the integrated
             linear ramp:

                s = sin(2*pi*integ(t) + phi)

             where:

                   t = start..inc..end

                   inc = (end - start) / length


              To modulate with a cosine, set PHI to pi/2.

    See Also:
             Demodfm
             Gsin
             Integ
#endif



/* generate a linear frequecny sweep */
gsweep(len, dx, start = 10, stop = 100, phi = 0)
{
        local s, f, inc;

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

        /* frequency increment */
        inc = (stop - start) / len;

        /* swept frequency values */
        f = gline(len, 1, inc, start);
        
        /* set deltax and offset */
        setdeltax(f, dx);
        setxoffset(f, 0);

        /* units */
        setvunits(f, "Hz");

        /* frequency modulation */
        s = sin(2 * pi * integ(f) + phi);

        if (outargc > 1)
        {
                /* return swept sine and instantaneous frequency values */
                return(s, f);
        }
        else
        {
                return(s);
        }
}