Add documentation for custom configurations

murrayrm · murrayrm · commit 93b50b13ecb9 · 2016-12-27T09:09:14.000-08:00
diff --git a/control/__init__.py b/control/__init__.py
@@ -66,6 +66,7 @@
 from .frdata import *
 from .canonical import *
 from .robust import *
+from .config import *
 
 # Exceptions
 from .exception import *
diff --git a/control/config.py b/control/config.py
@@ -16,13 +16,22 @@
 
 # Set defaults to match MATLAB
 def use_matlab_defaults():
+    """
+    Use MATLAB compatible configuration settings
+        * Bode plots plot gain in dB, phase in degrees, frequency in Hertz
+    """
     # Bode plot defaults
     global bode_dB; bode_dB = True
     global bode_deg; bode_deg = True
     global bode_Hz; bode_Hz = True
 
 # Set defaults to match FBS (Astrom and Murray)
 def use_fbs_defaults():
+    """
+    Use `Astrom and Murray <http://fbsbook.org>`_ compatible settings
+        * Bode plots plot gain in powers of ten, phase in degrees, 
+          frequency in Hertz
+    """
     # Bode plot defaults
     global bode_dB; bode_dB = False
     global bode_deg; bode_deg = True
diff --git a/doc/conventions.rst b/doc/conventions.rst
@@ -1,5 +1,7 @@
 .. _conventions-ref:
 
+.. currentmodule:: control
+
 ###################
 Library conventions
 ###################
@@ -74,3 +76,28 @@ can be computed like this::
 
     ft = D * U
 
+Package configuration
+=====================
+
+The python-control library can be customized to allow for different plotting
+conventions.  The currently configurable options allow the units for Bode
+plots to be set as dB for gain, degrees for phase and Hertz for frequency
+(MATLAB conventions) or the gain can be given in magnitude units (powers of
+10), corresponding to the conventions used in `Feedback Systems
+<http://www.cds.caltech.edu/~murray/FBSwiki>`_.
+
+Variables that can be configured, along with their default values:
+  * bode_dB (False): Bode plot magnitude plotted in dB (otherwise powers of 10)
+  * bode_deg (True): Bode plot phase plotted in degrees (otherwise radians)
+  * bode_Hz (False): Bode plot frequency plotted in Hertz (otherwise rad/sec)
+  * bode_number_of_samples (None): Number of frequency points in Bode plots
+  * bode_feature_periphery_decade (1.0): How many decades to include in the
+    frequency range on both sides of features (poles, zeros). 
+
+Functions that can be used to set standard configurations:
+
+.. autosummary::
+    :toctree: generated/
+
+    use_fbs_defaults
+    use_matlab_defaults
