diff --git a/control/bdalg.py b/control/bdalg.py index 0d1a5e8c4..540796258 100644 --- a/control/bdalg.py +++ b/control/bdalg.py @@ -62,12 +62,12 @@ __all__ = ['series', 'parallel', 'negate', 'feedback', 'append', 'connect'] def series(sys1, *sysn): - """Return the series connection (... * sys3 *) sys2 * sys1 + """Return the series connection (... \* sys3 \*) sys2 \* sys1 Parameters ---------- sys1: scalar, StateSpace, TransferFunction, or FRD - *sysn: other scalars, StateSpaces, TransferFunctions, or FRDs + sysn: other scalars, StateSpaces, TransferFunctions, or FRDs Returns ------- diff --git a/control/freqplot.py b/control/freqplot.py index a71d44cce..33cf0ad61 100644 --- a/control/freqplot.py +++ b/control/freqplot.py @@ -61,7 +61,8 @@ # Bode plot def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None, Plot=True, omega_limits=None, omega_num=None, *args, **kwargs): - """Bode plot for a system + """ + Bode plot for a system Plots a Bode plot for the system over a (optional) frequency range. @@ -84,7 +85,7 @@ def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None, If Hz=True the limits are in Hz otherwise in rad/s. omega_num: int number of samples - *args, **kwargs: + \*args, \**kwargs: Additional options to matplotlib (color, linestyle, etc) Returns @@ -253,7 +254,8 @@ def genZeroCenteredSeries(val_min, val_max, period): # Nyquist plot def nyquist_plot(syslist, omega=None, Plot=True, color='b', labelFreq=0, *args, **kwargs): - """Nyquist plot for a system + """ + Nyquist plot for a system Plots a Nyquist plot for the system over a (optional) frequency range. @@ -267,7 +269,7 @@ def nyquist_plot(syslist, omega=None, Plot=True, color='b', If True, plot magnitude labelFreq : int Label every nth frequency on the plot - *args, **kwargs: + \*args, \**kwargs: Additional options to matplotlib (color, linestyle, etc) Returns @@ -283,6 +285,7 @@ def nyquist_plot(syslist, omega=None, Plot=True, color='b', -------- >>> sys = ss("1. -2; 3. -4", "5.; 7", "6. 8", "9.") >>> real, imag, freq = nyquist_plot(sys) + """ # If argument was a singleton, turn it into a list if (not getattr(syslist, '__iter__', False)): diff --git a/control/lti.py b/control/lti.py index ca4c94f21..0bd05e902 100644 --- a/control/lti.py +++ b/control/lti.py @@ -264,7 +264,7 @@ def zero(sys): return sys.zero() def damp(sys, doprint=True): - ''' + """ Compute natural frequency, damping ratio, and poles of a system The function takes 1 or 2 parameters @@ -285,24 +285,26 @@ def damp(sys, doprint=True): poles: array Pole locations - Algorithm - -------- - If the system is continuous, - wn = abs(poles) - Z = -real(poles)/poles. + --------- + If the system is continuous, + wn = abs(poles) + Z = -real(poles)/poles. + + If the system is discrete, the discrete poles are mapped to their + equivalent location in the s-plane via - If the system is discrete, the discrete poles are mapped to their - equivalent location in the s-plane via - s = log10(poles)/dt - and - wn = abs(s) - Z = -real(s)/wn. + s = log10(poles)/dt + + and + + wn = abs(s) + Z = -real(s)/wn. See Also -------- pole - ''' + """ wn, damping, poles = sys.damp() if doprint: print('_____Eigenvalue______ Damping___ Frequency_') diff --git a/control/margins.py b/control/margins.py index a98ff3936..aa7b8e3fd 100644 --- a/control/margins.py +++ b/control/margins.py @@ -129,7 +129,7 @@ def stability_margins(sysdata, returnall=False, epsw=0.0): wg: float or array_like Frequency for gain margin (at phase crossover, phase = -180 degrees) wp: float or array_like - Frequency for phase margin (at gain crossover, gain = 0 dB) + Frequency for phase margin (at gain crossover, gain = 1) ws: float or array_like Frequency for stability margin (complex gain closest to -1) """ @@ -343,12 +343,12 @@ def margin(*args): wg: float Frequency for gain margin (at phase crossover, phase = -180 degrees) wp: float - Frequency for phase margin (at gain crossover, gain = 0 dB) + Frequency for phase margin (at gain crossover, gain = 1) Margins are calculated for a SISO open-loop system. If there is more than one gain crossover, the one at the smallest - margin (deviation from gain=0dB), in absolute sense, is + margin (deviation from gain = 1), in absolute sense, is returned. Likewise the smallest phase margin (in absolute sense) is returned. diff --git a/control/modelsimp.py b/control/modelsimp.py index 92a7acaa1..46f468685 100644 --- a/control/modelsimp.py +++ b/control/modelsimp.py @@ -125,8 +125,8 @@ def modred(sys, ELIM, method='matchdc'): Raises ------ ValueError - * if `method` is not either ``'matchdc'`` or ``'truncate'`` - * if eigenvalues of `sys.A` are not all in left half plane + - if `method` is not either ``'matchdc'`` or ``'truncate'`` + - if eigenvalues of `sys.A` are not all in left half plane (`sys` must be stable) Examples diff --git a/control/robust.py b/control/robust.py index 2cc1f9d3d..54e970a5d 100644 --- a/control/robust.py +++ b/control/robust.py @@ -336,14 +336,16 @@ def mixsyn(g,w1=None,w2=None,w3=None): Returns ------- k: synthesized controller; StateSpace object - cl: closed system mapping evaluation inputs to evaluation outputs; if p is the augmented plant, with - [z] = [p11 p12] [w], then cl is the system from w->z with u=-k*y. StateSpace object. + cl: closed system mapping evaluation inputs to evaluation outputs; if + p is the augmented plant, with + [z] = [p11 p12] [w], [y] [p21 g] [u] + then cl is the system from w->z with u=-k*y. StateSpace object. info: tuple with entries, in order, - gamma: scalar; H-infinity norm of cl - rcond: array; estimates of reciprocal condition numbers - computed during synthesis. See hinfsyn for details + - gamma: scalar; H-infinity norm of cl + - rcond: array; estimates of reciprocal condition numbers + computed during synthesis. See hinfsyn for details If a weighting w is scalar, it will be replaced by I*w, where I is ny-by-ny for w1 and w3, and nu-by-nu for w2. diff --git a/control/statefbk.py b/control/statefbk.py index e2f02c1a4..a2d75c30d 100644 --- a/control/statefbk.py +++ b/control/statefbk.py @@ -52,6 +52,7 @@ def place(A, B, p): """Place closed loop eigenvalues K = place(A, B, p) + Parameters ---------- A : 2-d array diff --git a/control/statesp.py b/control/statesp.py index 846721ba2..adb86adbc 100644 --- a/control/statesp.py +++ b/control/statesp.py @@ -414,7 +414,8 @@ def horner(self, s): # Method for generating the frequency response of the system def freqresp(self, omega): - """Evaluate the system's transfer func. at a list of freqs, omega. + """ + Evaluate the system's transfer func. at a list of freqs, omega. mag, phase, omega = self.freqresp(omega) @@ -427,22 +428,22 @@ def freqresp(self, omega): G(exp(j*omega*dt)) = mag*exp(j*phase). - Inputs: + Inputs ------ - omega: A list of frequencies in radians/sec at which the system - should be evaluated. The list can be either a python list - or a numpy array and will be sorted before evaluation. + omega: A list of frequencies in radians/sec at which the system + should be evaluated. The list can be either a python list + or a numpy array and will be sorted before evaluation. - Returns: + Returns ------- - mag: The magnitude (absolute value, not dB or log10) of the system - frequency response. + mag: The magnitude (absolute value, not dB or log10) of the system + frequency response. - phase: The wrapped phase in radians of the system frequency - response. + phase: The wrapped phase in radians of the system frequency + response. - omega: The list of sorted frequencies at which the response - was evaluated. + omega: The list of sorted frequencies at which the response + was evaluated. """ diff --git a/doc-requirements.txt b/doc-requirements.txt index 4df371870..b6ac1e58c 100644 --- a/doc-requirements.txt +++ b/doc-requirements.txt @@ -1,6 +1,4 @@ -numpydoc==0.4 -mock==1.0.1 -# install sphinx from git to get patched version -# (fixes bug in autosummary where tables do not display) --e git://github.com/sphinx-doc/sphinx.git@stable#egg=Sphinx-origin_stable - +numpy +scipy +matplotlib +numpydoc diff --git a/doc/Makefile b/doc/Makefile index ec3192d7b..b72312be4 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,130 +1,20 @@ -# Makefile for Sphinx documentation +# Minimal makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build -PAPER = +SPHINXPROJ = PythonControlLibrary +SOURCEDIR = . BUILDDIR = _build -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest - +# Put it first so that "make" without argument is like "make help". help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* generated/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PythonControl.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PythonControl.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/PythonControl" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PythonControl" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." +.PHONY: help Makefile -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/doc/classes.rst b/doc/classes.rst index 6f057eb83..9f63a77a7 100644 --- a/doc/classes.rst +++ b/doc/classes.rst @@ -1,8 +1,10 @@ -LTI system classes -================== - +.. _class-ref: .. currentmodule:: control +****************** +LTI system classes +****************** + The classes listed below are used to represent models of linear time-invariant (LTI) systems. They are usually created from factory functions such as :func:`tf` and :func:`ss`, so the user should normally not need to instantiate @@ -14,3 +16,4 @@ these directly. TransferFunction StateSpace FRD + diff --git a/doc/conf.py b/doc/conf.py index 42e190d51..fa8be8455 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,22 +1,22 @@ # -*- coding: utf-8 -*- # -# Python Control documentation build configuration file, created by -# sphinx-quickstart on Tue Jan 11 16:11:31 2011. +# Configuration file for the Sphinx documentation builder. # -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config -import sys +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# import os -import re +import sys +sys.path.insert(0, os.path.abspath('../')) # Use the readthedocs.org theme if installed -import os on_rtd = os.environ.get('READTHEDOCS', None) == 'True' if not on_rtd: # only import and set the theme if we're building docs locally @@ -27,263 +27,172 @@ except ImportError: html_theme = 'default' -# from unittest.mock import MagicMock # python3 -from mock import Mock as MagicMock # python2 - -class Mock(MagicMock): - @classmethod - def __getattr__(cls, name): - return Mock() - -MOCK_MODULES = [ - 'matplotlib', - 'matplotlib.mlab', - 'matplotlib.pyplot', - 'numpy', - 'numpy.linalg', - 'numpy.linalg.linalg', - 'numpy.random', - 'numpy.testing', - 'pylab', - 'scipy', - 'scipy.integrate', - 'scipy.interpolate', - 'scipy.linalg', - 'scipy.signal', - 'scipy.signal.ltisys', -] -# sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES) -for mod_name in MOCK_MODULES: - sys.modules[mod_name] = Mock() - if mod_name == 'numpy': - sys.modules['numpy'].pi = 3.14 +# -- Project information ----------------------------------------------------- -# disable autosummary code from numpy -# (otherwise, will generate many errors, because autosummary runs twice) -numpydoc_show_class_members = False +project = u'Python Control Systems Library' +copyright = u'2018, python-control.org' +author = u'Python Control Developers' -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('..')) +# Version information - read from the source code +import re +import control -# -- General configuration ----------------------------------------------------- +# The short X.Y version +version = re.sub(r'(\d+\.\d+)\.(.*)', r'\1', control.__version__) + +# The full version, including alpha/beta/rc tags +release = control.__version__ +print("version %s, release %s" % (version, release)) + +# -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -# Additional interesting extensions: -# ``sphinx.ext.autosummary`` : Generate function/method/attribute summary -# lists -# ``sphinx.ext.extlinks`` : Shorten external links -# ``sphinx.ext.viewcode`` : Include highlighted source code in the -# documentation -extensions = ['sphinx.ext.autodoc', 'numpydoc', 'sphinx.ext.pngmath', - 'sphinx.ext.intersphinx', 'sphinx.ext.todo', - 'sphinx.ext.autosummary'] +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.napoleon', + 'sphinx.ext.intersphinx', 'sphinx.ext.imgmath', + 'sphinx.ext.autosummary', +] +# scan documents for autosummary directives and generate stub pages for each. autosummary_generate = True +# list of autodoc directive flags that should be automatically applied +# to all autodoc directives. autodoc_default_flags = ['members', 'inherited-members'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -# The suffix of source filenames. +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] source_suffix = '.rst' -# The encoding of source files. -#source_encoding = 'utf-8-sig' - # The master toctree document. master_doc = 'index' -# General information about the project. -project = u'Python Control Systems Library' -copyright = u'2011, Richard M. Murray et al.' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -import control -# The short X.Y version. -version = re.sub(r'(\d+\.\d+)\.(.*)', r'\1', control.__version__) -# The full version, including alpha/beta/rc tags. -release = control.__version__ -print("version %s, release %s" % (version, release)) - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - #This config value contains the locations and names of other projects that #should be linked to in this documentation. intersphinx_mapping = \ - {'scipy':('http://docs.scipy.org/doc/scipy/reference/', None), - 'numpy':('http://docs.scipy.org/doc/numpy', None)} + {'scipy':('https://docs.scipy.org/doc/scipy/reference/', None), + 'numpy':('https://docs.scipy.org/doc/numpy', None)} #If this is True, todo and todolist produce output, else they produce nothing. #The default is False. todo_include_todos = True -# -- Options for HTML output --------------------------------------------------- +# -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -#html_theme = 'default' +# +# html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None +# +# html_theme_options = {} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +# -- Options for HTMLHelp output --------------------------------------------- -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' +# Output file base name for HTML help builder. +htmlhelp_basename = 'PythonControlLibrarydoc' -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None -# Output file base name for HTML help builder. -htmlhelp_basename = 'PythonControldoc' +# -- Options for LaTeX output ------------------------------------------------ +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', -# -- Options for LaTeX output -------------------------------------------------- + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). latex_documents = [ - ('index', 'PythonControl.tex', u'Python Control Documentation', - u'Python Control Developers', 'manual'), + (master_doc, 'PythonControlLibrary.tex', u'Python Control Library Documentation', + u'RMM', 'manual'), ] -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False +# -- Options for manual page output ------------------------------------------ -# If true, show page references after internal links. -#latex_show_pagerefs = False +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'pythoncontrollibrary', u'Python Control Library Documentation', + [author], 1) +] -# If true, show URL addresses after external links. -#latex_show_urls = False -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' +# -- Options for Texinfo output ---------------------------------------------- -# Documents to append as an appendix to all manuals. -#latex_appendices = [] +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'PythonControlLibrary', u'Python Control Library Documentation', + author, 'PythonControlLibrary', 'One line description of project.', + 'Miscellaneous'), +] -# If false, no module index is generated. -#latex_domain_indices = True +# -- Extension configuration ------------------------------------------------- -# -- Options for manual page output -------------------------------------------- +# -- Options for intersphinx extension --------------------------------------- -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'pythoncontrol', u'Python Control Documentation', - [u'Python Control Developers'], 1) -] +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/doc/control.rst b/doc/control.rst index c12936f42..40cb407bb 100644 --- a/doc/control.rst +++ b/doc/control.rst @@ -1,30 +1,29 @@ .. _function-ref: -================== +****************** Function reference -================== +****************** +.. Include header information from the main control module .. automodule:: control :no-members: :no-inherited-members: -.. currentmodule:: control - System creation =============== .. autosummary:: - :toctree: generated/ + :toctree: generated/ ss tf - frd + FRD rss drss System interconnections ======================= .. autosummary:: - :toctree: generated/ + :toctree: generated/ append connect @@ -37,7 +36,7 @@ Frequency domain plotting ========================= .. autosummary:: - :toctree: generated/ + :toctree: generated/ bode_plot nyquist_plot @@ -57,7 +56,7 @@ Time domain simulation ====================== .. autosummary:: - :toctree: generated/ + :toctree: generated/ forced_response impulse_response @@ -68,7 +67,7 @@ Time domain simulation Block diagram algebra ===================== .. autosummary:: - :toctree: generated/ + :toctree: generated/ series parallel @@ -78,7 +77,7 @@ Block diagram algebra Control system analysis ======================= .. autosummary:: - :toctree: generated/ + :toctree: generated/ dcgain evalfr @@ -94,7 +93,7 @@ Control system analysis Matrix computations =================== .. autosummary:: - :toctree: generated/ + :toctree: generated/ care dare @@ -107,7 +106,7 @@ Matrix computations Control system synthesis ======================== .. autosummary:: - :toctree: generated/ + :toctree: generated/ acker h2syn @@ -119,7 +118,7 @@ Control system synthesis Model simplification tools ========================== .. autosummary:: - :toctree: generated/ + :toctree: generated/ minreal balred @@ -133,7 +132,7 @@ Model simplification tools Utility functions and conversions ================================= .. autosummary:: - :toctree: generated/ + :toctree: generated/ augw canonical_form diff --git a/doc/conventions.rst b/doc/conventions.rst index 78269c5ea..048356436 100644 --- a/doc/conventions.rst +++ b/doc/conventions.rst @@ -2,9 +2,9 @@ .. currentmodule:: control -################### +******************* Library conventions -################### +******************* The python-control library uses a set of standard conventions for the way that different types of standard information used by the library. @@ -190,7 +190,6 @@ Variables that can be configured, along with their default values: Functions that can be used to set standard configurations: .. autosummary:: - :toctree: generated/ use_fbs_defaults use_matlab_defaults diff --git a/doc/index.rst b/doc/index.rst index 928da28a2..407e89817 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,15 +1,10 @@ -.. Python-Control documentation master file, created by - sphinx-quickstart on Thu Jan 6 09:49:36 2011. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - +############################## Python Control Systems Library -============================== +############################## The Python Control Systems Library (`python-control`) is a Python package that implements basic operations for analysis and design of feedback control systems. - .. rubric:: Features - Linear input/output systems in state-space and frequency domain diff --git a/doc/intro.rst b/doc/intro.rst index 5310be55b..7402576ba 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -1,6 +1,6 @@ -============ +************ Introduction -============ +************ Welcome to the Python Control Systems Toolbox (python-control) User's Manual. This manual contains information on using the python-control @@ -8,7 +8,7 @@ package, including documentation for all functions in the package and examples illustrating their use. Overview of the Toolbox ------------------------ +======================= The python-control package is a set of python classes and functions that implement common operations for the analysis and design of feedback control @@ -20,7 +20,7 @@ many of the common functions corresponding to commands available in the MATLAB Control Systems Toolbox. Some Differences from MATLAB ----------------------------- +============================ The python-control package makes use of NumPy and SciPy. A list of general differences between NumPy and MATLAB can be found `here `_. @@ -33,7 +33,7 @@ some thing to keep in mind: * You cannot use braces for collections; use tuples instead Installation ------------- +============ The `python-control` package may be installed using pip, conda or the standard distutils/setuptools mechanisms. @@ -83,7 +83,7 @@ The package requires `numpy` and `scipy`, and the plotting routines require described above. Getting Started ---------------- +=============== There are two different ways to use the package. For the default interface described in :ref:`function-ref`, simply import the control package as follows:: diff --git a/doc/matlab.rst b/doc/matlab.rst index c042f3846..fc0ec3427 100644 --- a/doc/matlab.rst +++ b/doc/matlab.rst @@ -1,15 +1,13 @@ .. _matlab-module: -============================= +**************************** MATLAB compatibility module -============================= +**************************** .. automodule:: control.matlab :no-members: :no-inherited-members: -.. currentmodule:: control.matlab - Creating linear models ====================== .. autosummary::