mwavepy.network
index
/home/alex/docs/python/path/mwavepy/network.py

Provides the Network class and related functions.

 
Modules
       
mwavepy.mathFunctions
numpy
os
pylab
scipy.stats
mwavepy.touchstone

 
Classes
       
__builtin__.object
Network

 
class Network(__builtin__.object)
    Represents a n-port microwave network.
 
the most fundemental properties are:
        s: scattering matrix. a kxnxn complex matrix where 'n' is number
                of ports of network.
        z0: characteristic impedance
        f: frequency vector in Hz. see also frequency, which is a
                Frequency object (see help on this class for more info)
        
 
The following operators are defined as follows:
        '+' : element-wise addition of the s-matrix
        '-' : element-wise subtraction of the s-matrix
        '*' : element-wise multiplication of the s-matrix
        '/' : element-wise division of the s-matrix
        '**': cascading of 2-port networks
        '//': de-embdeding of one network from the other.
 
various other network properties are accesable as well as plotting
routines are also defined for convenience, 
 
most properties are derived from the specifications given for
touchstone files.
 
  Methods defined here:
__add__(self, other)
element-wise addition of s-matrix
__div__(self, other)
element-wise complex division  of s-matrix
__eq__(self, other)
__floordiv__(self, other)
 implements de-embeding another network[s], from this network
 
see de_embed
__getitem__(self, key)
returns a Network object at a given single frequency
__init__(self, touchstone_file=None, name=None)
constructor.
 
takes:
        file: if given will load information from touchstone file
        name: name of this network.
__mul__(self, a)
element-wise complex multiplication  of s-matrix
__ne__(self, other)
__pow__(self, other)
implements cascading this network with another network
__repr__(self)
__str__(self)
__sub__(self, other)
element-wise subtraction of s-matrix
add_noise_polar(self, mag_dev, phase_dev, **kwargs)
adds a complex zero-mean gaussian white-noise signal of given
standard deviations for magnitude and phase
 
takes:
        mag_mag: standard deviation of magnitude
        phase_dev: standard deviation of phase [in degrees]
        n_ports: number of ports. defualt to 1
returns:
        nothing
change_frequency(self, new_frequency, **kwargs)
flip(self)
swaps the ports of a two port
interpolate(self, new_frequency, **kwargs)
calculates an interpolated network. defualt interpolation type
is linear. see notes about other interpolation types
 
takes:
        new_frequency:
        **kwargs: passed to scipy.interpolate.interp1d initializer.
                  
returns:
        result: an interpolated Network
 
