|
| 1 | +..currentmodule::control |
| 2 | + |
| 3 | +.. _version-0.10.2: |
| 4 | + |
| 5 | +Version 0.10.2 Release Notes |
| 6 | +---------------------------- |
| 7 | + |
| 8 | +* Released: date of release |
| 9 | +* `GitHub release page |
| 10 | +<https://github.com/python-control/python-control/releases/tag/0.10.2>`_ |
| 11 | + |
| 12 | +This release contains numerous bug fixes and improvements, including |
| 13 | +substantial updates to the documentation, including refactoring of the |
| 14 | +online manual into a User Guide and a Reference Manual, as well as |
| 15 | +more consistent and complete docstrings. In addition, signals and |
| 16 | +systems can now be referenced using signal labels in addition to |
| 17 | +offsets, and phase plane plots make use of the matplotlib |
| 18 | +`~matplotlib.pyplot.streamplot` function. Numerous other changes have |
| 19 | +been made to improve consistent of keyword arguments and function |
| 20 | +names, with legacy aliases available. |
| 21 | + |
| 22 | +This version of `python-control` requires Python 3.10 or higher, NumPy |
| 23 | +1.23 or higher (2.x recommended), and SciPy 1.8 or higher. |
| 24 | + |
| 25 | + |
| 26 | +New classes, functions, and methods |
| 27 | +................................... |
| 28 | + |
| 29 | +The following new classes, functions, and methods have been added in |
| 30 | +this release: |
| 31 | + |
| 32 | +* `find_operating_point`: this function replaces (with a legacy alias) |
| 33 | + the `find_eqpt` function and now returns an `OperatingPoint` object |
| 34 | + containing the information about the operating point. |
| 35 | + |
| 36 | +* `combine_tf` and `split_tf`: these two new functions allow you to |
| 37 | + create an MIMO transfer function from SISO transfer functions and |
| 38 | + vice versa. |
| 39 | + |
| 40 | +* `create_statefbk_iosystem` now allows the creation of state feedback |
| 41 | + controllers using a "reference gain" pattern (:math:`u = k_\text{f}\, |
| 42 | + r - K x`) in addition to the default "trajectory generation" pattern |
| 43 | + (:math:`u = u_\text{d} - K(x - x_\text{d})`). |
| 44 | + |
| 45 | +* `model_reduction`: has added functionality to allow specific states, |
| 46 | + inputs, or outputs that are eliminated can be specified by either |
| 47 | + listing the states, inputs, or outputs to be eliminated or those to |
| 48 | + be kept. |
| 49 | + |
| 50 | +* `place_acker`: renamed version of `acker` (which is still accessible |
| 51 | + via an alias). |
| 52 | + |
| 53 | + |
| 54 | +Bug fixes |
| 55 | +......... |
| 56 | + |
| 57 | +The following bugs have been fixed in this release: |
| 58 | + |
| 59 | +* `phase_plane_plot`: fixed a bug in which the return value was |
| 60 | + returning a sublist of lines rather than just a list of lines in |
| 61 | + `cplt.lines`. |
| 62 | + |
| 63 | +* Processing of the timebase parameter (`dt`) for I/O systems is now |
| 64 | + handled uniformly across all I/O system factor functions. This |
| 65 | + affected the `zpk` function, which was defaulting to a discrete time |
| 66 | + system to have timebase None instead of 0. |
| 67 | + |
| 68 | +* Multiplying (*), adding (+), or subtracting (-) a constant from any |
| 69 | + (MIMO) LTI object now acts element-wise (same as ndarray's). This |
| 70 | + fixes a bug where multiplying a MIMO LTI system by a constant was |
| 71 | + multiplying by a matrix filled with the constant rather than a |
| 72 | + diagonal matrix (scaled identity). |
| 73 | + |
| 74 | +* Fixed a bug where specifying an FRD system with fewer than 4 |
| 75 | + frequency points was generating an error because the default |
| 76 | + settings try to set up a smooth (interpolating) response and the |
| 77 | + default degree of the fit was 3. |
| 78 | + |
| 79 | +* Fixed some bugs where computing poles and zeros of transfer |
| 80 | + functions could generate spurious error messages about unsafe |
| 81 | + casting of complex numbers to real numbers. |
| 82 | + |
| 83 | +* `TimeResponseData.to_pandas`: multi-trace data (e.g., the output |
| 84 | + from a MIMO step response) was not being processed correctly. A new |
| 85 | + column 'trace' is now generated for multi-trace responses. |
| 86 | + |
| 87 | +* Fixed a bug where where some arguments to `nyquist_plot` were not |
| 88 | + being processed correctly and generated errors about unrecognized |
| 89 | + keywords. |
| 90 | + |
| 91 | +* Updated `ctrb` and `obsv` to handle 1D `B` or `C` matrix correctly. |
| 92 | + |
| 93 | +* `bode_plot`: Fixed missing plot title when `display_margin` keyword |
| 94 | + was used. |
| 95 | + |
| 96 | +* `singular_values_plot`: color cycling was not working correctly when |
| 97 | + a list of systems or responses was provided. |
| 98 | + |
| 99 | + |
| 100 | +Improvements |
| 101 | +............ |
| 102 | + |
| 103 | +The following additional improvements and changes in functionality |
| 104 | +were implemented in this release: |
| 105 | + |
| 106 | +* User documentation is now divided into a User Guide that provides a |
| 107 | + description of the main functionality of the python-control package, |
| 108 | + along with a Reference Manual describing classes, functions, and |
| 109 | + parameter in more detail. |
| 110 | + |
| 111 | +* Signal responses and I/O subsystem specifications can now use signal |
| 112 | + names in addition to indices to get the desired inputs, outputs, and |
| 113 | + states (e.g., `response.outputs['y0', 'y1']`). This is implemented |
| 114 | + via a new `NamedSignal` object, which generalizes `numpy.ndarray`. |
| 115 | + |
| 116 | +* `find_operating_point` (legacy `find_eqpt`): accepts new parameters |
| 117 | + `root_method` and `root_keyword` to set the root finding algorithm |
| 118 | + that is used. |
| 119 | + |
| 120 | +* `root_locus_map` now correctly handles the degenerate case of being |
| 121 | + passed a single gain. |
| 122 | + |
| 123 | +* The `PoleZeroData` object now takes a `sort_loci` parameter when it |
| 124 | + is created, with a default value of True. This is useful if you |
| 125 | + create a `PoleZeroData` object by hand (e.g., for producing stability |
| 126 | + diagrams). |
| 127 | + |
| 128 | +* Factory functions for I/O system creation are now consistent in |
| 129 | + terms of copying signal/system names, overriding system/signal |
| 130 | + names, and converting between classes. |
| 131 | + |
| 132 | +* The `tf` factory function to allow a 2D list of SISO transfer |
| 133 | + functions to be given as a means of creating a MIMO transfer |
| 134 | + function (use the new `combine_tf` function). |
| 135 | + |
| 136 | +* The `nlsys` factor function can now create a `NonlinearIOSystem` |
| 137 | + representation of a `StateSpace` system (passed as the first |
| 138 | + argument to `nlsys`). |
| 139 | + |
| 140 | +* LTI systems now have member functions for computing the various time |
| 141 | + responses and generating frequency domain plots. See `LTI.to_ss`, |
| 142 | + `LTI.to_tf`, `LTI.bode_plot`, `LTI.nyquist_plot`, `LTI.nichols_plot` |
| 143 | + and `LTI.forced_response`, `LTI.impulse_response`, |
| 144 | + `LTI.initial_response`, `LTI.step_response`. |
| 145 | + |
| 146 | +* String representations of I/O systems (accessed via `repr`, `print`, |
| 147 | + and `str`) have been updated to create a more consistent form and |
| 148 | + provide more useful information. See |
| 149 | +:ref:`displaying-lti-system-information` for more information. |
| 150 | + |
| 151 | +* Binary operations between MIMO and SISO functions are now supported, |
| 152 | + with the SISO system being converted to a MIMO system as if it were |
| 153 | + a scalar. |
| 154 | + |
| 155 | +* `nyquist_response`: generates an error if you force the system to |
| 156 | + evaluate the dynamics at a pole. |
| 157 | + |
| 158 | +* `phase_crossover_frequencies`: turned off spurious warning messages. |
| 159 | + |
| 160 | +* `ss2tf`: added new `method=scipy` capability, allowing `ss2tf` to |
| 161 | + work on MIMO systems even if Slycot is not present. |
| 162 | + |
| 163 | +* `flatsys.solve_flat_optimal` (legacy `flatsys.solve_flat_ocp`): |
| 164 | + allows scalar time vector. |
| 165 | + |
| 166 | +* Improved checking of matrix shapes and better error messages in |
| 167 | + state space factory functions and other operations were matrices are |
| 168 | + passed as arguments. |
| 169 | + |
| 170 | +* `FrequencyResponseData`: use `~FrequencyResponseData.complex` to |
| 171 | + access the (squeeze processed) complex frequency response (instead |
| 172 | + of the legacy `response` propery) and |
| 173 | + `~FrequencyResponseData.frdata` to access the 3D frequency response |
| 174 | + data array (instead of the legacy `fresp` attribute). |
| 175 | + |
| 176 | +* Time response and optimization function keywords have been |
| 177 | + regularized to allow consistent use of keywords across related |
| 178 | + functions: |
| 179 | + |
| 180 | + - Parameters specifying the inputs, outputs, and states are referred |
| 181 | + to as `inputs`, `outputs`, and `states` consistently throughout the |
| 182 | + functions. |
| 183 | + |
| 184 | + - Variables associated with inputs, outputs, states and time use |
| 185 | + those words plus an appropriate modifier: `initial_state`, |
| 186 | + `final_output`, `input_indices`, etc. |
| 187 | + |
| 188 | + - Aliases are used both to maintain backward compatibility and to |
| 189 | + allow shorthand descriptions: e.g., `U`, `Y`, `X0`. Short form |
| 190 | + aliases are documented in docstrings by listing the parameter as |
| 191 | + ``long_form (or sf) : type``. |
| 192 | + |
| 193 | + - Existing legacy keywords are allowed and generate a |
| 194 | + `PendingDeprecationWarning`. Specifying a parameter value in two |
| 195 | + different ways (e.g., via long form and an alias) generates a |
| 196 | + `TypeError`. |
| 197 | + |
| 198 | +* `phase_plane_plot`: makes use of the matplotlib |
| 199 | + `~matplotlib.pyplot.streamplot` function to provide better default |
| 200 | + phase plane diagrams. |
| 201 | + |
| 202 | + |
| 203 | +Deprecations |
| 204 | +............ |
| 205 | + |
| 206 | +The following functions have been newly deprecated in this release and |
| 207 | +generate a warning message when used: |
| 208 | + |
| 209 | +* `FrequencyResponseData.response`: use |
| 210 | + `FrequencyResponseData.complex` to return the complex value of the |
| 211 | + frequency response. |
| 212 | + |
| 213 | +* `FrequencyResponseData.fresp`: use `FrequencyResponseData.frdata |
| 214 | +<FrequencyResponseData>` to access the raw 3D frequency response |
| 215 | + data array. |
| 216 | + |
| 217 | +The listed items are slated to be removed in future releases (usually |
| 218 | +the next major or minor version update). |