diff --git a/README.rst b/README.rst index 48b398bc8..7a30f2cb8 100644 --- a/README.rst +++ b/README.rst @@ -24,7 +24,7 @@ Features Links ===== -- Project home page: http://python-control.sourceforge.net +- Project home page: http://python-control.org - Source code repository: https://github.com/python-control/python-control - Documentation: http://python-control.readthedocs.org/ - Issue tracker: https://github.com/python-control/python-control/issues @@ -46,7 +46,7 @@ https://github.com/python-control/Slycot Installation ============ -The package may be installed using pip or distutils. +The package may be installed using pip, conda, or distutils. Pip --- @@ -56,6 +56,14 @@ To install using pip:: pip install slycot # optional pip install control +conda-forge +----------- + +Binaries are available from conda-forge for selected platforms (Linux and +MacOS). Install using + + conda install -c conda-forge control + Distutils --------- diff --git a/control/config.py b/control/config.py index 98198aae7..10ab8a1ed 100644 --- a/control/config.py +++ b/control/config.py @@ -18,6 +18,8 @@ def use_matlab_defaults(): """ Use MATLAB compatible configuration settings + + The following conventions are used: * Bode plots plot gain in dB, phase in degrees, frequency in Hertz """ # Bode plot defaults @@ -28,7 +30,9 @@ def use_matlab_defaults(): # Set defaults to match FBS (Astrom and Murray) def use_fbs_defaults(): """ - Use `Astrom and Murray `_ compatible settings + Use `Feedback Systems `_ (FBS) compatible settings + + The following conventions are used: * Bode plots plot gain in powers of ten, phase in degrees, frequency in Hertz """ diff --git a/control/frdata.py b/control/frdata.py index 8c4e1f2f6..d34200455 100644 --- a/control/frdata.py +++ b/control/frdata.py @@ -452,8 +452,8 @@ def _convertToFRD(sys, omega, inputs=1, outputs=1): scalar, then the number of inputs and outputs can be specified manually, as in: - >>> sys = _convertToFRD(3.) # Assumes inputs = outputs = 1 - >>> sys = _convertToFRD(1., inputs=3, outputs=2) + >>> frd = _convertToFRD(3., omega) # Assumes inputs = outputs = 1 + >>> frd = _convertToFRD(1., omegs, inputs=3, outputs=2) In the latter example, sys's matrix transfer function is [[1., 1., 1.] [1., 1., 1.]]. diff --git a/control/freqplot.py b/control/freqplot.py index 33cf0ad61..f5761e282 100644 --- a/control/freqplot.py +++ b/control/freqplot.py @@ -70,8 +70,8 @@ def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None, ---------- syslist : linsys List of linear input/output systems (single system is OK) - omega : freq_range - Range of frequencies in rad/sec + omega : list + List of frequencies in rad/sec to be used for frequency response dB : boolean If True, plot result in dB Hz : boolean @@ -106,7 +106,7 @@ def bode_plot(syslist, omega=None, dB=None, Hz=None, deg=None, 2. If a discrete time model is given, the frequency response is plotted along the upper branch of the unit circle, using the mapping z = exp(j \omega dt) where omega ranges from 0 to pi/dt and dt is the discrete - time base. If not timebase is specified (dt = True), dt is set to 1. + timebase. If not timebase is specified (dt = True), dt is set to 1. Examples -------- diff --git a/control/lti.py b/control/lti.py index 0bd05e902..5950d9d58 100644 --- a/control/lti.py +++ b/control/lti.py @@ -82,9 +82,21 @@ def isctime(self, strict=False): return self.dt == 0 def issiso(self): + '''Check to see if a system is single input, single output''' return self.inputs == 1 and self.outputs == 1 def damp(self): + '''Natural frequency, damping ratio of system poles + + Returns + ------- + wn : array + Natural frequencies for each system pole + zeta : array + Damping ratio for each system pole + poles : array + Array of system poles + ''' poles = self.pole() if isdtime(self, strict=True): @@ -102,6 +114,16 @@ def dcgain(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 + + Parameters + ---------- + sys : LTI system + System to be checked + strict: bool (default = False) + If strict is True, do not treat scalars as SISO + """ if isinstance(sys, (int, float, complex, np.number)) and not strict: return True elif not isinstance(sys, LTI): diff --git a/control/statesp.py b/control/statesp.py index 4a617abd2..b55a8c681 100644 --- a/control/statesp.py +++ b/control/statesp.py @@ -1248,7 +1248,7 @@ def tf2ss(*args): def rss(states=1, outputs=1, inputs=1): """ - Create a stable **continuous** random state space object. + Create a stable *continuous* random state space object. Parameters ---------- @@ -1285,7 +1285,7 @@ def rss(states=1, outputs=1, inputs=1): def drss(states=1, outputs=1, inputs=1): """ - Create a stable **discrete** random state space object. + Create a stable *discrete* random state space object. Parameters ---------- diff --git a/control/xferfcn.py b/control/xferfcn.py index 50b9877fa..e8fe084f8 100644 --- a/control/xferfcn.py +++ b/control/xferfcn.py @@ -1017,7 +1017,7 @@ def _convertToTransferFunction(sys, **kw): If sys is an array-like type, then it is converted to a constant-gain transfer function. - >>> sys = _convertToTransferFunction([[1. 0.], [2. 3.]]) + >>> sys = _convertToTransferFunction([[1., 0.], [2., 3.]]) In this example, the numerator matrix will be [[[1.0], [0.0]], [[2.0], [3.0]]] diff --git a/doc/README b/doc/README index 9b829033e..f542badc5 100644 --- a/doc/README +++ b/doc/README @@ -1,7 +1,11 @@ Sphinx Documentation -------------------- +This directory contains the user manual for the python-control +toolbox. The documentation is built using sphinx. The master toctree +document is index.rst. -Note: Sphinx actually runs and imports python code, so broken code, or code not in conf.py sys.path, cannot be documented! +Note: Sphinx actually runs and imports python code, so broken code, or +code not in conf.py sys.path, cannot be documented! 1. Get Sphinx [http://sphinx.pocoo.org/] [python setup.py build/install] @@ -14,7 +18,8 @@ Note: Sphinx actually runs and imports python code, so broken code, or code not 4. >> touch *.rst >> make html [or make latex] -Creating/updating manual on sourceforge: - -5. >> rsync -rav _build/html/ user@shell.sourceforge.net:/home/project-web/python-control/htdocs/manual-N.mx/ +Creating/updating manual on readthedocs.org: +5. Log in to readthedocs.org and go to the 'Admin' menu for +python-control. Choose 'Versions' from the sidebar and mark the +latest release as 'Active'. Update the default version if needed. diff --git a/doc/control.rst b/doc/control.rst index 40cb407bb..1d0b14644 100644 --- a/doc/control.rst +++ b/doc/control.rst @@ -154,3 +154,5 @@ Utility functions and conversions timebase timebaseEqual unwrap + use_fbs_defaults + use_matlab_defaults diff --git a/doc/conventions.rst b/doc/conventions.rst index 048356436..829a2a1a8 100644 --- a/doc/conventions.rst +++ b/doc/conventions.rst @@ -45,8 +45,8 @@ transfer functions .. math:: G(s) = \frac{\text{num}(s)}{\text{den}(s)} - = \frac{a_0 s^n + a_1 s^{n-1} + \cdots + a_n} - {b_0 s^m + b_1 s^{m-1} + \cdots + b_m}, + = \frac{a_0 s^m + a_1 s^{m-1} + \cdots + a_m} + {b_0 s^n + b_1 s^{n-1} + \cdots + b_n}, where n is generally greater than or equal to m (for a proper transfer function). @@ -77,11 +77,10 @@ performed. Discrete time systems --------------------- -By default, all systems are considered to be continuous time systems. A -discrete time system is created by specifying the 'time base' dt. The time -base argument can be given when a system is constructed: +A discrete time system is created by specifying a nonzero 'timebase', dt. +The timebase argument can be given when a system is constructed: -* dt = None: no timebase specified +* dt = None: no timebase specified (default) * dt = 0: continuous time system * dt > 0: discrete time system with sampling period 'dt' * dt = True: discrete time with unspecified sampling period @@ -89,11 +88,16 @@ base argument can be given when a system is constructed: Only the :class:`StateSpace` and :class:`TransferFunction` classes allow explicit representation of discrete time systems. -Systems must have the same time base in order to be combined. For -continuous time systems, the :func:`sample_system` function or the -:meth:`StateSpace.sample` and :meth:`TransferFunction.sample` methods can be -used to create a discrete time system from a continuous time system. See -:ref:`utility-and-conversions`. +Systems must have compatible timebases in order to be combined. A system +with timebase `None` can be combined with a system having a specified +timebase; the result will have the timebase of the latter system. +Similarly, a discrete time system with unspecified sampling time (`dt = +True`) can be combined with a system having a specified sampling time; +the result will be a discrete time system with the sample time of the latter +system. For continuous time systems, the :func:`sample_system` function or +the :meth:`StateSpace.sample` and :meth:`TransferFunction.sample` methods +can be used to create a discrete time system from a continuous time system. +See :ref:`utility-and-conversions`. Conversion between representations ---------------------------------- @@ -106,18 +110,23 @@ argument or using the explicit conversion functions :func:`ss2tf` and 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 +A variety of functions in the library return time series data: sequences of +values that change over time. A common set of conventions is used for +returning such data: columns represent different points in time, rows are +different components (e.g., inputs, outputs or states). For return +arguments, an array of times is given as the first returned argument, +followed by one or more arrays of variable values. This convention 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`. + The convention used by python-control is different from the convention + used in the `scipy.signal + `_ library. 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 `scipy.signal`_. Types: @@ -177,7 +186,7 @@ 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 -`_. +`_ (FBS). Variables that can be configured, along with their default values: * bode_dB (False): Bode plot magnitude plotted in dB (otherwise powers of 10) @@ -190,6 +199,7 @@ 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 407e89817..7ea8fe1dd 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,7 +12,8 @@ implements basic operations for analysis and design of feedback control systems. - Time response: initial, step, impulse - Frequency response: Bode and Nyquist plots - Control analysis: stability, reachability, observability, stability margins -- Control design: eigenvalue placement, linear quadratic regulator +- Control design: eigenvalue placement, LQR, H2, Hinf +- Model reduction: balanced realizations, Hankel singular values - Estimator design: linear quadratic estimator (Kalman filter) .. rubric:: Documentation diff --git a/doc/intro.rst b/doc/intro.rst index 7402576ba..9677135c1 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -7,36 +7,41 @@ Manual. This manual contains information on using the python-control package, including documentation for all functions in the package and examples illustrating their use. -Overview of the Toolbox +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 systems. The initial goal is to implement all of the functionality required to work through the examples in the textbook `Feedback Systems -`_ by Astrom and Murray. A -MATLAB compatibility package (control.matlab) is available that provides -many of the common functions corresponding to commands available in the -MATLAB Control Systems Toolbox. +`_ by Astrom and Murray. A :ref:`matlab-module` is +available that provides many of the common functions corresponding to +commands available in the MATLAB Control Systems Toolbox. -Some Differences from MATLAB +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 +The python-control package makes use of `NumPy `_ and +`SciPy `_. A list of general differences between +NumPy and MATLAB can be found `here `_. In terms of the python-control package more specifically, here are some thing to keep in mind: * You must include commas in vectors. So [1 2 3] must be [1, 2, 3]. -* Functions that return multiple arguments use tuples -* You cannot use braces for collections; use tuples instead +* Functions that return multiple arguments use tuples. +* 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. +The `python-control` package can be installed using pip, conda or the +standard distutils/setuptools mechanisms. The package requires `numpy`_ and +`scipy`_, and the plotting routines require `matplotlib +`_. In addition, some routines require the `slycot +`_ library in order to implement +more advanced features (including some MIMO functionality). + To install using pip:: @@ -54,22 +59,23 @@ 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 `_. +`slycot` from source, which requires a working FORTRAN compiler and either +the `lapack` or `openplas` library. More information on the slycot package +can be obtained from the `slycot project page +`_. For users with the Anaconda distribution of Python, the following commands can be used:: conda install numpy scipy matplotlib # if not yet installed - conda install -c python-control -c cyclus slycot control + conda install -c conda-forge control -This installs `slycot` and `python-control` from the `python-control` -channel and uses the `cyclus` channel to obtain the required `lapack` -package. +This installs `slycot` and `python-control` from conda-forge, including the +`openblas` package. -Alternatively, to use setuptools, first `download the source `_ and unpack -it. To install in your home directory, use:: +Alternatively, to use setuptools, first `download the source +`_ and unpack it. +To install in your home directory, use:: python setup.py install --user @@ -78,11 +84,7 @@ or to install for all users (on Linux or Mac OS):: python setup.py build sudo python setup.py install -The package requires `numpy` and `scipy`, and the plotting routines require -`matplotlib`. In addition, some routines require the `slycot` module, -described above. - -Getting Started +Getting started =============== There are two different ways to use the package. For the default interface diff --git a/setup.py b/setup.py index 6751f64cd..cd4bcbf9f 100644 --- a/setup.py +++ b/setup.py @@ -19,9 +19,8 @@ Programming Language :: Python :: 2 Programming Language :: Python :: 2.7 Programming Language :: Python :: 3 -Programming Language :: Python :: 3.3 -Programming Language :: Python :: 3.4 Programming Language :: Python :: 3.5 +Programming Language :: Python :: 3.6 Topic :: Software Development Topic :: Scientific/Engineering Operating System :: Microsoft :: Windows