Add sgnsqr external function f(X) = sgn(x)*x^2

[eslickj]

Fixes None

Summary/Motivation:

This adds a signed square function to the contributed external function demonstration.

Here is an example of where this can be useful.

Say you have a pressure-flow relationship that says the mass flow is proportional to the square root of pressure drop, where pa is inlet pressure and pb is outlet pressure. Like this: mdot^2 = k(pb - pa).

The direction of flow is forward if the pressure drop is positive or backward if the pressure drop is negative. There are both positive and negative solutions to the equation. If we use the proposed sgnsqr function, there is now only one solution to the equation, and the sign of flow matches the sign of pressure drop.

The sign squared function is still smooth and replacing square with sgnsqr still gives us solutions to the original equation. It just limits us to one correct solution instead of two possibilities. I expect there could be many situations where it would be useful to limit the solutions of y = x^2 to a single solution.

Changes proposed in this PR:

• add sgnsqr external function to the ampl_external_demo library.

Legal Acknowledgement

By contributing to this software project, I have read the contribution guide and agree to the following terms and conditions for my contribution:

1. I agree my contributions are submitted under the BSD license.
2. I represent I am authorized to make the contributions and grant the license. If my employer has rights to intellectual property that includes these contributions, I represent that I have received permission to make contributions and grant the required license on behalf of that employer.

[jsiirola]

Overall, I don't see a huge problem with supporting a library of useful external functions; however, some concerns with this implementation:

• the ampl_function_demo module is really meant to be lightweight documentation for how to write and build AMPL external functions that are compatible with the Pyomo build system. I think if we are going to start supporting "real" external functions, then that should be in a separate module.
• this implementation is in C1 but not in C2. That could cause some solvers (e.g., ipopt) that assume continuous second derivatives to have trouble. @carldlaird should weigh in here.
• If we decide to go down the path of creating a library of "useful" external functions, we should consider including others (e.g., Add sinc(x) function #323).
• I think the package would need appropriate user documentation (at the very least to include caveats so that users understand the limitations of the function implementations).

[eslickj]

@jsiirola, I agree that if we decide that there are useful external functions we should add a new library. I was thinking that but then decided to see if I could get away with a short cut. The fact that the function isn't second order smooth is bothersome, but then again so is getting a solution with the wrong sign. I'm still not sure if this is a good idea or not. I know we could also do things with bounds and constraints, but I do a fair number of straight forward square simulations where bounds and constraints are harder to manage.

[rschwarz]

I have a general question about this functionality: Would this even work with IPOPT currently, which is using the NL interface (via files) to communicate the problem?

[jsiirola]

I have a general question about this functionality: Would this even work with IPOPT currently, which is using the NL interface (via files) to communicate the problem?

Yes. In fact, that is it's primary use case. It should also work with any other local nonlinear solver that accepts NL file inputs.

[rschwarz]

Thanks, I was unaware of the possibility and we have that same expression in our models, actually.

[jsiirola]

@eslickj, we discussed this at yesterday's dev call. The consensus was that we should move this to a separate contrib package. The package could host multiple ASL external libraries, and this should go into one that explicitly calls out that it is not a function in C2. We did not pick a name (although several were tossed around, like c1_functions or numerically_questionable_functions).

[eslickj]

@jsiirola. thanks. I'll close this and open a new PR soon.