Version 0.10.2 Release Notes (current)

• Released: date of release

• GitHub release page

This release includes numerous bug fixes and improvements, with major changes such as a substantial reorganization of the documentation into a User Guide and Reference Manual, more consistent and complete docstrings, and support for referencing signals and subsystems by name as well as by index. Phase plane plots now use matplotlib’s streamplot for better visuals. New functions include combine_tf and split_tf for MIMO/SISO conversion and disk_margins for stability analysis. Additional improvements include consistent keyword usage, expanded LTI system methods for plotting and responses, better error messages, and legacy aliases to maintain backward compatibility.

This version of python-control requires Python 3.10 or higher, NumPy 1.23 or higher (2.x recommended), and SciPy 1.8 or higher.

New classes, functions, and methods

The following new classes, functions, and methods have been added in this release:

• find_operating_point: this function replaces (with a legacy alias) the find_eqpt function and now returns an OperatingPoint object containing the information about the operating point.

• combine_tf and split_tf: these two new functions allow you to create an MIMO transfer function from SISO transfer functions and vice versa.

• create_statefbk_iosystem now allows the creation of state feedback controllers using a “reference gain” pattern () in addition to the default “trajectory generation” pattern ().

• disk_margins: compute disk-based stability margins for SISO and MIMO systems.

• model_reduction: allow specific states, inputs, or outputs to be either eliminated or retained.

• place_acker: renamed version of acker (which is still accessible via an alias).

Bug fixes

The following bugs have been fixed in this release:

• phase_plane_plot: fixed a bug in which the return value was returning a sublist of lines rather than just a list of lines in cplt.lines.

• Processing of the timebase parameter (dt) for I/O systems is now handled uniformly across all I/O system factory functions. This affected the zpk function, which was defaulting to a discrete time system to have timebase None instead of 0.

• Multiplying (*), adding (+), or subtracting (-) a constant from any (MIMO) LTI object now acts element-wise (same as ndarray’s). This fixes a bug where multiplying a MIMO LTI system by a constant was multiplying by a matrix filled with the constant rather than a diagonal matrix (scaled identity).

• Fixed a bug where specifying an FRD system with fewer than 4 frequency points was generating an error because the default settings try to set up a smooth (interpolating) response and the default degree of the fit was 3.

• Fixed some bugs where computing poles and zeros of transfer functions could generate spurious error messages about unsafe casting of complex numbers to real numbers.

• TimeResponseData.to_pandas: multi-trace data (e.g., the output from a MIMO step response) was not being processed correctly. A new column ‘trace’ is now generated for multi-trace responses.

• Fixed a bug where where some arguments to nyquist_plot were not being processed correctly and generated errors about unrecognized keywords.

• Updated ctrb and obsv to handle 1D B or C matrix correctly.

• bode_plot: Fixed missing plot title when display_margin keyword was used.

• singular_values_plot: color cycling was not working correctly when a list of systems or responses was provided.

• nyquist_plot: The lines parameter of the ControlPlot object now matches the documentation. A 2D array is returned with the first index corresponding to the response (system) index and the second index corresponding to the segment type (primary, mirror x unscaled, scaled).

• Fix some internal bugs that cropped up when using NumPy 2.3.1 but were latent prior to that.

Improvements

The following additional improvements and changes in functionality were implemented in this release:

• User documentation is now divided into a User Guide that provides a description of the main functionality of the python-control package, along with a Reference Manual describing classes, functions, and parameters in more detail.

• Signal responses and I/O subsystem specifications can now use signal names in addition to indices to get the desired inputs, outputs, and states (e.g., response.outputs['y0', 'y1']). This is implemented via a new NamedSignal object, which generalizes numpy.ndarray.

• find_operating_point (legacy find_eqpt): accepts new parameters root_method and root_kwargs to set the root finding algorithm that is used.

• root_locus_map now correctly handles the degenerate case of being passed a single gain.

• The PoleZeroData object now takes a sort_loci parameter when it is created, with a default value of True. This is useful if you create a PoleZeroData object by hand (e.g., for producing stability diagrams).

• Factory functions for I/O system creation are now consistent in terms of copying signal/system names, overriding system/signal names, and converting between classes.

• The tf factory function to allow a 2D list of SISO transfer functions to be given as a means of creating a MIMO transfer function (use the new combine_tf function).

• The nlsys factory function can now create a NonlinearIOSystem representation of a StateSpace system (passed as the first argument to nlsys).

• LTI systems now have member functions for computing the various time responses and generating frequency domain plots. See LTI.to_ss, LTI.to_tf, LTI.bode_plot, LTI.nyquist_plot, LTI.nichols_plot and LTI.forced_response, LTI.impulse_response, LTI.initial_response, LTI.step_response.

• String representations of I/O systems (accessed via repr, print, and str) have been updated to create a more consistent form and provide more useful information. See Displaying LTI System Information for more information.

• Binary operations between MIMO and SISO functions are now supported, with the SISO system being converted to a MIMO system as if it were a scalar.

• nyquist_response: generates an error if you force the system to evaluate the dynamics at a pole.

• phase_crossover_frequencies: turned off spurious warning messages.

• ss2tf: added new method=scipy capability, allowing ss2tf to work on MIMO systems even if Slycot is not present.

• flatsys.solve_flat_optimal (legacy flatsys.solve_flat_ocp): allows scalar time vector.

• Improved checking of matrix shapes and better error messages in state space factory functions and other operations where matrices are passed as arguments.

• FrequencyResponseData: use complex to access the (squeeze processed) complex frequency response (instead of the legacy response property) and ~FrequencyResponseData.frdata to access the 3D frequency response data array (instead of the legacy fresp attribute).

• Time response and optimization function keywords have been regularized to allow consistent use of keywords across related functions:

  • Parameters specifying the inputs, outputs, and states are referred to as inputs, outputs, and states consistently throughout the functions.

  • Variables associated with inputs, outputs, states and time use those words plus an appropriate modifier: initial_state, final_output, input_indices, etc.

  • Aliases are used both to maintain backward compatibility and to allow shorthand descriptions: e.g., U, Y, X0. Short form aliases are documented in docstrings by listing the parameter as long_form (or sf) : type.

  • Existing legacy keywords are allowed and generate a PendingDeprecationWarning. Specifying a parameter value in two different ways (e.g., via long form and an alias) generates a TypeError.

• phase_plane_plot: makes use of the matplotlib streamplot function to provide better default phase plane diagrams.

• root_locus_plot: added by the ability to recompute the root locus when zooming in on portions of the root locus diagram.

• nyquist_plot: updated the rescaling algorithm to use a more gradual change in the magnitude of the Nyquist curve. The blend_fraction parameter can be used to start the rescaling prior to reaching max_curve_magnitude, giving less confusing plots. Some default parameter values have been adjusted to improve Nyquist plots.

Deprecations

The following functions have been newly deprecated in this release and generate a warning message when used:

• FrequencyResponseData.response: use FrequencyResponseData.complex to return the complex value of the frequency response.

• FrequencyResponseData.fresp: use FrequencyResponseData.frdata to access the raw 3D frequency response data array.

The listed items are slated to be removed in future releases (usually the next major or minor version update).