add reference gain design pattern to create_statefbk_iosystem #1071

murrayrm · 2024-12-02T06:20:45Z

This PR adds a second design pattern to the create_statefbk_iosystem function, allowing controllers that use a static gain on the reference input instead of the desired state and input. As described in the user documentation:

The ~control.create_statefbk_iosystem function can be used to create an I/O system consisting of a state feedback gain (with optional integral action and gain scheduling) and an estimator. A basic state feedback controller of the form

$u = u_d - K (x - x_\text{d})$

can be created with the command::

ctrl, clsys = ct.create_statefbk_iosystem(sys, K)

where sys is the process dynamics and K is the state feedback gain (e.g., from LQR). The function returns the controller ctrl and the closed loop systems clsys, both as I/O systems. The input to the controller is the vector of desired states $x_\text{d}$, desired inputs $u_\text{d}$, and system states $x$.

The above design pattern is referred to as the "trajectory generation" ('trajgen') pattern, since it assumes that the input to the controller is a feasible trajectory $(x_\text{d}, u_\text{d})$. Alternatively, a controller using the "reference gain" pattern can be created, which implements a state feedback controller of the form

$u = k_\text{f}, r - K x$,

where $r$ is the reference input and $k_\text{f}$ is the feedforward gain (normally chosen so that the steady state output $y_\text{ss}$ will be equal to $r$).

A reference gain controller can be created with the command::
ctrl, clsys = ct.create_statefbk_iosystem(sys, K, kf, feedfwd_pattern='refgain')
The reference gain design pattern is described in more detail in Section 7.2 of FBS2e (Stabilization by State Feedback) and the trajectory generation design pattern is described in Section 8.5 (State Space Controller Design).

In addition, this PR includes some changes that make the error messages for setting up a state space system more informative, but giving the expected size of matrices that do not have the right dimensions. (This could go in a separate PR, but it is here because I got frustrated with the error messages while debugging some examples.)

coveralls · 2024-12-02T06:37:27Z

coverage: 94.737% (+0.02%) from 94.721%
when pulling bb52b70 on murrayrm:create_statefbk-29Nov2024
into 12dda4e on python-control:main.

slivingston · 2024-12-04T20:34:36Z

I will review this today.

slivingston · 2024-12-03T07:33:56Z

control/statefbk.py

-        (proportional and integral) are evaluated using the scheduling
-        variables specified by `gainsched_indices`.
+        Input/output system representing the controller.  For the 'trajgen'
+        design patter (default), this system takes as inputs the desired


Suggested change

design patter (default), this system takes as inputs the desired

design pattern (default), this system takes as inputs the desired

slivingston · 2024-12-03T07:34:07Z

control/statefbk.py

+        state `x_d`, the desired input `u_d`, and either the system state
+        `x` or the estimated state `xhat`.  It outputs the controller
+        action `u` according to the formula `u = u_d - K(x - x_d)`.  For
+        the 'refgain' design patter, the system takes as inputs the


Suggested change

the 'refgain' design patter, the system takes as inputs the

the 'refgain' design pattern, the system takes as inputs the

slivingston · 2024-12-05T01:52:47Z

doc/iosys.rst

+  ctrl, clsys = ct.create_statefbk_iosystem(sys, K, kf, feedfwd_pattern='refgain')
+
+This reference gain design pattern is described in more detail in Section
+7.2 of FBS2e (Stabilization by State Feedback) and the trajectory


I might have missed something, but some readers will not know the reference "FBS2e". One idea is to make FBS2e_ a link to the book website. This can be done with the following changes:

diff --git a/doc/conf.py b/doc/conf.py index 75981d6..a523713 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -285,3 +285,7 @@ import control.flatsys as fs import control.phaseplot as pp ct.reset_defaults() """ + +rst_prolog = """ +.. _FBS2e: https://fbswiki.org/wiki/index.php/Feedback_Systems:_An_Introduction_for_Scientists_and_Engineers +""" diff --git a/doc/iosys.rst b/doc/iosys.rst index e67f4dc..413f4d4 100644 --- a/doc/iosys.rst +++ b/doc/iosys.rst @@ -57,7 +57,7 @@ Example To illustrate the use of the input/output systems module, we create a model for a predator/prey system, following the notation and parameter -values in FBS2e. +values in FBS2e_. We begin by defining the dynamics of the system

Feel free to apply this change to your PR, or I can open another PR that adds this and possibly other docs enhancements.

slivingston · 2024-12-05T02:30:28Z

control/tests/statefbk_test.py

+
+    else:
+        ctrl, clsys = ct.create_statefbk_iosystem(
+            sys, K, Kf, feedfwd_pattern='refgain')


create_statefbk_iosystem() is a big function now with several different ways of being called and a docstring of 180 lines. One design pattern to handle this is changing the function to be internal and then creating user-facing functions that have names implying values of arguments like feedfwd_pattern; e.g., create_statefbk_trajgen(), which is implemented by calling _create_statefbk_iosystem() with feedfwd_pattern='trajgen'. However, this alternative may not help users in practice.

