/*****************************************************************************
*                                                                            *
*   SOS2ZP.SPL   Copyright (C) 2015 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Second order section form to zeros, poles and gain          *
*                                                                            *
*   Revisions:   15 Jun 2015  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/

#if @HELP_SOS2ZP

    SOS2ZP

    Purpose: Converts second order section coefficients to zeros, poles, gain.

    Syntax:  SOS2ZP(sos, g)

             (z, p, k) = SOS2ZP(sos, g)

                sos - A Nx6 array where the first 3 columns are the numerator
                      terms and the last 3 columns are the denominator terms.
                      Each row represents a 2nd order stage.

                  g - Optional. A real, the gain, Defaults to 1.0.


    Returns: A Nx3 array where the first column contains the zeros, the second
             column contains the poles and the third column contains the gain.
             
             (z, p, k) = sos2zp(sos, g) returns the zeros, poles and gain as
             three separate arrays.

    Example:
             sos = {{1, -2, 0, 1, -0.7, 0.1}};
             (z, p, k) = sos2zp(c);

             z = {0.0, 2.0};
             p = {0.5, 0.2};
             k = 1.0;

             The SOS coefficients represent the system:

                                 1 - 2z^(-1)
             H(z) = (1) * --------------------------
                          1 - 0.7 z^(-1) + 0.1 z^(-2)


             z contains the zeros, p contains the poles and k is the
             gain of the system.

    Remarks:
             SOS2ZP converts second order section coefficients to zeros,
             poles and gain of a discrete system where the input
             coefficients represent the following Z transform:

                               -1       -2                -1       -2
                    b10 + b11 z  + b12 z       b20 + b21 z  + b22 z
         H(z) = G * ________________________ *  ________________________ ...
                               -1       -2                -1       -2
                      1 + a11 z  + a12 z         1 + a21 z  + a22 z


             where the SOS form is an Nx6 array:

             {{b10, b11, b12, 1, a11, a12},
              {b20, b21, b22, 1, a21, a22}, 

                            ...

              {bN0, bN1, bN2, 1, aN1, aN2}} 

             Each row of the SOS coefficients represents a second order stage.

             See ZP2SOS to convert zeros, poles and gain to SOS coefficients.

    See Also:
             Cas2zp
             Cascade
             Tf2zpk
             Sos2cas
             Zp2cas
             Zp2sos
             Zp2tf
#endif


/* second order section form to zeros, poles and gain */
sos2zp(sos, g)
{
        local cas, z, p, k, zpk;

        if (argc < 2)
        {
                if (argc < 1)
                {
                        sos = {};
                }

                g = 1.0;
        }

        if (numcols(sos) != 6)
        {
                error("sos2zp - input SOS must be a Nx6 array");
        }

        /* convert to cascade form */
        cas = sos2cas(sos, g);

        /* zeros and poles for cascade */
        if (outargc > 1)
        {
                (z, p, k) = cas2zp(cas);
        }
        else
        {
                /* single array */
                zpk = cas2zp(cas);

                return(zpk);
        }
}