Package Configuration Parameters

The python-control package can be customized to allow for different default values for selected parameters. This includes the ability to change the way system names are created, to set the style for various types of plots, and to determine default solvers and parameters to use in solving optimization problems.

To set the default value of a configuration parameter, set the appropriate element of the config.defaults dictionary:

ct.config.defaults['module.parameter'] = value

The set_defaults() function can also be used to set multiple configuration parameters at the same time:

ct.set_defaults('module', param1=val1, param2=val2, ...]

Several functions available to set collections of parameters based on standard configurations:

`reset_defaults`()	Reset configuration values to their default (initial) values.
`use_fbs_defaults`()	Use Feedback Systems (FBS) compatible settings.
`use_matlab_defaults`()	Use MATLAB compatible configuration settings.
`use_legacy_defaults`(version)	Sets the defaults to whatever they were in a given release.

Finally, the config.defaults object can be used as a context manager for temporarily setting default parameters:

>>> with ct.config.defaults({'iosys.repr_format': 'info'}):
...     sys = ct.rss(4, 2, 2, name='sys')
...     print(repr(sys))
<StateSpace sys: ['u[0]', 'u[1]'] -> ['y[0]', 'y[1]']>

System creation parameters

control.default_dt: int = 0: Default value of dt when constructing new I/O systems. If dt is not specified explicitly this value will be used. Set to None to leave the timebase unspecified, 0 for continuous-time systems, True for discrete-time systems.

iosys.converted_system_name_prefix: str = '': Prefix to add to system name when converting a system from one representation to another.

iosys.converted_system_name_suffix: str = '$converted': Suffix to add to system name when converting a system from one representation to another.

iosys.duplicate_system_name_prefix: str = '': Prefix to add to system name when making a copy of a system.

iosys.duplicate_system_name_suffix: str = '$copy': Suffix to add to system name when making a copy of a system.

iosys.indexed_system_name_prefix: str = '': Prefix to add to system name when extracting a subset of the inputs and outputs.

iosys.indexed_system_name_suffix: str = '$indexed': Suffix to add to system name when extracting a subset of the inputs and outputs.

iosys.linearized_system_name_prefix: str = '': Prefix to add to system name when linearizing a system using linearize().

iosys.linearized_system_name_suffix: str = '$linearized': Suffix to add to system name when linearizing a system using linearize().

iosys.sampled_system_name_prefix: str = '': Prefix to add to system name when sampling a system at a set of frequency points in frd() or converting a continuous-time system to discrete time in sample_system().

iosys.sampled_system_name_suffix: str = '$sampled': Suffix to add to system name when sampling a system at a set of frequency points in frd() or converting a continuous-time system to discrete time in sample_system().

iosys.state_name_delim: str = '_': Used by interconnect() to set the names of the states of the interconnected system. If the state names are not explicitly given, the states will be given names of the form ‘<subsys_name><delim><state_name>’, for each subsys in syslist and each state_name of each subsys, where <delim> is the value of config.defaults[‘iosys.state_name_delim’].

statesp.remove_useless_states: bool = False: When creating a StateSpace system, remove states that have no effect on the input-output dynamics of the system.

System display parameters

iosys.repr_format: str = 'eval'

Set the default format used by iosys_repr() to create the representation of an InputOutputSystem:

‘info’ : <IOSystemType sysname: [inputs] -> [outputs]>

‘eval’ : system specific, loadable representation

‘latex’ : latex representation of the object

iosys.repr_show_count: bool = True: If True, show the input, output, and state count when using iosys_repr and the ‘eval’ format. Otherwise, the input, output, and state values are repressed from the output unless non-generic signal names are present.

xferfcn.display_format: str = 'poly'

Set the display format used in printing the TransferFunction object:

‘poly’: Single polynomial for numerator and denominator.

‘zpk’: Product of factors, showing poles and zeros.