In the scope of this PR, it suffices to ensure that mistakes when calling create_statefbk_iosystem() are caught. To that end, can you add a case for when feedfwd_pattern has an unknown value? E.g.,

Suggested change

sys, K, Kf, feedfwd_pattern='refgain')

sys, K, Kf, feedfwd_pattern='refgain')

with pytest.raises(NotImplementedError, match="unknown pattern"):

ct.create_statefbk_iosystem(sys, K, Kf, feedfwd_pattern='refgai')

Related to the above, there may be existing code that calls create_statefbk_iosystem() with 3 positional arguments, thus giving integral_action without using the keyword. With this PR, that would effectively be a call to create_statefbk_iosystem() with a value to feedfwd_gain but feedfwd_pattern still at its default. I modified the test test_lqr_integral_continuous to demonstrate this case, and the resulting error is

if isinstance(gain, np.ndarray): K = gain if K.shape != (sys_ninputs, estimator.noutputs + nintegrators): > raise ControlArgument( f'control gain must be an array of size {sys_ninputs}' f' x {sys_nstates}' + (f'+{nintegrators}' if nintegrators > 0 else '')) E control.exception.ControlArgument: control gain must be an array of size 2 x 4 control/statefbk.py:831: ControlArgument

It is good that an exception is raised, but users may be confused about the cause.

I think that having feedfwd_gain as the third parameter is intuitive and worth keeping, so I propose that a ControlArgument exception is raised if feedfwd_gain is not None but feedfwd_pattern != 'refgain'.

I've left the single function for now, though I agree this function is getting big and complicated. I'm not sure that splitting it in two simplifies things much, and the current naming matches the create_estimator_iosystem and create_mpc_iosystem naming pattern (and functionality).

I created the exception suggested above + unit test.

slivingston · 2024-12-05T02:38:10Z

control/tests/statefbk_test.py

+    (1, 1), (1, None),
+    (2, np.diag([1, 1])), (2, None),


Suggested change

(1, 1), (1, None),

(2, np.diag([1, 1])), (2, None),

(1, 1),

(1, None),

(2, np.diag([1, 1])),

(2, None),

Easier to read if we have one case (i.e., one assignment of parameters) per line

slivingston self-requested a review December 3, 2024 07:30

slivingston requested changes Dec 5, 2024

View reviewed changes

murrayrm added 4 commits December 6, 2024 14:35

add feedfwd keyword arguments (no functionality yet)

8780bdc

update StateSpace size checks/error messages to be more informative

391d29c

initial implementation, docstrings for refgain pattern

9ed4817

documentation updates

96b7b73

murrayrm force-pushed the create_statefbk-29Nov2024 branch 2 times, most recently from 604a3df to 96b7b73 Compare December 7, 2024 03:06

slivingston self-requested a review December 7, 2024 03:10

addressed @slivingston review comments

bb52b70

slivingston approved these changes Dec 7, 2024

View reviewed changes

murrayrm merged commit d700ad7 into python-control:main Dec 7, 2024
23 checks passed

murrayrm added this to the 0.10.2 milestone Feb 19, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

add reference gain design pattern to create_statefbk_iosystem #1071

add reference gain design pattern to create_statefbk_iosystem #1071

Uh oh!

murrayrm commented Dec 2, 2024 •

edited

Loading

Uh oh!

coveralls commented Dec 2, 2024 •

edited

Loading

Uh oh!

slivingston commented Dec 4, 2024

Uh oh!

slivingston Dec 3, 2024

Uh oh!

slivingston Dec 3, 2024

Uh oh!

slivingston Dec 5, 2024

Uh oh!

slivingston Dec 5, 2024

Uh oh!

slivingston Dec 5, 2024

Uh oh!

murrayrm Dec 7, 2024

Uh oh!

slivingston Dec 5, 2024

Uh oh!

Uh oh!

Uh oh!

	design patter (default), this system takes as inputs the desired
	design pattern (default), this system takes as inputs the desired

	the 'refgain' design patter, the system takes as inputs the
	the 'refgain' design pattern, the system takes as inputs the

add reference gain design pattern to create_statefbk_iosystem #1071

add reference gain design pattern to create_statefbk_iosystem #1071

Uh oh!

Conversation

murrayrm commented Dec 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented Dec 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slivingston commented Dec 4, 2024

Uh oh!

slivingston Dec 3, 2024

Choose a reason for hiding this comment

Uh oh!

slivingston Dec 3, 2024

Choose a reason for hiding this comment

Uh oh!

slivingston Dec 5, 2024

Choose a reason for hiding this comment

Uh oh!

slivingston Dec 5, 2024

Choose a reason for hiding this comment

Uh oh!

slivingston Dec 5, 2024

Choose a reason for hiding this comment

Uh oh!

murrayrm Dec 7, 2024

Choose a reason for hiding this comment

Uh oh!

slivingston Dec 5, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

murrayrm commented Dec 2, 2024 •

edited

Loading

coveralls commented Dec 2, 2024 •

edited

Loading