scipy.signal.

abcd_normalize#

scipy.signal.abcd_normalize(A=None, B=None, C=None, D=None, *, dtype=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).
dtypedtype | None, optional: Cast all matrices to the specified dtype. If set to None (default), their dtypes will be “complex128” if any of the matrices are complex-valued. Otherwise, they will be of the type “float64”.

Added in version 1.18.0: With this new parameter, all return values have identical dtypes. In previous versions the dtype of the input was preserved.

Returns:

A, B, C, Darray: State-space matrices as two-dimensional arrays with identical dtype.

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

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.]])

The following snippet shows the effect of the dtype parameter:

>>> import numpy as np
>>> from scipy.signal import abcd_normalize
>>> A, D = [[1, 2], [3, 4]], 2.5
...
>>> AA, BB, CC, DD = abcd_normalize(A=A, D=D)  # default type casting
>>> print(f" AA: {AA.dtype}, BB: {BB.dtype}\n CC: {CC.dtype}, DD: {DD.dtype}")
 AA: float64, BB: float64
 CC: float64, DD: float64
>>> AA, BB, CC, DD = abcd_normalize(A=A, D=D, dtype=np.float32)  # Explicit dtype
>>> print(f" AA: {AA.dtype}, BB: {BB.dtype}\n CC: {CC.dtype}, DD: {DD.dtype}")
 AA: float32, BB: float32
 CC: float32, DD: float32