Merge pull request #921 from KybernetikJo/improve-docstring-pep257

murrayrm · web-flow · commit ad1af2f237c5 · 2023-07-06T21:00:16.000-07:00
Add final point to docstrings, PEP257
diff --git a/control/canonical.py b/control/canonical.py
@@ -19,7 +19,7 @@
 
 
 def canonical_form(xsys, form='reachable'):
-    """Convert a system into canonical form
+    """Convert a system into canonical form.
 
     Parameters
     ----------
@@ -71,7 +71,7 @@ def canonical_form(xsys, form='reachable'):
 
 # Reachable canonical form
 def reachable_form(xsys):
-    """Convert a system into reachable canonical form
+    """Convert a system into reachable canonical form.
 
     Parameters
     ----------
@@ -134,7 +134,7 @@ def reachable_form(xsys):
 
 
 def observable_form(xsys):
-    """Convert a system into observable canonical form
+    """Convert a system into observable canonical form.
 
     Parameters
     ----------
@@ -255,7 +255,7 @@ def rsolve(M, y):
 
 
 def _bdschur_defective(blksizes, eigvals):
-    """Check  for defective modal decomposition
+    """Check  for defective modal decomposition.
 
     Parameters
     ----------
@@ -290,7 +290,7 @@ def _bdschur_defective(blksizes, eigvals):
 
 
 def _bdschur_condmax_search(aschur, tschur, condmax):
-    """Block-diagonal Schur decomposition search up to condmax
+    """Block-diagonal Schur decomposition search up to condmax.
 
     Iterates mb03rd with different pmax values until:
       - result is non-defective;
@@ -393,7 +393,7 @@ def _bdschur_condmax_search(aschur, tschur, condmax):
 
 
 def bdschur(a, condmax=None, sort=None):
-    """Block-diagonal Schur decomposition
+    """Block-diagonal Schur decomposition.
 
     Parameters
     ----------
@@ -482,7 +482,7 @@ def bdschur(a, condmax=None, sort=None):
 
 
 def modal_form(xsys, condmax=None, sort=False):
-    """Convert a system into modal canonical form
+    """Convert a system into modal canonical form.
 
     Parameters
     ----------
diff --git a/control/ctrlutil.py b/control/ctrlutil.py
@@ -50,7 +50,7 @@
 
 # Utility function to unwrap an angle measurement
 def unwrap(angle, period=2*math.pi):
-    """Unwrap a phase angle to give a continuous curve
+    """Unwrap a phase angle to give a continuous curve.
 
     Parameters
     ----------
@@ -87,7 +87,7 @@ def unwrap(angle, period=2*math.pi):
 
 def issys(obj):
     """Return True if an object is a Linear Time Invariant (LTI) system,
-    otherwise False
+    otherwise False.
 
     Examples
     --------
@@ -105,7 +105,7 @@ def issys(obj):
     return isinstance(obj, lti.LTI)
 
 def db2mag(db):
-    """Convert a gain in decibels (dB) to a magnitude
+    """Convert a gain in decibels (dB) to a magnitude.
 
     If A is magnitude,
 
@@ -133,7 +133,7 @@ def db2mag(db):
     return 10. ** (db / 20.)
 
 def mag2db(mag):
-    """Convert a magnitude to decibels (dB)
+    """Convert a magnitude to decibels (dB).
 
     If A is magnitude,
 
diff --git a/control/descfcn.py b/control/descfcn.py
@@ -74,7 +74,7 @@ def _f(self, x):
 
 def describing_function(
         F, A, num_points=100, zero_check=True, try_method=True):
-    """Numerically compute the describing function of a nonlinear function
+    """Numerically compute the describing function of a nonlinear function.
 
     The describing function of a nonlinearity is given by magnitude and phase
     of the first harmonic of the function when evaluated along a sinusoidal
diff --git a/control/dtime.py b/control/dtime.py
@@ -56,7 +56,7 @@
 def sample_system(sysc, Ts, method='zoh', alpha=None, prewarp_frequency=None,
         name=None, copy_names=True, **kwargs):
     """
