Add HermitianPSDCone

[blegat]

This PR makes it possible to create Hermitian PSD matrix of variable.

The point of argument is going to be how to handle the keyword arguments of @variable. This PR does the following:

• If binary is true for any entry, throw an error.
• fixed_value, start, lower_bound and upper_bound should correspond to entries of hermitian matrices. We interpret the real (resp. imaginary) part as the corresponding value for the real (resp. imaginary) variable created. IIRC @mlubin was worried that it would be confusing, e.g., that lower_bound = 1 + 2im would be interpreted as a lower bound of 1 for the real part and a lower bound of 2 for the imaginary part. As a related note, @ccoffrin was asking for @constraint(model, x + y * im .<= 1 + 2im) to be interpreted as @constraint(model, x <= 1) and @constraint(model, y <= 2).
• integer means that both the real and imaginary parts are integer. Maybe we should just error here ?

[codecov]

Codecov Report

Base: 97.65% // Head: 97.68% // Increases project coverage by +0.03% 🎉

Coverage data is based on head (55417aa) compared to base (67b92bc).
Patch coverage: 100.00% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3109      +/-   ##
==========================================
+ Coverage   97.65%   97.68%   +0.03%     
==========================================
  Files          33       33              
  Lines        4383     4442      +59     
==========================================
+ Hits         4280     4339      +59     
  Misses        103      103              

Impacted Files	Coverage Δ
src/sd.jl	100.00% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[ccoffrin]

HermitianPSDCone is natural for use in the SDP relaxation of AC-OPF. Shall we test that model?

[blegat]

Is that the model that was tested with ComplexOptInterface ?

[ccoffrin]

Almost, that model was a non-convex QCQP. To make it an SDP you need to lift the voltage variable products into a matrix put PSD on that.

[odow]

Nice enough for now. Users might be a bit confused with the real(H[1, 1]) name. It looks like a function call, not the string name. Potentially real_H[1, 1] and imag_H[1, 1]? Or re_H[1, 1] and im_H[1, 1]?

[blegat]

The advantage with this name is that it corresponds exactly to what you would get by typing real(H[1, 1]). Currently, you can get the value of the function by typing what is printed (unless you use anonymous variables).

[odow]

As discussed on the monthly meeting, we should add a page to the manual in the docs explaining all quirks of the complex support in JuMP.

• Behavior of complex bounds
• How to access real and imaginary parts of H
• Why the naming is what it is
• How to access things like value(lower_bound, H[1, 2]) instead of lower_bound(H[1, 2])

Potentially also deal with complex equality constraints, but that might be a separate PR, or in the AC-OPF case.

[odow]

Probably easiest if we leave the docs for a separate PR.

[odow]

I updated the printing. How's this?

[blegat]

Thanks, that's better

[odow]

The advantage with this name is that it corresponds exactly to what you would get by typing real(H[1, 1])

This is also not quite right, because it returns an affine expression, not the variable.

Moreover

julia> imag(H[1, 2])
0 real(H[1,2]) + imag(H[1,2])

julia> real(H[1, 2])
real(H[1,2]) + 0 imag(H[1,2])

[blegat]

This is also not quite right, because it returns an affine expression, not the variable.

Yes, we could smoothen that path in future PRs

[blegat]

It now throws errors in case the integer option is used as discussed in the jump-dev call. I'll merge tomorrow unless there is any more objection