xferfcn.floating_point_format: str = '.4g': Format to use for displaying coefficients in TransferFunction objects when generating string representations.

statesp.latex_num_format: str = '.3g': Format to use for displaying coefficients in StateSpace systems when generating LaTeX representations.

statesp.latex_repr_type: str = 'partitioned': Used when generating LaTeX representations of StateSpace systems. If ‘partitioned’, the A, B, C, D matrices are shown as a single, partitioned matrix; if ‘separate’, the matrices are shown separately.

statesp.latex_maxsize: int = 10: Maximum number of states plus inputs or outputs for which the LaTeX representation of the system dynamics will be generated.

Response parameters

control.squeeze_frequency_response: bool = None: Set the default value of the squeeze parameter for frequency_response() and FrequencyResponseData objects. If None then if a system is single-input, single-output (SISO) the outputs (and inputs) are returned as a 1D array (indexed by frequency), and if a system is multi-input or multi-output, then the outputs are returned as a 2D array (indexed by output and frequency) or a 3D array (indexed by output, input (or trace), and frequency). If squeeze=True, access to the output response will remove single-dimensional entries from the shape of the inputs and outputs even if the system is not SISO. If squeeze=False, the output is returned as a 3D array (indexed by the output, input, and frequency) even if the system is SISO.

control.squeeze_time_response: bool = None: Set the default value of the squeeze parameter for input_output_response() and other time response objects. By default, if a system is single-input, single-output (SISO) then the outputs (and inputs) are returned as a 1D array (indexed by time) and if a system is multi-input or multi-output, then the outputs are returned as a 2D array (indexed by output and time) or a 3D array (indexed by output, input, and time). If squeeze=True, access to the output response will remove single-dimensional entries from the shape of the inputs and outputs even if the system is not SISO. If squeeze=False, the output is returned as a 3D array (indexed by the output, input, and time) even if the system is SISO.

forced_response.return_x: bool = False: Determine whether forced_response() returns the values of the states when the TimeResponseData object is evaluated. The default value was True before version 0.9 and is False since then.

Plotting parameters

ctrlplot.rcParams: dict = {'axes.labelsize': 'small', 'axes.titlesize': 'small', 'figure.titlesize': 'medium', 'legend.fontsize': 'x-small', 'xtick.labelsize': 'small', 'ytick.labelsize': 'small'}: Overrides the default matplotlib parameters used for generating plots. This dictionary can also be accessed as ct.rcParams.

freqplot.dB: bool = False: If True, the magnitude in bode_plot() is plotted in dB (otherwise powers of 10).

freqplot.deg: bool = True: If True, the phase in bode_plot() is plotted in degrees (otherwise radians).

freqplot.feature_periphery_decades: int = 1: Number of decades in frequency to include on both sides of features (poles, zeros) when generating frequency plots.

freqplot.freq_label: bool = 'Frequency [{units}]': Label for the frequency axis in frequency plots, with units set to either ‘rad/sec’ or ‘Hz’ when the label is created.

freqplot.grid: bool = True: Include grids for magnitude and phase in frequency plots.

freqplot.Hz: bool = False: If True, use Hertz for frequency response plots (otherwise rad/sec).

freqplot.magnitude_label: str = 'Magnitude': Label to use on the magnitude portion of a frequency plot. Set to ‘Gain’ by use_fbs_defaults().

freqplot.number_of_samples: int = 1000: Number of frequency points to use in in frequency plots.

freqplot.share_magnitude: str = 'row': Determine whether and how axis limits are shared between the magnitude variables in bode_plot(). Can be set set to ‘row’ to share across all subplots in a row, ‘col’ to set across all subplots in a column, or False to allow independent limits.

freqplot.share_phase: str = 'row': Determine whether and how axis limits are shared between the phase variables in bode_plot(). Can be set set to ‘row’ to share across all subplots in a row, ‘col’ to set across all subplots in a column, or False to allow independent limits.