-    Convert a continuous time system to discrete time by sampling
+    Convert a continuous time system to discrete time by sampling.
 
     Parameters
     ----------
diff --git a/control/frdata.py b/control/frdata.py
@@ -729,7 +729,7 @@ def _convert_to_FRD(sys, omega, inputs=1, outputs=1):
 def frd(*args):
     """frd(d, w)
 
-    Construct a frequency response data model
+    Construct a frequency response data model.
 
     frd models store the (measured) frequency response of a system.
 
diff --git a/control/freqplot.py b/control/freqplot.py
@@ -94,7 +94,7 @@
 def bode_plot(syslist, omega=None,
               plot=True, omega_limits=None, omega_num=None,
               margins=None, method='best', *args, **kwargs):
-    """Bode plot for a system
+    """Bode plot for a system.
 
     Plots a Bode plot for the system over a (optional) frequency range.
 
@@ -542,7 +542,7 @@ def nyquist_plot(
         syslist, omega=None, plot=True, omega_limits=None, omega_num=None,
         label_freq=0, color=None, return_contour=False,
         warn_encirclements=True, warn_nyquist=True, **kwargs):
-    """Nyquist plot for a system
+    """Nyquist plot for a system.
 
     Plots a Nyquist plot for the system over a (optional) frequency range.
     The curve is computed by evaluating the Nyqist segment along the positive
@@ -1251,7 +1251,7 @@ def _compute_curve_offset(resp, mask, max_offset):
 #
 # TODO: think about how (and whether) to handle lists of systems
 def gangof4_plot(P, C, omega=None, **kwargs):
-    """Plot the "Gang of 4" transfer functions for a system
+    """Plot the "Gang of 4" transfer functions for a system.
 
     Generates a 2x2 plot showing the "Gang of 4" sensitivity functions
     [T, PS; CS, S]
diff --git a/control/iosys.py b/control/iosys.py
@@ -363,7 +363,7 @@ def find_states(self, name_list):
 
     def isctime(self, strict=False):
         """
-        Check to see if a system is a continuous-time system
+        Check to see if a system is a continuous-time system.
 
         Parameters
         ----------
@@ -397,7 +397,7 @@ def isdtime(self, strict=False):
         return self.dt > 0
 
     def issiso(self):
-        """Check to see if a system is single input, single output"""
+        """Check to see if a system is single input, single output."""
         return self.ninputs == 1 and self.noutputs == 1
 
     def _isstatic(self):
@@ -408,7 +408,7 @@ def _isstatic(self):
 # Test to see if a system is SISO
 def issiso(sys, strict=False):
     """
-    Check to see if a system is single input, single output
+    Check to see if a system is single input, single output.
 
     Parameters
     ----------
@@ -427,7 +427,7 @@ def issiso(sys, strict=False):
 
 # Return the timebase (with conversion if unspecified)
 def timebase(sys, strict=True):
-    """Return the timebase for a system
+    """Return the timebase for a system.
 
     dt = timebase(sys)
 
@@ -500,7 +500,7 @@ def common_timebase(dt1, dt2):
 # Check to see if a system is a discrete time system
 def isdtime(sys, strict=False):
     """
-    Check to see if a system is a discrete time system
+    Check to see if a system is a discrete time system.
 
     Parameters
     ----------
@@ -521,7 +521,7 @@ def isdtime(sys, strict=False):
 # Check to see if a system is a continuous time system
 def isctime(sys, strict=False):
     """
-    Check to see if a system is a continuous-time system
+    Check to see if a system is a continuous-time system.
 
     Parameters
     ----------
diff --git a/control/lti.py b/control/lti.py
@@ -252,7 +252,7 @@ def zeros(sys):
 
 def damp(sys, doprint=True):
     """
