added documentation to statesp, xferfcn, and conventions.rst describing new config parameters default_dt and remove_useless_states

sawyerbfuller · sawyerbfuller · commit 68c7ea6267ea · 2020-06-27T13:22:30.000-07:00
diff --git a/control/config.py b/control/config.py
@@ -161,6 +161,13 @@ class and functions.  If flat is `False`, then matrices are
     set_defaults('statesp', use_numpy_matrix=flag)
 
 def use_legacy_defaults(version):
+    """ Sets the defaults to whatever they were in a given release.
+
+    Parameters
+    ----------
+    version : string
+        version number of the defaults desired. Currently only supports `0.8.3`. 
+    """
     if version == '0.8.3': 
         use_numpy_matrix(True) # alternatively: set_defaults('statesp', use_numpy_matrix=True)
     else:
diff --git a/control/statesp.py b/control/statesp.py
@@ -149,7 +149,8 @@ class StateSpace(LTI):
     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.
+    time. The default value of 'dt' is None and can be changed by changing the 
+    value of ``control.config.defaults['statesp.default_dt']``.
 
     """
 
diff --git a/control/xferfcn.py b/control/xferfcn.py
@@ -93,7 +93,9 @@ class TransferFunction(LTI):
     instance variable and setting it to something other than 'None'.  If 'dt'
     has a non-zero value, then it must match whenever two transfer functions
     are combined.  If 'dt' is set to True, the system will be treated as a
-    discrete time system with unspecified sampling time.
+    discrete time system with unspecified sampling time. The default value of 
+    'dt' is None and can be changed by changing the value of 
+    ``control.config.defaults['xferfcn.default_dt']``.
 
     The TransferFunction class defines two constants ``s`` and ``z`` that
     represent the differentiation and delay operators in continuous and
diff --git a/doc/conventions.rst b/doc/conventions.rst
@@ -98,7 +98,9 @@ the result will be a discrete time system with the sample time of the latter
 system.  For continuous time systems, the :func:`sample_system` function or
 the :meth:`StateSpace.sample` and :meth:`TransferFunction.sample` methods
 can be used to create a discrete time system from a continuous time system.
-See :ref:`utility-and-conversions`.
+See :ref:`utility-and-conversions`. The default value of 'dt' can be changed by
+changing the values of ``control.config.defaults['statesp.default_dt']`` and 
+``control.config.defaults['xferfcn.default_dt']``.
 
 Conversion between representations
 ----------------------------------
@@ -220,9 +222,15 @@ Selected variables that can be configured, along with their default values:
   * freqplot.feature_periphery_decade (1.0): How many decades to include in the
     frequency range on both sides of features (poles, zeros).
     
-  * statesp.use_numpy_matrix: set the return type for state space matrices to
+  * statesp.use_numpy_matrix (True): set the return type for state space matrices to
     `numpy.matrix` (verus numpy.ndarray)
 
+  * statesp.default_dt and xferfcn.default_dt (None): set the default value of dt when 
+  constructing new LTI systems
+
+  * statesp.remove_useless_states (True): remove states that have no effect on the 
+  input-output dynamics of the system 
+
 Additional parameter variables are documented in individual functions
 
 Functions that can be used to set standard configurations:
@@ -234,3 +242,4 @@ Functions that can be used to set standard configurations:
     use_fbs_defaults
     use_matlab_defaults
     use_numpy_matrix
+    use_legacy_defaults