note:
        usefule keyward for  scipy.interpolate.interp1d:
         kind : str or int
                Specifies the kind of interpolation as a string ('linear',
                'nearest', 'zero', 'slinear', 'quadratic, 'cubic') or as an integer
                specifying the order of the spline interpolator to use.
multiply_noise(self, mag_dev, phase_dev, **kwargs)
multiplys a complex bivariate gaussian white-noise signal
of given standard deviations for magnitude and phase.   
magnitude mean is 1, phase mean is 0 
 
takes:
        mag_dev: standard deviation of magnitude
        phase_dev: standard deviation of phase [in degrees]
        n_ports: number of ports. defualt to 1
returns:
        nothing
nudge(self, amount=1e-12)
perturb s-parameters by small amount. this is usefule to work-around
numerical bugs.
takes:
        amount: amount to add to s parameters
returns:
        na
plot_polar_generic(self, attribute_r, attribute_theta, m=0, n=0, ax=None, show_legend=True, **kwargs)
generic plotting function for plotting a Network's attribute
in polar form
 
 
takes:
plot_s_all_db(self, ax=None, show_legend=True, *args, **kwargs)
plots all s parameters in log magnitude
 
takes:
        ax - matplotlib.axes object to plot on, used in case you
                want to update an existing plot.
        show_legend: boolean, to turn legend show legend of not
        *args,**kwargs - passed to the matplotlib.plot command
plot_s_complex(self, m=None, n=None, ax=None, show_legend=True, *args, **kwargs)
plots the scattering parameter of indecies m, n on complex plane
 
takes:
        m - first index, int
        n - second indext, int
        ax - matplotlib.axes object to plot on, used in case you
                want to update an existing plot.
        show_legend: boolean, to turn legend show legend of not
        *args,**kwargs - passed to the matplotlib.plot command
plot_s_db(self, m=None, n=None, ax=None, show_legend=True, *args, **kwargs)
plots the magnitude of the scattering parameter of indecies m, n
in log magnitude
 
takes:
        m - first index, int
        n - second indext, int
        ax - matplotlib.axes object to plot on, used in case you
                want to update an existing plot.
        show_legend: boolean, to turn legend show legend of not
        *args,**kwargs - passed to the matplotlib.plot command
plot_s_deg(self, m=None, n=None, ax=None, show_legend=True, *args, **kwargs)
plots the phase of a scattering parameter of indecies m, n in
degrees
 
takes:
        m - first index, int
        n - second indext, int
        ax - matplotlib.axes object to plot on, used in case you
                want to update an existing plot.
        show_legend: boolean, to turn legend show legend of not
        *args,**kwargs - passed to the matplotlib.plot command
plot_s_deg_unwrap = plot_s_deg_unwrapped(self, m=None, n=None, ax=None, show_legend=True, *args, **kwargs)
plot_s_deg_unwrapped(self, m=None, n=None, ax=None, show_legend=True, *args, **kwargs)
plots the phase of a scattering parameter of indecies m, n in
unwrapped degrees
 
takes:
        m - first index, int
        n - second indext, int
        ax - matplotlib.axes object to plot on, used in case you
                want to update an existing plot.
        show_legend: boolean, to turn legend show legend of not
        *args,**kwargs - passed to the matplotlib.plot command
plot_s_mag(self, m=None, n=None, ax=None, show_legend=True, *args, **kwargs)
plots the magnitude of a scattering parameter of indecies m, n
not in  magnitude
 
takes:
        m - first index, int
        n - second indext, int
        ax - matplotlib.axes object to plot on, used in case you
                want to update an existing plot.
        show_legend: boolean, to turn legend show legend of not
        *args,**kwargs - passed to the matplotlib.plot command
plot_s_polar(self, m=0, n=0, ax=None, show_legend=True, *args, **kwargs)
plots the scattering parameter of indecies m, n in polar form
 
takes:
        m - first index, int
        n - second indext, int
        ax - matplotlib.axes object to plot on, used in case you
                want to update an existing plot.
        show_legend: boolean, to turn legend show legend of not
        *args,**kwargs - passed to the matplotlib.plot command
plot_s_rad(self, m=None, n=None, ax=None, show_legend=True, *args, **kwargs)
plots the phase of a scattering parameter of indecies m, n in
radians
 
takes:
        m - first index, int
        n - second indext, int
        ax - matplotlib.axes object to plot on, used in case you
                want to update an existing plot.
        show_legend: boolean, to turn legend show legend of not
        *args,**kwargs - passed to the matplotlib.plot command
plot_s_rad_unwrapped(self, m=None, n=None, ax=None, show_legend=True, *args, **kwargs)
plots the phase of a scattering parameter of indecies m, n in
unwrapped radians
 
takes:
        m - first index, int
        n - second indext, int
        ax - matplotlib.axes object to plot on, used in case you
                want to update an existing plot.
        show_legend: boolean, to turn legend show legend of not
        *args,**kwargs - passed to the matplotlib.plot command
plot_s_smith(self, m=None, n=None, r=1, ax=None, show_legend=True, chart_type='z', *args, **kwargs)
plots the scattering parameter of indecies m, n on smith chart
 
takes:
        m - first index, int
        n - second indext, int
        r -  radius of smith chart
        ax - matplotlib.axes object to plot on, used in case you
                want to update an existing plot.
        show_legend: boolean, to turn legend show legend of not
        chart_type: string determining countour type. options are:
                'z': impedance contours (default)
                'y': admittance contours
        *args,**kwargs - passed to the matplotlib.plot command
plot_vs_frequency_generic(self, attribute, y_label=None, m=None, n=None, ax=None, show_legend=True, **kwargs)
generic plotting function for plotting a Network's attribute
vs frequency.
 
 
takes:
read_touchstone(self, filename)
loads  values from a touchstone file. 
 
takes:
        filename - touchstone file name, string. 
 
note: 
        ONLY 'S' FORMAT SUPORTED AT THE MOMENT 
        all work is tone in the touchstone class.
write_touchstone(self, filename=None, dir='./')
write a touchstone file representing this network.  the only 
format supported at the moment is :
        HZ S RI 
 
takes: 
        filename: a string containing filename without 
                extension[None]. if 'None', then will use the network's 
                name. if this is empty, then throws an error.
        dir: the directory to save the file in. [string]. Defaults 
                to './'
        
 
note:
        in the future could make possible use of the touchtone 
        class, but at the moment this would not provide any benefit 
        as it has not set_ functions.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)
f
the frequency vector for the network, in Hz.
frequency
returns a Frequency object, see  frequency.py
inv
a network representing inverse s-parameters, for de-embeding
number_of_ports
the number of ports the network has.
passivity
 passivity metric for a multi-port network. It returns
