add zpk() function

murrayrm · murrayrm · commit 91466d1276a3 · 2022-12-16T21:33:44.000-08:00
diff --git a/control/matlab/__init__.py b/control/matlab/__init__.py
@@ -115,7 +115,7 @@
 
 ==  ==========================  ============================================
 \*  :func:`tf`                  create transfer function (TF) models
-\   zpk                         create zero/pole/gain (ZPK) models.
+\*  :func:`zpk`                 create zero/pole/gain (ZPK) models.
 \*  :func:`ss`                  create state-space (SS) models
 \   dss                         create descriptor state-space models
 \   delayss                     create state-space models with delayed terms
diff --git a/control/tests/kwargs_test.py b/control/tests/kwargs_test.py
@@ -96,6 +96,7 @@ def test_kwarg_search(module, prefix):
      (control.tf, 0, 0, ([1], [1, 1]), {}),
      (control.tf2io, 0, 1, (), {}),
      (control.tf2ss, 0, 1, (), {}),
+     (control.zpk, 0, 0, ([1], [2, 3], 4), {}),
      (control.InputOutputSystem, 0, 0, (),
       {'inputs': 1, 'outputs': 1, 'states': 1}),
      (control.InputOutputSystem.linearize, 1, 0, (0, 0), {}),
@@ -184,6 +185,7 @@ def test_matplotlib_kwargs(function, nsysargs, moreargs, kwargs, mplcleanup):
     'tf2io' : test_unrecognized_kwargs,
     'tf2ss' : test_unrecognized_kwargs,
     'sample_system' : test_unrecognized_kwargs,
+    'zpk': test_unrecognized_kwargs,
     'flatsys.point_to_point':
         flatsys_test.TestFlatSys.test_point_to_point_errors,
     'flatsys.solve_flat_ocp':
diff --git a/control/tests/xferfcn_test.py b/control/tests/xferfcn_test.py
@@ -986,7 +986,7 @@ def test_repr(self, Hargs, ref):
                 np.testing.assert_array_almost_equal(H.num[p][m], H2.num[p][m])
                 np.testing.assert_array_almost_equal(H.den[p][m], H2.den[p][m])
             assert H.dt == H2.dt
-    
+
     def test_sample_named_signals(self):
         sysc = ct.TransferFunction(1.1, (1, 2), inputs='u', outputs='y')
 
@@ -1073,3 +1073,41 @@ def test_xferfcn_ndarray_precedence(op, tf, arr):
     # Apply the operator to the array and transfer function
     result = op(arr, tf)
     assert isinstance(result, ct.TransferFunction)
+
+
+@pytest.mark.parametrize(
+    "zeros, poles, gain, args, kwargs", [
+        ([], [-1], 1, [], {}),
+        ([1, 2], [-1, -2, -3], 5, [], {}),
+        ([1, 2], [-1, -2, -3], 5, [], {'name': "sys"}),
+        ([1, 2], [-1, -2, -3], 5, [], {'inputs': ["in"], 'outputs': ["out"]}),
+        ([1, 2], [-1, -2, -3], 5, [0.1], {}),
+        (np.array([1, 2]), np.array([-1, -2, -3]), 5, [], {}),
+])
+def test_zpk(zeros, poles, gain, args, kwargs):
+    # Create the transfer function
+    sys = ct.zpk(zeros, poles, gain, *args, **kwargs)
+
+    # Make sure the poles and zeros match
+    np.testing.assert_equal(sys.zeros().sort(), zeros.sort())
+    np.testing.assert_equal(sys.poles().sort(), poles.sort())
+
+    # Check to make sure the gain is OK
+    np.testing.assert_almost_equal(
+        gain, sys(0) * np.prod(-sys.poles()) / np.prod(-sys.zeros()))
+
+    # Check time base
+    if args:
+        assert sys.dt == args[0]
+
+    # Check inputs, outputs, name
+    input_labels = kwargs.get('inputs', [])
+    for i, label in enumerate(input_labels):
+        assert sys.input_labels[i] == label
+
+    output_labels = kwargs.get('outputs', [])
+    for i, label in enumerate(output_labels):
+        assert sys.output_labels[i] == label
+
+    if kwargs.get('name'):
+        assert sys.name == kwargs.get('name')
diff --git a/control/xferfcn.py b/control/xferfcn.py
@@ -65,7 +65,7 @@
 from .frdata import FrequencyResponseData
 from . import config
 
-__all__ = ['TransferFunction', 'tf', 'ss2tf', 'tfdata']
+__all__ = ['TransferFunction', 'tf', 'zpk', 'ss2tf', 'tfdata']
 
 
 # Define module default parameter values
@@ -796,7 +796,7 @@ def zeros(self):
         """Compute the zeros of a transfer function."""
         if self.ninputs > 1 or self.noutputs > 1:
             raise NotImplementedError(
-                "TransferFunction.zero is currently only implemented "
+                "TransferFunction.zeros is currently only implemented "
                 "for SISO systems.")
         else:
             # for now, just give zeros of a SISO tf
@@ -1577,8 +1577,55 @@ def tf(*args, **kwargs):
     else:
         raise ValueError("Needs 1 or 2 arguments; received %i." % len(args))
 
+
+def zpk(zeros, poles, gain, *args, **kwargs):
+    """zpk(zeros, poles, gain[, dt])
+
+    Create a transfer function from zeros, poles, gain.
+
+    Given a list of zeros z_i, poles p_j, and gain k, return the transfer
+    function:
+
+    .. math::
+      H(s) = k \\frac{(s - z_1) (s - z_2) \\cdots (s - z_m)}
+                     {(s - p_1) (s - p_2) \\cdots (s - p_n)}
+
+    Parameters
+    ----------
+    zeros : array_like
+        Array containing the location of zeros.
+    poles : array_like
+        Array containing the location of zeros.
+    gain : float
+        System gain
+    dt : None, True or float, optional
+        System timebase. 0 (default) indicates continuous
+        time, True indicates discrete time with unspecified sampling
+        time, positive number is discrete time with specified
+        sampling time, None indicates unspecified timebase (either
+        continuous or discrete time).
+    inputs, outputs, states : str, or list of str, optional
+        List of strings that name the individual signals.  If this parameter
+        is not given or given as `None`, the signal names will be of the
+        form `s[i]` (where `s` is one of `u`, `y`, or `x`). See
+        :class:`InputOutputSystem` for more information.
+    name : string, optional
+        System name (used for specifying signals). If unspecified, a generic
+        name <sys[id]> is generated with a unique integer id.
+
+    Returns
+    -------
+    out: :class:`TransferFunction`
+        Transfer function with given zeros, poles, and gain.
+
+    """
+    num, den = zpk2tf(zeros, poles, gain)
+    return TransferFunction(num, den, *args, **kwargs)
+
+
 # TODO: copy signal names
 def ss2tf(*args, **kwargs):
+
     """ss2tf(sys)
 
     Transform a state space system to a transfer function.
diff --git a/doc/control.rst b/doc/control.rst
@@ -18,6 +18,7 @@ System creation
     ss
     tf
     frd
+    zpk
     rss
     drss
     NonlinearIOSystem

-Original file line number
+Diff line change
     ss
     tf
     frd
 +    zpk
     rss
     drss
     NonlinearIOSystem