-    Compute natural frequencies, damping ratios, and poles of a system
+    Compute natural frequencies, damping ratios, and poles of a system.
 
     Parameters
     ----------
@@ -446,7 +446,7 @@ def frequency_response(sys, omega, squeeze=None):
 
 
 def dcgain(sys):
-    """Return the zero-frequency (or DC) gain of the given system
+    """Return the zero-frequency (or DC) gain of the given system.
 
     Returns
     -------
diff --git a/control/margins.py b/control/margins.py
@@ -505,7 +505,7 @@ def phase_crossover_frequencies(sys):
 def margin(*args):
     """margin(sysdata)
 
-    Calculate gain and phase margins and associated crossover frequencies
+    Calculate gain and phase margins and associated crossover frequencies.
 
     Parameters
     ----------
diff --git a/control/mateqn.py b/control/mateqn.py
@@ -88,7 +88,7 @@ def sb03md(n, C, A, U, dico, job='X', fact='N', trana='N', ldwork=None):
 
 
 def lyap(A, Q, C=None, E=None, method=None):
-    """Solves the continuous-time Lyapunov equation
+    """Solves the continuous-time Lyapunov equation.
 
     X = lyap(A, Q) solves
 
@@ -214,7 +214,7 @@ def lyap(A, Q, C=None, E=None, method=None):
 
 
 def dlyap(A, Q, C=None, E=None, method=None):
-    """Solves the discrete-time Lyapunov equation
+    """Solves the discrete-time Lyapunov equation.
 
     X = dlyap(A, Q) solves
 
@@ -342,7 +342,7 @@ def dlyap(A, Q, C=None, E=None, method=None):
 
 def care(A, B, Q, R=None, S=None, E=None, stabilizing=True, method=None,
          A_s="A", B_s="B", Q_s="Q", R_s="R", S_s="S", E_s="E"):
-    """Solves the continuous-time algebraic Riccati equation
+    """Solves the continuous-time algebraic Riccati equation.
 
     X, L, G = care(A, B, Q, R=None) solves
 
@@ -496,7 +496,7 @@ def care(A, B, Q, R=None, S=None, E=None, stabilizing=True, method=None,
 def dare(A, B, Q, R, S=None, E=None, stabilizing=True, method=None,
          A_s="A", B_s="B", Q_s="Q", R_s="R", S_s="S", E_s="E"):
     """Solves the discrete-time algebraic Riccati
-    equation
+    equation.
 
     X, L, G = dare(A, B, Q, R) solves
 
diff --git a/control/matlab/timeresp.py b/control/matlab/timeresp.py
@@ -7,7 +7,7 @@
 __all__ = ['step', 'stepinfo', 'impulse', 'initial', 'lsim']
 
 def step(sys, T=None, input=0, output=None, return_x=False):
-    '''Step response of a linear system
+    '''Step response of a linear system.
 
     If the system has multiple inputs or outputs (MIMO), one input has
     to be selected for the simulation.  Optionally, one output may be
