Free Filters Library to compute Butterworth, Chebyshev and Quasieliptic characteristic polynomials with minimum insertion loss. More...

Classes
class	CharPolys
	Characteristic polynomials class. More...

Functions
def	setGlobalVariablesLibFreeFilters
	Function to allow the GUI set values to the global variables of libcomonfunc module.
def	polyOmega
	Returns for the input polynomial $P_w(\omega)$ , with $s=j\omega$ or $\omega=-js$ .
def	polyCheby
	Compute Chebyshev polynomials from order 0 to N.
def	polyConj
	Returns the 'Paraconjugate' of the input polynomial , with complex variable restricted to the imaginary axis, $s=j\omega$ , and therefore $s^{*} = -s$ .
def	findEps
	This function finds the maximum of the function $g(s)=\|\frac{NUM(s)}{\epsilon DEN(s)}\|$ in the imaginary axis.
def	rootErrors
	Report errors in the roots position for a polynomial of the form SQF(s) = F(s)F(-s) with real coefficients.
def	factorization
	Factorization of polynomial SQF(s) of order 2N as a product of two polynomials, each one of order N.
def	vecSort
	Sort a vector of complex numbers so that their imaginary parts is in decreasing order.
def	butterworthFilter
	Compute characteristic polynomials and characteristic constants of a Butterwoth filter.
def	chebyshevFilter
	Compute characteristic polynomials and characteristic constants of a Chebyshev filter.
def	quasiElipticFilter
	Compute characteristic polynomials and characteristic constants of a Quasieliptic filter.

Variables
	mainWindow = None
	Module global variable equal either to None or to the GUI QMainWindow class instance, containing the application main window.
	importedExtraFilters = False
	Variable set to True if the non-free libextrafilters is available.

Detailed Description

Free Filters Library to compute Butterworth, Chebyshev and Quasieliptic characteristic polynomials with minimum insertion loss.

Author: J.M. Rius, J. Mateu, J.M. Tamayo, C. Collado, A. Padilla and J. O'Callaghan

Dpt. Signal Tehory and Communications, Universitat Politècnica de Catalunya (UPC),

Version: 2.0.3

Date: June 11, 2013

Acknowledgement: The software was developed in the frame of contract 21398/08/NL/GLC with the European Space Agency (ESA). Technical Offer was Christoph Ernst. Further features were developed under contract UPC-C7767 with Thales Alenia Space España (TAS-E). Contributions to the definition of the software functionality and testing have been made by Christoph Ernst, Mónica Martínez Mendoza and other ESA-ESTEC personnel, and Santiago Sobrino and Luis Roglá from TAS-E.

Copyright: © Universitat Politècnica de Catalunya (UPC) 2009.
Contact: lossy.nosp@m.filt.nosp@m.ers@t.nosp@m.sc.u.nosp@m.pc.ed.nosp@m.u

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program in file "LICENSE.GPL3"; if not, download it from http://www.gnu.org/licenses/gpl-3.0.html .

Additional permission under GNU GPL version 3 section 7:

If you modify this Program, or any covered work, by linking or combining it with the "Extra Filters Library" (libextrafilters), the "Lossy Filters Library" (liblossyfilters) or the "License Check Library" (libchecklicense), or modified versions of that libraries, containing parts covered by the terms described in files LICENSE.LIBEXTRAFILTERS and LICENSE.LIBLOSSYFILTERS, the licensors of this Program grant you additional permission to convey the resulting work.

Function Documentation

def libfreefilters.butterworthFilter	(	P,
		FT,
		symmetrizeZeros = `None`
	)

Compute characteristic polynomials and characteristic constants of a Butterwoth filter.

        @param P = Parameter class instance containing filter, synthesis and sweep parameters.
        @param  FT = Frequency transformation class instance.
        @param symmetrizeZeros = This parameter is ignored in this class of filter.  
        @return Ps = Characteristic polynomial of the numerator of \form#25 over characteristic constant \form#250 ( \form#251).
        @return Es = Characteristic polynomial of the denominator of \form#25 and \form#23.
        @return Fs = Caracteristic polynomial of the numerator of \form#23 considering a lossy system. 
        @return eps = Constant in the denominator of \form#25.
        @return epsR = Constant in the denominator of \form#23. 
        @return rootsErr = Maximum distance between the theoretical position of SQF roots and the actual position. Equal to zero for this kind of filter.

    @section butterCharPolys Algorithm
        [TN 102.1 sec. 7.2].
    <ol>
    <li> The roots of \form#252 can be found as [TN 102.1 eq. (28)]:

$s_k = \left\{ \begin{array}{ll} \exp \left( \frac{j\pi(2k-1)}{2N} \right) & \text{$N$ odd} \\ \exp \left( \frac{j\pi 2k }{2N} \right) & \text{$N$ even} \end{array} \right.$

where $k = 1 \ldots 2N$ and $ N $ is the filter order.

The coeffcicients of $ E(s) $ are obtained from the roots of $ E(s)E(-s) $ that lie in the LHS of the s-plane using the numpy.poly1d methods.

$ P(s) = 1 $

$ F(s) = s^N $

$\epsilon = 1$

$\epsilon_R = 1$

Definition at line 652 of file libfreefilters.py.

References libcommonfunc.warningMsg().

Referenced by libfreefilters.CharPolys.__init__().

Here is the call graph for this function:

Here is the caller graph for this function:

def libfreefilters.chebyshevFilter	(	P,
		FT,
		symmetrizeZeros = `None`
	)

Compute characteristic polynomials and characteristic constants of a Chebyshev filter.

        @param P = Parameter class instance containing filter, synthesis and sweep parameters.
        @param  FT = Frequency transformation class instance.
        @param symmetrizeZeros = This parameter is ignored in this class of filter.  
        @return Ps = Characteristic polynomial of the numerator of \form#25 over characteristic constant \form#250 ( \form#251).
        @return Es = Characteristic polynomial of the denominator of \form#25 and \form#23.
        @return Fs = Caracteristic polynomial of the numerator of \form#23 considering a lossy system. 
        @return eps = Constant in the denominator of \form#25.
        @return epsR = Constant in the denominator of \form#23. 
        @return rootsErr = Maximum distance between the theoretical position of SQF roots and the actual position. Equal to zero for this kind of filter.

    @section chebyCharPolys Algorithm
    [TN 102.1 sec. 7.3]
    <ol>
    <li> \form#260, 
    where \form#261 are the return losses (parameter "chebyLr") [TN102.1 eq.(25)].

    <li> \form#256

    <li> Since \form#255  has been obtained from its roots, the highest degree coeffcicient is equal to 1. 
    In order to guarantee that

$\max(S_{21}(\omega)) = \max \left(\frac{P(s)}{\epsilon E(s)} \right) = 1$

characteristic constant $\epsilon$ is recomputed with CharPolys.findEps() method.

$ F(s) = T_N(-js) $ where $ T_N $ is the Chebyshev polynomial of order N [TN 102.1 eq. (32)].

The polyCheby() method is used to compute $ T_N $ , while polyOmega() makes the change of variable $\omega = -js$ .

The roots of $ E(s) $ are [TN 102.1 eq. (34)]:

$\begin{eqnarray*} s_k &=& -\sinh(\mu) \sin(\theta) + j \cosh(\mu) \cos(\theta) \\ \mu &=& \frac{1}{N} \sinh^{-1} \left( \frac{1}{\epsilon} \right) \\ \theta &=& \left( \frac{\pi}{2} \right) \left( \frac{2k - 1}{N} \right) \\ k &=& 1 \ldots N \end{eqnarray*}$

The coeffcicients of $ E(s) $ are obtained from the roots using the numpy.poly1d methods.

It is not necessary to define $k = 1 \ldots 2N$ and pick up the roots in the LHS of the s-plane, as suggested in [TN 102.1 eq. (34)], since $\epsilon>0 \Rightarrow \mu>0$ and $k = 1 \ldots N \Rightarrow \sinh(\mu) \sin(\theta) > 0$ .

$\epsilon_R$ is the ratio of the highest degree coefficients of $ F(s) $ and $ E(s) $ in order to guarantee that $|S_{11}(\omega)| \rightarrow 1$ as $\omega \rightarrow \infty$ .

Definition at line 734 of file libfreefilters.py.

References findEps(), polyCheby(), and polyOmega().

Referenced by libfreefilters.CharPolys.__init__().

Here is the call graph for this function:

Here is the caller graph for this function:

def libfreefilters.factorization	(	SQF,
		method
	)

Factorization of polynomial SQF(s) of order 2N as a product of two polynomials, each one of order N.

    Polynomials are of type numpy.poly1d.
        @param SQF  = Polynomial to factorize as a product of two.
        @param method = Either an integer value between 1 and 4 describing the method of choosing which roots of the polynomial SQF go in each factor, or a list of Booleans.
                        <br>See documentation below.
        @return Fs, F22s = The two polynomials in which the input polynomial SQF is factorized.
        Fs and F22s are normalized to highest order coefficient equal to 1. 
        F22s is formed from the roots discarded in Fs, and should be equal to

$ (-1)^N F(s)^* = (-1)^N F^*(-s) $ [Cameron pp. 208,212], where $ F(s)^* $ is the 'Paraconjugate' polynomial of $ F(s) $ (see function CharPolys.polyConj).

Returns: rootsErr = Maximum distance between the theoretical position of SQF roots and the actual position. Real or imaginary parts with abs() smaller than tolerance will be considered as a zero. A pair of roots separated less than this tolerance in s-plane will be cosidered as a double root.

Factorization

The input polynomial is factorized as:

$SQF(s) = F(s)F_{22}(s)$

so that when s is restricted to the imaginary axis, $s=j\omega$ , it accomplishes the following:

$|SQF(j\omega)| = F(j\omega)F^{*}(j\omega), |SQF(j\omega)| = F_{22}(j\omega)F_{22}^{*}(j\omega), \forall \omega \in \Re.$

The roots of the polynomial SQF(s) must be symmetric about imaginary axis. Note that for pure imaginary roots, they must be of even multiplicity. This restriction is equivalent to the fact that SQF(s) can be factorized as:

$SQF(s) = F(s)F(-s)$

    There are different methods to choose the roots of F(s) from the roots of SQF(s): <br>
    <ol>
        <li>If 'method' argument is an integer:
            <ul>
            <li>method == 1 -> All zeros in the left s-plane (Hurwitz).
            <li>method == 2 -> All zeros in the right s-plane.
            <li>method == 3 -> The roots in right and left s-planes are ordered by decreasing imaginary part and alternatively we choose for F(s) a root in the right or in the left s-plane.
            <li>method == 4 -> The complementary of 3.
            </ul>
        <li>If 'method' argument is a list of Booleans:
            <ul>
                <li>If method[n] is True,  zeros_in_left_s-plane[n] go to F(s)  and the symmetrical zeros_in_right_s-plane[n] go to F(-s).
                <li>If method[n] is False, zeros_in_left_s-plane[n] go to F(-s) and the symmetrical zeros_in_right_s-plane[n] go to F(s).
                <li>The zeros zero_in_right_s-plane and zero_in_left_s-plane are ordered by decreasing imaginary part.          
            </ul>
    </ol>    
    F22(s) is composed of the remaining roots from SQF(s) to form the complementary function to F(s). Method 1 is complementary to method 2 and 3 to 4:

$F^{1}(s) = F^{2}_{22}(s), F^{2}(s) = F^{1}_{22}(s), F^{3}(s) = F^{4}_{22}(s), F^{4}(s) = F^{3}_{22}(s).$

Definition at line 515 of file libfreefilters.py.

References libcommonfunc.complexStr(), libcommonfunc.copy(), libcommonfunc.myPrint(), libcommonfunc.readVerbose(), rootErrors(), and vecSort().

Referenced by quasiElipticFilter().

Here is the call graph for this function:

Here is the caller graph for this function:

def libfreefilters.findEps	(	NUM,
		DEN
	)

This function finds the maximum of the function $g(s)=|\frac{NUM(s)}{\epsilon DEN(s)}|$ in the imaginary axis.

Usually $ NUM = Ps,Fs $ and $ DEN=Es $ . Polynomials are of type numpy.poly1d.

Parameters

NUM	= Numerator polynomial of the function to maximize.
DEN	= Denominator polynomial of the function to maximize.

Returns

eps = Maximum value of the function to maximize. It accomplishes that the maximum value of $g(s)=|\frac{NUM(s)}{\epsilon DEN(s)}|$ in the imaginary axis is equal to 0 dB. To do the maximization we procede as follows: $SQNUM(s) =|NUM(s)|^{2} = NUM(s)NUM^{*}(-s)$ for $s=j\omega$ . $SQDEN(s)=|DEN(s)|^{2} = DEN(s)DEN^{*}(-s)$ for $s=j\omega$ . The function f to maximize is:

$f(s)=\frac{SQNUM(s)}{SQDEN(s)}=\frac{|NUM(s)|^{2}}{|DEN(s)|^{2}}$

$f'(s)=\frac{SQNUM'(s)SQDEN(s)-SQNUM(s)SQDEN'(s)}{SQDEN(s)^{2}}=0$

The maximum of f is obtained in one of the roots of the numerator of $ f'(s) $

.

Definition at line 422 of file libfreefilters.py.

References polyConj().

Referenced by chebyshevFilter(), and quasiElipticFilter().

Here is the call graph for this function:

Here is the caller graph for this function:

def libfreefilters.polyCheby ( N )

Compute Chebyshev polynomials from order 0 to N.

@param N = Maximum order of polynomials (int)
@return Tn = List containing Chebyshev polynomials. List elements of type numpy.poly1d.

@section alfPolyCheby Algorithm

The recursion formula for Chebyshev polynomials

$T_{n}(\omega) = 2 \omega T_{n-1}(\omega) - T_{n-2}(\omega)$

is used to find $ T_N $ after setting $ T_0 = 1 $ and $T_1 = \omega$ .

Definition at line 379 of file libfreefilters.py.

Referenced by chebyshevFilter(), and quasiElipticFilter().

Here is the caller graph for this function:

def libfreefilters.polyConj ( P )

Returns the 'Paraconjugate' $ P_c(s) $ of the input polynomial $ P(s) $ , with complex variable restricted to the imaginary axis, $s=j\omega$ , and therefore $s^{*} = -s$ .

    If \form#174 is the polynomial order, \form#230 can be expressed as:

$P(s) = \sum_{n=0}^{N} c_{n}s^{n}$

We define the paraconjugate $P_c(s)$ as [Cameron pp. 208, footnote].:

$P_c(s) = P(s)^* = P^*(s^*) = P^{*}(-s) = \sum_{n=0}^{N}(-1)^{n}c_{n}^*s^{n}$

When the frequency is evaluated for complex $ s $ not in the imaginary axis, $s = \sigma + j\omega$ , you cannot compute $S_{22}$ using the 'paraconjugate' polynomial of $ F(s) $ , and must complex-conjugate the array of values of for each $ s $ .

Parameters

P	= Input polynomial .

Returns: Pc = Paraconjugate polynomial .

Definition at line 401 of file libfreefilters.py.

Referenced by libfreefilters.CharPolys.__init__(), findEps(), and quasiElipticFilter().

Here is the caller graph for this function:

def libfreefilters.polyOmega ( Pw )

Returns $ P_s(s) $ for the input polynomial $P_w(\omega)$ , with $s=j\omega$ or $\omega=-js$ .

    If \form#174 is the polynomial order, \form#220 and \form#216 can be expressed as:

$P_w(w) = \sum_{n=0}^{N}c_{n}\omega^{n}$

$P_s(s) = [P_w(\omega)]|_{\omega=-js} = \sum_{n=0}^{N}(-j)^{n}c_{n}s^{n}$

Parameters

Pw	= Input polynomial $P_w(\omega)$ .

Returns: Ps = .

Definition at line 359 of file libfreefilters.py.

Referenced by chebyshevFilter(), and quasiElipticFilter().

Here is the caller graph for this function:

def libfreefilters.quasiElipticFilter	(	P,
		FT,
		symmetrizeZeros = `None`
	)

Compute characteristic polynomials and characteristic constants of a Quasieliptic filter.

        @param P = Parameter class instance containing filter, synthesis and sweep parameters.
        @param  FT = Frequency transformation class instance.
        @param symmetrizeZeros = This parameter is ignored in this class of filter.  
        @return Ps = Characteristic polynomial of the numerator of \form#25 over characteristic constant \form#250 ( \form#251).
        @return Es = Characteristic polynomial of the denominator of \form#25 and \form#23.
        @return Fs = Caracteristic polynomial of the numerator of \form#23 considering a lossy system. 
        @return eps = Constant in the denominator of \form#25.
        @return epsR = Constant in the denominator of \form#23. 
        @return rootsErr = Maximum distance between the theoretical position of SQF roots and the actual position. 
                                        Real or imaginary parts with abs() smaller than tolerance will be considered as a zero. 
                                        A pair of roots separated less than this tolerance in s-plane will be cosidered as a double root.

    @section quasiElipticCharPolys Algorithm
    [TN 102.1 sec. 7.4]
    <ol>
    <li> \form#260, 
    where \form#261 are the return losses (parameter "chebyLr") [TN102.1 eq.(25)].

    <li> \form#270, [TN 102.1, eq. (40)]

    <li> In order to obtain \form#255, the first step is to compute the following linear combination of Chebyshev polynomials [Tn 102.1, eq. (37) and (38)]:

$\begin{eqnarray*} \alpha &=& \frac{(a+\sqrt{a^2-1})^2}{2} \\ \beta &=& -a^2 \\ \gamma &=& \frac{(a-\sqrt{a^2-1})^2}{2} \\ K_N(\omega) &=& \alpha \, \omega \, T_{N-1}(\omega) + \beta \, T_{N-2}(\omega) * + \gamma \, \omega \, T_{N-3}(\omega) \end{eqnarray*}$

Then, $E(j\omega)E(-j\omega)$ is [TN 102.1, eq. (41)]:

$E(\omega)E(-\omega) = \left( a^2 - \omega^2 \right)^2 + \epsilon^2 \, K^2_N (\omega)$

$ E(s)E(-s) $ is found by replacing $\omega = -js$ above by the function polyOmega().

    Finally, the roots of \form#255 are the roots of \form#252 that lie in the LHS of the s-plane.

    <li> Since \form#255  has been obtained from its roots, the highest degree coeffcicient is equal to 1. 
    According to eq. (39) and (41) in TN102.1, the polynomial \form#274 
    is the denominator of \form#275 and therefore includes the constant \form#276. 
    Consequently, \form#10 must be set to the square root of the highest degree coeffcicient of \form#252.

    <li> \form#215 follows from the energy conservation equation [TN 102.1, eq. (29)]:

$\left| S_{11}(s) \right|^2 + \left| S_{21}(s) \right|^2 = 1$

$\frac{\left| F(s) \right|^2}{\epsilon_R^2} = \left| E(s) \right|^2 - \frac{\left| P(s) \right|^2}{\epsilon^2}$

$\frac{F(s)F(-s)}{\epsilon_R^2} = E(s)E(-s) - \frac{P(s)P(-s)}{\epsilon^2}$

where we assume $\epsilon_R = 1$ .

The roots of $ F(s) $ are obtained from the roots of F(s)F(-s) by the CharPolys.factorization() method.

$\epsilon_R$ must be recomputed as the ratio of the highest degree coefficients of $ F(s) $ and $ E(s) $ in order to guarantee that $|S_{11}(\omega)| \rightarrow 1$ as $\omega \rightarrow \infty$ .

Definition at line 833 of file libfreefilters.py.

References factorization(), findEps(), polyCheby(), polyConj(), and polyOmega().

Referenced by libfreefilters.CharPolys.__init__().

Here is the call graph for this function:

Here is the caller graph for this function:

def libfreefilters.rootErrors ( roots_SQF )

Report errors in the roots position for a polynomial of the form SQF(s) = F(s)F(-s) with real coefficients.

The roots of the polynomial SQF(s) must be symmetric about imaginary axis. Note that for pure imaginary roots, they must be of even multiplicity.

The error is computed as the maximum distance between the roots theoretical and actual positions.

Parameters

roots_SQF = Array of roots. Type numpy.array.

Returns: maxErr = Maximum distance between the roots theoretical and actual positions.

Definition at line 447 of file libfreefilters.py.

Referenced by factorization().

Here is the caller graph for this function:

def libfreefilters.setGlobalVariablesLibFreeFilters ( variablesDict )

Function to allow the GUI set values to the global variables of libcomonfunc module.

This function is used in order to avoid circular imports.

Parameters

variablesDict,: Variable keyword argument list. Python creates a dictionary.

Definition at line 63 of file libfreefilters.py.

Referenced by mwfiltersgui.MainWindow.__init__().

Here is the caller graph for this function:

def libfreefilters.vecSort ( vec )

Sort a vector of complex numbers so that their imaginary parts is in decreasing order.

Parameters

vec	= complex vector to sort.

Returns: vecsort = sorted vector.

Definition at line 601 of file libfreefilters.py.

Referenced by factorization().

Here is the caller graph for this function:

Variable Documentation

libfreefilters.importedExtraFilters = False

Variable set to True if the non-free libextrafilters is available.

Otherwise set to False.

Definition at line 901 of file libfreefilters.py.

libfreefilters.mainWindow = None

Module global variable equal either to None or to the GUI QMainWindow class instance, containing the application main window.

It is equal to None (default) when the calling program is the console interface (mwfiltersgui.py –nogui). When creating the main window, the GUI executes the libfreefilters.setGlobalVariablesLibFreeFilters() function in order to set this variable. The GUI methods do not use this variable. They access the mainWindow class through ParamEditDlg.mainWindow and MainWindow 'self' attributes.

Definition at line 55 of file libfreefilters.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

Factorization

Variable Documentation