update config module to use dictionary + module.variable format

murrayrm · murrayrm · commit 44de990cbca2 · 2019-07-06T22:39:05.000-07:00
diff --git a/control/config.py b/control/config.py
@@ -5,58 +5,66 @@
 # variables that control the behavior of the control package.
 # Eventually it will be possible to read and write configuration
 # files.  For now, you can just choose between MATLAB and FBS default
-# values.
+# values + tweak a few other things.
 
 import warnings
 
-# Bode plot defaults
-bode_dB = False                 # Bode plot magnitude units
-bode_deg = True                 # Bode Plot phase units
-bode_Hz = False                 # Bode plot frequency units
-bode_number_of_samples = None   # Bode plot number of samples
-bode_feature_periphery_decade = 1.0  # Bode plot feature periphery in decades
+__all__ = ['reset_defaults', 'use_matlab_defaults', 'use_fbs_defaults',
+           'use_numpy_matrix']
+
+# Dictionary of default values
+defaults = {
+    'bode.dB':False, 'bode.deg':True, 'bode.Hz':False, 'bode.grid':True,
+    'freqplot.feature_periphery_decades':1, 'freqplot.number_of_samples':None,
+    'statesp.use_numpy_matrix':True,
+}
 
-# State space module variables
-_use_numpy_matrix = True        # Decide whether to use numpy.marix
 
 def reset_defaults():
-    """Reset package configuration values to their default values."""
-    global bode_dB; bode_dB = False
-    global bode_deg; bode_deg = True
-    global bode_Hz; bode_Hz = False
-    global bode_number_of_samples; bode_number_of_samples = None
-    global bode_feature_periphery_decade; bode_feature_periphery_decade = 1.0
-    global _use_numpy_matrix; _use_numpy_matrix = True
+    """Reset configuration values to their default values."""
+    defaults['bode.dB'] = False
+    defaults['bode.deg'] =  True
+    defaults['bode.Hz'] = False
+    defaults['bode.grid'] = True
+    defaults['freqplot.number_of_samples'] = None
+    defaults['freqplot.feature_periphery_decades'] = 1.0
+    defaults['statesp.use_numpy_matrix'] = True
 
 
 # Set defaults to match MATLAB
 def use_matlab_defaults():
-    """
-    Use MATLAB compatible configuration settings
+    """Use MATLAB compatible configuration settings.
 
     The following conventions are used:
-        * Bode plots plot gain in dB, phase in degrees, frequency in Hertz
+        * Bode plots plot gain in dB, phase in degrees, frequency in
+          Hertz, with grids
+
     """
     # Bode plot defaults
-    global bode_dB; bode_dB = True
-    global bode_deg; bode_deg = True
-    global bode_Hz; bode_Hz = True
-    global _use_numpy_matrix; _use_numpy_matrix = True
+    from .freqplot import bode_plot
+    defaults['bode.dB'] = True
+    defaults['bode.deg'] = True
+    defaults['bode.Hz'] = True
+    defaults['bode.grid'] = True
+    defaults['statesp.use_numpy_matrix'] = True
 
 
 # Set defaults to match FBS (Astrom and Murray)
 def use_fbs_defaults():
-    """
-    Use `Feedback Systems <http://fbsbook.org>`_ (FBS) compatible settings
+    """Use `Feedback Systems <http://fbsbook.org>`_ (FBS) compatible settings.
 
     The following conventions are used:
+
         * Bode plots plot gain in powers of ten, phase in degrees,
-          frequency in Hertz
+          frequency in Hertz, no grid
+
     """
     # Bode plot defaults
-    global bode_dB; bode_dB = False
-    global bode_deg; bode_deg = True
-    global bode_Hz; bode_Hz = False
+    from .freqplot import bode_plot
+    defaults['bode.dB'] = False
+    defaults['bode.deg'] = True
+    defaults['bode.Hz'] = False
+    defaults['bode.grid'] = False
 
 
 # Decide whether to use numpy.matrix for state space operations
@@ -68,8 +76,8 @@ def use_numpy_matrix(flag=True, warn=True):
     flag : bool
         If flag is `True` (default), use the Numpy (soon to be deprecated)
         `matrix` class to represent matrices in the `~control.StateSpace`
-        class and functions.  If flat is `False`, then matrices are represnted
-        by a 2D `ndarray` object.
+        class and functions.  If flat is `False`, then matrices are
+        represented by a 2D `ndarray` object.
 
     warn : bool
         If flag is `True` (default), issue a warning when turning on the use
@@ -80,4 +88,4 @@ class and functions.  If flat is `False`, then matrices are represnted
     if flag and warn:
         warnings.warn("Return type numpy.matrix is soon to be deprecated.",
 	              stacklevel=2)
-    global _use_numpy_matrix; _use_numpy_matrix = flag
+    defaults['statesp.use_numpy_matrix'] = flag
diff --git a/control/freqplot.py b/control/freqplot.py
@@ -48,6 +48,7 @@
 from .ctrlutil import unwrap
 from .bdalg import feedback
 from .margins import stability_margins
