Added: support for custom economic constraints `gE` in `NonLinMPC`

[franckgaga]

trafficstars

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 88.18182% with 26 lines in your changes missing coverage. Please review.

Project coverage is 98.28%. Comparing base (1a451a9) to head (58191fd).

Files with missing lines	Patch %	Lines
src/controller/nonlinmpc.jl	81.15%	26 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #118      +/-   ##
==========================================
- Coverage   98.93%   98.28%   -0.66%     
==========================================
  Files          24       24              
  Lines        3575     3664      +89     
==========================================
+ Hits         3537     3601      +64     
- Misses         38       63      +25     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[baggepinnen]

just a little note, I've never really come across the term "economic constraints" before, is this from some particular book on nonlinear MPC? I use nonlinear MPC with nonlinear constraints very often, but it almost never have an economic interpretation. Would it perhaps be more generic to call them "nonlinear constraints"? I'm thinking that someone who want's to add safety constraints such as collision avoidance will not find what they are looking for, not knowing to look for "economic constraints".

[franckgaga]

That's a good point. I named them economic constraints merely for consistency with my current notation. The nonlinear constraint function will not receive $\mathbf{U}$, $\mathbf{\hat{Y}}$ and $\mathbf{\hat{D}}$ but the slightly longer version appended with the $E$ subscript:

It is also incidently consistent with the custom objective term $J_E$.

Would it perhaps be more generic to call them "nonlinear constraints"?

It would not be precise enough since there is also the plant output and the terminal bounds that are also nonlinear (if the plant model is nonlinear). It's not a replacement of the nonlinear constraints but an addition to the current nonlinear constraints. Maybe just naming them "custom nonlinear constraints" would be sufficient. I would also change my notation to:

J_E(\mathbf{U_e, \hat{Y}_e, \hat{D}_e, p}) \quad \text{and} \quad \mathbf{g_c}(\mathbf{U_e, \hat{Y}_e, \hat{D}_e, p, \epsilon})

with the new notation $\mathbf{U_e} = \mathbf{U}_E$, $\mathbf{\hat{Y}_e} = \mathbf{\hat{Y}}_E$ and $\mathbf{\hat{D}_e} = \mathbf{\hat{D}}_E$ (and the "e" stands for "extended in lenght").

While we are at it, do you think that it's a bad idea to name the custom objective term the economic term? (but renaming it and changing the notation would be a breaking change since they are keyword arguments.)

edit : I changed a little bit my new notation to harmonize the mathematical notation to the code (the asterisk is not allowed in Julia's variable names)

[baggepinnen]

While we are at it, do you think that it's a bad idea to name the custom objective term the economic term?

Not necessarily bad, but I'd imagine that many aren't familiar with the term.

but renaming it and changing the notation would be a breaking change since they are keyword arguments.

One way of changing stuff like this in a non-breaking way is to introduce the new keyword, keep the old, and then do something like

function fun(; new = default, old = nothing)
    new = something(old, new)
end

the function something returns the first argument that is not nothing. If the old keyword is removed from the docs, no one will use it in the future, but existing usage will continue to work.

[franckgaga]

@baggepinnen there is no test at all for now so it's very experimental. I'll implement this soon. 🙂

But for now, do you have any comments about the documentation ? (see NonLinMPC in the dev doc)

[franckgaga]

One problem I see is how it's easy to forget to assign the nc keyword argument in combination with the custom nonlinear constraint function. I'm thinking of calling the JE and the gc function at least once in the NonLinMPC constructor and emit some warnings to guide the user a little bit.

Just calling sim! on NonLinModel is a quick way to troubleshoot bugs in the f and h functions. There is no such thing for the JE and gc args right now...