freqplot.share_frequency: str = 'col': Determine whether and how axis limits are shared between the frequency axes in bode_plot(). Can be set set to ‘row’ to share across all subplots in a row, ‘col’ to set across all subplots in a column, or False to allow independent limits.

freqplot.title_frame: str = 'axes': Set the frame of reference used to center the plot title. If set to ‘axes’, the horizontal position of the title will be centered relative to the axes. If set to ‘figure’, it will be centered with respect to the figure (faster execution).

freqplot.wrap_phase: bool = False: If wrap_phase is False, then the phase will be unwrapped so that it is continuously increasing or decreasing. If wrap_phase is True the phase will be restricted to the range [-180, 180) (or [ $-\pi$ , $\pi$ ) radians). If wrap_phase is specified as a float, the phase will be offset by 360 degrees if it falls below the specified value.

nichols.grid: bool = True: Set to True if nichols_plot() should include a Nichols-chart grid.

nyquist.arrows: int = 2: Specify the default number of arrows for nyquist_plot().

nyquist.arrow_size: float = 8: Arrowhead width and length (in display coordinates) for nyquist_plot().

nyquist.circle_style: dict = {'color': 'black', 'linestyle': 'dashed', 'linewidth': 1}: Style for unit circle in nyquist_plot().

nyquist.encirclement_threshold: float = 0.05: Define the threshold in nyquist_response() for generating a warning if the number of net encirclements is a non-integer value.

nyquist.indent_direction: str = 'right': Set the direction of indentation in nyquist_response() for poles on the imaginary axis. Valid values are ‘right’, ‘left’, or ‘none’.

nyquist.indent_points: int = 50: Set the number of points to insert in the Nyquist contour around poles that are at or near the imaginary axis in nyquist_response().

nyquist.indent_radius: float = 0.0001: Amount to indent the Nyquist contour around poles on or near the imaginary axis in nyquist_response(). Portions of the Nyquist plot corresponding to indented portions of the contour are plotted using a different line style.

nyquist.max_curve_magnitude: float = 20: Restrict the maximum magnitude of the Nyquist plot in nyquist_plot(). Portions of the Nyquist plot whose magnitude is restricted are plotted using a different line style.

nyquist.max_curve_offset: float = 0.02: When plotting scaled portion of the Nyquist plot in nyquist_plot(), increase/decrease the magnitude by this fraction of the max_curve_magnitude to allow any overlaps between the primary and mirror curves to be avoided.

nyquist.mirror_style: list of str = ['--', ':']: Linestyles for mirror image of the Nyquist curve in nyquist_plot(). The first element is used for unscaled portions of the Nyquist curve, the second element is used for portions that are scaled (using max_curve_magnitude). If False then omit the mirror image curve completely.

nyquist.primary_style: list of str = ['-', '-.']: Linestyles for primary image of the Nyquist curve in nyquist_plot(). The first element is used for unscaled portions of the Nyquist curve, the second element is used for portions that are scaled (using max_curve_magnitude).

nyquist.start_marker: str = 'o': Matplotlib marker to use to mark the starting point of the Nyquist plot in nyquist_plot().

nyquist.start_marker_size: float = 4: Start marker size (in display coordinates) in nyquist_plot().

phaseplot.arrows: int = 2: Set the default number of arrows in phase_plane_plot() and phaseplot.streamlines().

phaseplot.arrow_size: float = 8: Set the default size of arrows in phase_plane_plot() and phaseplot.streamlines().

phaseplot.arrow_style: matplotlib patch = None

Set the default style for arrows in phase_plane_plot() and phaseplot.streamlines(). If set to None, defaults to

mpl.patches.ArrowStyle(
    'simple', head_width=int(2 * arrow_size / 3),
    head_length=arrow_size)

phaseplot.separatrices_radius: float = 0.1: In phaseplot.separatrices(), set the offset from the equilibrium point to the starting point of the separatix traces, in the direction of the eigenvectors evaluated at that equilibrium point.

