scipy.signal.

abcd_normalize#

scipy.signal.abcd_normalize(A=None, B=None, C=None, D=None)[source]#

Check state-space matrices compatibility and ensure they are 2d arrays.

First, the input matrices are converted into two-dimensional arrays with appropriate dtype as needed. Then the dimensions n, q, p are determined by investigating the array shapes. If an input is None, or has size zero, it is set to an array of zeros of compatible shape. Finally, it is verified that all parameter shapes are compatible with each other. If that fails, a ValueError is raised. Note that the dimensions n, q, p are allowed to be zero.

Parameters:

Aarray_like, optional: Two-dimensional array of shape (n, n).
Barray_like, optional: Two-dimensional array of shape (n, p).
Carray_like, optional: Two-dimensional array of shape (q, n).
Darray_like, optional: Two-dimensional array of shape (q, p).

Returns:

A, B, C, Darray: State-space matrices as two-dimensional arrays with identical dtype. The result dtype is determined based on the standard dtype promotion rules except for when the inputs are all of integer dtype, in which case the returned arrays will have the default floating point dtype of float64.

Raises:

ValueError: If the dimensions n, q, or p could not be determined or if the shapes are incompatible with each other.

See also

StateSpace: Linear Time Invariant system in state-space form.
dlti: Discrete-time linear time invariant system base class.
tf2ss: Transfer function to state-space representation.
ss2tf: State-space to transfer function.
ss2zpk: State-space representation to zero-pole-gain representation.
cont2discrete: Transform a continuous to a discrete state-space system.

Notes

If a matrix is not modified, the original matrix (not a copy) is returned.

The State-space system representation section of the SciPy User Guide presents the corresponding definitions of continuous-time and disrcete time state space systems.

Array API Standard Support

abcd_normalize has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable SCIPY_ARRAY_API=1 and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported.

Library	CPU	GPU
NumPy	✅	n/a
CuPy	n/a	✅
PyTorch	✅	✅
JAX	✅	✅
Dask	✅	n/a

The result dtype when all array inputs are of integer dtype is the backend’s current default floating point dtype.

See Support for the array API standard for more information.

Examples

The following example demonstrates that the passed lists are converted into two-dimensional arrays:

>>> from scipy.signal import abcd_normalize
>>> AA, BB, CC, DD = abcd_normalize(A=[[1, 2], [3, 4]], B=[[-1], [5]],
...                                 C=[[4, 5]], D=2.5)
>>> AA.shape, BB.shape, CC.shape, DD.shape
((2, 2), (2, 1), (1, 2), (1, 1))

In the following, the missing parameter C is assumed to be an array of zeros with shape (1, 2):

>>> from scipy.signal import abcd_normalize
>>> AA, BB, CC, DD = abcd_normalize(A=[[1, 2], [3, 4]], B=[[-1], [5]], D=2.5)
>>> AA.shape, BB.shape, CC.shape, DD.shape
((2, 2), (2, 1), (1, 2), (1, 1))
>>> CC
array([[0., 0.]])