Add utilities mag2db and db2mag

cwrowley · cwrowley · commit bdac7c145e2d · 2015-04-08T22:38:01.000-04:00
These convert magnitudes to decibels and back
diff --git a/control/__init__.py b/control/__init__.py
@@ -75,7 +75,7 @@
 from .timeresp import forced_response, initial_response, step_response, \
     impulse_response
 from .xferfcn import TransferFunction
-from .ctrlutil import unwrap, issys
+from .ctrlutil import *
 from .frdata import FRD
 from .canonical import canonical_form, reachable_form
 
diff --git a/control/ctrlutil.py b/control/ctrlutil.py
@@ -45,6 +45,8 @@
 import numpy as np
 from numpy import pi
 
+__all__ = ['unwrap', 'issys', 'db2mag', 'mag2db']
+
 # Utility function to unwrap an angle measurement
 def unwrap(angle, period=2*pi):
     """Unwrap a phase angle to give a continuous curve
@@ -78,3 +80,43 @@ def unwrap(angle, period=2*pi):
 def issys(obj):
     """Return True if an object is a system, otherwise False"""
     return isinstance(obj, lti.Lti)
+
+def db2mag(db):
+    """Convert a gain in decibels (dB) to a magnitude
+
+    If A is magnitude,
+
+        db = 20 * log10(A)
+
+    Parameters
+    ----------
+    db : float or ndarray
+        input value or array of values, given in decibels
+
+    Returns
+    -------
+    mag : float or ndarray
+        corresponding magnitudes
+
+    """
+    return 10. ** (db / 20.)
+
+def mag2db(mag):
+    """Convert a magnitude to decibels (dB)
+
+    If A is magnitude,
+
+        db = 20 * log10(A)
+
+    Parameters
+    ----------
+    mag : float or ndarray
+        input magnitude or array of magnitudes
+
+    Returns
+    -------
+    db : float or ndarray
+        corresponding values in decibels
+
+    """
+    return 20. * np.log10(mag)
diff --git a/control/tests/ctrlutil_test.py b/control/tests/ctrlutil_test.py
@@ -41,6 +41,22 @@ def test_unwrap_list(self):
         angle_unwrapped = [0, 0.2, 0.4, 0.6]
         np.testing.assert_array_almost_equal(unwrap(angle, 1.0), angle_unwrapped)
 
+    def test_db2mag(self):
+        for mag, db in zip(self.mag, self.db):
+            np.testing.assert_almost_equal(mag, db2mag(db))
+
+    def test_db2mag_array(self):
+        mag_array = db2mag(self.db)
+        np.testing.assert_array_almost_equal(mag_array, self.mag)
+
+    def test_mag2db(self):
+        for db, mag in zip(self.db, self.mag):
+            np.testing.assert_almost_equal(db, mag2db(mag))
+
+    def test_mag2db_array(self):
+        db_array = mag2db(self.mag)
+        np.testing.assert_array_almost_equal(db_array, self.db)
+
 
 def test_suite():
     return unittest.TestLoader().loadTestsFromTestCase(TestUtils)
