From 70e8d2c045e9db04832f453f38e4e255babe7f88 Mon Sep 17 00:00:00 2001 From: odow Date: Tue, 7 Nov 2023 12:08:31 +1300 Subject: [PATCH] [docs] add start_value guidance for HermitianPSDCone variables --- docs/src/manual/complex.md | 67 +++++++++++++++++++++++++++++++++++++- 1 file changed, 66 insertions(+), 1 deletion(-) diff --git a/docs/src/manual/complex.md b/docs/src/manual/complex.md index 0cec4378d7f..a99d29577d4 100644 --- a/docs/src/manual/complex.md +++ b/docs/src/manual/complex.md @@ -67,7 +67,7 @@ julia> x = @variable(model, set = ComplexPlane()) _[1] + _[2] im ``` -## Complex-valued variable bounds +## Complex-valued variable and start values bounds Because complex-valued variables lack a total ordering, the definition of a variable bound for a complex-valued variable is ambiguous. If you pass a real- @@ -108,6 +108,26 @@ julia> start_value.(vars) 4.0 ``` +You can modify the bounds and start values by passing `imag(x)` or `real(x)` to +the appropriate function: + +```jldoctest complex_variables +julia> set_lower_bound(imag(x), 2) + +julia> lower_bound(imag(x)) +2.0 + +julia> delete_upper_bound(real(x)) + +julia> has_upper_bound(real(x)) +false + +julia> set_start_value(imag(x), 3) + +julia> start_value(imag(x)) +3.0 +``` + ## Complex-valued equality constraints JuMP reformulates complex-valued equality constraints into two real-valued @@ -251,6 +271,51 @@ julia> typeof(H[2, 1]) GenericAffExpr{ComplexF64, VariableRef} ``` +### Start values + +When setting the start value, you must be careful to set only the upper triangle +of real variables, and the upper triangle excluding the diagonal of imaginary +variables: +```jldoctest hermitian_psd_cone +julia> import LinearAlgebra + +julia> function set_hermitian_start( + H::LinearAlgebra.Hermitian, + start::LinearAlgebra.Hermitian, + ) + for j in 1:size(H, 2), i in 1:j + set_start_value(real(H[i, j]), real(start[i, j])) + if i < j + set_start_value(imag(H[i, j]), imag(start[i, j])) + end + end + return + end +set_hermitian_start (generic function with 1 method) + +julia> H0 = LinearAlgebra.Hermitian( + [1 (2+3im) (5+6im); (2-3im) 4 (7+8im); (5-6im) (7-8im) 9], + ) +3×3 LinearAlgebra.Hermitian{Complex{Int64}, Matrix{Complex{Int64}}}: + 1+0im 2+3im 5+6im + 2-3im 4+0im 7+8im + 5-6im 7-8im 9+0im + +julia> set_hermitian_start(H, H0) + +julia> start_value.(all_variables(model)) +9-element Vector{Float64}: + 1.0 + 2.0 + 4.0 + 5.0 + 7.0 + 9.0 + 3.0 + 6.0 + 8.0 +``` + ## Hermitian PSD constraints The [`HermitianPSDCone`](@ref) can also be used in the [`@constraint`](@ref)