pymor.models.transfer_function

Module Contents

class pymor.models.transfer_function.FactorizedTransferFunction(dim_input, dim_output, K, B, C, D, dK=None, dB=None, dC=None, dD=None, parameters={}, sampling_time=0, name=None)

Bases: TransferFunction

Transfer functions in generalized coprime factor form.

This class describes input-output systems given by a transfer function of the form \(H(s, \mu) = \mathcal{C}(s, \mu) \mathcal{K}(s, \mu)^{-1} \mathcal{B}(s, \mu) + \mathcal{D}(s, \mu)\).

Parameters

dim_input

The number of inputs.

dim_output

The number of outputs.

K, B, C, D

Functions that take s and return an Operator.

dK, dB, dC, dD

Functions that take s and return an Operator that is the derivative of K, B, C, D (optional).

parameters

The Parameters of the transfer function.

sampling_time

0 if the system is continuous-time, otherwise a positive number that denotes the sampling time (in seconds).

name

Name of the system.

class pymor.models.transfer_function.TransferFunction(dim_input, dim_output, tf, dtf=None, parameters={}, sampling_time=0, presets=None, name=None)

Bases: pymor.core.cache.CacheableObject, pymor.parameters.base.ParametricObject

Class for systems represented by a transfer function.

This class describes input-output systems given by a (parametrized) transfer function \(H(s, \mu)\).

Parameters

dim_input

The number of inputs.

dim_output

The number of outputs.

tf

The transfer function H, given by a callable that takes a complex value s and, if parametric, a parameter value mu. The result of tf(s, mu) is a NumPy array of shape (dim_output, dim_input).

dtf

The complex derivative of H with respect to s (optional).

parameters

The Parameters of the transfer function.

sampling_time

0 if the system is continuous-time, otherwise a positive number that denotes the sampling time (in seconds).

presets

A dict of preset attributes or None. The dict must only contain keys that correspond to attributes of TransferFunction such as h2_norm.

name

Name of the system.

dim_input

The number of inputs.

dim_output

The number of outputs.

tf

The transfer function.

dtf

The complex derivative of the transfer function.

Methods

bode	Compute magnitudes and phases.
bode_plot	Draw the Bode plot for all input-output pairs.
eval_dtf	Evaluate the derivative of the transfer function.
eval_tf	Evaluate the transfer function.
freq_resp	Evaluate the transfer function on the imaginary axis.
h2_inner	Compute H2 inner product with an LTIModel.
h2_norm	Compute the H2-norm using quadrature.
mag_plot	Draw the magnitude plot.

cache_region = 'memory'

bode(w, mu=None, adaptive_opts=None)

Compute magnitudes and phases.

Parameters

w

If len(w) == 2, the left and right limits used for the adaptive sampling. Otherwise, a sequence of angular frequencies at which to compute the transfer function.

mu

Parameter values for which to evaluate the transfer function.

adaptive_opts

Optional arguments for adaptive (ignored if len(w) != 2).

Returns

w

A sequence of angular frequencies at which the transfer function was computed (returned if len(w) == 2).

mag

Transfer function magnitudes at frequencies in w, NumPy array of shape (len(w), self.dim_output, self.dim_input).

phase

Transfer function phases (in radians) at frequencies in w, NumPy array of shape (len(w), self.dim_output, self.dim_input).

bode_plot(w, mu=None, ax=None, Hz=False, dB=False, deg=True, adaptive_opts=None, input_indices=None, output_indices=None, **mpl_kwargs)

Draw the Bode plot for all input-output pairs.

Parameters

w

If len(w) == 2, the left and right limits used for the adaptive sampling. Otherwise, a sequence of angular frequencies at which to compute the transfer function.

mu

Parameter values for which to evaluate the transfer function.

ax

Axis of shape (2 * self.dim_output, self.dim_input) to which to plot. If not given, matplotlib.pyplot.gcf is used to get the figure and create axis.

Hz

Should the frequency be in Hz on the plot.

dB

Should the magnitude be in dB on the plot.

deg

Should the phase be in degrees (otherwise in radians).

adaptive_opts

