From 474303b00b436e1359e83b1adec55c326d337925 Mon Sep 17 00:00:00 2001
From: Marc Lichtman <mlichtman@perspectalabs.com>
Date: Mon, 22 Oct 2018 17:20:00 -0400
Subject: docs- moved documentation inside docstring
---
gr-analog/python/analog/fm_emph.py | 375 ++++++++++++++++++-------------------
1 file changed, 184 insertions(+), 191 deletions(-)
(limited to 'gr-analog/python/analog/fm_emph.py')
diff --git a/gr-analog/python/analog/fm_emph.py b/gr-analog/python/analog/fm_emph.py
index 02bdd576ee..106457c07f 100644
--- a/gr-analog/python/analog/fm_emph.py
+++ b/gr-analog/python/analog/fm_emph.py
@@ -27,91 +27,87 @@ from gnuradio import gr, filter
import math
import cmath
-#
-# An analog deemphasis filter:
-#
-# R
-# o------/\/\/\/---+----o
-# |
-# = C
-# |
-# ---
-#
-# Has this transfer function:
-#
-# 1 1
-# ---- ---
-# RC tau
-# H(s) = ---------- = ----------
-# 1 1
-# s + ---- s + ---
-# RC tau
-#
-# And has its -3 dB response, due to the pole, at
-#
-# |H(j w_c)|^2 = 1/2 => s = j w_c = j (1/(RC))
-#
-# Historically, this corner frequency of analog audio deemphasis filters
-# been specified by the RC time constant used, called tau.
-# So w_c = 1/tau.
-#
-# FWIW, for standard tau values, some standard analog components would be:
-# tau = 75 us = (50K)(1.5 nF) = (50 ohms)(1.5 uF)
-# tau = 50 us = (50K)(1.0 nF) = (50 ohms)(1.0 uF)
-#
-# In specifying tau for this digital deemphasis filter, tau specifies
-# the *digital* corner frequency, w_c, desired.
-#
-# The digital deemphasis filter design below, uses the
-# "bilinear transformation" method of designing digital filters:
-#
-# 1. Convert digital specifications into the analog domain, by prewarping
-# digital frequency specifications into analog frequencies.
-#
-# w_a = (2/T)tan(wT/2)
-#
-# 2. Use an analog filter design technique to design the filter.
-#
-# 3. Use the bilinear transformation to convert the analog filter design to a
-# digital filter design.
-#
-# H(z) = H(s)|
-# s = (2/T)(1-z^-1)/(1+z^-1)
-#
-#
-# w_ca 1 1 - (-1) z^-1
-# H(z) = ---- * ----------- * -----------------------
-# 2 fs -w_ca -w_ca
-# 1 - ----- 1 + -----
-# 2 fs 2 fs
-# 1 - ----------- z^-1
-# -w_ca
-# 1 - -----
-# 2 fs
-#
-# We use this design technique, because it is an easy way to obtain a filter
-# design with the -6 dB/octave roll-off required of the deemphasis filter.
-#
-# Jackson, Leland B., _Digital_Filters_and_Signal_Processing_Second_Edition_,
-# Kluwer Academic Publishers, 1989, pp 201-212
-#
-# Orfanidis, Sophocles J., _Introduction_to_Signal_Processing_, Prentice Hall,
-# 1996, pp 573-583
-#
-
class fm_deemph(gr.hier_block2):
"""
- FM Deemphasis IIR filter.
+ FM Deemphasis IIR filter
+
+ Args:
+ fs: sampling frequency in Hz (float)
+ tau: Time constant in seconds (75us in US, 50us in EUR) (float)
+
+ An analog deemphasis filter:
+
+ R
+ o------/\/\/\/---+----o
+ |
+ = C
+ |
+ ---
+
+ Has this transfer function:
+
+ 1 1
+ ---- ---
+ RC tau
+ H(s) = ---------- = ----------
+ 1 1
+ s + ---- s + ---
+ RC tau
+
+ And has its -3 dB response, due to the pole, at
+
+ |H(j w_c)|^2 = 1/2 => s = j w_c = j (1/(RC))
+
+ Historically, this corner frequency of analog audio deemphasis filters
+ been specified by the RC time constant used, called tau.
+ So w_c = 1/tau.
+
+ FWIW, for standard tau values, some standard analog components would be:
+ tau = 75 us = (50K)(1.5 nF) = (50 ohms)(1.5 uF)
+ tau = 50 us = (50K)(1.0 nF) = (50 ohms)(1.0 uF)
+
+ In specifying tau for this digital deemphasis filter, tau specifies
+ the *digital* corner frequency, w_c, desired.
+
+ The digital deemphasis filter design below, uses the
+ "bilinear transformation" method of designing digital filters:
+
+ 1. Convert digital specifications into the analog domain, by prewarping
+ digital frequency specifications into analog frequencies.
+
+ w_a = (2/T)tan(wT/2)
+
+ 2. Use an analog filter design technique to design the filter.
+
+ 3. Use the bilinear transformation to convert the analog filter design to a
+ digital filter design.
+
+ H(z) = H(s)|
+ s = (2/T)(1-z^-1)/(1+z^-1)
+
+
+ w_ca 1 1 - (-1) z^-1
+ H(z) = ---- * ----------- * -----------------------
+ 2 fs -w_ca -w_ca
+ 1 - ----- 1 + -----
+ 2 fs 2 fs
+ 1 - ----------- z^-1
+ -w_ca
+ 1 - -----
+ 2 fs
+
+ We use this design technique, because it is an easy way to obtain a filter
+ design with the -6 dB/octave roll-off required of the deemphasis filter.
+
+ Jackson, Leland B., _Digital_Filters_and_Signal_Processing_Second_Edition_,
+ Kluwer Academic Publishers, 1989, pp 201-212
+
+ Orfanidis, Sophocles J., _Introduction_to_Signal_Processing_, Prentice Hall,
+ 1996, pp 573-583
"""
def __init__(self, fs, tau=75e-6):
- """
-
- Args:
- fs: sampling frequency in Hz (float)
- tau: Time constant in seconds (75us in US, 50us in EUR) (float)
- """
gr.hier_block2.__init__(self, "fm_deemph",
gr.io_signature(1, 1, gr.sizeof_float), # Input signature
gr.io_signature(1, 1, gr.sizeof_float)) # Output signature
@@ -144,125 +140,122 @@ class fm_deemph(gr.hier_block2):
deemph = filter.iir_filter_ffd(btaps, ataps, False)
self.connect(self, deemph, self)
-#
-# An analog preemphasis filter, that flattens out again at the high end:
-#
-# C
-# +-----||------+
-# | |
-# o------+ +-----+--------o
-# | R1 | |
-# +----/\/\/\/--+ \
- # /
-# \ R2
-# /
-# \
- # |
-# o--------------------------+--------o
-#
-# (This fine ASCII rendition is based on Figure 5-15
-# in "Digital and Analog Communication Systems", Leon W. Couch II)
-#
-# Has this transfer function:
-#
-# 1
-# s + ---
-# R1C
-# H(s) = ------------------
-# 1 R1
-# s + --- (1 + --)
-# R1C R2
-#
-#
-# It has a corner due to the numerator, where the rise starts, at
-#
-# |Hn(j w_cl)|^2 = 2*|Hn(0)|^2 => s = j w_cl = j (1/(R1C))
-#
-# It has a corner due to the denominator, where it levels off again, at
-#
-# |Hn(j w_ch)|^2 = 1/2*|Hd(0)|^2 => s = j w_ch = j (1/(R1C) * (1 + R1/R2))
-#
-# Historically, the corner frequency of analog audio preemphasis filters
-# been specified by the R1C time constant used, called tau.
-#
-# So
-# w_cl = 1/tau = 1/R1C; f_cl = 1/(2*pi*tau) = 1/(2*pi*R1*C)
-# w_ch = 1/tau2 = (1+R1/R2)/R1C; f_ch = 1/(2*pi*tau2) = (1+R1/R2)/(2*pi*R1*C)
-#
-# and note f_ch = f_cl * (1 + R1/R2).
-#
-# For broadcast FM audio, tau is 75us in the United States and 50us in Europe.
-# f_ch should be higher than our digital audio bandwidth.
-#
-# The Bode plot looks like this:
-#
-#
-# /----------------
-# /
-# / <-- slope = 20dB/decade
-# /
-# -------------/
-# f_cl f_ch
-#
-# In specifying tau for this digital preemphasis filter, tau specifies
-# the *digital* corner frequency, w_cl, desired.
-#
-# The digital preemphasis filter design below, uses the
-# "bilinear transformation" method of designing digital filters:
-#
-# 1. Convert digital specifications into the analog domain, by prewarping
-# digital frequency specifications into analog frequencies.
-#
-# w_a = (2/T)tan(wT/2)
-#
-# 2. Use an analog filter design technique to design the filter.
-#
-# 3. Use the bilinear transformation to convert the analog filter design to a
-# digital filter design.
-#
-# H(z) = H(s)|
-# s = (2/T)(1-z^-1)/(1+z^-1)
-#
-#
-# -w_cla
-# 1 + ------
-# 2 fs
-# 1 - ------------ z^-1
-# -w_cla -w_cla
-# 1 - ------ 1 - ------
-# 2 fs 2 fs
-# H(z) = ------------ * -----------------------
-# -w_cha -w_cha
-# 1 - ------ 1 + ------
-# 2 fs 2 fs
-# 1 - ------------ z^-1
-# -w_cha
-# 1 - ------
-# 2 fs
-#
-# We use this design technique, because it is an easy way to obtain a filter
-# design with the 6 dB/octave rise required of the premphasis filter.
-#
-# Jackson, Leland B., _Digital_Filters_and_Signal_Processing_Second_Edition_,
-# Kluwer Academic Publishers, 1989, pp 201-212
-#
-# Orfanidis, Sophocles J., _Introduction_to_Signal_Processing_, Prentice Hall,
-# 1996, pp 573-583
-#
class fm_preemph(gr.hier_block2):
"""
FM Preemphasis IIR filter.
+
+ Args:
+ fs: sampling frequency in Hz (float)
+ tau: Time constant in seconds (75us in US, 50us in EUR) (float)
+ fh: High frequency at which to flatten out (< 0 means default of 0.925*fs/2.0) (float)
+
+ An analog preemphasis filter, that flattens out again at the high end:
+
+ C
+ +-----||------+
+ | |
+ o------+ +-----+--------o
+ | R1 | |
+ +----/\/\/\/--+ \
+ /
+ \ R2
+ /
+ \
+ |
+ o--------------------------+--------o
+
+ (This fine ASCII rendition is based on Figure 5-15
+ in "Digital and Analog Communication Systems", Leon W. Couch II)
+
+ Has this transfer function:
+
+ 1
+ s + ---
+ R1C
+ H(s) = ------------------
+ 1 R1
+ s + --- (1 + --)
+ R1C R2
+
+
+ It has a corner due to the numerator, where the rise starts, at
+
+ |Hn(j w_cl)|^2 = 2*|Hn(0)|^2 => s = j w_cl = j (1/(R1C))
+
+ It has a corner due to the denominator, where it levels off again, at
+
+ |Hn(j w_ch)|^2 = 1/2*|Hd(0)|^2 => s = j w_ch = j (1/(R1C) * (1 + R1/R2))
+
+ Historically, the corner frequency of analog audio preemphasis filters
+ been specified by the R1C time constant used, called tau.
+
+ So
+ w_cl = 1/tau = 1/R1C; f_cl = 1/(2*pi*tau) = 1/(2*pi*R1*C)
+ w_ch = 1/tau2 = (1+R1/R2)/R1C; f_ch = 1/(2*pi*tau2) = (1+R1/R2)/(2*pi*R1*C)
+
+ and note f_ch = f_cl * (1 + R1/R2).
+
+ For broadcast FM audio, tau is 75us in the United States and 50us in Europe.
+ f_ch should be higher than our digital audio bandwidth.
+
+ The Bode plot looks like this:
+
+
+ /----------------
+ /
+ / <-- slope = 20dB/decade
+ /
+ -------------/
+ f_cl f_ch
+
+ In specifying tau for this digital preemphasis filter, tau specifies
+ the *digital* corner frequency, w_cl, desired.
+
+ The digital preemphasis filter design below, uses the
+ "bilinear transformation" method of designing digital filters:
+
+ 1. Convert digital specifications into the analog domain, by prewarping
+ digital frequency specifications into analog frequencies.
+
+ w_a = (2/T)tan(wT/2)
+
+ 2. Use an analog filter design technique to design the filter.
+
+ 3. Use the bilinear transformation to convert the analog filter design to a
+ digital filter design.
+
+ H(z) = H(s)|
+ s = (2/T)(1-z^-1)/(1+z^-1)
+
+
+ -w_cla
+ 1 + ------
+ 2 fs
+ 1 - ------------ z^-1
+ -w_cla -w_cla
+ 1 - ------ 1 - ------
+ 2 fs 2 fs
+ H(z) = ------------ * -----------------------
+ -w_cha -w_cha
+ 1 - ------ 1 + ------
+ 2 fs 2 fs
+ 1 - ------------ z^-1
+ -w_cha
+ 1 - ------
+ 2 fs
+
+ We use this design technique, because it is an easy way to obtain a filter
+ design with the 6 dB/octave rise required of the premphasis filter.
+
+ Jackson, Leland B., _Digital_Filters_and_Signal_Processing_Second_Edition_,
+ Kluwer Academic Publishers, 1989, pp 201-212
+
+ Orfanidis, Sophocles J., _Introduction_to_Signal_Processing_, Prentice Hall,
+ 1996, pp 573-583
"""
def __init__(self, fs, tau=75e-6, fh=-1.0):
- """
-
- Args:
- fs: sampling frequency in Hz (float)
- tau: Time constant in seconds (75us in US, 50us in EUR) (float)
- fh: High frequency at which to flatten out (< 0 means default of 0.925*fs/2.0) (float)
- """
gr.hier_block2.__init__(self, "fm_preemph",
gr.io_signature(1, 1, gr.sizeof_float), # Input signature
gr.io_signature(1, 1, gr.sizeof_float)) # Output signature
--
cgit v1.2.3