a matrix who's diagonals are equal to the total power 
received at all ports, normalized to the power at a single
excitement  port.
 
mathmatically, this is a test for unitary-ness of the 
s-parameter matrix. 
 
for two port this is 
        ( |S11|^2 + |S21|^2, |S22|^2+|S12|^2)
in general it is  
        S.H * S
where H is conjugate transpose of S, and * is dot product
 
note:
see more at,
http://en.wikipedia.org/wiki/Scattering_parameters#Lossless_networks
s
The scattering parameter matrix.
 
s-matrix has shape fxnxn, 
where; 
        f is frequency axis and,
        n's are port indicies
s11
s12
s21
s22
s_db
returns the magnitude of the s-parameters, in dB
 
note:
        dB is calculated by 
                20*log10(|s|)
s_deg
returns the phase of the s-parameters, in radians
s_deg_unwrap
returns the unwrapped phase of the s-paramerts, in degrees
s_mag
returns the magnitude of the s-parameters.
s_rad
returns the phase of the s-parameters, in radians.
s_rad_unwrap
returns the unwrapped phase of the s-parameters, in radians.
t
returns the t-parameters, which are also known as wave cascading
matrix.
y
z0
the characteristic impedance of the network.
 
z0 can be may be a number, or numpy.ndarray of shape n or fxn.

 
Functions
       
average(list_of_networks)
calculates the average network from a list of Networks. 
this is complex average of the s-parameters for a  list of Networks
 
takes:
        list_of_networks: a list of Networks
returns:
        ntwk: the resultant averaged Network [mwavepy.Network]
cascade(a, b)
DEPRECATED. see connect_s() instead.
 
cascade two s-matricies together.
 
a's port 2 == b's port 1
 
if you want a different port configuration use the flip() fuction
takes:
        a: a 2x2 or kx2x2 s-matrix
        b: a 2x2, kx2x2, 1x1, or kx1x1 s-matrix 
note:
        BE AWARE! this relies on s2t function which has a inf problem 
        if s11 or s22 is 1.
connect(ntwkA, k, ntwkB, l)
connect two n-port networks together. specifically, connect port 'k'
on ntwkA to port 'l' on ntwkB. The resultant network has
(ntwkA.nports+ntwkB.nports -2) ports. The port index's ('k','l') 
start from 0. Port impedances are taken into account.
 
takes:
        ntwkA: network 'A', [mwavepy.Network]
        k: port index on ntwkA [int] ( port indecies start from 0 )
        ntwkB: network 'B', [mwavepy.Network]
        l: port index on ntwkB [int]
 
returns:
        ntwkC': new network of rank (ntwkA.nports+ntwkB.nports -2)-ports
 
 
note:
        see functions connect_s() and innerconnect_s() for actual 
S-parameter connection algorithm.
        
        the effect of mis-matched port impedances is handled by inserting
a 2-port 'mismatch' network between the two connected ports.
connect_s(S, k, T, l)
connect two n-port networks together. specifically, connect port 'k'
on network 'S' to port 'l' on network 'T'. The resultant network has
(S.rank + T.rank-2)-ports
 
takes:
        S: S-parameter matrix [numpy.ndarray].
        k: port index on S (port indecies start from 0) [int]
        T: S-parameter matrix [numpy.ndarray]
        l: port index on T [int]
returns:
        S': new S-parameter matrix [numpy.ndarry]
        
 
note: 
        shape of S-parameter matrices can be either nxn, or fxnxn, where
f is the frequency axis. 
        internally, this function creates a larger composite network 
and calls the  innerconnect() function. see that function for more 
details about the implementation
csv_2_touchstone(filename)
converts a csv file saved from a Rhode swarz and possibly other 
 
takes:
        filename: name of file
returns:
        Network object
de_embed(a, b)
de-embed a 2x2 s-matrix from another 2x2 s-matrix
 
c = b**-1 * a
 
note:
        BE AWARE! this relies on s2t function which has a inf problem 
        if s11 or s22 is 1.
flip(a)
invert the ports of a networks s-matrix, 'flipping' it over
 
note:
                only works for 2-ports at the moment
func_on_networks(ntwk_list, func, attribute='s', *args, **kwargs)
Applies a function to some attribute of aa list of networks, and 
returns the result in the form of a Network. This means information 
that may not be s-parameters is stored in the s-matrix of the
returned Network.
 
takes:
        ntwk_list: list of mwavepy.Network types
        func: function to operate on ntwk_list s-matrices
        attribute: attribute of Network's  in ntwk_list for func to act on
        *args: passed to func
        **kwargs: passed to func
 
returns:
        mwavepy.Network type, with s-matrix the result of func, 
                operating on ntwk_list's s-matrices
 
 