Optional arguments for adaptive (ignored if len(w) != 2).

input_indices

Optional argument to select specific inputs to be paired with all outputs or selected ones. If None, all inputs are used for plotting, otherwise, an iterable containing the indices of the selected inputs has to be passed. The order of the plots depends on the order of the indices in the iterable. It is possible to pass negative indices to access the inputs counting backwards.

output_indices

Optional argument to select specific outputs to be paired with all inputs or selected ones. If None, all outputs are used for plotting, otherwise, an iterable containing the indices of the selected outputs has to be passed. The order of the plots depends on the order of the indices in the iterable. It is possible to pass negative indices to access the outputs counting backwards.

mpl_kwargs

Keyword arguments used in the matplotlib plot function.

Returns

artists

List of matplotlib artists added.

eval_dtf(s, mu=None)

Evaluate the derivative of the transfer function.

Parameters

s

Laplace variable as a complex number.

mu

Parameter values.

Returns

Transfer function value as a 2D NumPy array.

eval_tf(s, mu=None)

Evaluate the transfer function.

Parameters

s

Laplace variable as a complex number.

mu

Parameter values.

Returns

Transfer function value as a 2D NumPy array.

freq_resp(w, mu=None, adaptive_type='bode', adaptive_opts=None)

Evaluate the transfer function on the imaginary axis.

Parameters

w

If len(w) == 2, the left and right limits used for the adaptive sampling. Otherwise, a sequence of angular frequencies at which to compute the transfer function.

mu

Parameter values for which to evaluate the transfer function.

adaptive_type

The plot type that adaptive sampling should be used for ('bode', 'mag'). Ignored if len(w) != 2.

adaptive_opts

Optional arguments for adaptive (ignored if len(w) != 2). If xscale and yscale are not set, 'log' is used.

Returns

w

A sequence of angular frequencies at which the transfer function was computed (returned if len(w) == 2).

tfw

Transfer function values at frequencies in w, NumPy array of shape (len(w), self.dim_output, self.dim_input).

h2_inner(lti, mu=None)

Compute H2 inner product with an LTIModel.

Uses the inner product formula based on the pole-residue form (see, e.g., Lemma 1 in [ABG10]). It assumes that self.tf is defined on -lti.poles().

Parameters

lti

LTIModel consisting of Operators that can be converted to NumPy arrays. The D operator is ignored.

mu

Parameter values.

Returns

inner

H2 inner product.

h2_norm(return_norm_only=True, mu=None, **quad_kwargs)

Compute the H2-norm using quadrature.

This method uses scipy.integrate.quad and makes no assumptions on the form of the transfer function. It only assumes that self.tf is defined over the imaginary axis.

By default, the absolute error tolerance in scipy.integrate.quad is set to zero (see its optional argument epsabs). It can be changed by using the epsabs keyword argument.

Parameters

return_norm_only

Whether to only return the approximate H2-norm.

mu

Parameter values.

quad_kwargs

Keyword arguments passed to scipy.integrate.quad.

Returns

norm

Computed H2-norm.

norm_relerr

Relative error estimate (returned if return_norm_only is False and presets does not contain 'h2_norm').

info

Quadrature info (returned if return_norm_only is False and full_output is True and presets does not contain 'h2_norm'). See scipy.integrate.quad documentation for more details.

mag_plot(w, mu=None, ax=None, ord=None, Hz=False, dB=False, adaptive_opts=None, **mpl_kwargs)

Draw the magnitude plot.

Parameters

w

If len(w) == 2, the left and right limits used for the adaptive sampling. Otherwise, a sequence of angular frequencies at which to compute the transfer function.

mu

Parameter values for which to evaluate the transfer function.

ax

Axis to which to plot. If not given, matplotlib.pyplot.gca is used.

ord

The order of the norm used to compute the magnitude (the default is the Frobenius norm).

Hz

Should the frequency be in Hz on the plot.

dB

Should the magnitude be in dB on the plot.

adaptive_opts

Optional arguments for adaptive (ignored if len(w) != 2).

mpl_kwargs

Keyword arguments used in the matplotlib plot function.

Returns

out

List of matplotlib artists added.