Restructure config.rst to document all defaults + update docstrings, code

murrayrm · murrayrm · commit b750119bed7a · 2025-02-02T20:39:22.000-08:00
diff --git a/control/frdata.py b/control/frdata.py
@@ -1014,8 +1014,13 @@ def frd(*args, **kwargs):
     input_prefix, output_prefix : string, optional
         Set the prefix for input and output signals.  Defaults = 'u', 'y'.
     name : string, optional
-        System name. If unspecified, a generic name <sys[id]> is generated
-        with a unique integer id.
+        Set the name of the system. If unspecified and the system is
+        sampled from an existing system, the new system name is determined
+        by adding the prefix and suffix strings in
+        config.defaults['iosys.sampled_system_name_prefix'] and
+        config.defaults['iosys.sampled_system_name_suffix'], with the
+        default being to add the suffix '$ampled'.  Otherwise, a generic
+        name <sys[id]> is generated with a unique integer id
 
     See Also
     --------
diff --git a/control/freqplot.py b/control/freqplot.py
@@ -213,7 +213,8 @@ def bode_plot(
         Set the frame of reference used to center the plot title. If set to
         'axes' (default), the horizontal position of the title will be
         centered relative to the axes.  If set to 'figure', it will be
-        centered with respect to the figure (faster execution).
+        centered with respect to the figure (faster execution).  The
+        default value can be set using config.defaults['freqplot.title_frame'].
     wrap_phase : bool or float
         If wrap_phase is `False` (default), then the phase will be unwrapped
         so that it is continuously increasing or decreasing.  If wrap_phase is
@@ -1200,14 +1201,17 @@ def nyquist_response(
         be set using config.defaults['nyquist.encirclement_threshold'].
     indent_direction : str, optional
         For poles on the imaginary axis, set the direction of indentation to
-        be 'right' (default), 'left', or 'none'.
+        be 'right' (default), 'left', or 'none'.  The default value can
+        be set using config.defaults['nyquist.indent_direction'].
     indent_points : int, optional
         Number of points to insert in the Nyquist contour around poles that
         are at or near the imaginary axis.
     indent_radius : float, optional
         Amount to indent the Nyquist contour around poles on or near the
-        imaginary axis. Portions of the Nyquist plot corresponding to indented
-        portions of the contour are plotted using a different line style.
+        imaginary axis. Portions of the Nyquist plot corresponding to
+        indented portions of the contour are plotted using a different line
+        style. The default value can be set using
+        config.defaults['nyquist.indent_radius'].
     omega_limits : array_like of two values
         Set limits for plotted frequency range. If Hz=True the limits are
         in Hz otherwise in rad/s.  Specifying ``omega`` as a list of two
@@ -1539,7 +1543,9 @@ def nyquist_plot(
         ``omega`` as a list of two elements is equivalent to providing
         ``omega_limits``.
     unit_circle : bool, optional
-        If ``True``, display the unit circle, to read gain crossover frequency.
+        If ``True``, display the unit circle, to read gain crossover
+        frequency.  The circle style is determined by
+        config.defaults['nyquist.circle_style'].
     mt_circles : array_like, optional
         Draw circles corresponding to the given magnitudes of sensitivity.
     ms_circles : array_like, optional
@@ -1577,12 +1583,13 @@ def nyquist_plot(
     arrows : int or 1D/2D array of floats, optional
         Specify the number of arrows to plot on the Nyquist curve.  If an
         integer is passed. that number of equally spaced arrows will be
-        plotted on each of the primary segment and the mirror image.  If a 1D
-        array is passed, it should consist of a sorted list of floats between
-        0 and 1, indicating the location along the curve to plot an arrow.  If
-        a 2D array is passed, the first row will be used to specify arrow
-        locations for the primary curve and the second row will be used for
-        the mirror image.
+        plotted on each of the primary segment and the mirror image.  If a
+        1D array is passed, it should consist of a sorted list of floats
+        between 0 and 1, indicating the location along the curve to plot an
+        arrow.  If a 2D array is passed, the first row will be used to
+        specify arrow locations for the primary curve and the second row
+        will be used for the mirror image.  Default value is 2 and can be
+        set using config.defaults['nyquist.arrows'].
     arrow_size : float, optional
         Arrowhead width and length (in display coordinates).  Default value is
         8 and can be set using config.defaults['nyquist.arrow_size'].
@@ -1619,11 +1626,14 @@ def nyquist_plot(
     max_curve_magnitude : float, optional
         Restrict the maximum magnitude of the Nyquist plot to this value.
         Portions of the Nyquist plot whose magnitude is restricted are
-        plotted using a different line style.
+        plotted using a different line style.  The default value is 20 and
+        can be set using config.defaults['nyquist.max_curve_magnitude'].
     max_curve_offset : float, optional
         When plotting scaled portion of the Nyquist plot, increase/decrease
         the magnitude by this fraction of the max_curve_magnitude to allow
         any overlaps between the primary and mirror curves to be avoided.
+        The default value is 0.02 and can be set using
+        config.defaults['nyquist.max_curve_magnitude'].
     mirror_style : [str, str] or False
         Linestyles for mirror image of the Nyquist curve.  The first element
         is used for unscaled portions of the Nyquist curve, the second element
diff --git a/control/nichols.py b/control/nichols.py
@@ -51,7 +51,8 @@ def nichols_plot(
         Passed to `matplotlib` as the format string for all lines in the plot.
         The `omega` parameter must be present (use omega=None if needed).
     grid : boolean, optional
-        True if the plot should include a Nichols-chart grid. Default is True.
+        True if the plot should include a Nichols-chart grid. Default is
+        True and can be set using config.defaults['nichols.grid'].
     **kwargs : :func:`matplotlib.pyplot.plot` keyword properties, optional
         Additional keywords passed to `matplotlib` to specify line properties.
 
diff --git a/control/nlsys.py b/control/nlsys.py
@@ -2320,9 +2320,10 @@ def interconnect(
 
     states : int, list of str, or None, optional
         Description of the system states.  Same format as `inputs`. The
-        default is `None`, in which case the states will be given names of the
-        form '<subsys_name>.<state_name>', for each subsys in syslist and each
-        state_name of each subsys.
+        default is `None`, in which case the states will be given names of
+        the form '<subsys_name><delim><state_name>', for each subsys in
+        syslist and each state_name of each subsys, where <delim> is the
+        value of config.defaults['iosys.state_name_delim'].
 
     params : dict, optional
         Parameter values for the systems.  Passed to the evaluation functions
diff --git a/control/phaseplot.py b/control/phaseplot.py
@@ -48,6 +48,7 @@
 _phaseplot_defaults = {
     'phaseplot.arrows': 2,                  # number of arrows around curve
     'phaseplot.arrow_size': 8,              # pixel size for arrows
+    'phaseplot.arrow_style': None,          # set arrow style
     'phaseplot.separatrices_radius': 0.1    # initial radius for separatrices
 }
 
@@ -120,6 +121,15 @@ def phase_plane_plot(
 
     Other Parameters
     ----------------
+    arrows : int
+        Set the number of arrows to plot along the streamlines. The default
+        value can be set in config.defaults['phaseplot.arrows'].
+    arrow_size : float
+        Set the size of arrows to plot along the streamlines.  The default
+        value can be set in config.defaults['phaseplot.arrow_size'].
+    arrow_style : matplotlib patch
+        Set the style of arrows to plot along the streamlines.  The default
+        value can be set in config.defaults['phaseplot.arrow_style'].
     dir : str, optional
         Direction to draw streamlines: 'forward' to flow forward in time
         from the reference points, 'reverse' to flow backward in time, or
@@ -383,6 +393,15 @@ def streamlines(
 
     Other Parameters
     ----------------
+    arrows : int
+        Set the number of arrows to plot along the streamlines. The default
+        value can be set in config.defaults['phaseplot.arrows'].
+    arrow_size : float
+        Set the size of arrows to plot along the streamlines.  The default
+        value can be set in config.defaults['phaseplot.arrow_size'].
+    arrow_style : matplotlib patch
+        Set the style of arrows to plot along the streamlines.  The default
+        value can be set in config.defaults['phaseplot.arrow_style'].
     rcParams : dict
         Override the default parameters used for generating plots.
         Default is set by config.default['ctrlplot.rcParams'].
@@ -593,6 +612,13 @@ def separatrices(
     suppress_warnings : bool, optional
         If set to `True`, suppress warning messages in generating trajectories.
 
+    Notes
+    -----
+    The value of config.defaults['separatrices_radius'] is used to set the
+    offset from the equlibrium point to the starting point of the separatix
+    traces, in the direction of the eigenvectors evaluated at that
+    equilibrium point.
+
     """
     # Process keywords
     rcParams = config._get_param('ctrlplot', 'rcParams', kwargs, pop=True)
diff --git a/control/pzmap.py b/control/pzmap.py
@@ -31,7 +31,7 @@
 
 # Define default parameter values for this module
 _pzmap_defaults = {
-    'pzmap.grid': None,                 # Plot omega-damping grid
+    'pzmap.grid': False,                 # Plot omega-damping grid
     'pzmap.marker_size': 6,             # Size of the markers
     'pzmap.marker_width': 1.5,          # Width of the markers
     'pzmap.expansion_factor': 1.8,      # Amount to scale plots beyond features
@@ -273,16 +273,27 @@ def pole_zero_plot(
 
     Notes
     -----
-    1. By default, the pzmap function calls matplotlib.pyplot.axis('equal'),
-       which means that trying to reset the axis limits may not behave as
-       expected.  To change the axis limits, use the `scaling` keyword of
-       use matplotlib.pyplot.gca().axis('auto') and then set the axis
-       limits to the desired values.
-
-    2. Pole/zero plots that use the continuous time omega-damping grid do
-       not work with the ``ax`` keyword argument, due to the way that axes
-       grids are implemented.  The ``grid`` argument must be set to
-       ``False`` or ``'empty'`` when using the ``ax`` keyword argument.
+    By default, the pzmap function calls matplotlib.pyplot.axis('equal'),
+    which means that trying to reset the axis limits may not behave as
+    expected.  To change the axis limits, use the `scaling` keyword of use
+    matplotlib.pyplot.gca().axis('auto') and then set the axis limits to
+    the desired values.
+
+    Pole/zero plots that use the continuous time omega-damping grid do not
+    work with the ``ax`` keyword argument, due to the way that axes grids
+    are implemented.  The ``grid`` argument must be set to ``False`` or
+    ``'empty'`` when using the ``ax`` keyword argument.
+
+    The limits of the pole/zero plot are set based on the location features
+    in the plot, including the location of poles, zeros, and local maxima
+    of root locus curves.  The locations of local maxima are expanded by a
+    buffer factor set by config.defaults['phaseplot.buffer_factor'] that is
+    applied to the locations of the local maxima.  The final axis limits
+    are set to by the largest features in the plot multiplied by an
+    expansion factor set by config.defaults['phaseplot.expansion_factor'].
+    The default value for the buffer factor is 1.05 (5% buffer around local
+    maxima) and the default value for the expansion factor is 1.8 (80%
+    increase in limits around the most distant features).
 
     """
     # Get parameter values
diff --git a/control/timeplot.py b/control/timeplot.py
@@ -153,7 +153,7 @@ def time_response_plot(
     trace_labels : list of str, optional
         Replace the default trace labels with the given labels.
     trace_props : array of dicts
-        List of line properties to use when plotting combined outputs.  The
+        List of line properties to use when plotting multiple traces.  The
         default values are set by config.defaults['timeplot.trace_props'].
 
     Notes
diff --git a/doc/config.rst b/doc/config.rst
diff --git a/doc/response.rst b/doc/response.rst
diff --git a/doc/test_sphinxdocs.py b/doc/test_sphinxdocs.py