+from .config import defaults
 
 __all__ = ['bode_plot', 'nyquist_plot', 'gangof4_plot',
            'bode', 'nyquist', 'gangof4']
@@ -62,10 +63,10 @@
 # Bode plot
 
 
-def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None,
-              Plot=True, omega_limits=None, omega_num=None, margins=None, *args, **kwargs):
-    """
-    Bode plot for a system
+def bode_plot(syslist, omega=None,
+              Plot=True, omega_limits=None, omega_num=None,
+              margins=None, *args, **kwargs):
+    """Bode plot for a system
 
     Plots a Bode plot for the system over a (optional) frequency range.
 
@@ -76,18 +77,21 @@ def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None,
     omega : list
         List of frequencies in rad/sec to be used for frequency response
     dB : boolean
-        If True, plot result in dB
+        If True, plot result in dB.  Defaults to config.defaults['bode.dB'].
     Hz : boolean
-        If True, plot frequency in Hz (omega must be provided in rad/sec)
+        If True, plot frequency in Hz (omega must be provided in rad/sec).
+        Defaults to config.defaults['bode.Hz']
     deg : boolean
-        If True, plot phase in degrees (else radians)
+        If True, plot phase in degrees (else radians).  Defaults to
+        config.defaults['bode.deg']
     Plot : boolean
         If True, plot magnitude and phase
     omega_limits: tuple, list, ... of two values
         Limits of the to generate frequency vector.
         If Hz=True the limits are in Hz otherwise in rad/s.
     omega_num: int
-        number of samples
+        Number of samples to plot.  Defaults to
+        config.defaults['freqplot.number_of_samples'].
     margins : boolean
         If True, plot gain and phase margin
     \*args, \**kwargs:
@@ -102,6 +106,12 @@ def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None,
     omega : array (list if len(syslist) > 1)
         frequency in rad/sec
 
+    Other Parameters
+    ----------------
+    grid : bool
+        If True, plot grid lines on gain and phase plots.  Default is set by
+        config.defaults['bode.grid'].
+
     Notes
     -----
     1. Alternatively, you may use the lower-level method (mag, phase, freq)
@@ -117,15 +127,13 @@ def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None,
     --------
     >>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.")
     >>> mag, phase, omega = bode(sys)
+
     """
-    # Set default values for options
-    from . import config
-    if dB is None:
-        dB = config.bode_dB
-    if deg is None:
-        deg = config.bode_deg
-    if Hz is None:
-        Hz = config.bode_Hz
+    # Set default values for options (and pop from list to allow use in plots)
+    dB = kwargs.pop('dB', defaults.get('bode.dB', False))
+    deg = kwargs.pop('deg', defaults.get('bode.deg', True))
+    Hz = kwargs.pop('Hz', defaults.get('bode.Hz', False))
+    grid = kwargs.pop('grid', defaults.get('bode.grid', True))
 
     # If argument was a singleton, turn it into a list
     if not getattr(syslist, '__iter__', False):
@@ -235,7 +243,7 @@ def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None,
                                    color=pltline[0].get_color())
 
                 # Add a grid to the plot + labeling
-                ax_mag.grid(False if margins else True, which='both')
+                ax_mag.grid(grid and not margins, which='both')
                 ax_mag.set_ylabel("Magnitude (dB)" if dB else "Magnitude")
 
                 # Phase plot
@@ -377,7 +385,7 @@ def gen_zero_centered_series(val_min, val_max, period):
                                                                  ylim[1],
                                                                  math.pi / 12.),
                                         minor=True)
-                ax_phase.grid(False if margins else True, which='both')
+                ax_phase.grid(grid and not margins, which='both')
                 # ax_mag.grid(which='minor', alpha=0.3)
                 # ax_mag.grid(which='major', alpha=0.9)
                 # ax_phase.grid(which='minor', alpha=0.3)
@@ -592,7 +600,7 @@ def gangof4_plot(P, C, omega=None):
 
 # Compute reasonable defaults for axes
 def default_frequency_range(syslist, Hz=None, number_of_samples=None, 
-                            feature_periphery_decade=None):
+                            feature_periphery_decades=None):
     """Compute a reasonable default frequency range for frequency
     domain plots.
 
