python-control
diff --git a/‎doc/freqplot-mimo_bode-default.png‎
-31 Bytes b/‎doc/freqplot-mimo_bode-default.png‎
-31 Bytes
diff --git a/‎doc/freqplot-nyquist-custom.png‎
-90 Bytes b/‎doc/freqplot-nyquist-custom.png‎
-90 Bytes
diff --git a/‎doc/freqplot-nyquist-default.png‎
61 Bytes b/‎doc/freqplot-nyquist-default.png‎
61 Bytes
diff --git a/‎doc/freqplot-siso_bode-default.png‎
-91 Bytes b/‎doc/freqplot-siso_bode-default.png‎
-91 Bytes
diff --git a/‎doc/freqplot-siso_bode-omega.png‎
-61 Bytes b/‎doc/freqplot-siso_bode-omega.png‎
-61 Bytes
diff --git a/‎doc/phaseplot-dampedosc-default.png‎
-149 Bytes b/‎doc/phaseplot-dampedosc-default.png‎
-149 Bytes
diff --git a/‎doc/phaseplot-invpend-meshgrid.png‎
27.9 KB b/‎doc/phaseplot-invpend-meshgrid.png‎
27.9 KB
diff --git a/‎doc/phaseplot-oscillator-helpers.png‎
-820 Bytes b/‎doc/phaseplot-oscillator-helpers.png‎
-820 Bytes
diff --git a/‎doc/plotting.rst‎
Lines changed: 111 additions & 3 deletions b/‎doc/plotting.rst‎
Lines changed: 111 additions & 3 deletions
diff --git a/‎doc/pzmap-siso_ctime-default.png‎
0 Bytes b/‎doc/pzmap-siso_ctime-default.png‎
0 Bytes
@@ -423,6 +423,114 @@ Instead, the plot is generated directly be a call to the
 :mod:`~control.phaseplot` helper functions.
 
 
+Customizing control plots
+=========================
+
+A set of common options are available to customize control plots in
+various ways.  The following general rules apply:
+
+* If a plotting function is called multiple times with data that generate
+  control plots with the same shape for the array of subplots, the new data
+  will be overlayed with the old data, with a change in color(s) for the
+  new data (chosen from the standard matplotlib color cycle).  If not
+  overridden, the plot title and legends will be updated to reflect all
+  data shown on the plot.
+
+* If a plotting function is called and the shape for the array of subplots
+  does not match the currently displayed plot, a new figure is created.
+  Note that only the shape is checked, so if two different types of
+  plotting commands that generate the same shape of suplots are called
+  sequentially, the :func:`matplotlib.pyplot.figure` command should be used
+  to explicitly create a new figure.
+
+* The ``ax`` keyword argument can be used to direct the plotting function
+  to use a specific axes or array of axes.  The value of the ``ax`` keyword
+  must have the proper number of axes for the plot (so a plot generating a
+  2x2 array of subplots should be given a 2x2 array of axes for the ``ax``
+  keyword).
+
+* The ``label`` keyword argument can be used to override the line labels
+  that are used in generating the title and legend.  If more than one line
+  is being plotted in a given call to a plot command, the ``label``
+  argument value should be a list of labels, one for each line, in the
+  order they will appear in the legend.
+
+  For input/output plots (frequency and time responses), the labels that
+  appear in the legend are of the form "<output name>, <input name>, <trace
+  name>, <system name>".  The trace name is used only for multi-trace time
+  plots (for example, step responses for MIMO systems).  Common information
+  present in all traces is removed, so that the labels appearing in the
+  legend represent the unique characteristics of each line.
+
+  For non-input/output plots (e.g., Nyquist plots, pole/zero plots, root
+  locus plots), the default labels are the system name.
+
+  If ``label`` is set to ``False``, individual lines are still given
+  labels, but no legend is generated in the plot (this can also be
+  accomplished by setting ``legend_map`` to ``False``.
+
+  Note: the ``label`` keyword argument is not implemented for describing
+  function plots or phase plane plots, since these plots are primarily
+  intended to be for a single system.  Standard ``matplotlib`` commands can
+  be used to customize these plots for displaying information for multiple
+  systems.
+
+* The ``legend_loc``, ``legend_map`` and ``show_legend`` keyword arguments
+  can be used to customize the locations for legends.  By default, a
+  minimal number of legends are used such that lines can be uniquely
+  identified and no legend is generated if there is only one line in the
+  plot.  Setting ``show_legend`` to ``False`` will suppress the legend and
+  setting it to ``True`` will force the legend to be displayed even if
+  there is only a single line in each axes.  In addition, if the value of
+  the ``legend_loc`` keyword argument is set to a string or integer, it
+  will set the position of the legend as described in the
+  :func:`matplotlib.legend`` documentation.  Finally, ``legend_map`` can be
+  set to an` array that matches the shape of the suplots, with each item
+  being a string indicating the location of the legend for that axes (or
+  ``None`` for no legend).
+
+* The ``rcParams`` keyword argument can be used to override the default
+  matplotlib style parameters used when creating a plot.  The default
+  parameters for all control plots are given by the ``ct.rcParams``
+  dictionary and have the following values:
+
+  .. list-table::
+     :widths: 50 50
+     :header-rows: 1
+
+     * - Key
+       - Value
+     * - 'axes.labelsize'
+       - 'small'
+     * - 'axes.titlesize'
+       - 'small'
+     * - 'figure.titlesize'
+       - 'medium'
+     * - 'legend.fontsize'
+       - 'x-small'
+     * - 'xtick.labelsize'
+       - 'small'
+     * - 'ytick.labelsize'
+       - 'small'
+
+  Only those values that should be changed from the default need to be
+  specified in the ``rcParams`` keyword argument.  To override the defaults
+  for all control plots, update the ``ct.rcParams`` dictionary entries.
+
+  The default values for style parameters for control plots can be restored
+  using :func:`~control.reset_rcParams`.
+
+* The ``title`` keyword can be used to override the automatic creation of
+  the plot title.  The default title is a string of the form "<Type> plot
+  for <syslist>" where <syslist> is a list of the sys names contained in
+  the plot (which can be updated if the plotting is called multiple times).
+  Use ``title=False`` to suppress the title completely.  The title can also
+  be updated using the :func:`~control.ControlPlot.set_plot_title` method
+  for the returned control plot object.
+
+  The plot title is only generated if ``ax`` is ``None``.
+
+
 Response and plotting functions
 ===============================
 
@@ -432,7 +540,7 @@ Response functions
 Response functions take a system or list of systems and return a response
 object that can be used to retrieve information about the system (e.g., the
 number of encirclements for a Nyquist plot) as well as plotting (via the
-`plot` method).
+``plot`` method).
 
 .. autosummary::
    :toctree: generated/
@@ -481,8 +589,8 @@ returned values from plotting routines.
    :toctree: generated/
 
    ~control.combine_time_responses
-   ~control.get_plot_axes
-   ~control.suptitle
+   ~control.reset_rcParams
+   control.ControlPlot.set_plot_title
 
 
 Response and plotting classes