example:
        averaging can be implemented with func_on_networks by 
                func_on_networks(ntwk_list,mean)
impedance_mismatch(z1, z2)
returns a two-port network for a impedance mis-match
 
takes:
        z1: complex impedance of port 1 [ number, list, or 1D ndarray]
        z2: complex impedance of port 2 [ number, list, or 1D ndarray]
returns:
        2-port s-matrix for the impedance mis-match
innerconnect(ntwkA, k, l)
connect two ports of a single n-port network, resulting in a 
(n-2)-port network. port indecies start from 0.
 
takes:
        ntwk: the network. [mwavepy.Network]
        k: port index [int] (port indecies start from 0)
        l: port index [int]
returns:
        ntwk': new network of with n-2 ports. [mwavepy.Network]
        
note:
        see functions connect_s() and innerconnect_s() for actual 
S-parameter connection algorithm.
innerconnect_s(S, k, l)
connect two ports of a single n-port network, resulting in a 
(n-2)-port network.
 
takes:
        S: S-parameter matrix [numpy.ndarray] 
        k: port index [int]
        l: port index [int]
returns:
        S': new S-parameter matrix [numpy.ndarry]
        
This function is based on the algorithm presented in the paper:
        'Perspectives in Microwave Circuit Analysis' by R. C. Compton
         and D. B. Rutledge
The original algorithm is given in 
        'A NEW GENERAL COMPUTER ALGORITHM FOR S-MATRIX CALCULATION OF
        INTERCONNECTED MULTIPORTS' by Gunnar Filipsson
inv(s)
inverse s-parameters, used for de-embeding
load_all_touchstones(dir='.', contains=None, f_unit=None)
loads all touchtone files in a given dir 
 
takes:
        dir  - the path to the dir, passed as a string (defalut is cwd)
        contains - string which filename must contain to be loaded, not 
                used if None.(default None)
returns:
        ntwkDict - a Dictonary with keys equal to the file name (without
                a suffix), and values equal to the corresponding ntwk types
one_port_2_two_port(ntwk)
calculates the two-port network given a  symetric, reciprocal and 
lossless one-port network.
 
takes:
        ntwk: a symetric, reciprocal and lossless one-port network.
returns:
        ntwk: the resultant two-port Network
plot_uncertainty_bounds(ntwk_list, attribute='s_mag', m=0, n=0, n_deviations=3, alpha=0.3, *args, **kwargs)
plots mean value with +- uncertainty bounds in an Network attribute,
for a list of Networks. 
 
takes:
        ntwk_list: list of Netmwork types [list]
        attribute: attribute of Network type to analyze [string] 
        m: first index of attribute matrix [int]
        n: second index of attribute matrix [int]
        n_deviations: number of std deviations to plot as bounds [number]
        alpha: passed to matplotlib.fill_between() command. [number, 0-1]
        *args,**kwargs: passed to Network.plot_'attribute' command
        
returns:
        None
        
 
Caution:
         if your list_of_networks is for a calibrated short, then the 
        std dev of deg_unwrap might blow up, because even though each
        network is unwrapped, they may fall on either side fo the pi 
        relative to one another.
plot_uncertainty_bounds_s_deg(*args, **kwargs)
this just calls 
        plot_uncertainty_bounds(attribute= 's_deg',*args,**kwargs)
see plot_uncertainty_bounds for help
plot_uncertainty_bounds_s_mag(*args, **kwargs)
this just calls 
        plot_uncertainty_bounds(attribute= 's_mag',*args,**kwargs)
see plot_uncertainty_bounds for help
s2t(s)
converts a scattering parameters to 'wave cascading parameters'
 
input matrix shape should be should be 2x2, or kx2x2
 
BUG: if s -matrix has ones for reflection, thsi will produce inf's
you cant cascade a matrix like this anyway, but we should handle it 
better
t2s(t)
converts a 'wave cascading parameters' to scattering parameters 
 
input matrix shape should be should be 2x2, or kx2x2
two_port_reflect(ntwk1, ntwk2, **kwargs)
generates a two-port reflective (S21=S12=0) network, from the
 2 one-port networks
 
takes:
        ntwk1: Network on  port 1 [mwavepy.Network]
        ntwk2: Network on  port 2 [mwavepy.Network]
 
returns:
        result: two-port reflective network, S12=S21=0 [mwavepy.Network]
 
 
example:
to use a working band to create a two-port reflective standard from
two one-port standards
        my_media= ...
        two_port_reflect(my_media.short(), my_media.match())
write_dict_of_networks(ntwkDict, dir='.')
writes a dictionary of networks to a given directory

 
Data
        ALMOST_ZER0 = 1e-06