pzmap.buffer_factor: float = 1.05: The limits of the pole/zero plot generated by pole_zero_plot() are set based on the location features in the plot, including the location of poles, zeros, and local maxima of root locus curves. The locations of local maxima are expanded by the buffer factor set by buffer_factor.

pzmap.expansion_factor: float = 1.8: The final axis limits of the pole/zero plot generated by pole_zero_plot() are set to by the largest features in the plot multiplied by an expansion factor set by expansion_factor.

pzmap.grid: bool = False

If True plot omega-damping grid in pole_zero_plot(). If False or None show imaginary axis for continuous-time systems, unit circle for discrete-time systems. If ‘empty’, do not draw any additional lines.

Note: this setting only applies to pole/zero plots. For root locus plots, the ‘rlocus.grid’ parameter value is used as the default.

pzmap.marker_size: float = 6: Set the size of the markers used for poles and zeros in pole_zero_plot().

pzmap.marker_width: float = 1.5: Set the line width of the markers used for poles and zeros in pole_zero_plot().

rlocus.grid: bool = True: If True, plot omega-damping grid in root_locus_plot(). If False or None show imaginary axis for continuous-time systems, unit circle for discrete-time systems. If ‘empty’, do not draw any additional lines.

sisotool.initial_gain: float = 1: Initial gain to use for plotting root locus in sisotool().

timeplot.input_props: list of dict = [{'color': 'tab:red'}, {'color': 'tab:purple'}, {'color': 'tab:brown'}, {'color': 'tab:olive'}, {'color': 'tab:cyan'}]: List of line properties to use when plotting combined inputs in time_response_plot(). The line properties for each input will be cycled through this list.

timeplot.output_props: list of dict = [{'color': 'tab:blue'}, {'color': 'tab:orange'}, {'color': 'tab:green'}, {'color': 'tab:pink'}, {'color': 'tab:gray'}]: List of line properties to use when plotting combined outputs in time_response_plot(). The line properties for each input will be cycled through this list.

timeplot.trace_props: list of dict = [{'linestyle': '-'}, {'linestyle': '--'}, {'linestyle': ':'}, {'linestyle': '-.'}]: List of line properties to use when plotting multiple traces in time_response_plot(). The line properties for each input will be cycled through this list.

timeplot.sharex: str = 'col': Determine whether and how x-axis limits are shared between subplots in time_response_plot(). Can be set set to ‘row’ to share across all subplots in a row, ‘col’ to set across all subplots in a column, ‘all’ to share across all subplots, or False to allow independent limits.

timeplot.sharey: bool = False: Determine whether and how y-axis limits are shared between subplots in time_response_plot(). Can be set set to ‘row’ to share across all subplots in a row, ‘col’ to set across all subplots in a column, ‘all’ to share across all subplots, or False to allow independent limits.

timeplot.time_label: str = 'Time [s]': Label to use for the time axis in time_response_plot().

Optimization parameters

optimal.minimize_method: str = None: Set the method used by scipy.optimize.minimize() when called in solve_optimal_trajectory() and solve_optimal_estimate().

optimal.minimize_options: dict = {}: Set the value of the options keyword used by scipy.optimize.minimize() when called in solve_optimal_trajectory() and solve_optimal_estimate().

optimal.minimize_kwargs: dict = {}: Set the keyword arguments passed to scipy.optimize.minimize() when called in solve_optimal_trajectory() and solve_optimal_estimate().

optimal.solve_ivp_method: str = None: Set the method used by scipy.integrate.solve_ivp() when called in solve_optimal_trajectory() and solve_optimal_estimate().

optimal.solve_ivp_options: dict = {}: Set the value of the options keyword used by scipy.integrate.solve_ivp() when called in solve_optimal_trajectory() and solve_optimal_estimate().