diff --git a/README.rst b/README.rst index f5d4bd97b..48b398bc8 100644 --- a/README.rst +++ b/README.rst @@ -41,7 +41,7 @@ functionality is limited or absent, and installation of slycot is recommended (see below). Note that in order to install slycot, you will need a FORTRAN compiler on your machine. The Slycot wrapper can be found at: -https://github.com/jgoppert/Slycot +https://github.com/python-control/Slycot Installation ============ diff --git a/control/__init__.py b/control/__init__.py index a7ea1e61d..99cf9a73d 100644 --- a/control/__init__.py +++ b/control/__init__.py @@ -65,6 +65,8 @@ from .ctrlutil import * from .frdata import * from .canonical import * +from .robust import * +from .config import * # Exceptions from .exception import * diff --git a/control/config.py b/control/config.py index 9e5b027ec..188a4efd7 100644 --- a/control/config.py +++ b/control/config.py @@ -16,6 +16,10 @@ # Set defaults to match MATLAB def use_matlab_defaults(): + """ + Use MATLAB compatible configuration settings + * Bode plots plot gain in dB, phase in degrees, frequency in Hertz + """ # Bode plot defaults global bode_dB; bode_dB = True global bode_deg; bode_deg = True @@ -23,6 +27,11 @@ def use_matlab_defaults(): # Set defaults to match FBS (Astrom and Murray) def use_fbs_defaults(): + """ + Use `Astrom and Murray `_ compatible settings + * Bode plots plot gain in powers of ten, phase in degrees, + frequency in Hertz + """ # Bode plot defaults global bode_dB; bode_dB = False global bode_deg; bode_deg = True diff --git a/control/dtime.py b/control/dtime.py index 25ebfb8b6..36053da33 100644 --- a/control/dtime.py +++ b/control/dtime.py @@ -65,7 +65,7 @@ def sample_system(sysc, Ts, method='zoh', alpha=None): Ts : real Sampling period method : string - Method to use for conversion: 'matched' (default), 'tustin', 'zoh' + Method to use for conversion: 'matched', 'tustin', 'zoh' (default) Returns ------- diff --git a/control/frdata.py b/control/frdata.py index a7130e35f..ff1663b15 100644 --- a/control/frdata.py +++ b/control/frdata.py @@ -469,7 +469,7 @@ def _convertToFRD(sys, omega, inputs=1, outputs=1): sys.__class__) def frd(*args): - ''' + """ Construct a Frequency Response Data model, or convert a system frd models store the (measured) frequency response of a system. @@ -501,5 +501,5 @@ def frd(*args): See Also -------- ss, tf - ''' + """ return FRD(*args) diff --git a/control/timeresp.py b/control/timeresp.py index 3e9e168ca..ed95e319a 100644 --- a/control/timeresp.py +++ b/control/timeresp.py @@ -1,78 +1,12 @@ # timeresp.py - time-domain simulation routes -""" -Time domain simulation. - -This file contains a collection of functions that calculate -time responses for linear systems. - -.. _time-series-convention: - -Convention for Time Series --------------------------- - -This is a convention for function arguments and return values that -represent time series: sequences of values that change over time. It -is used throughout the library, for example in the functions -:func:`forced_response`, :func:`step_response`, :func:`impulse_response`, -and :func:`initial_response`. - -.. note:: - This convention is different from the convention used in the library - :mod:`scipy.signal`. In Scipy's convention the meaning of rows and columns - is interchanged. Thus, all 2D values must be transposed when they are - used with functions from :mod:`scipy.signal`. - -Types: - - * **Arguments** can be **arrays**, **matrices**, or **nested lists**. - * **Return values** are **arrays** (not matrices). - -The time vector is either 1D, or 2D with shape (1, n):: - - T = [[t1, t2, t3, ..., tn ]] - -Input, state, and output all follow the same convention. Columns are different -points in time, rows are different components. When there is only one row, a -1D object is accepted or returned, which adds convenience for SISO systems:: - - U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)] - [u2(t1), u2(t2), u2(t3), ..., u2(tn)] - ... - ... - [ui(t1), ui(t2), ui(t3), ..., ui(tn)]] +"""Time domain simulation. - Same for X, Y +This file contains a collection of functions that calculate time +responses for linear systems. -So, U[:,2] is the system's input at the third point in time; and U[1] or U[1,:] -is the sequence of values for the system's second input. +See doc/conventions.rst#time-series-conventions_ for more information +on how time series data are represented. -The initial conditions are either 1D, or 2D with shape (j, 1):: - - X0 = [[x1] - [x2] - ... - ... - [xj]] - -As all simulation functions return *arrays*, plotting is convenient:: - - t, y = step(sys) - plot(t, y) - -The output of a MIMO system can be plotted like this:: - - t, y, x = lsim(sys, u, t) - plot(t, y[0], label='y_0') - plot(t, y[1], label='y_1') - -The convention also works well with the state space form of linear systems. If -``D`` is the feedthrough *matrix* of a linear system, and ``U`` is its input -(*matrix* or *array*), then the feedthrough part of the system's response, -can be computed like this:: - - ft = D * U - ----------------------------------------------------------------- """ """Copyright (c) 2011 by California Institute of Technology @@ -453,6 +387,9 @@ def step_response(sys, T=None, X0=0., input=None, output=None, If True, transpose all input and output arrays (for backward compatibility with MATLAB and scipy.signal.lsim) + return_x: bool + If True, return the state vector (default = False). + Returns ------- T: array @@ -529,6 +466,9 @@ def initial_response(sys, T=None, X0=0., input=0, output=None, If True, transpose all input and output arrays (for backward compatibility with MATLAB and scipy.signal.lsim) + return_x: bool + If True, return the state vector (default = False). + Returns ------- T: array @@ -599,6 +539,9 @@ def impulse_response(sys, T=None, X0=0., input=0, output=None, If True, transpose all input and output arrays (for backward compatibility with MATLAB and scipy.signal.lsim) + return_x: bool + If True, return the state vector (default = False). + Returns ------- T: array diff --git a/doc/control.rst b/doc/control.rst index 3fdf48475..f3d124ee5 100644 --- a/doc/control.rst +++ b/doc/control.rst @@ -17,22 +17,31 @@ System creation ss tf + frd rss drss +System interconnections +======================= +.. autosummary:: + :toctree: generated/ + + append + connect + feedback + negate + parallel + series + Frequency domain plotting ========================= .. autosummary:: :toctree: generated/ - bode bode_plot - nyquist nyquist_plot - gangof4 gangof4_plot - nichols nichols_plot Time domain simulation @@ -47,74 +56,6 @@ Time domain simulation step_response phase_plot -.. _time-series-convention: - -Convention for Time Series --------------------------- - -This is a convention for function arguments and return values that -represent time series: sequences of values that change over time. It -is used throughout the library, for example in the functions -:func:`forced_response`, :func:`step_response`, :func:`impulse_response`, -and :func:`initial_response`. - -.. note:: - This convention is different from the convention used in the library - :mod:`scipy.signal`. In Scipy's convention the meaning of rows and columns - is interchanged. Thus, all 2D values must be transposed when they are - used with functions from :mod:`scipy.signal`. - -Types: - - * **Arguments** can be **arrays**, **matrices**, or **nested lists**. - * **Return values** are **arrays** (not matrices). - -The time vector is either 1D, or 2D with shape (1, n):: - - T = [[t1, t2, t3, ..., tn ]] - -Input, state, and output all follow the same convention. Columns are different -points in time, rows are different components. When there is only one row, a -1D object is accepted or returned, which adds convenience for SISO systems:: - - U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)] - [u2(t1), u2(t2), u2(t3), ..., u2(tn)] - ... - ... - [ui(t1), ui(t2), ui(t3), ..., ui(tn)]] - - Same for X, Y - -So, U[:,2] is the system's input at the third point in time; and U[1] or U[1,:] -is the sequence of values for the system's second input. - -The initial conditions are either 1D, or 2D with shape (j, 1):: - - X0 = [[x1] - [x2] - ... - ... - [xj]] - -As all simulation functions return *arrays*, plotting is convenient:: - - t, y = step(sys) - plot(t, y) - -The output of a MIMO system can be plotted like this:: - - t, y, x = lsim(sys, u, t) - plot(t, y[0], label='y_0') - plot(t, y[1], label='y_1') - -The convention also works well with the state space form of linear systems. If -``D`` is the feedthrough *matrix* of a linear system, and ``U`` is its input -(*matrix* or *array*), then the feedthrough part of the system's response, -can be computed like this:: - - ft = D * U - - Block diagram algebra ===================== .. autosummary:: @@ -160,6 +101,8 @@ Control system synthesis :toctree: generated/ acker + h2syn + hinfsyn lqr place @@ -183,12 +126,15 @@ Utility functions and conversions unwrap db2mag mag2db + damp isctime isdtime + issiso issys pade sample_system canonical_form + observable_form reachable_form ss2tf ssdata diff --git a/doc/conventions.rst b/doc/conventions.rst new file mode 100644 index 000000000..881a0a6bb --- /dev/null +++ b/doc/conventions.rst @@ -0,0 +1,103 @@ +.. _conventions-ref: + +.. 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. + +.. _time-series-convention: + +Time series data +================ + +This is a convention for function arguments and return values that +represent time series: sequences of values that change over time. It +is used throughout the library, for example in the functions +:func:`forced_response`, :func:`step_response`, :func:`impulse_response`, +and :func:`initial_response`. + +.. note:: + This convention is different from the convention used in the library + :mod:`scipy.signal`. In Scipy's convention the meaning of rows and columns + is interchanged. Thus, all 2D values must be transposed when they are + used with functions from :mod:`scipy.signal`. + +Types: + + * **Arguments** can be **arrays**, **matrices**, or **nested lists**. + * **Return values** are **arrays** (not matrices). + +The time vector is either 1D, or 2D with shape (1, n):: + + T = [[t1, t2, t3, ..., tn ]] + +Input, state, and output all follow the same convention. Columns are different +points in time, rows are different components. When there is only one row, a +1D object is accepted or returned, which adds convenience for SISO systems:: + + U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)] + [u2(t1), u2(t2), u2(t3), ..., u2(tn)] + ... + ... + [ui(t1), ui(t2), ui(t3), ..., ui(tn)]] + + Same for X, Y + +So, U[:,2] is the system's input at the third point in time; and U[1] or U[1,:] +is the sequence of values for the system's second input. + +The initial conditions are either 1D, or 2D with shape (j, 1):: + + X0 = [[x1] + [x2] + ... + ... + [xj]] + +As all simulation functions return *arrays*, plotting is convenient:: + + t, y = step(sys) + plot(t, y) + +The output of a MIMO system can be plotted like this:: + + t, y, x = lsim(sys, u, t) + plot(t, y[0], label='y_0') + plot(t, y[1], label='y_1') + +The convention also works well with the state space form of linear systems. If +``D`` is the feedthrough *matrix* of a linear system, and ``U`` is its input +(*matrix* or *array*), then the feedthrough part of the system's response, +can be computed like this:: + + ft = D * U + +Package configuration +===================== + +The python-control library can be customized to allow for different plotting +conventions. The currently configurable options allow the units for Bode +plots to be set as dB for gain, degrees for phase and Hertz for frequency +(MATLAB conventions) or the gain can be given in magnitude units (powers of +10), corresponding to the conventions used in `Feedback Systems +`_. + +Variables that can be configured, along with their default values: + * bode_dB (False): Bode plot magnitude plotted in dB (otherwise powers of 10) + * bode_deg (True): Bode plot phase plotted in degrees (otherwise radians) + * bode_Hz (False): Bode plot frequency plotted in Hertz (otherwise rad/sec) + * bode_number_of_samples (None): Number of frequency points in Bode plots + * bode_feature_periphery_decade (1.0): How many decades to include in the + frequency range on both sides of features (poles, zeros). + +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 fcce6d38c..928da28a2 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -26,6 +26,7 @@ implements basic operations for analysis and design of feedback control systems. :maxdepth: 2 intro + conventions control classes matlab diff --git a/doc/intro.rst b/doc/intro.rst index bd3add56b..a55913291 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -35,14 +35,38 @@ some thing to keep in mind: Installation ------------ -The `python-control` package may be installed using pip or the standard -distutils/setuptools mechanisms. +The `python-control` package may be installed using pip, conda or the +standard distutils/setuptools mechanisms. To install using pip:: pip install slycot # optional pip install control +Many parts of `python-control` will work without `slycot`, but some +functionality is limited or absent, and installation of `slycot` is +recommended. + +*Note*: the `slycot` library only works on some platforms, mostly +linux-based. Users should check to insure that slycot is installed +correctly by running the command:: + + python -c "import slycot" + +and verifying that no error message appears. It may be necessary to install +`slycot` from source, which requires a working FORTRAN compiler and the +`lapack` library. More information on the slycot package can be obtained +from the `slycot project page `_. + +For users with a working the Anaconda distribution of Python, the following +command can be used:: + + conda install -c python-control -c cyclus slycot python-control + +This installs `slycot` and `python-control` from the `python-control` +channel and uses the `cyclus` channel to obtain the required `lapack` +package. + Alternatively, to use setuptools, first `download the source `_ and unpack it. To install in your home directory, use:: @@ -54,11 +78,8 @@ or to install for all users (on Linux or Mac OS):: sudo python setup.py install The package requires `numpy` and `scipy`, and the plotting routines require -`matplotlib`. In addition, some routines use a module called `slycot`, which is -a Python wrapper around some FORTRAN routines. Many parts of `python-control` -will work without `slycot`, but some functionality is limited or absent, and -installation of `slycot` is recommended. For more information, see the GitHub -repository for `slycot `_. +`matplotlib`. In addition, some routines require the `slycot` module, +described above. Getting Started --------------- pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy