Update I/O system repr() and str() by murrayrm · Pull Request #1091 · python-control/python-control
This PR provides updates to the string representations of I/O systems, including both the __repr__ and __str__ functions (used for repr(), str(), and print()) as well as LaTeX output (via _repr_html_):
- Created a set of standard
_repr_*formats forInputOutputSystem's that can be overridden in subclasses to get the most useful representations based on the system type, using method names similar to_repr_latex_used by Jupyter notebooks:_repr_info_: generates a minimal description of the I/O system in the form<SystemClass name: [input list] -> [output list][, dt=timebase]>. This is the default format that exists for all I/O systems. The inclusion of the timebase is new._repr_eval_: generates an "evaluatable" description of the I/O system, if possible (otherwise return_repr_info_()). This is used inLTIsystems to show the state space matrices, numerator/denominator, or freuquency response data. This format is similar to what was done before this PR forLTIclasses, but now includes the signal names (if non-generic) or the signal counts (if generic). The inclusion of the string names make sure that you can recreate the system with the proper labels. The inclusion of the string counts lets you see the number of inputs and outputs._repr_html_: generates an HTML/LaTeX description of the I/O system, if possible (otherwise return_repr_info_()). This method is picked up by Jupyter notebooks to display the value of a variable and replaces_repr_latex_used in prior versions. This is similar to what was present before, except that now there is a "header" that shows the system name and signal names before showing a LaTeX representation of the state space matrices and/or transfer functions (this required changing_repr_latex_to_repr_html_). Note that since the timebase information is included in the header, it is no longer included in the LaTeX formatted code.
- Created a new function
iosys_repr(similar tonp.array_repr) that allows different representations of I/O systems via aformatparameter ('info', 'eval', or 'latex'). - The transfer function
display_formatparameter is now handled in a dynamic fashion. If it is set toNone(default) on system creation, the display style will followconfig.defaults['xferfcn.display_format']. If set topolyorzpkon system creation, that overrides the default. - Updated the
str()(print) representation ofInputOutputSystemsto includedtafter the state/input/output names (suppressed if it matches the defaultdt). - Updated the
str()(print) representation forNonlinearIOSystemsto include list of parameter labels. - Updated the
str()(print) representation forInterconnectedSystemsto include the list of subsystems (in 'info' form) as well summaries of the connections and outputs matrix (might be an eventual replacement forconnection_table). - All representations now apply
np.printoptionsto system arrays before generating strings, so you get consistent formatting across representations (including latex) and you can use things likesuppressto display near-zero numbers as '0'. - Fixed up various line spacings in
str()(print) to make things consistent across the various I/O system classes, including adding some indentation for transfer functions and MIMO systems (see screen shots below). - Added
examples/repr_gallery.ipynbandexampes/repr_gallery.pyfiles to show all of the various output formats and options (with dashed lines at the start and end so you can see any extraneous blank lines). - Added
config.defaultsoptions 'iosys.repr_format' and 'iosys.repr_show_count' to control representation formats. - The
combine_tffunction now accepts system and signal name keywords. (This is not strictly related to the main subject of this PR, but I needed since I had to set the name of the system in order for doctests to work.) - Added the ability of
config.defaultsto be called as a context manager, so that you can temporarily change default parameters (this is used inexamples/repr_gallery.py). (This is more general than this PR, but I used it extensively inrepr_gallery). - Updated docstrings and unit tests.
A detailed set of before and after views are attached as PDFs, generated by the new examples/repr_gallery.ipynb and exampes/repr_gallery.py files:
- Before: repr_gallery-10.1-29Dec2024.pdf
- After: repr_gallery-10.1-04Jan2025.pdf
Some highlights (pulled from repr_gallery):
- State space system, repr(), 'eval' format:
StateSpace: sys_ss, dt=0: ------------------------- StateSpace( array([[ 0., 1.], [-4., -5.]]), array([[0.], [1.]]), array([[-1., 1.]]), array([[0.]]), name='sys_ss', states=2, outputs=1, inputs=1) ---- - Discrete time, state space system, repr(), 'eval' format:
StateSpace: sys_dss, dt=0.1: ---------------------------- StateSpace( array([[ 0.98300988, 0.07817246], [-0.31268983, 0.59214759]]), array([[0.00424753], [0.07817246]]), array([[-1., 1.]]), array([[0.]]), dt=0.1, name='sys_dss', states=2, outputs=1, inputs=1) ---- - MIMO transfer function, repr(), 'eval' format:
TransferFunction: sys_mtf_zpk, dt=0: ------------------------------------ TransferFunction( [[array([ 1., -1.]), array([0.])], [array([1, 0]), array([1, 0])]], [[array([1., 5., 4.]), array([1.])], [array([1]), array([1, 2, 1])]], name='sys_mtf_zpk', outputs=2, inputs=2) ---- - Discrete time, state space system, repr(), ,'info' format:
TransferFunction: sys_dss_poly, dt=0.1: --------------------------------------- <TransferFunction sys_dss_poly: ['u[0]'] -> ['y[0]'], dt=0.1> ---- - Discrete time, state space systems, str():
<StateSpace>: sys_dss Inputs (1): ['u[0]'] Outputs (1): ['y[0]'] States (2): ['x[0]', 'x[1]'] dt = 0.1 A = [[ 0.98300988 0.07817246] [-0.31268983 0.59214759]] B = [[0.00424753] [0.07817246]] C = [[-1. 1.]] D = [[0.]] ---- - Nonlinear I/O system, str():
NonlinearIOSystem: sys_nl, dt=0: -------------------------------- <NonlinearIOSystem>: sys_nl Inputs (1): ['u[0]'] Outputs (1): ['y[0]'] States (2): ['x[0]', 'x[1]'] Parameters: ['a', 'b'] Update: <function nl_update at 0x1258ed800> Output: <function nl_output at 0x1258ed8a0> - Linear interconnected system, str():
LinearICSystem: sys_ic, dt=0: ----------------------------- <LinearICSystem>: sys_ic Inputs (2): ['r[0]', 'r[1]'] Outputs (2): ['y[0]', 'y[1]'] States (2): ['proc_x[0]', 'proc_x[1]'] Subsystems (2): * <StateSpace proc: ['u[0]', 'u[1]'] -> ['y[0]', 'y[1]']> * <StateSpace ctrl: ['u[0]', 'u[1]'] -> ['y[0]', 'y[1]'], dt=None> Connections: * proc.u[0] <- ctrl.y[0] * proc.u[1] <- ctrl.y[1] * ctrl.u[0] <- -proc.y[0] + r[0] * ctrl.u[1] <- -proc.y[1] + r[1] Outputs: * y[0] <- proc.y[0] * y[1] <- proc.y[1] A = [[-2. 3.] [-1. -5.]] B = [[-2. 0.] [ 0. -3.]] C = [[-1. 1.] [ 1. 0.]] D = [[0. 0.] [0. 0.]] ----