@@ -132,7 +132,7 @@ def stepinfo(sysdata, T=None, yfinal=None, SettlingTimeThreshold=0.02,
     return S
 
 def impulse(sys, T=None, input=0, output=None, return_x=False):
-    '''Impulse response of a linear system
+    '''Impulse response of a linear system.
 
     If the system has multiple inputs or outputs (MIMO), one input has
     to be selected for the simulation.  Optionally, one output may be
@@ -181,7 +181,7 @@ def impulse(sys, T=None, input=0, output=None, return_x=False):
     return (out[1], out[0], out[2]) if return_x else (out[1], out[0])
 
 def initial(sys, T=None, X0=0., input=None, output=None, return_x=False):
-    '''Initial condition response of a linear system
+    '''Initial condition response of a linear system.
 
     If the system has multiple outputs (?IMO), optionally, one output
     may be selected. If no selection is made for the output, all
@@ -232,7 +232,7 @@ def initial(sys, T=None, X0=0., input=None, output=None, return_x=False):
 
 
 def lsim(sys, U=0., T=None, X0=0.):
-    '''Simulate the output of a linear system
+    '''Simulate the output of a linear system.
 
     As a convenience for parameters `U`, `X0`:
     Numbers (scalars) are converted to constant arrays with the correct shape.
diff --git a/control/matlab/wrappers.py b/control/matlab/wrappers.py
@@ -17,7 +17,7 @@
 def bode(*args, **kwargs):
     """bode(syslist[, omega, dB, Hz, deg, ...])
 
-    Bode plot of the frequency response
+    Bode plot of the frequency response.
 
     Plots a bode gain and phase diagram
 
@@ -79,7 +79,7 @@ def bode(*args, **kwargs):
 def nyquist(*args, **kwargs):
     """nyquist(syslist[, omega])
 
-    Nyquist plot of the frequency response
+    Nyquist plot of the frequency response.
 
     Plots a Nyquist plot for the system over a (optional) frequency range.
 
@@ -184,7 +184,7 @@ def ngrid():
 
 
 def dcgain(*args):
-    '''Compute the gain of the system in steady state
+    '''Compute the gain of the system in steady state.
 
     The function takes either 1, 2, 3, or 4 parameters:
 
diff --git a/control/nichols.py b/control/nichols.py
@@ -66,7 +66,7 @@
 
 
 def nichols_plot(sys_list, omega=None, grid=None):
-    """Nichols plot for a system
+    """Nichols plot for a system.
 
     Plots a Nichols plot for the system over a (optional) frequency range.
 
@@ -133,7 +133,7 @@ def _inner_extents(ax):
 
 def nichols_grid(cl_mags=None, cl_phases=None, line_style='dotted', ax=None,
                  label_cl_phases=True):
-    """Nichols chart grid
+    """Nichols chart grid.
 
     Plots a Nichols chart grid on the current axis, or creates a new chart
     if no plot already exists.
diff --git a/control/phaseplot.py b/control/phaseplot.py
@@ -53,7 +53,7 @@ def _find(condition):
 def phase_plot(odefun, X=None, Y=None, scale=1, X0=None, T=None,
               lingrid=None, lintime=None, logtime=None, timepts=None,
               parms=(), verbose=True):
-    """Phase plot for 2D dynamical systems
+    """Phase plot for 2D dynamical systems.
 
     Produces a vector field or stream line plot for a planar system.
 
diff --git a/control/rlocus.py b/control/rlocus.py
@@ -79,7 +79,7 @@ def root_locus(sys, kvect=None, xlim=None, ylim=None,
                plotstr=None, plot=True, print_gain=None, grid=None, ax=None,
                initial_gain=None, **kwargs):
 
-    """Root locus plot
+    """Root locus plot.
 
     Calculate the root locus by finding the roots of 1+k*TF(s)
     where TF is self.num(s)/self.den(s) and each k is an element
diff --git a/control/sisotool.py b/control/sisotool.py
@@ -205,7 +205,7 @@ def rootlocus_pid_designer(plant, gain='P', sign=+1, input_signal='r',
                            Kp0=0, Ki0=0, Kd0=0, deltaK=0.001, tau=0.01,
                            C_ff=0, derivative_in_feedback_path=False,
                            plot=True):
-    """Manual PID controller design based on root locus using Sisotool
+    """Manual PID controller design based on root locus using Sisotool.
 
     Uses `sisotool` to investigate the effect of adding or subtracting an
     amount `deltaK` to the proportional, integral, or derivative (PID) gains of
diff --git a/control/statefbk.py b/control/statefbk.py
diff --git a/control/statesp.py b/control/statesp.py
diff --git a/control/stochsys.py b/control/stochsys.py
diff --git a/control/xferfcn.py b/control/xferfcn.py