@@ -603,24 +611,18 @@ def default_frequency_range(syslist, Hz=None, number_of_samples=None,
     ----------
     syslist : list of LTI
         List of linear input/output systems (single system is OK)
-
     Hz : bool
         If True, the limits (first and last value) of the frequencies
         are set to full decades in Hz so it fits plotting with logarithmic
         scale in Hz otherwise in rad/s. Omega is always returned in rad/sec.
-
     number_of_samples : int, optional
-        Number of samples to generate.  Defaults to ``numpy.logspace`` default
-        value.
-
-    feature_periphery_decade : float, optional
+        Number of samples to generate.  The default value is read from
+        ``config.defaults['freqplot.number_of_samples'].  If None, then the
+        default from `numpy.logspace` is used.
+    feature_periphery_decades : float, optional
         Defines how many decades shall be included in the frequency range on
-        both sides of features (poles, zeros).
-
-        Example: If there is a feature, e.g. a pole, at 1 Hz and
-        feature_periphery_decade=1., then the range of frequencies shall span
-        0.1 .. 10 Hz.  The default value is read from
-        ``config.bode_feature_periphery_decade``.
+        both sides of features (poles, zeros).  The default value is read from
+        ``config.defaults['freqplot.feature_periphery_decades']``.
 
     Returns
     -------
@@ -643,9 +645,10 @@ def default_frequency_range(syslist, Hz=None, number_of_samples=None,
     # Set default values for options
     from . import config
     if number_of_samples is None:
-        number_of_samples = config.bode_number_of_samples
-    if feature_periphery_decade is None:
-        feature_periphery_decade = config.bode_feature_periphery_decade
+        number_of_samples = config.defaults['freqplot.number_of_samples']
+    if feature_periphery_decades is None:
+        feature_periphery_decades = \
+            config.defaults['freqplot.feature_periphery_decades']
 
     # Find the list of all poles and zeros in the systems
     features = np.array(())
@@ -693,14 +696,14 @@ def default_frequency_range(syslist, Hz=None, number_of_samples=None,
     if Hz:
         features /= 2. * math.pi
         features = np.log10(features)
-        lsp_min = np.floor(np.min(features) - feature_periphery_decade)
-        lsp_max = np.ceil(np.max(features) + feature_periphery_decade)
+        lsp_min = np.floor(np.min(features) - feature_periphery_decades)
+        lsp_max = np.ceil(np.max(features) + feature_periphery_decades)
         lsp_min += np.log10(2. * math.pi)
         lsp_max += np.log10(2. * math.pi)
     else:
         features = np.log10(features)
-        lsp_min = np.floor(np.min(features) - feature_periphery_decade)
-        lsp_max = np.ceil(np.max(features) + feature_periphery_decade)
+        lsp_min = np.floor(np.min(features) - feature_periphery_decades)
+        lsp_max = np.ceil(np.max(features) + feature_periphery_decades)
     if freq_interesting:
         lsp_min = min(lsp_min, np.log10(min(freq_interesting)))
         lsp_max = max(lsp_max, np.log10(max(freq_interesting)))
diff --git a/control/matlab/__init__.py b/control/matlab/__init__.py
@@ -87,6 +87,10 @@
 from .timeresp import *
 from .wrappers import *
 
+# Set up defaults corresponding to MATLAB conventions
+from ..config import *
+use_matlab_defaults()
+
 r"""
 The following tables give an overview of the module ``control.matlab``.
 They also show the implementation progress and the planned features of the
diff --git a/control/statesp.py b/control/statesp.py
@@ -86,7 +86,7 @@ def _ssmatrix(data, axis=1):
     """
     # Convert the data into an array or matrix, as configured
     # If data is passed as a string, use (deprecated?) matrix constructor
-    if config._use_numpy_matrix or isinstance(data, str):
+    if config.defaults['statesp.use_numpy_matrix'] or isinstance(data, str):
         arr = np.matrix(data, dtype=float)
     else:
         arr = np.array(data, dtype=float)
@@ -128,15 +128,21 @@ class StateSpace(LTI):
     where u is the input, y is the output, and x is the state.
 
     The main data members are the A, B, C, and D matrices.  The class also
-    keeps track of the number of states (i.e., the size of A).
-
-    Discrete-time state space system are implemented by using the 'dt' instance
-    variable and setting it to the sampling period.  If 'dt' is not None,
-    then it must match whenever two state space systems are combined.
+    keeps track of the number of states (i.e., the size of A).  The data
+    format used to store state space matrices is set using the value of
+    `config.defaults['use_numpy_matrix']`.  If True (default), the state space
+    elements are stored as `numpy.matrix` objects; otherwise they are
+    `numpy.ndarray` objects.  The :func:`~control.use_numpy_matrix` function
+    can be used to set the storage type.
+
+    Discrete-time state space system are implemented by using the 'dt'
+    instance variable and setting it to the sampling period.  If 'dt' is not
+    None, then it must match whenever two state space systems are combined.
     Setting dt = 0 specifies a continuous system, while leaving dt = None
     means the system timebase is not specified.  If 'dt' is set to True, the
-    system will be treated as a discrete time system with unspecified
-    sampling time.
+    system will be treated as a discrete time system with unspecified sampling
+    time.
+
     """
 
     # Allow ndarray * StateSpace to give StateSpace._rmul_() priority
diff --git a/control/tests/config_test.py b/control/tests/config_test.py
diff --git a/doc/conventions.rst b/doc/conventions.rst
