From 3ea08a58b19372a49d0943eed8a4b49e97e9ab6c Mon Sep 17 00:00:00 2001 From: Tim Holy Date: Sun, 25 Oct 2026 09:18:36 -0500 Subject: [PATCH 1/4] =?UTF-8?q?Rename=20internal=20uses=20of=20=CF=81=20an?= =?UTF-8?q?d=20=CF=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Give the row reference log-scales (logref), the estimated plain Sinkhorn rate (μ2), the LSQR rotation diagonal (rdiag, rdiagbar), and the preconditioner ridge (ridge) descriptive names. Write the PowerMean penalty in the log slack as ρ (_powermean_ρ) and the augmented- Lagrangian per-entry term as ℓ. Assisted-by: Claude Opus 5.5 --- src/dense_heuristic.jl | 25 +++++++++--------- src/heuristic_covers.jl | 58 ++++++++++++++++++++--------------------- src/minimal_covers.jl | 34 ++++++++++++------------ src/powermean.jl | 20 +++++++------- src/powermean_newton.jl | 2 +- 5 files changed, 70 insertions(+), 69 deletions(-) diff --git a/src/dense_heuristic.jl b/src/dense_heuristic.jl index cc18242..1628d3b 100644 --- a/src/dense_heuristic.jl +++ b/src/dense_heuristic.jl @@ -36,21 +36,22 @@ function _tri_logabs!(Lp::Vector{T}, A::AbstractMatrix) where {T} return Lp end -# Row sums of the diagonally normalized log magnitudes `Lp[i,j] - ρ[i] - ρ[j]` -# and the row support counts; see `_sym_unconstrained!`. -function _tri_normsums!(s::Vector{T}, cnt::Vector{Int}, Lp::Vector{T}, ρ::Vector{T}, n::Int) where {T} +# Row sums of the diagonally normalized log magnitudes +# `Lp[i,j] - logref[i] - logref[j]` and the row support counts; see +# `_sym_unconstrained!`. +function _tri_normsums!(s::Vector{T}, cnt::Vector{Int}, Lp::Vector{T}, logref::Vector{T}, n::Int) where {T} fill!(s, zero(T)) fill!(cnt, 0) ninf = T(-Inf) for jp in 1:n o = _trioff(jp) - rj = ρ[jp] + rj = logref[jp] sj = zero(T) cj = 0 for ip in 1:jp-1 l = Lp[o+ip] if l != ninf - l -= ρ[ip] + rj + l -= logref[ip] + rj s[ip] += l cnt[ip] += 1 sj += l @@ -125,13 +126,13 @@ function _symcover_dense!(a::AbstractVector, A::AbstractMatrix, ::Type{T}, maxit cnt = Vector{Int}(undef, n) _tri_logabs!(Lp, A) # Covariant reference from the diagonal; see `_sym_reference!`. - ρ = Vector{T}(undef, n) + logref = Vector{T}(undef, n) for jp in 1:n l = Lp[_trioff(jp)+jp] - ρ[jp] = ifelse(l == T(-Inf), T(NaN), l / 2) + logref[jp] = ifelse(l == T(-Inf), T(NaN), l / 2) end - _tri_normsums!(α, cnt, Lp, ρ, n) # `α` carries the row log sums here - nmissing = count(ip -> cnt[ip] > 0 && isnan(ρ[ip]), 1:n) + _tri_normsums!(α, cnt, Lp, logref, n) # `α` carries the row log sums here + nmissing = count(ip -> cnt[ip] > 0 && isnan(logref[ip]), 1:n) if nmissing > 0 # Rare path: some supported row has a zero diagonal entry. function foreach_entries(f) @@ -143,14 +144,14 @@ function _symcover_dense!(a::AbstractVector, A::AbstractMatrix, ::Type{T}, maxit end end end - _sym_reference!(ρ, foreach_entries, nmissing) - _tri_normsums!(α, cnt, Lp, ρ, n) + _sym_reference!(logref, foreach_entries, nmissing) + _tri_normsums!(α, cnt, Lp, logref, n) end # Unsupported rows may keep NaN references; `_uncon_scale` never reads them. nztotal = sum(cnt) halfmu = iszero(nztotal) ? zero(T) : sum(α) / (2 * nztotal) for ip in 1:n - α[ip] = _uncon_scale(α[ip], cnt[ip], halfmu, ρ[ip]) + α[ip] = _uncon_scale(α[ip], cnt[ip], halfmu, logref[ip]) lα[ip] = log(α[ip]) end diff --git a/src/heuristic_covers.jl b/src/heuristic_covers.jl index 0f4dcfb..7b638a0 100644 --- a/src/heuristic_covers.jl +++ b/src/heuristic_covers.jl @@ -402,67 +402,67 @@ end # ∑_{i,j: A[i,j]≠0} (log(a[i]*a[j]) - log|A[i,j]|)² # is stationary where (diag(n) + S) α = 𝔞, with `n` the row support counts, `S` # the support indicator, and 𝔞 the row sums of log|A_ij|. The start is one -# Jacobi-type sweep of that system, α = diag(n)⁻¹(𝔞 - S ρ) + c e, from the -# reference point ρ of `_sym_reference!`, with the constant `c` fixed by the -# balance nᵀα = eᵀ𝔞/2 that every exact solution satisfies. Equivalently, it is -# the per-row geometric mean of the diagonally normalized entries -# |A_ij| / sqrt(|A_ii A_jj|), scaled back by sqrt|A_ii|. On complete support the -# sweep is exact (Sherman–Morrison), and because ρ co-varies with `A`, the -# start is exactly scale-covariant on any support whose components each hold a -# nonzero diagonal entry. +# Jacobi-type sweep of that system, α = diag(n)⁻¹(𝔞 - S·logref) + c e, from +# the reference log-scales `logref` of `_sym_reference!`, with the constant `c` +# fixed by the balance nᵀα = eᵀ𝔞/2 that every exact solution satisfies. +# Equivalently, it is the per-row geometric mean of the diagonally normalized +# entries |A_ij| / sqrt(|A_ii A_jj|), scaled back by sqrt|A_ii|. On complete +# support the sweep is exact (Sherman–Morrison), and because `logref` +# co-varies with `A`, the start is exactly scale-covariant on any support whose +# components each hold a nonzero diagonal entry. # # Returns the row support counts. function _sym_unconstrained!(a::AbstractVector{T}, foreach_entries::F) where {T,F} ax = eachindex(a) nza = zeros(Int, ax) - ρ = fill!(similar(a, T), T(NaN)) # NaN marks a row without a reference + logref = fill!(similar(a, T), T(NaN)) # NaN marks a row without a reference foreach_entries() do i, j, lv nza[i] += 1 if i == j - ρ[i] = lv / 2 + logref[i] = lv / 2 else nza[j] += 1 end end - nmissing = count(i -> !iszero(nza[i]) && isnan(ρ[i]), ax) - _sym_reference!(ρ, foreach_entries, nmissing) + nmissing = count(i -> !iszero(nza[i]) && isnan(logref[i]), ax) + _sym_reference!(logref, foreach_entries, nmissing) loga = fill!(similar(a, T), zero(T)) foreach_entries() do i, j, lv - l = lv - ρ[i] - ρ[j] + l = lv - logref[i] - logref[j] loga[i] += l i == j || (loga[j] += l) end nztotal = sum(nza) halfmu = iszero(nztotal) ? zero(T) : sum(loga) / (2 * nztotal) for i in ax - a[i] = _uncon_scale(loga[i], nza[i], halfmu, ρ[i]) + a[i] = _uncon_scale(loga[i], nza[i], halfmu, logref[i]) end return nza end # Keep supported scales positive when `exp` underflows. -_uncon_scale(si::T, ni::Int, halfmu::T, ρi::T) where {T} = - iszero(ni) ? zero(T) : max(exp(si / ni - halfmu + ρi), floatmin(T)) +_uncon_scale(si::T, ni::Int, halfmu::T, logrefi::T) where {T} = + iszero(ni) ? zero(T) : max(exp(si / ni - halfmu + logrefi), floatmin(T)) # Covariant reference log-scales. The caller is expected to initialize -# {log|A_ii|/2 if A_ii ≠ 0 -# ρ[i] = { -# {NaN otherwise +# {log|A_ii|/2 if A_ii ≠ 0 +# logref[i] = { +# {NaN otherwise # `nmissing` counts supported rows (those with some A_ij ≠ 0) for which # A_ii == 0. # # A breadth-first search from all rows with a nonzero diagonal entry assigns -# every other reachable row the mean of `log|A_ik| - ρ[k]` over its neighbors +# every other reachable row the mean of `log|A_ik| - logref[k]` over its neighbors # `k` in the preceding layer, so the reference spreads outward by graph distance # from the diagonal. The cost is proportional to the number of entries. # # Rows in components with no nonzero diagonal entry never receive a reference # and are set to zero, on which the start is not covariant. -function _sym_reference!(ρ::AbstractVector{T}, foreach_entries::F, nmissing::Int) where {T,F} +function _sym_reference!(logref::AbstractVector{T}, foreach_entries::F, nmissing::Int) where {T,F} if nmissing > 0 # Adjacency lists of the off-diagonal support, by position. - o = first(eachindex(ρ)) - 1 - n = length(ρ) + o = first(eachindex(logref)) - 1 + n = length(logref) deg = zeros(Int, n) foreach_entries() do i, j, lv i == j && return @@ -489,7 +489,7 @@ function _sym_reference!(ρ::AbstractVector{T}, foreach_entries::F, nmissing::In queue = Vector{Int}(undef, n) qend = 0 for p in 1:n - if !isnan(ρ[p+o]) + if !isnan(logref[p+o]) dist[p] = 0 qend += 1 queue[qend] = p @@ -506,11 +506,11 @@ function _sym_reference!(ρ::AbstractVector{T}, foreach_entries::F, nmissing::In for s in ptr[v]:ptr[v+1]-1 u = nbr[s] if dist[u] == dist[v] - 1 - tot += nlv[s] - ρ[u+o] + tot += nlv[s] - logref[u+o] cnt += 1 end end - ρ[v+o] = tot / cnt + logref[v+o] = tot / cnt end for s in ptr[v]:ptr[v+1]-1 u = nbr[s] @@ -522,10 +522,10 @@ function _sym_reference!(ρ::AbstractVector{T}, foreach_entries::F, nmissing::In end end end - for i in eachindex(ρ) - isnan(ρ[i]) && (ρ[i] = zero(T)) + for i in eachindex(logref) + isnan(logref[i]) && (logref[i] = zero(T)) end - return ρ + return logref end function unconstrained_min!(::AbsLog{2}, a::AbstractVector{T}, A::AbstractMatrix) where T diff --git a/src/minimal_covers.jl b/src/minimal_covers.jl index 945cae9..7020624 100644 --- a/src/minimal_covers.jl +++ b/src/minimal_covers.jl @@ -445,7 +445,7 @@ function _lsqr(Amul!, Atmul!, b::AbstractVector{T}, x0::AbstractVector{T}; tmpm = similar(u) tmpn = similar(v) ϕbar = β - ρbar = α + rdiagbar = α anorm2 = α^2 # Frobenius norm² of the lower bidiagonal ≈ ‖M‖² (iszero(β) || iszero(α)) && return x, 0 # x0 already optimal iters = 0 @@ -462,16 +462,16 @@ function _lsqr(Amul!, Atmul!, b::AbstractVector{T}, x0::AbstractVector{T}; α > 0 && (v ./= α) anorm2 += β^2 + α^2 # Orthogonal transformation applied to the bidiagonal system. - ρ = hypot(ρbar, β) - iszero(ρ) && break - c = ρbar / ρ - s = β / ρ + rdiag = hypot(rdiagbar, β) + iszero(rdiag) && break + c = rdiagbar / rdiag + s = β / rdiag θ = s * α - ρbar = -c * α + rdiagbar = -c * α ϕ = c * ϕbar ϕbar = s * ϕbar - @. x += (ϕ / ρ) * w - @. w = v - (θ / ρ) * w + @. x += (ϕ / rdiag) * w + @. w = v - (θ / rdiag) * w # Stop when the normal-equations residual is negligible relative to ‖M‖‖r‖, # or when the least-squares residual itself has vanished (consistent system). arnorm = ϕbar * α * abs(c) @@ -532,13 +532,13 @@ SupportSystem{T}(N, supp::S, args...) where {T,S} = SupportSystem{T,S}(N, supp, # # Per-entry augmented-Lagrangian term with multiplier λ ≥ 0 and penalty weight κ: # -# ψ(z) = z² for z ≥ b, -# ψ(z) = κ(z − s)² + s·b for z < b, +# ℓ(z) = z² for z ≥ b, +# ℓ(z) = κ(z − s)² + s·b for z < b, # # where `s = λ/(2κ)` and `b = λ/(2(κ-1))`. The omitted constant is independent # of `z`. Precomputed scales keep the branch test identical across sweeps. -# Objective `f(x) = Σ_e mult_e·ψ_e(z_e)`. +# Objective `f(x) = Σ_e mult_e·ℓ_e(z_e)`. function _fal(x, κ, λ, sscale, bscale, supp::EdgeList{T}, symmetric::Bool) where {T} edges, cvals, qs = supp.edges, supp.cvals, supp.qsign κT = T(κ) @@ -1275,9 +1275,9 @@ function _precond_pattern(::Type{T}, supp::EdgeList, v0, N::Int, mult) where {T} Mv[p] += v0[p]^2 dmax = max(dmax, Mv[p]) end - ρ = _precond_ridge(dmax) + ridge = _precond_ridge(dmax) for p in 1:N - push!(I, p); push!(J, p); push!(V, Mv[p] + ρ) + push!(I, p); push!(J, p); push!(V, Mv[p] + ridge) end # `sparse` sums duplicates and keeps any that cancel as stored zeros, so the # pattern holds every pair of unknowns that some entry joins. @@ -1683,9 +1683,9 @@ function _abslog2_auglag(sys::SupportSystem{T}, x0; mdiag[p] += v0[p]^2 dmax = max(dmax, mdiag[p]) end - ρ = _precond_ridge(dmax) + ridge = _precond_ridge(dmax) for p in 1:N - nzv[dpos[p]] = mdiag[p] + ρ + nzv[dpos[p]] = mdiag[p] + ridge end factorize!(MF, Msp) nrefactor[] += 1 @@ -1743,9 +1743,9 @@ function _abslog2_auglag(sys::SupportSystem{T}, x0; mdiag[p] += v0[p]^2 dmax = max(dmax, mdiag[p]) end - ρ = _precond_ridge(dmax) + ridge = _precond_ridge(dmax) keep = max_weight_forest(N, hI, hJ, hW) - HF[] = tree_cholesky(N, hI[keep], hJ[keep], hV[keep], mdiag .+ ρ) + HF[] = tree_cholesky(N, hI[keep], hJ[keep], hV[keep], mdiag .+ ridge) nrefactor[] += 1 prevκ[] = κl copyto!(prevpat, vpat) diff --git a/src/powermean.jl b/src/powermean.jl index aa2090c..32329d7 100644 --- a/src/powermean.jl +++ b/src/powermean.jl @@ -286,10 +286,10 @@ function _powermean_target(S::GroupedSupport{T}, sl, y, p::T) where {T} end # The objective restricted to one group scale `x`, with its partners fixed, is -# `n * ψ(x - F) + const`, where `F` is the group's target and -# `ψ(z) = (exp(-p z) - 1 + p z) / p`. This gives the exact change of the objective +# `n * ρ(x - F) + const`, where `F` is the group's target and +# `ρ(z) = (exp(-p z) - 1 + p z) / p`. This gives the exact change of the objective # under a relaxed step. -_powermean_ψ(p, z) = (expm1(-p * z) + p * z) / p +_powermean_ρ(p, z) = (expm1(-p * z) + p * z) / p # Largest `|∑ R^p / n - 1|` over the groups of `S`, the scale-invariant imbalance # of the balance conditions `∑_j R[i,j]^p = n_i`. @@ -322,10 +322,10 @@ function _powermean_halfsweep!(x, y, S::GroupedSupport{T}, p::T, ω::T) where {T imb = max(imb, abs(expm1(-p * δ))) xg = F if ω != 1 - ψδ = _powermean_ψ(p, δ) + ρδ = _powermean_ρ(p, δ) w = ω for _ in 0:POWERMEAN_NBACKTRACK - if _powermean_ψ(p, (1 - w) * δ) <= (1 + (w - 1)^2) / 2 * ψδ + if _powermean_ρ(p, (1 - w) * δ) <= (1 + (w - 1)^2) / 2 * ρδ xg = F + (1 - w) * δ break end @@ -399,13 +399,13 @@ function _powermean_sinkhorn!(α, β, R::GroupedSupport{T}, C::GroupedSupport{T} if ω == 1 nplain += 1 if nplain >= POWERMEAN_NESTIMATE - ρ, ρprev = sqrt(r / r2), sqrt(r1 / r3) - if zero(T) < ρ < one(T) && zero(T) < ρprev < one(T) && - log(ρ) >= POWERMEAN_STEADY * log(ρprev) - ωopt = min(ωmax, 2 / (1 + sqrt(1 - ρ))) + μ2, μ2prev = sqrt(r / r2), sqrt(r1 / r3) + if zero(T) < μ2 < one(T) && zero(T) < μ2prev < one(T) && + log(μ2) >= POWERMEAN_STEADY * log(μ2prev) + ωopt = min(ωmax, 2 / (1 + sqrt(1 - μ2))) ω = min(ωopt, T(POWERMEAN_OMEGA_START)) rprev, rwin, nwin, nstall = r, T(Inf), 0, 0 - _powermean_nsweeps(r, tol, _sor_rate(ρ, ωopt)) > budget && break + _powermean_nsweeps(r, tol, _sor_rate(μ2, ωopt)) > budget && break end end r3, r2, r1 = r2, r1, r diff --git a/src/powermean_newton.jl b/src/powermean_newton.jl index fb37b66..45e7996 100644 --- a/src/powermean_newton.jl +++ b/src/powermean_newton.jl @@ -4,7 +4,7 @@ # symmetric: one scale per row), the objective has one term per stored entry `e` # joining unknowns `u[e] <= v[e]`: # -# E(x) = ∑_e mult[e] * ψ(x[u] + x[v] - L[e]), ψ(z) = (exp(-p z) - 1 + p z)/p, +# E(x) = ∑_e mult[e] * ρ(x[u] + x[v] - L[e]), ρ(z) = (exp(-p z) - 1 + p z)/p, # # with `L = log|A|`. An asymmetric entry has multiplicity one. A symmetric # off-diagonal pair is stored once with multiplicity two and a diagonal entry once From 9e3011eb142f25c76ce0dec7f5b018ccfd081f10 Mon Sep 17 00:00:00 2001 From: Tim Holy Date: Sun, 25 Oct 2026 09:25:08 -0500 Subject: [PATCH 2/4] =?UTF-8?q?Name=20the=20penalty=20argument=20=CF=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use ρ for the penalty argument and for the penalty in docstrings and comments across src/, ext/, and test/. The LSQR iteration keeps its own ϕ and ϕbar, which are unrelated to the penalty. Assisted-by: Claude Opus 5.5 --- ext/MatrixCoversIpoptExt.jl | 2 +- ext/MatrixCoversUnitfulExt.jl | 88 +++++++-------- src/balanced.jl | 18 +-- src/heuristic_covers.jl | 34 +++--- src/minimal_covers.jl | 36 +++--- src/penalties.jl | 40 +++---- src/powermean.jl | 26 ++--- src/soft_covers.jl | 36 +++--- src/sparse_support.jl | 24 ++-- src/transversal.jl | 2 +- test/element_types.jl | 4 +- test/extensions.jl | 202 +++++++++++++++++----------------- test/helpers.jl | 20 ++-- test/heuristic_covers.jl | 34 +++--- test/maxbalance.jl | 2 +- test/minimal_covers.jl | 4 +- test/penalties.jl | 22 ++-- test/powermean.jl | 10 +- test/soft_covers.jl | 86 +++++++-------- test/storage_types.jl | 18 +-- test/unitful.jl | 48 ++++---- 21 files changed, 378 insertions(+), 378 deletions(-) diff --git a/ext/MatrixCoversIpoptExt.jl b/ext/MatrixCoversIpoptExt.jl index c5f6882..8e961da 100644 --- a/ext/MatrixCoversIpoptExt.jl +++ b/ext/MatrixCoversIpoptExt.jl @@ -350,7 +350,7 @@ end # ============================================================ # Soft cover: soft_cover!(::AbsLinear{p}, a, b, A) # Asymmetric soft-cover model. Post-processing balances component gauges; zero -# entries contribute the constant `ϕ(0) = 1`. +# entries contribute the constant `ρ(0) = 1`. # ============================================================ function MatrixCovers.soft_cover!(::AbsLinear{2}, a::AbstractVector, b::AbstractVector, A) diff --git a/ext/MatrixCoversUnitfulExt.jl b/ext/MatrixCoversUnitfulExt.jl index 09dff7e..e36cecf 100644 --- a/ext/MatrixCoversUnitfulExt.jl +++ b/ext/MatrixCoversUnitfulExt.jl @@ -197,47 +197,47 @@ symsplit(x::AbstractVector) = (x, ()) symsplit(r::Tuple) = (first(r), Base.tail(r)) asymsplit(r::Tuple) = (r[1], r[2], Base.tail(Base.tail(r))) -function sym(f, A::QMatrix, ϕ...; kwargs...) - a, rest = symsplit(f(ϕ..., strip_matrix(A); kwargs...)) +function sym(f, A::QMatrix, ρ...; kwargs...) + a, rest = symsplit(f(ρ..., strip_matrix(A); kwargs...)) return isempty(rest) ? reattach(a, factor_units_sym(A)) : (reattach(a, factor_units_sym(A)), rest...) end -function asym(f, A::QMatrix, ϕ...; kwargs...) +function asym(f, A::QMatrix, ρ...; kwargs...) ua, ub = factor_units(A) - a, b, rest = asymsplit(f(ϕ..., strip_matrix(A); kwargs...)) + a, b, rest = asymsplit(f(ρ..., strip_matrix(A); kwargs...)) return (reattach(a, ua), reattach(b, ub), rest...) end # Allocating scratch from `A` permits uninitialized destination vectors. -function sym!(f, a::QVector, A::QMatrix, ϕ...; kwargs...) +function sym!(f, a::QVector, A::QMatrix, ρ...; kwargs...) ua = factor_units_sym(A) An = strip_matrix(A) - x, rest = symsplit(f(ϕ..., similar(a, float(real(eltype(An)))), An; kwargs...)) + x, rest = symsplit(f(ρ..., similar(a, float(real(eltype(An)))), An; kwargs...)) a .= reattach(x, ua) return isempty(rest) ? a : (a, rest...) end -function asym!(f, a::QVector, b::QVector, A::QMatrix, ϕ...; kwargs...) +function asym!(f, a::QVector, b::QVector, A::QMatrix, ρ...; kwargs...) ua, ub = factor_units(A) An = strip_matrix(A) T = float(real(eltype(An))) - x, y, rest = asymsplit(f(ϕ..., similar(a, T), similar(b, T), An; kwargs...)) + x, y, rest = asymsplit(f(ρ..., similar(a, T), similar(b, T), An; kwargs...)) a .= reattach(x, ua) b .= reattach(y, ub) return (a, b, rest...) end # `a` is a start, and is read. -function symstart!(f, a::QVector, A::QMatrix, ϕ...; kwargs...) +function symstart!(f, a::QVector, A::QMatrix, ρ...; kwargs...) ua = factor_units_sym(A) - x, rest = symsplit(f(ϕ..., strip_start(a, ua), strip_matrix(A); kwargs...)) + x, rest = symsplit(f(ρ..., strip_start(a, ua), strip_matrix(A); kwargs...)) a .= reattach(x, ua) return isempty(rest) ? a : (a, rest...) end -function asymstart!(f, a::QVector, b::QVector, A::QMatrix, ϕ...; kwargs...) +function asymstart!(f, a::QVector, b::QVector, A::QMatrix, ρ...; kwargs...) ua, ub = factor_units(A) - x, y, rest = asymsplit(f(ϕ..., strip_start(a, ua), strip_start(b, ub), strip_matrix(A); kwargs...)) + x, y, rest = asymsplit(f(ρ..., strip_start(a, ua), strip_start(b, ub), strip_matrix(A); kwargs...)) a .= reattach(x, ua) b .= reattach(y, ub) return (a, b, rest...) @@ -246,16 +246,16 @@ end # Mirror the core penalty dispatch while specializing on unitful matrices. const PENALTIES = (:(AbsLog{1}), :(AbsLog{2}), :(AbsLinear{1}), :(AbsLinear{2})) -# Heuristic covers and initializers: `ϕ` is checked but not consulted. +# Heuristic covers and initializers: `ρ` is checked but not consulted. MC.symcover(A::QMatrix; kwargs...) = sym(MC.symcover, A; kwargs...) -MC.symcover(ϕ::MC.AbstractCoverPenalty, A::QMatrix; kwargs...) = sym(MC.symcover, A, ϕ; kwargs...) +MC.symcover(ρ::MC.AbstractCoverPenalty, A::QMatrix; kwargs...) = sym(MC.symcover, A, ρ; kwargs...) MC.symcover!(a::QVector, A::QMatrix; kwargs...) = sym!(MC.symcover!, a, A; kwargs...) -MC.symcover!(ϕ::MC.AbstractCoverPenalty, a::QVector, A::QMatrix; kwargs...) = sym!(MC.symcover!, a, A, ϕ; kwargs...) +MC.symcover!(ρ::MC.AbstractCoverPenalty, a::QVector, A::QMatrix; kwargs...) = sym!(MC.symcover!, a, A, ρ; kwargs...) MC.cover(A::QMatrix; kwargs...) = asym(MC.cover, A; kwargs...) -MC.cover(ϕ::MC.AbstractCoverPenalty, A::QMatrix; kwargs...) = asym(MC.cover, A, ϕ; kwargs...) +MC.cover(ρ::MC.AbstractCoverPenalty, A::QMatrix; kwargs...) = asym(MC.cover, A, ρ; kwargs...) MC.cover!(a::QVector, b::QVector, A::QMatrix; kwargs...) = asym!(MC.cover!, a, b, A; kwargs...) -MC.cover!(ϕ::MC.AbstractCoverPenalty, a::QVector, b::QVector, A::QMatrix; kwargs...) = asym!(MC.cover!, a, b, A, ϕ; kwargs...) +MC.cover!(ρ::MC.AbstractCoverPenalty, a::QVector, b::QVector, A::QMatrix; kwargs...) = asym!(MC.cover!, a, b, A, ρ; kwargs...) # Core `cover`/`cover!` methods dispatch on `Adjoint`/`Transpose` without an eltype # bound, so a wrapped `Quantity` matrix needs these to stay unambiguous. @@ -289,46 +289,46 @@ const QSparseSym = Union{QSparse, Symmetric{<:Quantity,<:SparseMatrixCSC}, Hermitian{<:Quantity,<:SparseMatrixCSC}} -MC.symcover_min(ϕ::AbsLog{2}, A::QSparseSym; kwargs...) = - sym(MC.symcover_min, A, ϕ; kwargs...) +MC.symcover_min(ρ::AbsLog{2}, A::QSparseSym; kwargs...) = + sym(MC.symcover_min, A, ρ; kwargs...) -MC.cover_min(ϕ::AbsLog{2}, A::QSparse; kwargs...) = - asym(MC.cover_min, A, ϕ; kwargs...) +MC.cover_min(ρ::AbsLog{2}, A::QSparse; kwargs...) = + asym(MC.cover_min, A, ρ; kwargs...) MC.cover_transversal(A::QSparse; kwargs...) = asym(MC.cover_transversal, A; kwargs...) -MC.soft_symcover(ϕ::AbsLog{2}, A::QSparseSym; kwargs...) = - sym(MC.soft_symcover, A, ϕ; kwargs...) +MC.soft_symcover(ρ::AbsLog{2}, A::QSparseSym; kwargs...) = + sym(MC.soft_symcover, A, ρ; kwargs...) -MC.soft_cover(ϕ::AbsLog{2}, A::QSparse; kwargs...) = - asym(MC.soft_cover, A, ϕ; kwargs...) +MC.soft_cover(ρ::AbsLog{2}, A::QSparse; kwargs...) = + asym(MC.soft_cover, A, ρ; kwargs...) -MC.symcover_min!(ϕ::AbsLog{2}, a::QVector, A::QSparseSym; kwargs...) = - symstart!(MC.symcover_min!, a, A, ϕ; kwargs...) +MC.symcover_min!(ρ::AbsLog{2}, a::QVector, A::QSparseSym; kwargs...) = + symstart!(MC.symcover_min!, a, A, ρ; kwargs...) -MC.cover_min!(ϕ::AbsLog{2}, a::QVector, b::QVector, A::QSparse; kwargs...) = - asymstart!(MC.cover_min!, a, b, A, ϕ; kwargs...) +MC.cover_min!(ρ::AbsLog{2}, a::QVector, b::QVector, A::QSparse; kwargs...) = + asymstart!(MC.cover_min!, a, b, A, ρ; kwargs...) for P in PENALTIES @eval begin - MC.soft_symcover(ϕ::$P, A::QMatrix; kwargs...) = sym(MC.soft_symcover, A, ϕ; kwargs...) - MC.soft_symcover!(ϕ::$P, a::QVector, A::QMatrix; kwargs...) = symstart!(MC.soft_symcover!, a, A, ϕ; kwargs...) - MC.soft_cover(ϕ::$P, A::QMatrix; kwargs...) = asym(MC.soft_cover, A, ϕ; kwargs...) - MC.soft_cover!(ϕ::$P, a::QVector, b::QVector, A::QMatrix; kwargs...) = asymstart!(MC.soft_cover!, a, b, A, ϕ; kwargs...) - - MC.symcover_min(ϕ::$P, A::QMatrix; kwargs...) = sym(MC.symcover_min, A, ϕ; kwargs...) - MC.symcover_min!(ϕ::$P, a::QVector, A::QMatrix; kwargs...) = symstart!(MC.symcover_min!, a, A, ϕ; kwargs...) - MC.cover_min(ϕ::$P, A::QMatrix; kwargs...) = asym(MC.cover_min, A, ϕ; kwargs...) - MC.cover_min!(ϕ::$P, a::QVector, b::QVector, A::QMatrix; kwargs...) = asymstart!(MC.cover_min!, a, b, A, ϕ; kwargs...) + MC.soft_symcover(ρ::$P, A::QMatrix; kwargs...) = sym(MC.soft_symcover, A, ρ; kwargs...) + MC.soft_symcover!(ρ::$P, a::QVector, A::QMatrix; kwargs...) = symstart!(MC.soft_symcover!, a, A, ρ; kwargs...) + MC.soft_cover(ρ::$P, A::QMatrix; kwargs...) = asym(MC.soft_cover, A, ρ; kwargs...) + MC.soft_cover!(ρ::$P, a::QVector, b::QVector, A::QMatrix; kwargs...) = asymstart!(MC.soft_cover!, a, b, A, ρ; kwargs...) + + MC.symcover_min(ρ::$P, A::QMatrix; kwargs...) = sym(MC.symcover_min, A, ρ; kwargs...) + MC.symcover_min!(ρ::$P, a::QVector, A::QMatrix; kwargs...) = symstart!(MC.symcover_min!, a, A, ρ; kwargs...) + MC.cover_min(ρ::$P, A::QMatrix; kwargs...) = asym(MC.cover_min, A, ρ; kwargs...) + MC.cover_min!(ρ::$P, a::QVector, b::QVector, A::QMatrix; kwargs...) = asymstart!(MC.cover_min!, a, b, A, ρ; kwargs...) end end # `PowerMean` is parametric in its exponent. -MC.cover_transversal(ϕ::PowerMean, A::QMatrix; kwargs...) = asym(MC.cover_transversal, A, ϕ; kwargs...) -MC.cover_transversal!(ϕ::PowerMean, a::QVector, b::QVector, A::QMatrix; kwargs...) = asym!(MC.cover_transversal!, a, b, A, ϕ; kwargs...) -MC.soft_symcover(ϕ::PowerMean, A::QMatrix; kwargs...) = sym(MC.soft_symcover, A, ϕ; kwargs...) -MC.soft_symcover!(ϕ::PowerMean, a::QVector, A::QMatrix; kwargs...) = symstart!(MC.soft_symcover!, a, A, ϕ; kwargs...) -MC.soft_cover(ϕ::PowerMean, A::QMatrix; kwargs...) = asym(MC.soft_cover, A, ϕ; kwargs...) -MC.soft_cover!(ϕ::PowerMean, a::QVector, b::QVector, A::QMatrix; kwargs...) = asymstart!(MC.soft_cover!, a, b, A, ϕ; kwargs...) +MC.cover_transversal(ρ::PowerMean, A::QMatrix; kwargs...) = asym(MC.cover_transversal, A, ρ; kwargs...) +MC.cover_transversal!(ρ::PowerMean, a::QVector, b::QVector, A::QMatrix; kwargs...) = asym!(MC.cover_transversal!, a, b, A, ρ; kwargs...) +MC.soft_symcover(ρ::PowerMean, A::QMatrix; kwargs...) = sym(MC.soft_symcover, A, ρ; kwargs...) +MC.soft_symcover!(ρ::PowerMean, a::QVector, A::QMatrix; kwargs...) = symstart!(MC.soft_symcover!, a, A, ρ; kwargs...) +MC.soft_cover(ρ::PowerMean, A::QMatrix; kwargs...) = asym(MC.soft_cover, A, ρ; kwargs...) +MC.soft_cover!(ρ::PowerMean, a::QVector, b::QVector, A::QMatrix; kwargs...) = asymstart!(MC.soft_cover!, a, b, A, ρ; kwargs...) end # module MatrixCoversUnitfulExt diff --git a/src/balanced.jl b/src/balanced.jl index 5f33beb..d3aed69 100644 --- a/src/balanced.jl +++ b/src/balanced.jl @@ -28,7 +28,7 @@ const BALANCED_NRIDGE = 4 const BALANCED_RIDGE_GROWTH = 1e4 """ - a, b, stats = cover_transversal(ϕ::PowerMean{p}, A; target=1e-2, maxbalance=false, tol=1e-9, maxiter, fillbudget, flopbudget) + a, b, stats = cover_transversal(ρ::PowerMean{p}, A; target=1e-2, maxbalance=false, tol=1e-9, maxiter, fillbudget, flopbudget) Return the hard cover of the square matrix `A` that is tight on its maximum-product transversals and pushes the coverage ratios @@ -39,8 +39,8 @@ minimizes the sum taken over the nonzero entries off the transversals, among the hard covers with `prod(a) * prod(b) == π*` (see [`cover_transversal(A)`](@ref -cover_transversal)). Each term is `target^p * φ(r/target)` up to a constant, with -`φ` the [`PowerMean{p}`](@ref) penalty, so it is least at `r = target`; the hard +cover_transversal)). Each term is `target^p * ρ(r/target)` up to a constant, with +`ρ` the [`PowerMean{p}`](@ref) penalty, so it is least at `r = target`; the hard constraint caps every ratio at one, and the transversal entries have ratio one. `0 < target <= 1` and `0 < p < ∞` are required; otherwise an `ArgumentError` is thrown. `cover_transversal(AbsLog{2}(), A)` is `cover_transversal(A)`. @@ -69,7 +69,7 @@ largest ratio of an entry leading from `K` to `I`. This determines the products `a[i]*b[j]` within each block uniquely. When `σ` is the only maximum-product transversal, the largest ratio within a block equals the block's `θ`, the largest geometric-mean ratio of a cycle of entries off `σ`, which is the least -largest ratio that any cover tight on `σ` can have there. `ϕ` and `target` fix +largest ratio that any cover tight on `σ` can have there. `ρ` and `target` fix the scales between blocks: they minimize the objective above summed over the entries joining different blocks, with each block's scales moving together. At the minimizer, for every set of blocks that the entries joining it to the other @@ -136,7 +136,7 @@ afterwards. See also: [`cover_transversal!`](@ref), [`PowerMean`](@ref). """ -function cover_transversal(ϕ::PowerMean{p}, A::AbstractMatrix; target::Real=1e-2, +function cover_transversal(ρ::PowerMean{p}, A::AbstractMatrix; target::Real=1e-2, maxbalance::Bool=false, tol::Real=BALANCED_TOL, maxiter::Union{Integer,Nothing}=nothing, fillbudget::Real=LSQR_FILL_BUDGET, @@ -148,16 +148,16 @@ end cover_transversal(::AbsLog{2}, A::AbstractMatrix; kwargs...) = cover_transversal(A; kwargs...) """ - a, b, stats = cover_transversal!(ϕ::PowerMean, a, b, A; kwargs...) + a, b, stats = cover_transversal!(ρ::PowerMean, a, b, A; kwargs...) -Mutating counterpart of [`cover_transversal(ϕ, A)`](@ref cover_transversal): +Mutating counterpart of [`cover_transversal(ρ, A)`](@ref cover_transversal): writes the cover into `a` and `b` and returns them with the solver's statistics. The initial contents of `a` and `b` are ignored. `eachindex(a)` must match `axes(A, 1)` and `eachindex(b)` must match `axes(A, 2)`. """ -function cover_transversal!(ϕ::PowerMean, a::AbstractVector, b::AbstractVector, A::AbstractMatrix; kwargs...) +function cover_transversal!(ρ::PowerMean, a::AbstractVector, b::AbstractVector, A::AbstractMatrix; kwargs...) _check_cover_axes(a, b, A) - anew, bnew, stats = cover_transversal(ϕ, A; kwargs...) + anew, bnew, stats = cover_transversal(ρ, A; kwargs...) a .= anew b .= bnew return a, b, stats diff --git a/src/heuristic_covers.jl b/src/heuristic_covers.jl index 7b638a0..71c3207 100644 --- a/src/heuristic_covers.jl +++ b/src/heuristic_covers.jl @@ -6,12 +6,12 @@ # ============================================================ """ - a = symcover(ϕ, A; maxiter=3) + a = symcover(ρ, A; maxiter=3) a = symcover(A; maxiter=3) Return a vector `a` whose outer product `a*a'` is a hard cover of the square, symmetric matrix `A`: `a[i] * a[j] >= abs(A[i, j])` for all `i`, `j`. This is a -fast heuristic; for the cover that minimizes a penalty `ϕ`, use +fast heuristic; for the cover that minimizes a penalty `ρ`, use [`symcover_min`](@ref). The heuristic starts from the per-row geometric means of the diagonally @@ -19,7 +19,7 @@ normalized entries `abs(A[i, j]) / sqrt(abs(A[i, i] * A[j, j]))`, rescaled by `sqrt(abs(A[i, i]))`. It then raises the scales until every entry is covered and applies `maxiter` tightening iterations. -`ϕ` is accepted for API compatibility but is ignored. +`ρ` is accepted for API compatibility but is ignored. See also: [`symcover!`](@ref), [`symcover_min`](@ref), [`soft_symcover`](@ref), [`cover`](@ref). @@ -51,7 +51,7 @@ logarithms of the entries. The result is also permutation-equivariant up to floating-point round-off: covering `A[p, p]` for a permutation `p` gives `a[p]`. """ -symcover(ϕ::AbstractCoverPenalty, A::AbstractMatrix; kwargs...) = symcover(A; kwargs...) +symcover(ρ::AbstractCoverPenalty, A::AbstractMatrix; kwargs...) = symcover(A; kwargs...) function symcover(A::AbstractMatrix; kwargs...) axes(A, 2) == axes(A, 1) || throw(ArgumentError("symcover requires a square matrix")) @@ -61,17 +61,17 @@ function symcover(A::AbstractMatrix; kwargs...) end """ - a = symcover!(ϕ, a, A; maxiter=3) + a = symcover!(ρ, a, A; maxiter=3) a = symcover!(a, A; maxiter=3) Mutating counterpart of [`symcover`](@ref): writes the symmetric hard cover into `a` and returns it, rather than allocating a new vector. `eachindex(a)` -must match `axes(A, 1)` (and `A` must be square). `ϕ` has the same meaning as in +must match `axes(A, 1)` (and `A` must be square). `ρ` has the same meaning as in [`symcover`](@ref), and is likewise ignored by the current heuristic covers. See also: [`symcover`](@ref). """ -symcover!(ϕ::AbstractCoverPenalty, a::AbstractVector, A::AbstractMatrix; kwargs...) = symcover!(a, A; kwargs...) +symcover!(ρ::AbstractCoverPenalty, a::AbstractVector, A::AbstractMatrix; kwargs...) = symcover!(a, A; kwargs...) function symcover!(a::AbstractVector, A::AbstractMatrix; kwargs...) ax = axes(A, 1) @@ -96,12 +96,12 @@ function _symcover!(a::AbstractVector, A::AbstractMatrix; maxiter::Int=3) end """ - a, b = cover(ϕ, A; maxiter, cgiter, start=:auto) + a, b = cover(ρ, A; maxiter, cgiter, start=:auto) a, b = cover(A; maxiter, cgiter, start=:auto) Given a matrix `A`, return vectors `a` and `b` such that `a[i] * b[j] >= abs(A[i, j])` for all `i`, `j`. This is a fast heuristic; for the cover that -minimizes a penalty `ϕ`, use [`cover_min`](@ref). +minimizes a penalty `ρ`, use [`cover_min`](@ref). The heuristic refines a starting point with up to `cgiter` conjugate-gradient iterations (`cgiter=0` disables refinement), raises the scales until every @@ -123,7 +123,7 @@ entry is covered, and then applies `maxiter` improvement passes. structurally nonsingular, and `:unconstrained` otherwise. The factors use the per-component balance convention described by -[`cover_min`](@ref). `ϕ` is accepted for API compatibility but is ignored. +[`cover_min`](@ref). `ρ` is accepted for API compatibility but is ignored. See also: [`cover!`](@ref), [`cover_transversal`](@ref), [`cover_min`](@ref), [`symcover`](@ref). @@ -181,7 +181,7 @@ which stop earlier once the residual is at roundoff. With `start=:geomean` the cover is permutation-equivariant up to floating-point round-off: covering `A[p, q]` for permutations `p`, `q` gives `a[p]` and `b[q]`. """ -cover(ϕ::AbstractCoverPenalty, A::AbstractMatrix; kwargs...) = cover(A; kwargs...) +cover(ρ::AbstractCoverPenalty, A::AbstractMatrix; kwargs...) = cover(A; kwargs...) function cover(A::AbstractMatrix; kwargs...) T = float(real(eltype(A))) @@ -201,18 +201,18 @@ function cover(A::Transpose; kwargs...) end """ - a, b = cover!(ϕ, a, b, A; maxiter, cgiter, start=:auto) + a, b = cover!(ρ, a, b, A; maxiter, cgiter, start=:auto) a, b = cover!(a, b, A; maxiter, cgiter, start=:auto) Mutating counterpart of [`cover`](@ref): writes the hard cover into `a` and `b` and returns them, rather than allocating new vectors. `eachindex(a)` must -match `axes(A, 1)` and `eachindex(b)` must match `axes(A, 2)`. `ϕ` has the same +match `axes(A, 1)` and `eachindex(b)` must match `axes(A, 2)`. `ρ` has the same meaning as in [`cover`](@ref), and is likewise ignored by the current heuristic covers. See also: [`cover`](@ref). """ -cover!(ϕ::AbstractCoverPenalty, a::AbstractVector, b::AbstractVector, A::AbstractMatrix; kwargs...) = +cover!(ρ::AbstractCoverPenalty, a::AbstractVector, b::AbstractVector, A::AbstractMatrix; kwargs...) = cover!(a, b, A; kwargs...) function cover!(a::AbstractVector, b::AbstractVector, A::AbstractMatrix; kwargs...) @@ -530,7 +530,7 @@ end function unconstrained_min!(::AbsLog{2}, a::AbstractVector{T}, A::AbstractMatrix) where T ax = eachindex(a) - axes(A) == (ax, ax) || throw(DimensionMismatch("`unconstrained_min!(ϕ, a, A)` requires a square matrix with matching axes to `a` (got axes(A)=$(string(axes(A))), axes(a)=$(string(axes(a)))")) + axes(A) == (ax, ax) || throw(DimensionMismatch("`unconstrained_min!(ρ, a, A)` requires a square matrix with matching axes to `a` (got axes(A)=$(string(axes(A))), axes(a)=$(string(axes(a)))")) foreach_entries(f) = foreach_support_sym((i, j, v) -> f(i, j, log(T(v))), A) return _sym_unconstrained!(a, foreach_entries) end @@ -549,8 +549,8 @@ end function unconstrained_min!(::AbsLog{2}, a::AbstractVector, b::AbstractVector, A::AbstractMatrix) T = float(promote_type(eltype(a), eltype(b))) - axes(A, 1) == eachindex(a) || throw(DimensionMismatch("`unconstrained_min!(ϕ, a, b, A)` requires row indices of `A` to match `a`, got axes(A, 1)=$(string(axes(A, 1))), axes(a)=$(string(axes(a)))")) - axes(A, 2) == eachindex(b) || throw(DimensionMismatch("`unconstrained_min!(ϕ, a, b, A)` requires column indices of `A` to match `b`, got axes(A, 2)=$(string(axes(A, 2))), axes(b)=$(string(axes(b)))")) + axes(A, 1) == eachindex(a) || throw(DimensionMismatch("`unconstrained_min!(ρ, a, b, A)` requires row indices of `A` to match `a`, got axes(A, 1)=$(string(axes(A, 1))), axes(a)=$(string(axes(a)))")) + axes(A, 2) == eachindex(b) || throw(DimensionMismatch("`unconstrained_min!(ρ, a, b, A)` requires column indices of `A` to match `b`, got axes(A, 2)=$(string(axes(A, 2))), axes(b)=$(string(axes(b)))")) loga = fill!(similar(a, T), zero(T)) logb = fill!(similar(b, T), zero(T)) nza = zeros(Int, axes(A, 1)) diff --git a/src/minimal_covers.jl b/src/minimal_covers.jl index 7020624..6dd6533 100644 --- a/src/minimal_covers.jl +++ b/src/minimal_covers.jl @@ -6,14 +6,14 @@ # ============================================================ """ - a, stats = symcover_min(ϕ, A; kwargs...) + a, stats = symcover_min(ρ, A; kwargs...) a, stats = symcover_min(A; kwargs...) -Return the ϕ-minimal symmetric hard cover of `A`: the vector `a` minimizing -`∑ ϕ(|A[i,j]|/(a[i]*a[j]))` subject to `a[i]*a[j] >= |A[i,j]|`. The +Return the ρ-minimal symmetric hard cover of `A`: the vector `a` minimizing +`∑ ρ(|A[i,j]|/(a[i]*a[j]))` subject to `a[i]*a[j] >= |A[i,j]|`. The default penalty is `AbsLog{2}()`. -Supported ϕ values: +Supported ρ values: - `AbsLog{2}()`: native. - `AbsLog{1}()`: requires JuMP and HiGHS. - `AbsLinear{1}()` and `AbsLinear{2}()`: require JuMP and Ipopt and return the @@ -91,11 +91,11 @@ function symcover_min end symcover_min(A::AbstractMatrix; kwargs...) = symcover_min(AbsLog{2}(), A; kwargs...) """ - a, b, stats = cover_min(ϕ, A; kwargs...) + a, b, stats = cover_min(ρ, A; kwargs...) a, b, stats = cover_min(A; kwargs...) -Return the ϕ-minimal asymmetric hard cover of `A`: vectors `a`, `b` minimizing -`∑ ϕ(|A[i,j]|/(a[i]*b[j]))` subject to `a[i]*b[j] >= |A[i,j]|`. The +Return the ρ-minimal asymmetric hard cover of `A`: vectors `a`, `b` minimizing +`∑ ρ(|A[i,j]|/(a[i]*b[j]))` subject to `a[i]*b[j] >= |A[i,j]|`. The default penalty is `AbsLog{2}()`. The objective and the constraints depend only on the products `a[i]*b[j]`, @@ -115,7 +115,7 @@ distant rows or columns, such as `norm(a)`, inherit the spread. the floating-point range throw an error; converting `A` to `BigFloat` extends the range. -Supported ϕ values, `stats`, and the failure behavior are as for +Supported ρ values, `stats`, and the failure behavior are as for [`symcover_min`](@ref): - `AbsLog{2}()`: native. - `AbsLog{1}()`: requires JuMP and HiGHS. @@ -154,10 +154,10 @@ function cover_min end cover_min(A::AbstractMatrix; kwargs...) = cover_min(AbsLog{2}(), A; kwargs...) """ - a, stats = symcover_min!(ϕ, a, A; kwargs...) + a, stats = symcover_min!(ρ, a, A; kwargs...) a, stats = symcover_min!(a, A; kwargs...) -Refine the symmetric hard cover `a` in place. The no-ϕ form uses `AbsLog{2}()`; +Refine the symmetric hard cover `a` in place. The no-ρ form uses `AbsLog{2}()`; supported penalties, keywords, `stats`, and failure behavior match [`symcover_min`](@ref). @@ -176,12 +176,12 @@ symcover_min!(a::AbstractVector, A::AbstractMatrix; kwargs...) = symcover_min!(AbsLog{2}(), a, A; kwargs...) """ - a, b, stats = cover_min!(ϕ, a, b, A; kwargs...) + a, b, stats = cover_min!(ρ, a, b, A; kwargs...) a, b, stats = cover_min!(a, b, A; kwargs...) Refine the asymmetric hard cover `(a, b)` in place. The start must cover `A` and be positive on supported rows and columns; unsupported scales are zeroed. The -no-ϕ form uses `AbsLog{2}()`; supported penalties, keywords, `stats`, and +no-ρ form uses `AbsLog{2}()`; supported penalties, keywords, `stats`, and failure behavior match [`cover_min`](@ref). Equivalent starts `(c*a, b/c)` give the same balanced result. @@ -241,7 +241,7 @@ function cover_min!(::AbsLog{2}, a::AbstractVector, b::AbstractVector, A::Abstra end # Multistart drivers for the `AbsLinear` kernels in MatrixCoversIpoptExt. -function symcover_min(ϕ::AbsLinear, A::AbstractMatrix; strategies=SYMCOVER_MIN_STRATEGIES) +function symcover_min(ρ::AbsLinear, A::AbstractMatrix; strategies=SYMCOVER_MIN_STRATEGIES) ax = axes(A, 1) axes(A, 2) == ax || throw(ArgumentError("symcover_min requires a square matrix")) isempty(strategies) && @@ -255,19 +255,19 @@ function symcover_min(ϕ::AbsLinear, A::AbstractMatrix; strategies=SYMCOVER_MIN_ throw(ArgumentError("symcover_min: no strategy in $(string(strategies)) yields a starting cover of `A`")) labels = Symbol[strategy for (strategy, ok) in zip(strategies, built) if ok] covers = starts[built] - stats = [last(symcover_min!(ϕ, a, A))::ExternalSolverStats for a in covers] - objs = [cover_objective(ϕ, a, A) for a in covers] + stats = [last(symcover_min!(ρ, a, A))::ExternalSolverStats for a in covers] + objs = [cover_objective(ρ, a, A) for a in covers] k = _multistart_select(objs) return covers[k], MultistartStats{ExternalSolverStats,eltype(objs)}(labels, stats, objs, k, Symbol[]) end -function cover_min(ϕ::AbsLinear, A::AbstractMatrix; strategies=COVER_MIN_STRATEGIES) +function cover_min(ρ::AbsLinear, A::AbstractMatrix; strategies=COVER_MIN_STRATEGIES) isempty(strategies) && throw(ArgumentError("cover_min: `strategies` must name at least one starting cover")) labels = Symbol[strategy for strategy in strategies] covers = [initialize_cover(A; strategy) for strategy in strategies] - stats = [last(cover_min!(ϕ, a, b, A))::ExternalSolverStats for (a, b) in covers] - objs = [cover_objective(ϕ, a, b, A) for (a, b) in covers] + stats = [last(cover_min!(ρ, a, b, A))::ExternalSolverStats for (a, b) in covers] + objs = [cover_objective(ρ, a, b, A) for (a, b) in covers] k = _multistart_select(objs) a, b = covers[k] return a, b, MultistartStats{ExternalSolverStats,eltype(objs)}(labels, stats, objs, k, Symbol[]) diff --git a/src/penalties.jl b/src/penalties.jl index e084b93..40b1a5b 100644 --- a/src/penalties.jl +++ b/src/penalties.jl @@ -1,5 +1,5 @@ # ============================================================ -# φ types +# ρ types # ============================================================ """ @@ -37,10 +37,10 @@ abstract type AbstractCoverPenalty<:Function end Penalty type for - φ(r) = |log(r)|^p if r > 0 + ρ(r) = |log(r)|^p if r > 0 0 if r = 0 -Defining `φ(0) = 0` makes zero entries of `A`, for which `log(r) = -∞`, +Defining `ρ(0) = 0` makes zero entries of `A`, for which `log(r) = -∞`, contribute nothing to the objective. The objective is convex in the logarithms of the scales; `AbsLog{1}` may have multiple minima. @@ -51,8 +51,8 @@ struct AbsLog{p} <: AbstractCoverPenalty end """ AbsLinear{p} -Penalty type for `φ(r) = |1 - r|^p`. Unlike [`AbsLog`](@ref), this penalty is -continuous at `r = 0`, so each zero entry of `A` contributes `φ(0) = 1` to the +Penalty type for `ρ(r) = |1 - r|^p`. Unlike [`AbsLog`](@ref), this penalty is +continuous at `r = 0`, so each zero entry of `A` contributes `ρ(0) = 1` to the objective. The resulting optimization problems are not convex and may have multiple local @@ -65,10 +65,10 @@ struct AbsLinear{p} <: AbstractCoverPenalty end Penalty type for - φ(r) = (r^p - 1 - p*log(r)) / p if r > 0 + ρ(r) = (r^p - 1 - p*log(r)) / p if r > 0 0 if r = 0 -with `p > 0`. As for [`AbsLog`](@ref), defining `φ(0) = 0` makes zero entries +with `p > 0`. As for [`AbsLog`](@ref), defining `ρ(0) = 0` makes zero entries of `A` contribute nothing. `PowerMean{2}` is the default penalty for soft covers. For entries modeled as @@ -128,28 +128,28 @@ function objective_type(x) end """ - cover_objective(ϕ, a, b, A) - cover_objective(ϕ, a, A) + cover_objective(ρ, a, b, A) + cover_objective(ρ, a, A) -Compute `∑ ϕ(|A[i,j]|/(a[i]*b[j]))`. The shorter form uses the symmetric cover +Compute `∑ ρ(|A[i,j]|/(a[i]*b[j]))`. The shorter form uses the symmetric cover `a*a'`. Both forms sum over every entry of `A`, so in the symmetric form each off-diagonal pair contributes twice and each diagonal entry once. -Zero entries of `A` are handled according to `ϕ`: -- `AbsLog{p}`, `PowerMean{p}`: zero entries contribute 0 (φ(0) = 0 by convention). -- `AbsLinear{p}`: zero entries contribute 1 (φ(0) = |1-0|^p = 1). +Zero entries of `A` are handled according to `ρ`: +- `AbsLog{p}`, `PowerMean{p}`: zero entries contribute 0 (ρ(0) = 0 by convention). +- `AbsLinear{p}`: zero entries contribute 1 (ρ(0) = |1-0|^p = 1). `eachindex(a)` must match `axes(A, 1)` and `eachindex(b)` must match `axes(A, 2)`. The nonzero entries of `A` are enumerated by [`foreach_support`](@ref). See also: -- Penalty types (options for `ϕ`): [`AbsLog`](@ref), [`AbsLinear`](@ref), [`PowerMean`](@ref). +- Penalty types (options for `ρ`): [`AbsLog`](@ref), [`AbsLinear`](@ref), [`PowerMean`](@ref). - Solvers that minimize it: [`symcover_min`](@ref), [`cover_min`](@ref), [`soft_symcover`](@ref), [`soft_cover`](@ref). """ -function cover_objective(ϕ, a, b, A) +function cover_objective(ρ, a, b, A) eachindex(a) == axes(A, 1) || throw(DimensionMismatch("indices of `a` must match row-indexing of `A`, got eachindex(a)=$(string(eachindex(a))), axes(A, 1)=$(string(axes(A, 1)))")) eachindex(b) == axes(A, 2) || @@ -162,7 +162,7 @@ function cover_objective(ϕ, a, b, A) # A nonzero entry over a zero scale is uncovered; `typemax` is the ratio's # stand-in for the infinite excess. r = iszero(ab) ? typemax(T) : T(v / ab) - s[] += T(ϕ(r)) + s[] += T(ρ(r)) nsupport[] += 1 end # Every entry outside the support has `r = 0` whatever its scales, including a @@ -171,10 +171,10 @@ function cover_objective(ϕ, a, b, A) # `PowerMean`, but a nonzero constant for `AbsLinear`, which is continuous at `r = 0`. # The guard prevents `0 * Inf` for penalties that are infinite at zero. nzero = length(a) * length(b) - nsupport[] - return iszero(nzero) ? s[] : s[] + nzero * T(ϕ(zero(T))) + return iszero(nzero) ? s[] : s[] + nzero * T(ρ(zero(T))) end -cover_objective(ϕ, a, A) = cover_objective(ϕ, a, a, A) +cover_objective(ρ, a, A) = cover_objective(ρ, a, a, A) # Adjoint/Transpose dispatch: covering A' or transpose(A) swaps the row/column scales. -cover_objective(ϕ, a, b, A::Adjoint) = cover_objective(ϕ, b, a, parent(A)) -cover_objective(ϕ, a, b, A::Transpose) = cover_objective(ϕ, b, a, parent(A)) +cover_objective(ρ, a, b, A::Adjoint) = cover_objective(ρ, b, a, parent(A)) +cover_objective(ρ, a, b, A::Transpose) = cover_objective(ρ, b, a, parent(A)) diff --git a/src/powermean.jl b/src/powermean.jl index 32329d7..c53f9a9 100644 --- a/src/powermean.jl +++ b/src/powermean.jl @@ -49,28 +49,28 @@ _powermean_type(Ts::Type...) = float(promote_type(Ts..., Float64)) # Public methods # ============================================================ -function soft_cover(ϕ::PowerMean, A::AbstractMatrix; tol::Union{Real,Nothing}=nothing, +function soft_cover(ρ::PowerMean, A::AbstractMatrix; tol::Union{Real,Nothing}=nothing, maxiter::Integer=POWERMEAN_MAXITER, newton::Bool=true, maxnewton::Integer=POWERMEAN_MAXNEWTON, linsolve::Symbol=:auto) - return _soft_cover_powermean(ϕ, A, :soft_cover; tol, maxiter, newton, maxnewton, linsolve) + return _soft_cover_powermean(ρ, A, :soft_cover; tol, maxiter, newton, maxnewton, linsolve) end -function soft_cover!(ϕ::PowerMean, a::AbstractVector, b::AbstractVector, A::AbstractMatrix; +function soft_cover!(ρ::PowerMean, a::AbstractVector, b::AbstractVector, A::AbstractMatrix; tol::Union{Real,Nothing}=nothing, maxiter::Integer=POWERMEAN_MAXITER, newton::Bool=true, maxnewton::Integer=POWERMEAN_MAXNEWTON, linsolve::Symbol=:auto) - return _soft_cover_powermean!(ϕ, a, b, A, :soft_cover!; tol, maxiter, newton, maxnewton, linsolve) + return _soft_cover_powermean!(ρ, a, b, A, :soft_cover!; tol, maxiter, newton, maxnewton, linsolve) end -function soft_symcover(ϕ::PowerMean, A::AbstractMatrix; tol::Union{Real,Nothing}=nothing, +function soft_symcover(ρ::PowerMean, A::AbstractMatrix; tol::Union{Real,Nothing}=nothing, maxiter::Integer=POWERMEAN_MAXITER, newton::Bool=true, maxnewton::Integer=POWERMEAN_MAXNEWTON, linsolve::Symbol=:auto) - return _soft_symcover_powermean(ϕ, A, :soft_symcover; tol, maxiter, newton, maxnewton, linsolve) + return _soft_symcover_powermean(ρ, A, :soft_symcover; tol, maxiter, newton, maxnewton, linsolve) end -function soft_symcover!(ϕ::PowerMean, a::AbstractVector, A::AbstractMatrix; +function soft_symcover!(ρ::PowerMean, a::AbstractVector, A::AbstractMatrix; tol::Union{Real,Nothing}=nothing, maxiter::Integer=POWERMEAN_MAXITER, newton::Bool=true, maxnewton::Integer=POWERMEAN_MAXNEWTON, linsolve::Symbol=:auto) - return _soft_symcover_powermean!(ϕ, a, A, :soft_symcover!; tol, maxiter, newton, maxnewton, linsolve) + return _soft_symcover_powermean!(ρ, a, A, :soft_symcover!; tol, maxiter, newton, maxnewton, linsolve) end # ============================================================ @@ -82,9 +82,9 @@ end # convention selects `b == a`. The test is exact, since a nearly symmetric matrix # has a genuinely asymmetric minimizer. # The `:unconstrained` start makes a truncated iteration scale-covariant as well. -function _soft_cover_powermean(ϕ::PowerMean, A::AbstractMatrix, fname::Symbol; kwargs...) +function _soft_cover_powermean(ρ::PowerMean, A::AbstractMatrix, fname::Symbol; kwargs...) if _abs_symmetric_exact(A) - a, stats = _soft_symcover_powermean(ϕ, A, fname; kwargs...) + a, stats = _soft_symcover_powermean(ρ, A, fname; kwargs...) return a, copy(a), stats end T = float(real(eltype(A))) @@ -92,7 +92,7 @@ function _soft_cover_powermean(ϕ::PowerMean, A::AbstractMatrix, fname::Symbol; b = similar(Array{T}, axes(A, 2)) covariant_start!(a, b, flat_support(A, T); fname) _balance_cover!(a, b, A) - return _soft_cover_powermean!(ϕ, a, b, A, fname; kwargs...) + return _soft_cover_powermean!(ρ, a, b, A, fname; kwargs...) end function _soft_cover_powermean!(::PowerMean{p}, a::AbstractVector, b::AbstractVector, @@ -117,13 +117,13 @@ function _soft_cover_powermean!(::PowerMean{p}, a::AbstractVector, b::AbstractVe return a, b, PowerMeanStats{T}(stats) end -function _soft_symcover_powermean(ϕ::PowerMean, A::AbstractMatrix, fname::Symbol; kwargs...) +function _soft_symcover_powermean(ρ::PowerMean, A::AbstractMatrix, fname::Symbol; kwargs...) ax = axes(A, 1) axes(A, 2) == ax || throw(ArgumentError("$fname requires a square matrix")) # Symmetry is checked by `_soft_symcover_powermean!`; the start is only read there. a = similar(Array{float(real(eltype(A)))}, ax) _initialize_symcover!(a, A, :geomean, :none) - return _soft_symcover_powermean!(ϕ, a, A, fname; kwargs...) + return _soft_symcover_powermean!(ρ, a, A, fname; kwargs...) end function _soft_symcover_powermean!(::PowerMean{p}, a::AbstractVector, A::AbstractMatrix, fname::Symbol; diff --git a/src/soft_covers.jl b/src/soft_covers.jl index fe03c64..ef366fa 100644 --- a/src/soft_covers.jl +++ b/src/soft_covers.jl @@ -5,10 +5,10 @@ # ============================================================ """ - a, stats = soft_symcover(ϕ, A; kwargs...) + a, stats = soft_symcover(ρ, A; kwargs...) a, stats = soft_symcover(A; kwargs...) -Return the scales `a` that minimize `∑ ϕ(|A[i,j]|/(a[i]*a[j]))` for symmetric +Return the scales `a` that minimize `∑ ρ(|A[i,j]|/(a[i]*a[j]))` for symmetric `A`. Unlike a hard cover, this soft cover penalizes violations of `a[i]*a[j] >= |A[i,j]|` rather than forbidding them. The default penalty is `PowerMean{2}()`. @@ -108,20 +108,20 @@ function soft_symcover(::AbsLog{2}, A::AbstractMatrix; linsolve::Symbol=:auto, end # Sole owner of the starts/σ/rng defaults for the symmetric `AbsLinear` multistart. -function soft_symcover(ϕ::AbsLinear, A::AbstractMatrix; starts::Int=5, +function soft_symcover(ρ::AbsLinear, A::AbstractMatrix; starts::Int=5, σ::Union{Real,Nothing}=nothing, sigma::Union{Real,Nothing}=nothing, rng::AbstractRNG=MersenneTwister(_MULTISTART_SEED)) ax = axes(A, 1) axes(A, 2) == ax || throw(ArgumentError("soft_symcover requires a square matrix")) require_abs_symmetric(A, :soft_symcover) - return _soft_symcover_abslinear(ϕ, A, starts, _resolve_alias(σ, sigma, 2.0, :σ, :sigma), rng) + return _soft_symcover_abslinear(ρ, A, starts, _resolve_alias(σ, sigma, 2.0, :σ, :sigma), rng) end """ - a, stats = soft_symcover!(ϕ, a, A; kwargs...) + a, stats = soft_symcover!(ρ, a, A; kwargs...) a, stats = soft_symcover!(a, A; kwargs...) -Refine one symmetric soft-cover start in place. The no-ϕ form uses +Refine one symmetric soft-cover start in place. The no-ρ form uses `PowerMean{2}()`. Build a start with [`initialize_symcover`](@ref) and `feasible=:none`. @@ -147,10 +147,10 @@ function soft_symcover!(::AbsLog{2}, a::AbstractVector, A::AbstractMatrix; kwarg end """ - a, b, stats = soft_cover(ϕ, A; kwargs...) + a, b, stats = soft_cover(ρ, A; kwargs...) a, b, stats = soft_cover(A; kwargs...) -Return the scales `a`, `b` that minimize `∑ ϕ(|A[i,j]|/(a[i]*b[j]))`. This is +Return the scales `a`, `b` that minimize `∑ ρ(|A[i,j]|/(a[i]*b[j]))`. This is the asymmetric counterpart of [`soft_symcover`](@ref): it penalizes violations of `a[i]*b[j] >= |A[i,j]|` rather than forbidding them. The default penalty is `PowerMean{2}()`. `stats` and the failure behavior are as for @@ -220,20 +220,20 @@ function soft_cover(::AbsLog{2}, A::AbstractMatrix; linsolve::Symbol=:auto, end # Sole owner of the starts/σ/rng defaults for the asymmetric `AbsLinear` multistart. -function soft_cover(ϕ::AbsLinear, A::AbstractMatrix; starts::Int=4, +function soft_cover(ρ::AbsLinear, A::AbstractMatrix; starts::Int=4, σ::Union{Real,Nothing}=nothing, sigma::Union{Real,Nothing}=nothing, rng::AbstractRNG=MersenneTwister(_MULTISTART_SEED)) - return _soft_cover_abslinear(ϕ, A, starts, _resolve_alias(σ, sigma, 2.0, :σ, :sigma), rng) + return _soft_cover_abslinear(ρ, A, starts, _resolve_alias(σ, sigma, 2.0, :σ, :sigma), rng) end """ - a, b, stats = soft_cover!(ϕ, a, b, A; kwargs...) + a, b, stats = soft_cover!(ρ, a, b, A; kwargs...) a, b, stats = soft_cover!(a, b, A; kwargs...) Refine the starting point `(a, b)` into a soft cover of `A` in place. Scales must be finite and positive on supported rows and columns; unsupported scales are zeroed. The start need not cover `A`. Build one with [`initialize_cover`](@ref) -and `feasible=:none`. The no-ϕ form uses `PowerMean{2}()`. +and `feasible=:none`. The no-ρ form uses `PowerMean{2}()`. For the convex penalties (`PowerMean`, `AbsLog`) the result is the minimizer returned by [`soft_cover`](@ref), with the same keywords, and does not depend on @@ -397,10 +397,10 @@ function _soft_symcover_abslinear_inits(A::AbstractMatrix, starts::Int, σ::Real end # Scale-covariant symmetric `AbsLinear` multistart. -function _soft_symcover_abslinear(ϕ::AbsLinear, A::AbstractMatrix, starts::Int, σ::Real, rng) +function _soft_symcover_abslinear(ρ::AbsLinear, A::AbstractMatrix, starts::Int, σ::Real, rng) return _multistart_run(ExternalSolverStats, _soft_symcover_abslinear_inits, - (a, A) -> last(soft_symcover!(ϕ, a, A)), - (a, A) -> cover_objective(ϕ, a, A), + (a, A) -> last(soft_symcover!(ρ, a, A)), + (a, A) -> cover_objective(ρ, a, A), A, starts, σ, rng) end @@ -430,10 +430,10 @@ function _soft_cover_abslinear_inits(A::AbstractMatrix, starts::Int, σ::Real, r end # Scale-covariant asymmetric `AbsLinear` multistart. -function _soft_cover_abslinear(ϕ::AbsLinear, A::AbstractMatrix, starts::Int, σ::Real, rng) +function _soft_cover_abslinear(ρ::AbsLinear, A::AbstractMatrix, starts::Int, σ::Real, rng) (a, b), stats = _multistart_run(ExternalSolverStats, _soft_cover_abslinear_inits, - (ab, A) -> last(soft_cover!(ϕ, ab[1], ab[2], A)), - (ab, A) -> cover_objective(ϕ, ab[1], ab[2], A), + (ab, A) -> last(soft_cover!(ρ, ab[1], ab[2], A)), + (ab, A) -> cover_objective(ρ, ab[1], ab[2], A), A, starts, σ, rng) return a, b, stats end diff --git a/src/sparse_support.jl b/src/sparse_support.jl index 7b4e097..9e3dfca 100644 --- a/src/sparse_support.jl +++ b/src/sparse_support.jl @@ -150,25 +150,25 @@ end # Otherwise they are the generic methods, which check the other keywords. const _SparseSym = Union{SparseMatrixCSC,Symmetric{<:Any,<:SparseMatrixCSC},Hermitian{<:Any,<:SparseMatrixCSC}} -symcover_min(ϕ::AbsLog{2}, S::_SparseSym; linsolve::Symbol=:lsqr, kwargs...) = - invoke(symcover_min, Tuple{AbsLog{2},AbstractMatrix}, ϕ, S; linsolve, kwargs...) +symcover_min(ρ::AbsLog{2}, S::_SparseSym; linsolve::Symbol=:lsqr, kwargs...) = + invoke(symcover_min, Tuple{AbsLog{2},AbstractMatrix}, ρ, S; linsolve, kwargs...) -cover_min(ϕ::AbsLog{2}, A::SparseMatrixCSC; linsolve::Symbol=:lsqr, kwargs...) = - invoke(cover_min, Tuple{AbsLog{2},AbstractMatrix}, ϕ, A; linsolve, kwargs...) +cover_min(ρ::AbsLog{2}, A::SparseMatrixCSC; linsolve::Symbol=:lsqr, kwargs...) = + invoke(cover_min, Tuple{AbsLog{2},AbstractMatrix}, ρ, A; linsolve, kwargs...) cover_transversal(A::SparseMatrixCSC; linsolve::Symbol=:lsqr, kwargs...) = invoke(cover_transversal, Tuple{AbstractMatrix}, A; linsolve, kwargs...) -symcover_min!(ϕ::AbsLog{2}, a::AbstractVector, S::_SparseSym; linsolve::Symbol=:lsqr, kwargs...) = - invoke(symcover_min!, Tuple{AbsLog{2},AbstractVector,AbstractMatrix}, ϕ, a, S; linsolve, kwargs...) +symcover_min!(ρ::AbsLog{2}, a::AbstractVector, S::_SparseSym; linsolve::Symbol=:lsqr, kwargs...) = + invoke(symcover_min!, Tuple{AbsLog{2},AbstractVector,AbstractMatrix}, ρ, a, S; linsolve, kwargs...) -cover_min!(ϕ::AbsLog{2}, a::AbstractVector, b::AbstractVector, A::SparseMatrixCSC; +cover_min!(ρ::AbsLog{2}, a::AbstractVector, b::AbstractVector, A::SparseMatrixCSC; linsolve::Symbol=:lsqr, kwargs...) = - invoke(cover_min!, Tuple{AbsLog{2},AbstractVector,AbstractVector,AbstractMatrix}, ϕ, a, b, A; + invoke(cover_min!, Tuple{AbsLog{2},AbstractVector,AbstractVector,AbstractMatrix}, ρ, a, b, A; linsolve, kwargs...) -soft_symcover(ϕ::AbsLog{2}, S::_SparseSym; linsolve::Symbol=:lsqr, kwargs...) = - invoke(soft_symcover, Tuple{AbsLog{2},AbstractMatrix}, ϕ, S; linsolve, kwargs...) +soft_symcover(ρ::AbsLog{2}, S::_SparseSym; linsolve::Symbol=:lsqr, kwargs...) = + invoke(soft_symcover, Tuple{AbsLog{2},AbstractMatrix}, ρ, S; linsolve, kwargs...) -soft_cover(ϕ::AbsLog{2}, A::SparseMatrixCSC; linsolve::Symbol=:lsqr, kwargs...) = - invoke(soft_cover, Tuple{AbsLog{2},AbstractMatrix}, ϕ, A; linsolve, kwargs...) +soft_cover(ρ::AbsLog{2}, A::SparseMatrixCSC; linsolve::Symbol=:lsqr, kwargs...) = + invoke(soft_cover, Tuple{AbsLog{2},AbstractMatrix}, ρ, A; linsolve, kwargs...) diff --git a/src/transversal.jl b/src/transversal.jl index e337ce7..2d876d1 100644 --- a/src/transversal.jl +++ b/src/transversal.jl @@ -54,7 +54,7 @@ matrices default to `:lsqr`. As for [`cover_min`](@ref), an active-set method finishes a solve whose multiplier iteration stops early. `cover_transversal(AbsLog{2}(), A)` is the same. With a [`PowerMean`](@ref) -penalty, [`cover_transversal(ϕ, A; target)`](@ref cover_transversal) instead +penalty, [`cover_transversal(ρ, A; target)`](@ref cover_transversal) instead pushes the coverage ratios of the entries off the transversal toward `target`. See also: [`cover_transversal!`](@ref), [`cover_min`](@ref). diff --git a/test/element_types.jl b/test/element_types.jl index 6cad9aa..a571730 100644 --- a/test/element_types.jl +++ b/test/element_types.jl @@ -109,8 +109,8 @@ @test eltype(b) === Float32 @test iscover(a, b, A; rtol=1e-6) - for ϕ in (AbsLog{1}(), AbsLinear{1}(), AbsLinear{2}()) - x, y, _ = soft_cover!(ϕ, copy(a0), copy(b0), A) + for ρ in (AbsLog{1}(), AbsLinear{1}(), AbsLinear{2}()) + x, y, _ = soft_cover!(ρ, copy(a0), copy(b0), A) @test eltype(x) === Float64 @test eltype(y) === Float32 @test all(isfinite, x) && all(isfinite, y) diff --git a/test/extensions.jl b/test/extensions.jl index 23d4b93..f1175fe 100644 --- a/test/extensions.jl +++ b/test/extensions.jl @@ -41,10 +41,10 @@ # soft_symcover(AbsLog{p}): unconstrained, lower objective than constrained for A in ([2.0 1.0; 1.0 3.0], [100.0 1.0; 1.0 0.01], [4.0 2.0 1.0; 2.0 3.0 2.0; 1.0 2.0 5.0]) - for ϕ in (AbsLog{1}(), AbsLog{2}()) - a_soft, _ = soft_symcover(ϕ, A) - a_hard, _ = symcover_min(ϕ, A) - @test cover_objective(ϕ, a_soft, A) <= cover_objective(ϕ, a_hard, A) + 1e-8 + for ρ in (AbsLog{1}(), AbsLog{2}()) + a_soft, _ = soft_symcover(ρ, A) + a_hard, _ = symcover_min(ρ, A) + @test cover_objective(ρ, a_soft, A) <= cover_objective(ρ, a_hard, A) + 1e-8 end end # Rank-1 matrix: both achieve zero objective @@ -72,15 +72,15 @@ end for A in ([2.0 1.0; 1.0 3.0], [100.0 1.0; 1.0 0.01], [4.0 2.0 1.0; 2.0 3.0 2.0; 1.0 2.0 5.0]) a_fast = symcover(AbsLinear{2}(), A) - for ϕ in (AbsLinear{1}(), AbsLinear{2}()) + for ρ in (AbsLinear{1}(), AbsLinear{2}()) # symcover_min: valid hard cover, at most as costly as heuristic - a_min, _ = symcover_min(ϕ, A) + a_min, _ = symcover_min(ρ, A) @test iscover(a_min, A; atol=1e-6) - @test cover_objective(ϕ, a_min, A) <= cover_objective(ϕ, a_fast, A) + 1e-8 + @test cover_objective(ρ, a_min, A) <= cover_objective(ρ, a_fast, A) + 1e-8 # soft_symcover: lower or equal objective than constrained version - a_soft, _ = soft_symcover(ϕ, A) - @test cover_objective(ϕ, a_soft, A) <= cover_objective(ϕ, a_min, A) + 1e-8 + a_soft, _ = soft_symcover(ρ, A) + @test cover_objective(ρ, a_soft, A) <= cover_objective(ρ, a_min, A) + 1e-8 end # AbsLinear{2} ≤ AbsLinear{1} soft objectives (p=2 is a stricter lower bound) a2, _ = soft_symcover(AbsLinear{2}(), A) @@ -107,7 +107,7 @@ end # Refinements from widely dispersed starts must reach a local minimum, not stop on the # flat part of the (1-r)^2 objective: sorted objectives either agree to 1e-8 (the same # minimum) or differ by more than 1e-3 (distinct minima; `Agen` has two). - ϕ = AbsLinear{2}() + ρ = AbsLinear{2}() rng = StableRNG(7) L = randn(rng, 5, 5) Asym = exp.((L .+ L') ./ 2) @@ -117,8 +117,8 @@ end es = sort(map(1:12) do _ a = exp.(3 .* randn(rng, 5)) b = exp.(3 .* randn(rng, 5)) - sym ? cover_objective(ϕ, first(soft_symcover!(ϕ, a, A)), A) : - cover_objective(ϕ, soft_cover!(ϕ, a, b, A)[1:2]..., A) + sym ? cover_objective(ρ, first(soft_symcover!(ρ, a, A)), A) : + cover_objective(ρ, soft_cover!(ρ, a, b, A)[1:2]..., A) end) gaps = diff(es) ./ es[begin:end-1] @test all(g -> g < 1e-8 || g > 1e-3, gaps) @@ -131,13 +131,13 @@ end # Ipopt may instead fail numerically as the scales diverge. A = ones(3, 3) plateau = r"Ipopt stopped on a plateau: every supported entry in (row|column) 3" - for (ϕ, msg) in ((AbsLinear{1}(), Regex(plateau.pattern * "|Ipopt terminated with status")), + for (ρ, msg) in ((AbsLinear{1}(), Regex(plateau.pattern * "|Ipopt terminated with status")), (AbsLinear{2}(), plateau)) - @test_throws msg soft_cover!(ϕ, ones(3), [1.0, 1.0, 1e40], A) - @test_throws msg soft_symcover!(ϕ, [1.0, 1.0, 1e40], A) - @test_throws msg cover_min!(ϕ, ones(3), [1.0, 1.0, 1e40], A) - @test_throws msg symcover_min!(ϕ, [1.0, 1.0, 1e40], A) - @test_throws MatrixCovers.SolverFailure soft_cover!(ϕ, ones(3), [1.0, 1.0, 1e40], A) + @test_throws msg soft_cover!(ρ, ones(3), [1.0, 1.0, 1e40], A) + @test_throws msg soft_symcover!(ρ, [1.0, 1.0, 1e40], A) + @test_throws msg cover_min!(ρ, ones(3), [1.0, 1.0, 1e40], A) + @test_throws msg symcover_min!(ρ, [1.0, 1.0, 1e40], A) + @test_throws MatrixCovers.SolverFailure soft_cover!(ρ, ones(3), [1.0, 1.0, 1e40], A) end end @@ -145,21 +145,21 @@ end A = [4.0 2.0 1.0; 2.0 3.0 2.0; 1.0 2.0 5.0] Aasym = [1.0 2.0 3.0; 4.0 5.0 6.0] - for ϕ in PENALTIES + for ρ in PENALTIES # Refinement does not worsen the start beyond solver tolerance. a0 = initialize_symcover(A) - a, _ = symcover_min!(ϕ, copy(a0), A) + a, _ = symcover_min!(ρ, copy(a0), A) @test iscover(a, A; rtol=1e-6) - @test cover_objective(ϕ, a, A) <= cover_objective(ϕ, a0, A) * (1 + 1e-6) + 1e-8 + @test cover_objective(ρ, a, A) <= cover_objective(ρ, a0, A) * (1 + 1e-6) + 1e-8 ab0, bb0 = initialize_cover(Aasym) - ab, bb, _ = cover_min!(ϕ, copy(ab0), copy(bb0), Aasym) + ab, bb, _ = cover_min!(ρ, copy(ab0), copy(bb0), Aasym) @test iscover(ab, bb, Aasym; rtol=1e-6) - @test cover_objective(ϕ, ab, bb, Aasym) <= cover_objective(ϕ, ab0, bb0, Aasym) * (1 + 1e-6) + 1e-8 + @test cover_objective(ρ, ab, bb, Aasym) <= cover_objective(ρ, ab0, bb0, Aasym) * (1 + 1e-6) + 1e-8 # The asymmetric result is pinned to the balance convention, so the start is # read only up to the gauge a -> c*a, b -> b/c that leaves a[i]*b[j] fixed. - ga, gb, _ = cover_min!(ϕ, 4 .* ab0, bb0 ./ 4, Aasym) + ga, gb, _ = cover_min!(ρ, 4 .* ab0, bb0 ./ 4, Aasym) @test ga ≈ ab && gb ≈ bb end @@ -179,18 +179,18 @@ end 1.06622031288736 0.243512973596586 38.0236584552296 0.0279078887878805; 29.4700945830419 38.0236584552296 8.96405068596511 26.5775238859338; 0.0181293142917846 0.0279078887878805 26.5775238859338 42.6650094474717] - ϕ = AbsLinear{2}() - a_hard, _ = symcover_min!(ϕ, initialize_symcover(Abasin; strategy=:hardcover), Abasin) - a_geo, _ = symcover_min!(ϕ, initialize_symcover(Abasin; strategy=:geomean), Abasin) + ρ = AbsLinear{2}() + a_hard, _ = symcover_min!(ρ, initialize_symcover(Abasin; strategy=:hardcover), Abasin) + a_geo, _ = symcover_min!(ρ, initialize_symcover(Abasin; strategy=:geomean), Abasin) @test iscover(a_hard, Abasin; rtol=1e-6) @test iscover(a_geo, Abasin; rtol=1e-6) - @test cover_objective(ϕ, a_geo, Abasin) < cover_objective(ϕ, a_hard, Abasin) - 0.5 + @test cover_objective(ρ, a_geo, Abasin) < cover_objective(ρ, a_hard, Abasin) - 0.5 # Offset axes survive the Ipopt position mapping. Ao = OffsetArray(A, -1, -1) - ao, _ = symcover_min!(ϕ, initialize_symcover(Ao), Ao) + ao, _ = symcover_min!(ρ, initialize_symcover(Ao), Ao) @test axes(ao, 1) == axes(Ao, 1) - @test collect(ao) ≈ first(symcover_min!(ϕ, initialize_symcover(A), A)) + @test collect(ao) ≈ first(symcover_min!(ρ, initialize_symcover(A), A)) end @testset "soft_symcover multistart and refiner (Ipopt)" begin @@ -201,16 +201,16 @@ end @test_throws "requires a start that covers `A`" symcover_min!(AbsLinear{2}(), copy(a0), A) @test first(soft_symcover!(AbsLinear{2}(), copy(a0), A)) isa AbstractVector - for ϕ in (AbsLinear{1}(), AbsLinear{2}(), AbsLog{1}()) - @test first(soft_symcover(ϕ, A)) == first(soft_symcover(ϕ, A)) # deterministic + for ρ in (AbsLinear{1}(), AbsLinear{2}(), AbsLog{1}()) + @test first(soft_symcover(ρ, A)) == first(soft_symcover(ρ, A)) # deterministic end # No start on the menu beats the driver. - for ϕ in (AbsLinear{1}(), AbsLinear{2}()) - a, _ = soft_symcover(ϕ, A) + for ρ in (AbsLinear{1}(), AbsLinear{2}()) + a, _ = soft_symcover(ρ, A) for strategy in (:hardcover, :geomean, :leaveout) - single, _ = soft_symcover!(ϕ, initialize_symcover(A; strategy, feasible=:none), A) - @test cover_objective(ϕ, a, A) <= cover_objective(ϕ, single, A) * (1 + 1e-6) + 1e-8 + single, _ = soft_symcover!(ρ, initialize_symcover(A; strategy, feasible=:none), A) + @test cover_objective(ρ, a, A) <= cover_objective(ρ, single, A) * (1 + 1e-6) + 1e-8 end end @@ -221,8 +221,8 @@ end 0.23770314779348869 49.972622569225109 2.4189759139690739 8.1401049198051822 7.3601096491681046; 3.0721768720180109 333.53567816710364 0.92571970793600067 7.3601096491681046 1.0844635712556003] d = [20.451338935482074, 0.69212569803171398, 35.401627522529395, 15.904906661932396, 0.19696509774727827] - for ϕ in (AbsLinear{1}(), AbsLinear{2}()) - @test covaries(A -> first(soft_symcover(ϕ, A)), Abasins, d; rtol=1e-5) + for ρ in (AbsLinear{1}(), AbsLinear{2}()) + @test covaries(A -> first(soft_symcover(ρ, A)), Abasins, d; rtol=1e-5) end @test_throws "positive scale on every supported row" soft_symcover!(AbsLinear{2}(), [1.0, -1.0, 2.0], A) @@ -240,31 +240,31 @@ end @test !iscover(a0, b0, A) @test_throws "requires a start that covers `A`" cover_min!(AbsLinear{2}(), copy(a0), copy(b0), A) - for ϕ in (AbsLinear{1}(), AbsLinear{2}(), AbsLog{1}(), AbsLog{2}()) - a, b = soft_cover(ϕ, A) - @test soft_cover(ϕ, A)[1:2] == (a, b) # deterministic + for ρ in (AbsLinear{1}(), AbsLinear{2}(), AbsLog{1}(), AbsLog{2}()) + a, b = soft_cover(ρ, A) + @test soft_cover(ρ, A)[1:2] == (a, b) # deterministic # The objective depends on `a`, `b` only through their products, so the split is # fixed by the balance convention rather than left to the solver. @test balance(a, b) ≈ 0 atol=1e-7 # Gauge-invariant in the start: (a, b) and (2a, b/2) name the same point. - ag, bg, _ = soft_cover!(ϕ, 2 .* copy(a0), copy(b0) ./ 2, A) - ah, bh, _ = soft_cover!(ϕ, copy(a0), copy(b0), A) + ag, bg, _ = soft_cover!(ρ, 2 .* copy(a0), copy(b0) ./ 2, A) + ah, bh, _ = soft_cover!(ρ, copy(a0), copy(b0), A) @test ag ≈ ah && bg ≈ bh end # No start on the menu beats the driver. - for ϕ in (AbsLinear{1}(), AbsLinear{2}()) - a, b, _ = soft_cover(ϕ, A) + for ρ in (AbsLinear{1}(), AbsLinear{2}()) + a, b, _ = soft_cover(ρ, A) for strategy in (:hardcover, :unconstrained) - sa, sb, _ = soft_cover!(ϕ, initialize_cover(A; strategy, feasible=:none)..., A) - @test cover_objective(ϕ, a, b, A) <= cover_objective(ϕ, sa, sb, A) * (1 + 1e-6) + 1e-8 + sa, sb, _ = soft_cover!(ρ, initialize_cover(A; strategy, feasible=:none)..., A) + @test cover_objective(ρ, a, b, A) <= cover_objective(ρ, sa, sb, A) * (1 + 1e-6) + 1e-8 end # The asymmetric soft cover relaxes the symmetric one on a symmetric matrix. As = [4.0 2.0 1.0; 2.0 3.0 2.0; 1.0 2.0 5.0] - aa, ab, _ = soft_cover(ϕ, As) - @test cover_objective(ϕ, aa, ab, As) <= - cover_objective(ϕ, first(soft_symcover(ϕ, As)), As) * (1 + 1e-6) + 1e-8 + aa, ab, _ = soft_cover(ρ, As) + @test cover_objective(ρ, aa, ab, As) <= + cover_objective(ρ, first(soft_symcover(ρ, As)), As) * (1 + 1e-6) + 1e-8 end # Covariant starts make the selected cover covariant on irregular support too. @@ -284,42 +284,42 @@ end @testset "AbsLog{1} canonical selection on the optimal face (HiGHS)" begin # Select the `AbsLog{2}`-minimal member of the `AbsLog{1}` optimal face. - ϕ1, ϕ2 = AbsLog{1}(), AbsLog{2}() + ρ1, ρ2 = AbsLog{1}(), AbsLog{2}() rng = StableRNG(17) for n in (3, 5, 8) B = exp.(3 .* randn(rng, n, n)) .* (rand(rng, n, n) .> 0.25) A = (B + B') / 2 all(iszero, A) && continue - a, _ = symcover_min(ϕ1, A) + a, _ = symcover_min(ρ1, A) @test iscover(a, A; rtol=1e-7) # No cover beats it on AbsLog{1}: the canonical selection does not cost optimality. # Any feasible cover is a witness; use the AbsLog{2}-minimal one, and the heuristic. - for other in (first(symcover_min(ϕ2, A)), symcover(A)) - @test cover_objective(ϕ1, a, A) <= cover_objective(ϕ1, other, A) * (1 + 1e-6) + 1e-8 + for other in (first(symcover_min(ρ2, A)), symcover(A)) + @test cover_objective(ρ1, a, A) <= cover_objective(ρ1, other, A) * (1 + 1e-6) + 1e-8 end # Start-independent in the *result*, not merely in the objective value. for strategy in (:hardcover, :geomean, :diagfeasible) - @test first(symcover_min!(ϕ1, initialize_symcover(A; strategy), A)) ≈ a + @test first(symcover_min!(ρ1, initialize_symcover(A; strategy), A)) ≈ a end # Scale-covariant: both objectives see `A` only through the residuals, which a # rescaling leaves invariant, so the selected member co-varies with the frame. D = Diagonal(exp.(randn(rng, n))) - @test first(symcover_min(ϕ1, D * A * D)) ≈ D * a + @test first(symcover_min(ρ1, D * A * D)) ≈ D * a end # Gauge balancing and `AbsLog{1}` face selection are independent. Aasym = [3.0 1.0 7.0; 2.0 5.0 1.0; 8.0 1.0 4.0] - a, b, _ = cover_min(ϕ1, Aasym) + a, b, _ = cover_min(ρ1, Aasym) nza = vec(count(!iszero, Aasym, dims=2)) nzb = vec(count(!iszero, Aasym, dims=1)) @test sum(nza .* log.(a)) ≈ sum(nzb .* log.(b)) atol=1e-8 @test iscover(a, b, Aasym; rtol=1e-7) # Gauge-invariant in the start, and start-independent in the result. a0, b0 = initialize_cover(Aasym; strategy=:geomean) - ag, bg, _ = cover_min!(ϕ1, 4 .* a0, b0 ./ 4, Aasym) + ag, bg, _ = cover_min!(ρ1, 4 .* a0, b0 ./ 4, Aasym) @test ag ≈ a && bg ≈ b end @@ -331,53 +331,53 @@ end 0.0181293142917846 0.0279078887878805 26.5775238859338 42.6650094474717] Aasym = [1.0 2.0 3.0; 40.0 5.0 0.6] - for ϕ in (AbsLinear{1}(), AbsLinear{2}()) - a, _ = symcover_min(ϕ, Abasin) + for ρ in (AbsLinear{1}(), AbsLinear{2}()) + a, _ = symcover_min(ρ, Abasin) @test iscover(a, Abasin; rtol=1e-6) # No start on the menu beats the driver. for strategy in (:hardcover, :geomean, :leaveout) - single, _ = symcover_min!(ϕ, initialize_symcover(Abasin; strategy), Abasin) - @test cover_objective(ϕ, a, Abasin) <= - cover_objective(ϕ, single, Abasin) * (1 + 1e-6) + 1e-8 + single, _ = symcover_min!(ρ, initialize_symcover(Abasin; strategy), Abasin) + @test cover_objective(ρ, a, Abasin) <= + cover_objective(ρ, single, Abasin) * (1 + 1e-6) + 1e-8 end - @test first(symcover_min(ϕ, Abasin)) == a # deterministic + @test first(symcover_min(ρ, Abasin)) == a # deterministic - ab, bb, _ = cover_min(ϕ, Aasym) + ab, bb, _ = cover_min(ρ, Aasym) @test iscover(ab, bb, Aasym; rtol=1e-6) for strategy in (:hardcover, :unconstrained) - sa, sb, _ = cover_min!(ϕ, initialize_cover(Aasym; strategy)..., Aasym) - @test cover_objective(ϕ, ab, bb, Aasym) <= - cover_objective(ϕ, sa, sb, Aasym) * (1 + 1e-6) + 1e-8 + sa, sb, _ = cover_min!(ρ, initialize_cover(Aasym; strategy)..., Aasym) + @test cover_objective(ρ, ab, bb, Aasym) <= + cover_objective(ρ, sa, sb, Aasym) * (1 + 1e-6) + 1e-8 end - @test cover_min(ϕ, Aasym)[1:2] == (ab, bb) # deterministic + @test cover_min(ρ, Aasym)[1:2] == (ab, bb) # deterministic # The asymmetric cover relaxes the symmetric one: independent row and column # scales can only do better on the same matrix. - asym_a, asym_b, _ = cover_min(ϕ, Abasin) - @test cover_objective(ϕ, asym_a, asym_b, Abasin) <= - cover_objective(ϕ, first(symcover_min(ϕ, Abasin)), Abasin) * (1 + 1e-6) + 1e-8 + asym_a, asym_b, _ = cover_min(ρ, Abasin) + @test cover_objective(ρ, asym_a, asym_b, Abasin) <= + cover_objective(ρ, first(symcover_min(ρ, Abasin)), Abasin) * (1 + 1e-6) + 1e-8 end # Restricting `strategies` changes the selected basin. - ϕ = AbsLinear{2}() - @test first(symcover_min(ϕ, Abasin; strategies=(:hardcover,))) ≈ - first(symcover_min!(ϕ, initialize_symcover(Abasin; strategy=:hardcover), Abasin)) - @test cover_objective(ϕ, first(symcover_min(ϕ, Abasin)), Abasin) < - cover_objective(ϕ, first(symcover_min(ϕ, Abasin; strategies=(:hardcover,))), Abasin) - 0.5 + ρ = AbsLinear{2}() + @test first(symcover_min(ρ, Abasin; strategies=(:hardcover,))) ≈ + first(symcover_min!(ρ, initialize_symcover(Abasin; strategy=:hardcover), Abasin)) + @test cover_objective(ρ, first(symcover_min(ρ, Abasin)), Abasin) < + cover_objective(ρ, first(symcover_min(ρ, Abasin; strategies=(:hardcover,))), Abasin) - 0.5 # A matrix whose every row carries a single support entry admits no :leaveout start; # that strategy forfeits its slot rather than failing the solve. Adiag = [4.0 0.0; 0.0 9.0] - @test first(symcover_min(ϕ, Adiag)) ≈ [2.0, 3.0] rtol=1e-4 + @test first(symcover_min(ρ, Adiag)) ≈ [2.0, 3.0] rtol=1e-4 - @test_throws "unknown strategy :banana" symcover_min(ϕ, Abasin; strategies=(:banana,)) - @test_throws "no strategy in (:leaveout,)" symcover_min(ϕ, Adiag; strategies=(:leaveout,)) - @test_throws "has no asymmetric formulation" cover_min(ϕ, Aasym; strategies=(:leaveout,)) + @test_throws "unknown strategy :banana" symcover_min(ρ, Abasin; strategies=(:banana,)) + @test_throws "no strategy in (:leaveout,)" symcover_min(ρ, Adiag; strategies=(:leaveout,)) + @test_throws "has no asymmetric formulation" cover_min(ρ, Aasym; strategies=(:leaveout,)) # An empty menu is reported as such by both drivers, rather than as the # unrelated "no strategy yields a start" that a fall-through would produce. - @test_throws "at least one starting cover" cover_min(ϕ, Aasym; strategies=()) - @test_throws "at least one starting cover" symcover_min(ϕ, Abasin; strategies=()) - @test_throws "symcover_min:" symcover_min(ϕ, Abasin; strategies=()) + @test_throws "at least one starting cover" cover_min(ρ, Aasym; strategies=()) + @test_throws "at least one starting cover" symcover_min(ρ, Abasin; strategies=()) + @test_throws "symcover_min:" symcover_min(ρ, Abasin; strategies=()) end @testset "error hint gated on argument types" begin @@ -496,21 +496,21 @@ end # Ipopt: the AbsLinear kernels, whose starts the caller supplies. for p in (1, 2) - ϕ = AbsLinear{p}() - sh, _ = symcover_min!(ϕ, symcover(ϕ, M), M) - sd, _ = symcover_min!(ϕ, symcover(ϕ, dense), dense) + ρ = AbsLinear{p}() + sh, _ = symcover_min!(ρ, symcover(ρ, M), M) + sd, _ = symcover_min!(ρ, symcover(ρ, dense), dense) @test sh ≈ sd rtol=1e-5 - ah, bh, _ = cover_min!(ϕ, cover(ϕ, M)..., M) - ad, bd, _ = cover_min!(ϕ, cover(ϕ, dense)..., dense) + ah, bh, _ = cover_min!(ρ, cover(ρ, M)..., M) + ad, bd, _ = cover_min!(ρ, cover(ρ, dense)..., dense) @test ah ≈ ad rtol=1e-5 @test bh ≈ bd rtol=1e-5 - @test first(soft_symcover!(ϕ, first(soft_symcover(ϕ, M)), M)) ≈ - first(soft_symcover!(ϕ, first(soft_symcover(ϕ, dense)), dense)) rtol=1e-5 + @test first(soft_symcover!(ρ, first(soft_symcover(ρ, M)), M)) ≈ + first(soft_symcover!(ρ, first(soft_symcover(ρ, dense)), dense)) rtol=1e-5 - sah, sbh, _ = soft_cover!(ϕ, soft_cover(ϕ, M)[1:2]..., M) - sad, sbd, _ = soft_cover!(ϕ, soft_cover(ϕ, dense)[1:2]..., dense) + sah, sbh, _ = soft_cover!(ρ, soft_cover(ρ, M)[1:2]..., M) + sad, sbd, _ = soft_cover!(ρ, soft_cover(ρ, dense)[1:2]..., dense) @test sah ≈ sad rtol=1e-5 @test sbh ≈ sbd rtol=1e-5 end @@ -599,36 +599,36 @@ end 1.06622031288736 0.243512973596586 38.0236584552296 0.0279078887878805; 29.4700945830419 38.0236584552296 8.96405068596511 26.5775238859338; 0.0181293142917846 0.0279078887878805 26.5775238859338 42.6650094474717] - ϕ = AbsLinear{2}() - a, ms = @inferred symcover_min(ϕ, Abasin) + ρ = AbsLinear{2}() + a, ms = @inferred symcover_min(ρ, Abasin) @test ms isa MatrixCovers.MultistartStats{ESS,Float64} @test ms.labels == [:hardcover, :geomean, :leaveout] @test ms.labels[ms.selected] === :geomean @test isempty(ms.failed) @test all(s -> s.solver === :Ipopt, ms.stats) - @test ms.objectives[ms.selected] == cover_objective(ϕ, a, Abasin) + @test ms.objectives[ms.selected] == cover_objective(ρ, a, Abasin) @test ms.objectives[ms.selected] <= minimum(ms.objectives) * (1 + 1e-6) # Each record describes the refinement of its own start. - _, s_hard = symcover_min!(ϕ, initialize_symcover(Abasin; strategy=:hardcover), Abasin) + _, s_hard = symcover_min!(ρ, initialize_symcover(Abasin; strategy=:hardcover), Abasin) @test ms.stats[1].objective ≈ s_hard.objective @test MatrixCovers.converged(ms) === MatrixCovers.converged(ms.stats[ms.selected]) @test_throws MethodError MatrixCovers.iterations(ms) # A strategy that yields no start for `A` is not recorded. - _, ms = symcover_min(ϕ, [4.0 0.0; 0.0 9.0]) + _, ms = symcover_min(ρ, [4.0 0.0; 0.0 9.0]) @test ms.labels == [:hardcover, :geomean] a, b, ms = @inferred cover_min(AbsLinear{1}(), Aasym) @test ms.labels == [:hardcover, :unconstrained] @test ms.objectives[ms.selected] == cover_objective(AbsLinear{1}(), a, b, Aasym) # Random multistart: failed random starts are recorded and left out. - a, b, ms = @inferred soft_cover(ϕ, ones(3, 3); starts=8, σ=10.0, rng=StableRNG(2)) + a, b, ms = @inferred soft_cover(ρ, ones(3, 3); starts=8, σ=10.0, rng=StableRNG(2)) @test !isempty(ms.failed) @test all(l -> startswith(string(l), "rand"), ms.failed) @test isempty(intersect(ms.labels, ms.failed)) @test length(ms.labels) + length(ms.failed) == 8 @test length(ms.stats) == length(ms.objectives) == length(ms.labels) - @test ms.objectives[ms.selected] == cover_objective(ϕ, a, b, ones(3, 3)) - a, ms = @inferred soft_symcover(ϕ, Float32.(A)) + @test ms.objectives[ms.selected] == cover_objective(ρ, a, b, ones(3, 3)) + a, ms = @inferred soft_symcover(ρ, Float32.(A)) @test ms isa MatrixCovers.MultistartStats{ESS,Float32} @test ms.labels[1:2] == [:geomean, :hardcover] diff --git a/test/helpers.jl b/test/helpers.jl index bcfe90b..8225d89 100644 --- a/test/helpers.jl +++ b/test/helpers.jl @@ -1,6 +1,6 @@ # Shared helpers for the themed test files. -# The four penalty instances, for loops over properties that must hold for every ϕ. +# The four penalty instances, for loops over properties that must hold for every ρ. const PENALTIES = (AbsLog{1}(), AbsLog{2}(), AbsLinear{1}(), AbsLinear{2}()) # Penalties with native soft-cover solvers, for properties of the soft-cover family. @@ -91,24 +91,24 @@ function covaries(coverfn, A, dr::AbstractVector, dc::AbstractVector; kwargs...) end """ - covaries_objective(ϕ, coverfn, A, d; kwargs...) - covaries_objective(ϕ, coverfn, A, dr, dc; kwargs...) + covaries_objective(ρ, coverfn, A, d; kwargs...) + covaries_objective(ρ, coverfn, A, dr, dc; kwargs...) Scale invariance of the attained objective: the cover found in a rescaled frame -must score the same as the cover found in the original frame, since `ϕ` sees only +must score the same as the cover found in the original frame, since `ρ` sees only the ratios `|A[i,j]| / (a[i]*b[j])`, which every diagonal rescaling leaves fixed. This is the sharp statement of covariance for an iterate driven to convergence. """ -function covaries_objective(ϕ, coverfn, A, d::AbstractVector; kwargs...) - E = cover_objective(ϕ, coverfn(A), A) +function covaries_objective(ρ, coverfn, A, d::AbstractVector; kwargs...) + E = cover_objective(ρ, coverfn(A), A) AD = d .* A .* transpose(d) - return isapprox(cover_objective(ϕ, coverfn(AD), AD), E; kwargs...) + return isapprox(cover_objective(ρ, coverfn(AD), AD), E; kwargs...) end -function covaries_objective(ϕ, coverfn, A, dr::AbstractVector, dc::AbstractVector; kwargs...) +function covaries_objective(ρ, coverfn, A, dr::AbstractVector, dc::AbstractVector; kwargs...) a, b = coverfn(A) - E = cover_objective(ϕ, a, b, A) + E = cover_objective(ρ, a, b, A) AD = dr .* A .* transpose(dc) aD, bD = coverfn(AD) - return isapprox(cover_objective(ϕ, aD, bD, AD), E; kwargs...) + return isapprox(cover_objective(ρ, aD, bD, AD), E; kwargs...) end diff --git a/test/heuristic_covers.jl b/test/heuristic_covers.jl index 51c8a5b..7239615 100644 --- a/test/heuristic_covers.jl +++ b/test/heuristic_covers.jl @@ -5,8 +5,8 @@ # Cover property: a[i]*a[j] >= abs(A[i,j]) for all i, j for A in ([2.0 1.0; 1.0 3.0], [1.0 -0.2; -0.2 0.0], [1.0 0.0; 0.0 0.0], [100.0 1.0; 1.0 0.01]) - for ϕ in PENALTIES - a = symcover(ϕ, A) + for ρ in PENALTIES + a = symcover(ρ, A) @test iscover(a, A; rtol=8eps()) end # Default dispatch @@ -24,22 +24,22 @@ # Diagonal scaling covariance A = [2.0 1.0; 1.0 3.0] d = [2.0, 0.5] - for ϕ in PENALTIES - @test covaries(A -> symcover(ϕ, A), A, d) + for ρ in PENALTIES + @test covaries(A -> symcover(ρ, A), A, d) end # Non-square input is rejected, with the message naming the called function @test_throws "symcover requires a square matrix" symcover([1.0 2.0; 3.0 4.0; 5.0 6.0]) @test_throws "symcover! requires a square matrix" symcover!(zeros(3), [1.0 2.0; 3.0 4.0; 5.0 6.0]) end -@testset "symcover does not currently consult ϕ" begin +@testset "symcover does not currently consult ρ" begin # The current heuristic accepts but ignores the penalty. rng = StableRNG(1) for n in (2, 5, 40) B = randn(rng, n, n); A = (B + B') / 2 a = symcover(A) - for ϕ in PENALTIES - @test symcover(ϕ, A) == a + for ρ in PENALTIES + @test symcover(ρ, A) == a end end @@ -79,8 +79,8 @@ end # Cover property: a[i]*b[j] >= abs(A[i,j]) for all i, j for A in ([2.0 1.0; 1.0 3.0], [0.0 1.0; -2.0 0.0], [1.0 0.0; 0.0 0.0], [100.0 1.0; 1.0 0.01]) - for ϕ in PENALTIES - a, b = cover(ϕ, A) + for ρ in PENALTIES + a, b = cover(ρ, A) @test iscover(a, b, A; rtol=8eps()) end # Default dispatch @@ -94,8 +94,8 @@ end @test a[1] == 0 # Zero-diagonal matrix A = [0.0 1.0; -1.0 0.0] - for ϕ in PENALTIES - a, b = cover(ϕ, A) + for ρ in PENALTIES + a, b = cover(ρ, A) @test iscover(a, b, A; rtol=8eps()) end # Rectangular matrix @@ -105,8 +105,8 @@ end # Diagonal scaling covariance: cover(A .* dr .* dc') is cover(A) scaled by dr, dc up to a scalar A = [2.0 1.0; 1.0 3.0] dr, dc = [2.0, 0.5], [3.0, 0.25] - for ϕ in PENALTIES - @test covaries(A -> cover(ϕ, A), A, dr, dc) + for ρ in PENALTIES + @test covaries(A -> cover(ρ, A), A, dr, dc) end end @@ -124,10 +124,10 @@ end @test r === (abuf2, bbuf2) @test abuf2 == aB && bbuf2 == bB - # The bang forms take the same ϕ as the allocating ones, and likewise ignore it. - for ϕ in PENALTIES - @test symcover!(ϕ, similar(a), A) == a - @test cover!(ϕ, similar(aB), similar(bB), B) == (aB, bB) + # The bang forms take the same ρ as the allocating ones, and likewise ignore it. + for ρ in PENALTIES + @test symcover!(ρ, similar(a), A) == a + @test cover!(ρ, similar(aB), similar(bB), B) == (aB, bB) end # Adjoint/Transpose wrappers match the allocating forms. diff --git a/test/maxbalance.jl b/test/maxbalance.jl index 2d655c0..61908dc 100644 --- a/test/maxbalance.jl +++ b/test/maxbalance.jl @@ -153,7 +153,7 @@ end θ, σ = minimax_ratio(A) @test cut_imbalance(a, b, A, σ, 1:n) <= 1e-10 @test maximum(last, offtransversal_ratios(a, b, A, σ)) ≈ θ rtol = 1e-10 - # The products do not depend on `ϕ` or `target`. + # The products do not depend on `ρ` or `target`. a1, b1 = cover_transversal(PowerMean{1}(), A; target=0.5, maxbalance=true) @test logproduct_gap(a, b, a1, b1, A) <= 1e-12 a2, b2 = cover_transversal(PowerMean{2}(), A) diff --git a/test/minimal_covers.jl b/test/minimal_covers.jl index f0824a6..36ce993 100644 --- a/test/minimal_covers.jl +++ b/test/minimal_covers.jl @@ -756,7 +756,7 @@ end @test collect(ao) == a && collect(bo) == b end -@testset "no-ϕ convenience methods for the *_min family" begin +@testset "no-ρ convenience methods for the *_min family" begin # symcover_min(A) and cover_min(A) default to AbsLog{2}, matching # symcover(A)/cover(A). Solved natively, so no extension is needed. A = [4.0 2.0 1.0; 2.0 3.0 2.0; 1.0 2.0 5.0] @@ -770,7 +770,7 @@ end Aasym = [4.0 1.0 0.0; 1.0 9.0 2.0] # AbsLog{2} has a unique minimizer, so refining any valid start reproduces the - # cold solve exactly, and the no-ϕ form selects the same penalty. + # cold solve exactly, and the no-ρ form selects the same penalty. a = initialize_symcover(A) @test first(symcover_min!(AbsLog{2}(), copy(a), A)) ≈ first(symcover_min(AbsLog{2}(), A)) @test first(symcover_min!(copy(a), A)) == first(symcover_min!(AbsLog{2}(), copy(a), A)) diff --git a/test/penalties.jl b/test/penalties.jl index 215f5ba..92af1c3 100644 --- a/test/penalties.jl +++ b/test/penalties.jl @@ -24,9 +24,9 @@ end @testset "PowerMean" begin - φ(p, r) = (r^p - 1 - p * log(r)) / p + ρ(p, r) = (r^p - 1 - p * log(r)) / p for p in (1, 2, 3.5, 0.5), r in (1e-3, 0.3, 1.0, 1.7, 40.0) - @test PowerMean{p}()(r) ≈ φ(p, r) rtol=1e-12 atol=1e-15 + @test PowerMean{p}()(r) ≈ ρ(p, r) rtol=1e-12 atol=1e-15 end # Accurate near r = 1, where the formula cancels to O(log(r)^2). @test PowerMean{2}()(1 + 1e-9) ≈ 1e-18 rtol=1e-6 @@ -45,7 +45,7 @@ end for p in (1, 2) E = cover_objective(PowerMean{p}(), a, b, A) @test isfinite(E) - @test E ≈ sum(φ(p, abs(A[i, j]) / (a[i] * b[j])) for i in 1:3, j in 1:3 if A[i, j] != 0) + @test E ≈ sum(ρ(p, abs(A[i, j]) / (a[i] * b[j])) for i in 1:3, j in 1:3 if A[i, j] != 0) @test cover_objective(PowerMean{p}(), a, b, sparse(A)) ≈ E end end @@ -74,10 +74,10 @@ end dense[i, j] = v end a, b = [2.0, 1.0, 0.5], [1.5, 0.5, 3.0, 1.0] - for ϕ in SOFT_PENALTIES + for ρ in SOFT_PENALTIES # Agreement with the dense reference pins the zero-entry accounting: the - # entries the hook skips still carry `ϕ(0)`, which `AbsLinear` makes nonzero. - @test cover_objective(ϕ, a, b, M) ≈ cover_objective(ϕ, a, b, dense) + # entries the hook skips still carry `ρ(0)`, which `AbsLinear` makes nonzero. + @test cover_objective(ρ, a, b, M) ≈ cover_objective(ρ, a, b, dense) end # A zero scale under a nonzero entry is uncovered, and under a zero entry is not. @@ -103,8 +103,8 @@ end # Offset axes are honored, not merely tolerated: the score is unchanged. Ao = OffsetArray(A, -1:0, 2:3) ao, bo = OffsetArray([2.0, 1.0], -1:0), OffsetArray([1.0, 3.0], 2:3) - for ϕ in SOFT_PENALTIES - @test cover_objective(ϕ, ao, bo, Ao) ≈ cover_objective(ϕ, [2.0, 1.0], [1.0, 3.0], A) + for ρ in SOFT_PENALTIES + @test cover_objective(ρ, ao, bo, Ao) ≈ cover_objective(ρ, [2.0, 1.0], [1.0, 3.0], A) end end @@ -113,10 +113,10 @@ end # give identical results, and the accumulator stays real. Ac = [1.0+2.0im 0.5-1.0im; 0.3+0.1im 3.0+0.0im] a, b = [2.0, 1.0], [1.5, 0.5] - for ϕ in SOFT_PENALTIES - v = cover_objective(ϕ, a, b, Ac) + for ρ in SOFT_PENALTIES + v = cover_objective(ρ, a, b, Ac) @test v isa Real - @test v == cover_objective(ϕ, a, b, abs.(Ac)) + @test v == cover_objective(ρ, a, b, abs.(Ac)) end end diff --git a/test/powermean.jl b/test/powermean.jl index e5c89b1..96abc26 100644 --- a/test/powermean.jl +++ b/test/powermean.jl @@ -55,7 +55,7 @@ end # `R.^p` spanning tens of decades, where the first-order iteration crawls; # dense support is exercised at larger `p` below. for p in (1, 2) - ϕ = PowerMean{p}() + ρ = PowerMean{p}() dense = pm_testmatrix(rng, 30, 30; σ=2.0, z=0.0) rect = pm_testmatrix(rng, 40, 17; σ=4.0, zrows=(3, 11), zcols=(5,)) wide = pm_testmatrix(rng, 12, 45; σ=6.0, z=0.5, zrows=(1,), zcols=(2, 44)) @@ -63,23 +63,23 @@ end sp.nzval .= exp.(3 .* randn(rng, nnz(sp))) sp[7, :] .= 0; sp[:, 9] .= 0; dropzeros!(sp) for A in (dense, rect, wide, sp) - a, b = @test_logs scales(soft_cover(ϕ, A)) + a, b = @test_logs scales(soft_cover(ρ, A)) @test pm_imbalance(p, a, b, A) < 1e-11 @test isbalanced(a, b, A) @test all(iszero(a[i]) == all(iszero, A[i, :]) for i in axes(A, 1)) @test all(iszero(b[j]) == all(iszero, A[:, j]) for j in axes(A, 2)) end - @test scales(soft_cover(ϕ, sp))[1] isa Vector{Float64} + @test scales(soft_cover(ρ, sp))[1] isa Vector{Float64} S = pm_testmatrix(rng, 35, 35; σ=3.0, zrows=(4,), zcols=(4,)) S = S + S' Ssp = sparse(S) for M in (S, Ssp, Symmetric(Ssp)) - a = scales(soft_symcover(ϕ, M)) + a = scales(soft_symcover(ρ, M)) @test pm_imbalance(p, a, a, M) < 1e-11 @test a[4] == 0 # The unique minimizer is symmetric, so the asymmetric solver agrees. - x, y = scales(soft_cover(ϕ, M)) + x, y = scales(soft_cover(ρ, M)) supp = findall(!iszero, S) @test (x .* y')[supp] ≈ (a .* a')[supp] rtol=1e-10 end diff --git a/test/soft_covers.jl b/test/soft_covers.jl index 26a60c6..1617e1e 100644 --- a/test/soft_covers.jl +++ b/test/soft_covers.jl @@ -24,33 +24,33 @@ end end end - # Non-square rejected (default dispatch and all ϕ) + # Non-square rejected (default dispatch and all ρ) @test_throws "requires a square matrix" soft_symcover([1.0 2.0; 3.0 4.0; 5.0 6.0]) - for ϕ in SOFT_PENALTIES - @test_throws "requires a square matrix" soft_symcover(ϕ, [1.0 2.0; 3.0 4.0; 5.0 6.0]) + for ρ in SOFT_PENALTIES + @test_throws "requires a square matrix" soft_symcover(ρ, [1.0 2.0; 3.0 4.0; 5.0 6.0]) end # Rank-1 is exact: A = [4 2; 2 1] = [2;1]*[2 1], so exact cover has all ratios = 1 A = [4.0 2.0; 2.0 1.0] - for ϕ in SOFT_PENALTIES - a, _ = soft_symcover(ϕ, A) - @test cover_objective(ϕ, a, A) ≈ 0.0 atol=1e-8 + for ρ in SOFT_PENALTIES + a, _ = soft_symcover(ρ, A) + @test cover_objective(ρ, a, A) ≈ 0.0 atol=1e-8 end - # Diagonal-scaling covariance: soft_symcover(ϕ, ·) co-varies with a diagonal rescaling of A. + # Diagonal-scaling covariance: soft_symcover(ρ, ·) co-varies with a diagonal rescaling of A. A = [2.0 1.0; 1.0 3.0] d = [2.0, 0.5] - for ϕ in SOFT_PENALTIES - @test covaries(a -> first(soft_symcover(ϕ, a)), A, d; rtol=1e-5) + for ρ in SOFT_PENALTIES + @test covaries(a -> first(soft_symcover(ρ, a)), A, d; rtol=1e-5) end # Lower objective than naive uniform scaling perturbations A = [4.0 2.0 1.0; 2.0 3.0 2.0; 1.0 2.0 5.0] - for ϕ in SOFT_PENALTIES - a, _ = soft_symcover(ϕ, A) - E = cover_objective(ϕ, a, A) + for ρ in SOFT_PENALTIES + a, _ = soft_symcover(ρ, A) + E = cover_objective(ρ, a, A) for scale in [0.5, 0.9, 1.1, 2.0] - @test E <= cover_objective(ϕ, scale .* a, A) + 1e-8 + @test E <= cover_objective(ρ, scale .* a, A) + 1e-8 end end @@ -58,18 +58,18 @@ end γ = 0.5 A_zero = [γ 1.0; 1.0 0.0] A_small = [γ 1.0; 1.0 1e-10] - for ϕ in (AbsLinear{1}(), AbsLinear{2}()) - a_zero, _ = soft_symcover(ϕ, A_zero) - a_small, _ = soft_symcover(ϕ, A_small) + for ρ in (AbsLinear{1}(), AbsLinear{2}()) + a_zero, _ = soft_symcover(ρ, A_zero) + a_small, _ = soft_symcover(ρ, A_small) @test a_small ≈ a_zero atol=1e-5 end # The leave-one-out basin selection is covariant away from its documented tie. - for ϕ in (AbsLinear{1}(), AbsLinear{2}()) + for ρ in (AbsLinear{1}(), AbsLinear{2}()) for (B, d) in ((A_small, [50.0, 0.02]), ([3.0 7.6e-10; 7.6e-10 80.0], [35.0, 3400.0])) - a0, _ = soft_symcover(ϕ, B) - as, _ = soft_symcover(ϕ, B .* d .* d') + a0, _ = soft_symcover(ρ, B) + as, _ = soft_symcover(ρ, B .* d .* d') @test as .* as' ≈ (d .* d') .* (a0 .* a0') rtol=1e-6 end end @@ -489,13 +489,13 @@ end Asym = [4.0 1.0 0.5; 1.0 3.0 1.0; 0.5 1.0 2.5] Agen = [1.0 2.0 0.5; 0.25 3.0 1.0] - @testset "refining the multistart's own start reproduces it: $ϕ" for ϕ in SOFT_PENALTIES + @testset "refining the multistart's own start reproduces it: $ρ" for ρ in SOFT_PENALTIES a = initialize_symcover(Asym; strategy=:geomean, feasible=:none) - soft_symcover!(ϕ, a, Asym) - @test cover_objective(ϕ, a, Asym) ≈ cover_objective(ϕ, first(soft_symcover(ϕ, Asym)), Asym) rtol=1e-6 + soft_symcover!(ρ, a, Asym) + @test cover_objective(ρ, a, Asym) ≈ cover_objective(ρ, first(soft_symcover(ρ, Asym)), Asym) rtol=1e-6 end - @testset "no-ϕ form defaults to PowerMean{2}" begin + @testset "no-ρ form defaults to PowerMean{2}" begin a1, a2 = initialize_symcover(Asym; strategy=:geomean, feasible=:none), initialize_symcover(Asym; strategy=:geomean, feasible=:none) @test first(soft_symcover!(a1, Asym)) == first(soft_symcover!(PowerMean{2}(), a2, Asym)) b1, c1 = initialize_cover(Agen; strategy=:geomean, feasible=:none) @@ -508,7 +508,7 @@ end Abasins = [0.021778451276962405 1.5690256886348526 1.5690256886348526 0.20473123461805692] starts() = (initialize_symcover(Abasins; strategy=:geomean, feasible=:none), ones(2)) - o(ϕ, a) = cover_objective(ϕ, a, Abasins) + o(ρ, a) = cover_objective(ρ, a, Abasins) s1, s2 = starts() @test o(AbsLog{2}(), first(soft_symcover!(AbsLog{2}(), s1, Abasins))) ≈ @@ -520,13 +520,13 @@ end end # Unlike symcover_min!, a soft refiner imposes no coverage constraint on its start. - @testset "start need not cover A: $ϕ" for ϕ in SOFT_PENALTIES + @testset "start need not cover A: $ρ" for ρ in SOFT_PENALTIES a = fill(0.01, 3) @test !iscover(a, Asym) - @test first(soft_symcover!(ϕ, a, Asym)) === a + @test first(soft_symcover!(ρ, a, Asym)) === a b, c = fill(0.01, 2), fill(0.01, 3) @test !iscover(b, c, Agen) - @test soft_cover!(ϕ, b, c, Agen)[1:2] === (b, c) + @test soft_cover!(ρ, b, c, Agen)[1:2] === (b, c) end @testset "invalid starts throw, naming the function called" begin @@ -542,27 +542,27 @@ end # Scales on unsupported rows are inert and come back zero, matching every other # cover in the package. - @testset "unsupported rows are zeroed: $ϕ" for ϕ in SOFT_PENALTIES + @testset "unsupported rows are zeroed: $ρ" for ρ in SOFT_PENALTIES Az = [1.0 0.0 2.0; 0.0 0.0 0.0; 2.0 0.0 3.0] a = initialize_symcover(Az; strategy=:geomean, feasible=:none) - @test first(soft_symcover!(ϕ, a, Az))[2] == 0 + @test first(soft_symcover!(ρ, a, Az))[2] == 0 end - @testset "asymmetric refiners pin the balance convention: $ϕ" for ϕ in SOFT_PENALTIES + @testset "asymmetric refiners pin the balance convention: $ρ" for ρ in SOFT_PENALTIES a, b = initialize_cover(Agen; strategy=:geomean, feasible=:none) a .*= 7 # move the gauge; the objective cannot see it b ./= 7 - soft_cover!(ϕ, a, b, Agen) + soft_cover!(ρ, a, b, Agen) @test isbalanced(a, b, Agen) end - @testset "offset axes propagate: $ϕ" for ϕ in SOFT_PENALTIES + @testset "offset axes propagate: $ρ" for ρ in SOFT_PENALTIES Ao = OffsetArray(Asym, -1:1, -1:1) ao = initialize_symcover(Ao; strategy=:geomean, feasible=:none) - soft_symcover!(ϕ, ao, Ao) + soft_symcover!(ρ, ao, Ao) @test axes(ao, 1) == axes(Ao, 1) aref = initialize_symcover(Asym; strategy=:geomean, feasible=:none) - soft_symcover!(ϕ, aref, Asym) + soft_symcover!(ρ, aref, Asym) @test collect(ao) ≈ aref rtol=1e-6 end end @@ -611,17 +611,17 @@ MatrixCovers.require_abs_symmetric(::HookOnlyMatrix, fname) = nothing end @test first(soft_symcover(PowerMean{2}(), M)) ≈ first(soft_symcover(PowerMean{2}(), dense)) rtol=1e-12 - for ϕ in (AbsLinear{1}(), AbsLinear{2}(), AbsLog{1}(), AbsLog{2}()) - @test symcover(ϕ, M) ≈ symcover(ϕ, dense) rtol=1e-10 - @test first(soft_symcover(ϕ, M)) ≈ first(soft_symcover(ϕ, dense)) rtol=1e-6 - @test iscover(symcover(ϕ, M), dense; rtol=8eps()) - @test cover_objective(ϕ, symcover(ϕ, M), M) ≈ - cover_objective(ϕ, symcover(ϕ, dense), dense) rtol=1e-10 + for ρ in (AbsLinear{1}(), AbsLinear{2}(), AbsLog{1}(), AbsLog{2}()) + @test symcover(ρ, M) ≈ symcover(ρ, dense) rtol=1e-10 + @test first(soft_symcover(ρ, M)) ≈ first(soft_symcover(ρ, dense)) rtol=1e-6 + @test iscover(symcover(ρ, M), dense; rtol=8eps()) + @test cover_objective(ρ, symcover(ρ, M), M) ≈ + cover_objective(ρ, symcover(ρ, dense), dense) rtol=1e-10 end - for ϕ in (AbsLinear{1}(), AbsLinear{2}(), AbsLog{1}(), AbsLog{2}()) - ah, bh = cover(ϕ, M) - ad, bd = cover(ϕ, dense) + for ρ in (AbsLinear{1}(), AbsLinear{2}(), AbsLog{1}(), AbsLog{2}()) + ah, bh = cover(ρ, M) + ad, bd = cover(ρ, dense) @test ah ≈ ad rtol=1e-10 @test bh ≈ bd rtol=1e-10 @test iscover(ah, bh, dense; rtol=8eps()) diff --git a/test/storage_types.jl b/test/storage_types.jl index a5dc7e7..3163d7f 100644 --- a/test/storage_types.jl +++ b/test/storage_types.jl @@ -28,8 +28,8 @@ end [100.0 1.0; 1.0 0.01]) for A in (sparse(Adense), Symmetric(sparse(tril(Adense)), :L), Symmetric(sparse(triu(Adense)), :U), Hermitian(sparse(tril(Adense)), :L), Hermitian(sparse(triu(Adense)), :U)) - for ϕ in PENALTIES - a = symcover(ϕ, A) + for ρ in PENALTIES + a = symcover(ρ, A) @test iscover(a, Adense; atol=1e-12) end # Default dispatch @@ -55,8 +55,8 @@ end for dv in ([4.0, 9.0, 1.0], [4.0, 0.0, 1.0], [0.25, 100.0]) D = Diagonal(dv) Ddense = Matrix(D) - for ϕ in PENALTIES - a = symcover(ϕ, D) + for ρ in PENALTIES + a = symcover(ρ, D) @test iscover(a, Ddense; atol=1e-12) end a3, b3 = cover(D) @@ -84,8 +84,8 @@ end Adense = Matrix(A) a, b = cover(A) @test iscover(a, b, Adense; atol=1e-12) - for ϕ in PENALTIES - a = symcover(ϕ, A) + for ρ in PENALTIES + a = symcover(ρ, A) @test iscover(a, Adense; atol=1e-12) end # cover_objective matches dense for AbsLog{2} @@ -209,9 +209,9 @@ end @test first(symcover_min(AbsLog{2}(), sparse(symdenses[1]))) isa Vector{Float64} # Every soft_symcover penalty returns a dense Vector on sparse-backed input. let Ssp = sparse(symdenses[1]) - for ϕ in SOFT_PENALTIES - @test first(soft_symcover(ϕ, Ssp)) isa Vector{Float64} - @test first(soft_symcover(ϕ, Symmetric(Ssp))) isa Vector{Float64} + for ρ in SOFT_PENALTIES + @test first(soft_symcover(ρ, Ssp)) isa Vector{Float64} + @test first(soft_symcover(ρ, Symmetric(Ssp))) isa Vector{Float64} end end diff --git a/test/unitful.jl b/test/unitful.jl index a7f1f40..30a835c 100644 --- a/test/unitful.jl +++ b/test/unitful.jl @@ -174,18 +174,18 @@ a, b = f(A) @test unit.(a) == unit.(b) == UA end - for ϕ in PENALTIES - @test unit.(symcover(ϕ, A)) == UA - @test unit.(first(soft_symcover(ϕ, A))) == UA - @test unit.(first(symcover_min(ϕ, A))) == UA - @test all(unit.(v) == UA for v in cover(ϕ, A)) - @test all(unit.(v) == UA for v in soft_cover(ϕ, A)[1:2]) - @test all(unit.(v) == UA for v in cover_min(ϕ, A)[1:2]) + for ρ in PENALTIES + @test unit.(symcover(ρ, A)) == UA + @test unit.(first(soft_symcover(ρ, A))) == UA + @test unit.(first(symcover_min(ρ, A))) == UA + @test all(unit.(v) == UA for v in cover(ρ, A)) + @test all(unit.(v) == UA for v in soft_cover(ρ, A)[1:2]) + @test all(unit.(v) == UA for v in cover_min(ρ, A)[1:2]) end - for ϕ in (PowerMean{1}(), PowerMean{2}()) - @test unit.(scales(soft_symcover(ϕ, A))) == UA - @test all(unit.(v) == UA for v in scales(soft_cover(ϕ, A))) - @test all(unit.(v) == UA for v in scales(cover_transversal(ϕ, A))) + for ρ in (PowerMean{1}(), PowerMean{2}()) + @test unit.(scales(soft_symcover(ρ, A))) == UA + @test all(unit.(v) == UA for v in scales(soft_cover(ρ, A))) + @test all(unit.(v) == UA for v in scales(cover_transversal(ρ, A))) end end @@ -200,7 +200,7 @@ @test cover!(a, b, A) == (a, b) @test unit.(a) == unit.(b) == UA - # The heuristics ignore `ϕ`, so the forms that take one agree with those + # The heuristics ignore `ρ`, so the forms that take one agree with those # that do not. a = Vector{Quantity{Float64}}(undef, 3) @test symcover!(AbsLog{2}(), a, A) === a @@ -230,7 +230,7 @@ @test scales(cover_min!(AbsLog{2}(), a, b, A)) == (a, b) @test unit.(a) == unit.(b) == UA - # The no-ϕ forms of the `*_min` family default their penalty, and carry + # The no-ρ forms of the `*_min` family default their penalty, and carry # the units the same way. a = initialize_symcover(A) @test first(symcover_min!(a, A)) === a @@ -333,31 +333,31 @@ # `unit(A[i,j]) == unit(a[i])*unit(b[j])` makes every ratio the objective # forms dimensionless, so the score is a plain number and is identical to # the score of the unit-stripped problem. - ϕs = (AbsLog{1}(), AbsLog{2}(), AbsLinear{1}(), AbsLinear{2}()) + ρs = (AbsLog{1}(), AbsLog{2}(), AbsLinear{1}(), AbsLinear{2}()) a = symcover(A) - for ϕ in ϕs - s = cover_objective(ϕ, a, A) + for ρ in ρs + s = cover_objective(ρ, a, A) @test s isa Float64 - @test s == cover_objective(ϕ, ustrip.(a), ustrip.(A)) + @test s == cover_objective(ρ, ustrip.(a), ustrip.(A)) end # Heterogeneous units across coordinates, not just a single uniform unit. H = Quantity[4.0u"m^-2" 1.0u"m^-1*mm^-1"; 1.0u"m^-1*mm^-1" 4.0u"mm^-2"] h = symcover(H) - for ϕ in ϕs - @test cover_objective(ϕ, h, H) == cover_objective(ϕ, ustrip.(h), ustrip.(H)) + for ρ in ρs + @test cover_objective(ρ, h, H) == cover_objective(ρ, ustrip.(h), ustrip.(H)) end # The asymmetric form, whose row and column scales carry different units. ru, cu = (u"m", u"s"), (u"kg", u"K", u"m/s") B = [1.0 / (r * c) for r in ru, c in cu] .* [1e3 1e-2 5.0; 2.0 1e4 1e-1] ab, bb = cover(B) - for ϕ in ϕs - s = cover_objective(ϕ, ab, bb, B) + for ρ in ρs + s = cover_objective(ρ, ab, bb, B) @test s isa Float64 - @test s == cover_objective(ϕ, ustrip.(ab), ustrip.(bb), ustrip.(B)) + @test s == cover_objective(ρ, ustrip.(ab), ustrip.(bb), ustrip.(B)) end # Scale invariance: renaming the units cannot change a dimensionless score. @@ -365,8 +365,8 @@ # absolute tolerance is meaningful here. U2 = (u"mm", u"km/hr", u"kN") A2 = [uconvert(unit(1 / (u * v)), A[i, j]) for (i, u) in enumerate(U2), (j, v) in enumerate(U2)] - for ϕ in ϕs - @test cover_objective(ϕ, symcover(A2), A2) ≈ cover_objective(ϕ, a, A) atol = 1e-12 + for ρ in ρs + @test cover_objective(ρ, symcover(A2), A2) ≈ cover_objective(ρ, a, A) atol = 1e-12 end end From 4f9ce24972657e09af6196ec6e48f1803ecd55aa Mon Sep 17 00:00:00 2001 From: Tim Holy Date: Sun, 25 Oct 2026 09:50:06 -0500 Subject: [PATCH 3/4] Evaluate penalties on the log slack MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Built-in penalties are now functions of the log slack z = log(a[i]*b[j]) - log|A[i,j]| instead of the ratio r = |A[i,j]|/(a[i]*b[j]): AbsLog{p}: ρ(z) = |z|^p AbsLinear{p}: ρ(z) = |1 - exp(-z)|^p PowerMean{p}: ρ(z) = (exp(-p z) - 1 + p z)/p A user-defined AbstractCoverPenalty must likewise be callable on z. cover_objective sums only over the nonzero entries of A and never evaluates the penalty on a zero entry. A nonzero entry over a zero scale product has z = -Inf, where every built-in penalty is infinite. For AbsLinear, zero entries no longer add a constant 1 each, and the Ipopt soft-cover models drop the same constant, so the objective they report matches cover_objective. Assisted-by: Claude Opus 5.5 --- ext/MatrixCoversIpoptExt.jl | 15 ++---- src/penalties.jl | 100 ++++++++++++++++++------------------ test/extensions.jl | 12 +++-- test/penalties.jl | 73 ++++++++++++++++++-------- 4 files changed, 114 insertions(+), 86 deletions(-) diff --git a/ext/MatrixCoversIpoptExt.jl b/ext/MatrixCoversIpoptExt.jl index 8e961da..d8112b9 100644 --- a/ext/MatrixCoversIpoptExt.jl +++ b/ext/MatrixCoversIpoptExt.jl @@ -300,13 +300,12 @@ function MatrixCovers.soft_symcover!(::AbsLinear{2}, a::AbstractVector, A) fi, fj, flog = _sym_edge_list(A, T) supported = _degrees(fi, n) .> 0 ti, tj, tlog, tw = _triangle(fi, fj, flog) - n_zeros = n^2 - length(fi) # a zero entry contributes (1-0)^2 = 1 regardless of α model = _ipopt_model(; unscaled=true) start0 = [supported[k] ? log(T(a[pr[k]])) : zero(T) for k in 1:n] @variable(model, α[k=1:n], start = start0[k]) @objective(model, Min, - sum(tw[k] * (1 - exp(tlog[k] - α[ti[k]] - α[tj[k]]))^2 for k in eachindex(ti)) + n_zeros) + sum(tw[k] * (1 - exp(tlog[k] - α[ti[k]] - α[tj[k]]))^2 for k in eachindex(ti))) JuMP.optimize!(model) stats = solved_stats(model, "soft_symcover!") lα = JuMP.value.(α) @@ -326,7 +325,6 @@ function MatrixCovers.soft_symcover!(::AbsLinear{1}, a::AbstractVector, A) fi, fj, flog = _sym_edge_list(A, T) supported = _degrees(fi, n) .> 0 ti, tj, tlog, tw = _triangle(fi, fj, flog) - n_zeros = n^2 - length(fi) # a zero entry contributes |1 - 0| = 1 regardless of α model = _ipopt_model() start0 = [supported[k] ? log(T(a[pr[k]])) : zero(T) for k in 1:n] @@ -336,7 +334,7 @@ function MatrixCovers.soft_symcover!(::AbsLinear{1}, a::AbstractVector, A) @constraint(model, 1 - exp(tlog[k] - α[ti[k]] - α[tj[k]]) <= t[k]) @constraint(model, -1 + exp(tlog[k] - α[ti[k]] - α[tj[k]]) <= t[k]) end - @objective(model, Min, sum(tw[k] * t[k] for k in eachindex(ti)) + n_zeros) + @objective(model, Min, sum(tw[k] * t[k] for k in eachindex(ti))) JuMP.optimize!(model) stats = solved_stats(model, "soft_symcover!") lα = JuMP.value.(α) @@ -349,8 +347,7 @@ end # ============================================================ # Soft cover: soft_cover!(::AbsLinear{p}, a, b, A) -# Asymmetric soft-cover model. Post-processing balances component gauges; zero -# entries contribute the constant `ρ(0) = 1`. +# Asymmetric soft-cover model. Post-processing balances component gauges. # ============================================================ function MatrixCovers.soft_cover!(::AbsLinear{2}, a::AbstractVector, b::AbstractVector, A) @@ -362,7 +359,6 @@ function MatrixCovers.soft_cover!(::AbsLinear{2}, a::AbstractVector, b::Abstract ei, ej, elog = _edge_list(A, T) nza = _degrees(ei, m) nzb = _degrees(ej, n) - n_zeros = m * n - length(ei) model = _ipopt_model(; unscaled=true) α0 = [nza[i] > 0 ? log(T(a[pr[i]])) : zero(T) for i in 1:m] @@ -370,7 +366,7 @@ function MatrixCovers.soft_cover!(::AbsLinear{2}, a::AbstractVector, b::Abstract @variable(model, α[i=1:m], start = α0[i]) @variable(model, β[j=1:n], start = β0[j]) @objective(model, Min, - sum((1 - exp(elog[e] - α[ei[e]] - β[ej[e]]))^2 for e in eachindex(ei)) + n_zeros) + sum((1 - exp(elog[e] - α[ei[e]] - β[ej[e]]))^2 for e in eachindex(ei))) _pin_gauge!(model, α, β, A, nza, nzb) JuMP.optimize!(model) stats = solved_stats(model, "soft_cover!") @@ -395,7 +391,6 @@ function MatrixCovers.soft_cover!(::AbsLinear{1}, a::AbstractVector, b::Abstract ei, ej, elog = _edge_list(A, T) nza = _degrees(ei, m) nzb = _degrees(ej, n) - n_zeros = m * n - length(ei) model = _ipopt_model() α0 = [nza[i] > 0 ? log(T(a[pr[i]])) : zero(T) for i in 1:m] @@ -407,7 +402,7 @@ function MatrixCovers.soft_cover!(::AbsLinear{1}, a::AbstractVector, b::Abstract @constraint(model, 1 - exp(elog[e] - α[ei[e]] - β[ej[e]]) <= t[e]) @constraint(model, -1 + exp(elog[e] - α[ei[e]] - β[ej[e]]) <= t[e]) end - @objective(model, Min, sum(t) + n_zeros) + @objective(model, Min, sum(t)) _pin_gauge!(model, α, β, A, nza, nzb) JuMP.optimize!(model) stats = solved_stats(model, "soft_cover!") diff --git a/src/penalties.jl b/src/penalties.jl index 40b1a5b..f92db9a 100644 --- a/src/penalties.jl +++ b/src/penalties.jl @@ -1,5 +1,5 @@ # ============================================================ -# ρ types +# Penalty types # ============================================================ """ @@ -8,17 +8,23 @@ Supertype of cover penalties. Built-in subtypes are [`AbsLog`](@ref), [`AbsLinear`](@ref), and [`PowerMean`](@ref). -[`cover_objective`](@ref) applies the penalty to -`r = |A[i,j]|/(a[i]*b[j])` and sums over `A`. +A penalty is a function `ρ(z)` of the log slack + + z = log(a[i]*b[j]) - log|A[i,j]| = -log(r), r = |A[i,j]|/(a[i]*b[j]), + +of a nonzero entry of `A`. A hard cover has `z ≥ 0` on every nonzero entry, +`z = 0` marks a tight entry, and `z < 0` an entry the cover violates. +[`cover_objective`](@ref) sums `ρ(z)` over the nonzero entries of `A`. # Extending -A subtype must be callable on a nonnegative real: +A subtype must be callable on a real log slack: - (::MyPenalty)(r::Real) + (::MyPenalty)(z::Real) -The method must accept `r = 0` and `r = typemax(...)`. Penalties are usually -singleton structs. +The method must accept `z = -Inf`, which [`cover_objective`](@ref) passes for a +nonzero entry over a zero product `a[i]*b[j]`, and `z = Inf`, which it passes +when the ratio underflows to zero. Penalties are usually singleton structs. [`cover_objective`](@ref) works for any subtype, but solvers support only specific built-in penalties: @@ -35,14 +41,14 @@ abstract type AbstractCoverPenalty<:Function end """ AbsLog{p} -Penalty type for +The ℓ_p penalty on the log slack, - ρ(r) = |log(r)|^p if r > 0 - 0 if r = 0 + ρ(z) = |z|^p. -Defining `ρ(0) = 0` makes zero entries of `A`, for which `log(r) = -∞`, -contribute nothing to the objective. The objective is convex in the logarithms -of the scales; `AbsLog{1}` may have multiple minima. +`AbsLog{1}` gives the ℓ₁ objective, a linear program, and `AbsLog{2}` the ℓ₂ +objective, whose minimizer among hard covers is the ℓ₂-minimal cover. The +objective is convex in the logarithms of the scales; +`AbsLog{1}` may have multiple minima. `ρ(±Inf) = Inf`. See also: [`AbsLinear`](@ref). """ @@ -51,9 +57,13 @@ struct AbsLog{p} <: AbstractCoverPenalty end """ AbsLinear{p} -Penalty type for `ρ(r) = |1 - r|^p`. Unlike [`AbsLog`](@ref), this penalty is -continuous at `r = 0`, so each zero entry of `A` contributes `ρ(0) = 1` to the -objective. +Penalty type for + + ρ(z) = |1 - exp(-z)|^p, + +which is `|1 - r|^p` in the ratio `r = exp(-z)`. It is bounded for slack +entries, approaching `ρ(Inf) = 1`, and grows exponentially for violated ones, +with `ρ(-Inf) = Inf`. The resulting optimization problems are not convex and may have multiple local minima. @@ -65,11 +75,10 @@ struct AbsLinear{p} <: AbstractCoverPenalty end Penalty type for - ρ(r) = (r^p - 1 - p*log(r)) / p if r > 0 - 0 if r = 0 + ρ(z) = (exp(-p*z) - 1 + p*z) / p, -with `p > 0`. As for [`AbsLog`](@ref), defining `ρ(0) = 0` makes zero entries -of `A` contribute nothing. +with `p > 0`. In the ratio `r = exp(-z)`, this is `(r^p - 1 - p*log(r)) / p`. +`ρ(±Inf) = Inf`. `PowerMean{2}` is the default penalty for soft covers. For entries modeled as independent normal variables with standard deviations `a[i]*b[j]`, it gives the @@ -93,15 +102,15 @@ struct PowerMean{p} <: AbstractCoverPenalty end end -(::AbsLog{p})(r::Real) where p = iszero(r) ? zero(float(r)) : abs(log(r))^p -(::AbsLinear{p})(r::Real) where p = abs(oneunit(r) - r)^p -# `expm1(t) - t` avoids the cancellation in `r^p - 1 - t` near `r = 1`. -function (::PowerMean{p})(r::Real) where p - rf = float(r) - iszero(rf) && return zero(rf) - isinf(rf) && return rf - t = p * log(rf) - return (expm1(t) - t) / p +(::AbsLog{p})(z::Real) where p = abs(float(z))^p +(::AbsLinear{p})(z::Real) where p = abs(expm1(-float(z)))^p +# `expm1(-t) + t` avoids the cancellation in `exp(-t) - 1 + t` near `z = 0`. At +# `z = -Inf` that sum is `Inf - Inf`. +function (::PowerMean{p})(z::Real) where p + zf = float(z) + zf == -Inf && return -zf + t = p * zf + return (expm1(-t) + t) / p end # ============================================================ @@ -131,15 +140,14 @@ end cover_objective(ρ, a, b, A) cover_objective(ρ, a, A) -Compute `∑ ρ(|A[i,j]|/(a[i]*b[j]))`. The shorter form uses the symmetric cover -`a*a'`. - -Both forms sum over every entry of `A`, so in the symmetric form each -off-diagonal pair contributes twice and each diagonal entry once. +Compute `∑ ρ(z[i,j])` over the nonzero entries of `A`, where +`z[i,j] = log(a[i]*b[j]) - log|A[i,j]|` is the log slack. The shorter form uses +the symmetric cover `a*a'`. -Zero entries of `A` are handled according to `ρ`: -- `AbsLog{p}`, `PowerMean{p}`: zero entries contribute 0 (ρ(0) = 0 by convention). -- `AbsLinear{p}`: zero entries contribute 1 (ρ(0) = |1-0|^p = 1). +Both forms sum over every nonzero entry of `A`, so in the symmetric form each +off-diagonal pair contributes twice and each diagonal entry once. Zero entries +of `A` constrain nothing and are excluded from the sum; `ρ` is never evaluated +for them. A nonzero entry over a zero product `a[i]*b[j]` has `z = -Inf`. `eachindex(a)` must match `axes(A, 1)` and `eachindex(b)` must match `axes(A, 2)`. @@ -156,22 +164,14 @@ function cover_objective(ρ, a, b, A) throw(DimensionMismatch("indices of `b` must match column-indexing of `A`, got eachindex(b)=$(string(eachindex(b))), axes(A, 2)=$(string(axes(A, 2)))")) T = promote_type(objective_type(A), objective_type(a), objective_type(b)) s = Ref(zero(T)) - nsupport = Ref(0) foreach_support(A) do i, j, v ab = a[i] * b[j] - # A nonzero entry over a zero scale is uncovered; `typemax` is the ratio's - # stand-in for the infinite excess. - r = iszero(ab) ? typemax(T) : T(v / ab) - s[] += T(ρ(r)) - nsupport[] += 1 + # The slack comes from the unitless ratio, so scales and entries may carry + # units. A nonzero entry over a zero scale is uncovered by an infinite amount. + z = iszero(ab) ? -T(Inf) : -log(T(v / ab)) + s[] += T(ρ(z)) end - # Every entry outside the support has `r = 0` whatever its scales, including a - # zero entry over a zero scale, which constrains nothing. They therefore share - # one penalty value, and only their count is needed: zero for `AbsLog` and - # `PowerMean`, but a nonzero constant for `AbsLinear`, which is continuous at `r = 0`. - # The guard prevents `0 * Inf` for penalties that are infinite at zero. - nzero = length(a) * length(b) - nsupport[] - return iszero(nzero) ? s[] : s[] + nzero * T(ρ(zero(T))) + return s[] end cover_objective(ρ, a, A) = cover_objective(ρ, a, a, A) diff --git a/test/extensions.jl b/test/extensions.jl index f1175fe..2a87f1e 100644 --- a/test/extensions.jl +++ b/test/extensions.jl @@ -95,12 +95,14 @@ end a1, _ = soft_symcover(AbsLinear{1}(), A_rank1) @test cover_objective(AbsLinear{1}(), a1, A_rank1) < 1e-8 - # Matrix with zeros: zero entries contribute 1 each regardless of cover - A = [0.0 1.0; 1.0 0.0] # only off-diagonal nonzero; min possible = 0 (off-diag) + 2 (diag zeros) - a2, _ = soft_symcover(AbsLinear{2}(), A) - @test cover_objective(AbsLinear{2}(), a2, A) ≈ 2.0 atol=1e-8 + # Matrix with zeros: zero entries are excluded, so the off-diagonal pair can be + # fit exactly + A = [0.0 1.0; 1.0 0.0] + a2, s2 = soft_symcover(AbsLinear{2}(), A) + @test cover_objective(AbsLinear{2}(), a2, A) ≈ 0.0 atol=1e-8 + @test only(s2.stats[s2.selected].objective) ≈ 0.0 atol=1e-8 a1, _ = soft_symcover(AbsLinear{1}(), A) - @test cover_objective(AbsLinear{1}(), a1, A) ≈ 2.0 atol=1e-8 + @test cover_objective(AbsLinear{1}(), a1, A) ≈ 0.0 atol=1e-8 end @testset "AbsLinear{2} soft refinement converges from dispersed starts" begin diff --git a/test/penalties.jl b/test/penalties.jl index 92af1c3..4b87922 100644 --- a/test/penalties.jl +++ b/test/penalties.jl @@ -7,33 +7,63 @@ @test cover_objective(AbsLog{1}(), a, A) ≈ sum(abs(log(a[i]*a[j]/abs(A[i,j]))) for i in 1:2, j in 1:2 if A[i,j] != 0) # AbsLog{2}: sum of squared log-domain excesses @test cover_objective(AbsLog{2}(), a, A) ≈ sum(abs(log(a[i]*a[j]/abs(A[i,j])))^2 for i in 1:2, j in 1:2 if A[i,j] != 0) - # AbsLinear{1} and AbsLinear{2}: ratio deviations from 1 (ALL entries, including zeros) + # AbsLinear{1} and AbsLinear{2}: ratio deviations from 1 @test cover_objective(AbsLinear{1}(), a, A) ≈ sum(abs(abs(A[i,j])/(a[i]*a[j]) - 1) for i in 1:2, j in 1:2) @test cover_objective(AbsLinear{2}(), a, A) ≈ sum((abs(A[i,j])/(a[i]*a[j]) - 1)^2 for i in 1:2, j in 1:2) # Two-argument form equals one-argument form @test cover_objective(AbsLog{2}(), a, a, A) == cover_objective(AbsLog{2}(), a, A) @test cover_objective(AbsLinear{2}(), a, a, A) == cover_objective(AbsLinear{2}(), a, A) - # AbsLog{p}: zero entries contribute 0 + # Zero entries are excluded from the sum for every penalty A0 = [1.0 0.0; 0.0 5.0] a0 = [1.0, 2.0] @test cover_objective(AbsLog{1}(), a0, A0) ≈ log(5/4) @test cover_objective(AbsLog{2}(), a0, A0) ≈ log(5/4)^2 - # AbsLinear{p}: zero entries contribute 1 each - @test cover_objective(AbsLinear{1}(), a0, A0) ≈ 0.0 + 1.0 + 1.0 + 1/4 # (0,1), (1,0) off-diag zeros - @test cover_objective(AbsLinear{2}(), a0, A0) ≈ 0.0 + 1.0 + 1.0 + 1/16 # (0,1), (1,0) off-diag zeros + @test cover_objective(AbsLinear{1}(), a0, A0) ≈ 1/4 + @test cover_objective(AbsLinear{2}(), a0, A0) ≈ 1/16 + @test cover_objective(PowerMean{2}(), a0, A0) ≈ ((5/4)^2 - 1 - 2 * log(5/4)) / 2 +end + +@testset "Penalties in the log slack" begin + zs = (-3.0, -0.4, 0.0, 1e-3, 0.7, 5.0) + for p in (1, 2, 3) + for z in zs + @test AbsLog{p}()(z) ≈ abs(z)^p + @test AbsLinear{p}()(z) ≈ abs(1 - exp(-z))^p atol=1e-15 + end + # Tight entries cost nothing. + @test AbsLog{p}()(0.0) === 0.0 + @test AbsLinear{p}()(0.0) === 0.0 + # Infinite slack in either direction. + @test AbsLog{p}()(Inf) === Inf + @test AbsLog{p}()(-Inf) === Inf + @test AbsLinear{p}()(Inf) === 1.0 + @test AbsLinear{p}()(-Inf) === Inf + end + @test AbsLog{2}()(3) === 9.0 + @test AbsLog{2}()(-0.5f0) isa Float32 + @test AbsLinear{2}()(0.5f0) isa Float32 + # The ratio form `|1 - r|^p` at `r = exp(-z)`. + for r in (0.0, 0.25, 1.0, 3.0) + @test AbsLinear{2}()(-log(r)) ≈ (1 - r)^2 + end end @testset "PowerMean" begin - ρ(p, r) = (r^p - 1 - p * log(r)) / p - for p in (1, 2, 3.5, 0.5), r in (1e-3, 0.3, 1.0, 1.7, 40.0) - @test PowerMean{p}()(r) ≈ ρ(p, r) rtol=1e-12 atol=1e-15 + ρ(p, z) = (exp(-p * z) - 1 + p * z) / p + for p in (1, 2, 3.5, 0.5), z in (-3.7, -0.5, 0.0, 1e-2, 1.2, 6.9) + @test PowerMean{p}()(z) ≈ ρ(p, z) rtol=1e-12 atol=1e-15 end - # Accurate near r = 1, where the formula cancels to O(log(r)^2). - @test PowerMean{2}()(1 + 1e-9) ≈ 1e-18 rtol=1e-6 - @test PowerMean{2}()(1.0) == 0 - # Zero is the structural-zero convention; an uncovered entry is infinite. + # The ratio form `(r^p - 1 - p log r)/p` at `r = exp(-z)`. + for p in (1, 2), r in (1e-3, 0.3, 1.7, 40.0) + @test PowerMean{p}()(-log(r)) ≈ (r^p - 1 - p * log(r)) / p rtol=1e-12 + end + # Accurate near z = 0, where the formula cancels to O(z^2). + @test PowerMean{2}()(1e-9) ≈ 1e-18 rtol=1e-6 @test PowerMean{2}()(0.0) === 0.0 @test PowerMean{2}()(Inf) === Inf + @test PowerMean{2}()(-Inf) === Inf + @test PowerMean{0.5}()(-Inf) === Inf + @test PowerMean{2}()(-1000.0) === Inf @test PowerMean{2}()(Float32(0.5)) isa Float32 @test_throws "requires a real exponent p > 0" PowerMean{0}() @test_throws "requires a real exponent p > 0" PowerMean{-1.0}() @@ -45,7 +75,7 @@ end for p in (1, 2) E = cover_objective(PowerMean{p}(), a, b, A) @test isfinite(E) - @test E ≈ sum(ρ(p, abs(A[i, j]) / (a[i] * b[j])) for i in 1:3, j in 1:3 if A[i, j] != 0) + @test E ≈ sum(ρ(p, log(a[i] * b[j] / abs(A[i, j]))) for i in 1:3, j in 1:3 if A[i, j] != 0) @test cover_objective(PowerMean{p}(), a, b, sparse(A)) ≈ E end end @@ -76,24 +106,25 @@ end a, b = [2.0, 1.0, 0.5], [1.5, 0.5, 3.0, 1.0] for ρ in SOFT_PENALTIES # Agreement with the dense reference pins the zero-entry accounting: the - # entries the hook skips still carry `ρ(0)`, which `AbsLinear` makes nonzero. + # entries the hook skips are excluded from the dense sum as well. @test cover_objective(ρ, a, b, M) ≈ cover_objective(ρ, a, b, dense) end # A zero scale under a nonzero entry is uncovered, and under a zero entry is not. az = [0.0, 1.0, 0.5] - @test isinf(cover_objective(AbsLog{2}(), az, b, M)) + for ρ in SOFT_PENALTIES + @test cover_objective(ρ, az, b, M) === Inf + end # Column 4 carries no support, so zeroing its scale constrains nothing. @test isfinite(cover_objective(AbsLog{2}(), a, [1.5, 0.5, 3.0, 0.0], M)) @test cover_objective(AbsLog{2}(), b, a, M') ≈ cover_objective(AbsLog{2}(), a, b, dense) - # A penalty infinite at `r = 0` is legal, and a matrix with no zero entries must - # not pick up its value: the zero-entry term is skipped, not multiplied by zero. - infatzero(r) = iszero(r) ? Inf : abs(log(r)) - @test cover_objective(infatzero, [1.0, 1.0], [1.0, 1.0], [1.0 2.0; 3.0 4.0]) ≈ - sum(abs(log(v)) for v in (1.0, 2.0, 3.0, 4.0)) - @test isinf(cover_objective(infatzero, [1.0, 1.0], [1.0, 1.0], [1.0 0.0; 3.0 4.0])) + # Any function of the log slack is accepted, and it is never evaluated on a zero + # entry: one that fails at `z = Inf` still scores a matrix with zeros. + finiteonly(z) = (isfinite(z) || error("evaluated at z = $z"); abs(z)) + @test cover_objective(finiteonly, [1.0, 1.0], [1.0, 1.0], [1.0 0.0; 3.0 4.0]) ≈ + sum(log(v) for v in (1.0, 3.0, 4.0)) end @testset "cover_objective: index checking" begin From dbbbe9271bc11938f892efff3b21ff8943ed5d6f Mon Sep 17 00:00:00 2001 From: Tim Holy Date: Sun, 25 Oct 2026 09:54:48 -0500 Subject: [PATCH 4/4] Document penalties as functions of the log slack MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit State the cover objective as a sum of ρ(z) over the nonzero entries of A, with z = log(a[i]*b[j]) - log|A[i,j]|, and name the AbsLog cases by their ℓ_p norms. Write the solver docstrings, the cover_transversal target objective, the documentation pages, and the README in the same terms. Assisted-by: Claude Opus 5.5 --- README.md | 8 +++--- docs/src/index.md | 4 +-- docs/src/objectives.md | 55 +++++++++++++++++++++++++++--------------- src/balanced.jl | 13 +++++----- src/minimal_covers.jl | 14 ++++++----- src/soft_covers.jl | 7 +++--- 6 files changed, 62 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 74aeb0b..bd1f145 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,11 @@ to [bounds on $`\hat A`$'s eigenvalues](https://en.wikipedia.org/wiki/Gershgorin The package provides O(mn) heuristics (`symcover`, `cover`), *soft* covers that penalize violations (`soft_symcover`, `soft_cover`), and objective-minimal hard -covers (`symcover_min`, `cover_min`). The default penalties, squared-log for -hard covers and the power-mean penalty `PowerMean{2}` for soft covers, use -built-in solvers; other penalties use JuMP with HiGHS or Ipopt. +covers (`symcover_min`, `cover_min`). Penalties are functions of the log slack +`z = log(a[i]*b[j]) - log|A[i,j]|` of each nonzero entry. The defaults, the ℓ₂ +penalty `AbsLog{2}` (`z^2`) for hard covers and the power-mean penalty +`PowerMean{2}` for soft covers, use built-in solvers; other penalties use JuMP +with HiGHS or Ipopt. ## Installation diff --git a/docs/src/index.md b/docs/src/index.md index 9fd42fd..9d6fbfe 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -13,8 +13,8 @@ C_{ij} \;\geq\; |A_{ij}| \quad \text{for all } i, j. ``` For symmetric `A`, a single vector suffices (`b = a`). A matrix has many hard -covers; a *minimal cover* is the one that minimizes a chosen penalty on the gap -between `C` and `|A|`. A *soft cover* penalizes violations of the inequality +covers; a *minimal cover* is the one that minimizes a chosen penalty on the log +slack `log C[i,j] - log|A[i,j]|` of each nonzero entry. A *soft cover* penalizes violations of the inequality instead of enforcing it. ## Installation diff --git a/docs/src/objectives.md b/docs/src/objectives.md index d6a5bea..8532ada 100644 --- a/docs/src/objectives.md +++ b/docs/src/objectives.md @@ -7,27 +7,44 @@ CurrentModule = MatrixCovers ## Penalty functions Any hard cover is valid, but tighter covers better capture the scaling of `A`. -The tightness of a cover is measured through the ratios -`r[i, j] = |A[i,j]| / (a[i] * b[j])`: a hard cover has every `0 ≤ r[i, j] ≤ 1`, -and `r[i, j] == 1` means the constraint is exactly tight. +The tightness of a cover is measured on each nonzero entry by the coverage ratio +`r[i, j] = |A[i,j]| / (a[i] * b[j])`, or equivalently by the log slack -A **penalty function** `ϕ` combines those ratios into a scalar objective: +```math +z_{ij} = \log(a_i b_j) - \log|A_{ij}| = -\log r_{ij}. +``` + +A hard cover has every `z[i, j] ≥ 0` (every `r[i, j] ≤ 1`), `z[i, j] == 0` means +the constraint is exactly tight, and `z[i, j] < 0` marks an entry the cover +violates. + +A **penalty function** `ρ` combines the log slacks into a scalar objective, a +sum over the nonzero entries of `A`: ```math -\sum_{i,j} \phi\!\left(\frac{|A_{ij}|}{a_i\, b_j}\right). +E = \sum_{i,j:\, A_{ij} \ne 0} \rho(z_{ij}). ``` -Three penalty families are provided: +Zero entries constrain nothing and are excluded from the sum. A nonzero entry +over a zero product `a[i] * b[j]` has `z = -∞`, and every built-in penalty is +infinite there. + +Three penalty families are provided, all parameterized by an exponent `p`: + +- [`AbsLog`](@ref)`{p}`: `ρ(z) = |z|^p`, the ℓ_p penalty on the log slacks. + `AbsLog{1}` gives the ℓ₁ objective, a linear program, and `AbsLog{2}` the ℓ₂ + objective, whose minimizer among hard covers is the ℓ₂-minimal cover. It is + convex in log space, and `AbsLog{2}` is the default for hard covers. +- [`PowerMean`](@ref)`{p}`: `ρ(z) = (exp(-p z) - 1 + p z)/p`, which is + `(r^p - 1 - p log r)/p` in the ratio. It is strictly convex in log space and + power-mean `p = 2` is the default for soft covers. Its minimizer makes the + mean of `r^p` over the nonzero entries of every row and column equal to one. +- [`AbsLinear`](@ref)`{p}`: `ρ(z) = |1 - exp(-z)|^p`, which is `|1 - r|^p` in + the ratio. It is nonconvex. On entries the cover satisfies it is at most one, + approaching one as `r → 0`, so a small entry costs a soft cover at most a + bounded amount; an exact zero is excluded from the sum and costs nothing. -- [`AbsLog`](@ref)`{p}`: `ϕ(r) = |log r|^p`, with `ϕ(0) = 0`. It is convex in - log space and is the default for hard covers. -- [`PowerMean`](@ref)`{p}`: `ϕ(r) = (r^p - 1 - p log r)/p`, with `ϕ(0) = 0`. It - is strictly convex in log space and is the default for soft covers. Its - minimizer makes the mean of `r^p` over the nonzero entries of every row and - column equal to one. -- [`AbsLinear`](@ref)`{p}`: `ϕ(r) = |1-r|^p`. It is nonconvex but finite and - continuous at zero, so an entry that shrinks to zero drops out of the soft - cover continuously. +A penalty object is callable on a log slack: `AbsLog{2}()(z)` returns `z^2`. [`cover_objective`](@ref) evaluates any penalty for a given cover: @@ -41,10 +58,10 @@ julia> a = symcover(A) 2.0 4.0 -julia> cover_objective(AbsLog{1}(), a, A) # sum of log-excesses (L1) +julia> cover_objective(AbsLog{1}(), a, A) # ℓ₁: sum of log slacks 2.772588722239781 -julia> cover_objective(AbsLog{2}(), a, A) # sum of squared log-excesses (L2) +julia> cover_objective(AbsLog{2}(), a, A) # ℓ₂: sum of squared log slacks 3.843624111345611 ``` @@ -68,8 +85,8 @@ their `_min` counterparts minimize the selected objective. covers that are tight on a maximum-product transversal (see [Transversals and conditioning](@ref)); with a `PowerMean{p}` penalty and a `target` ratio `t`, it instead pushes the ratios of the entries off the -transversal toward `t`, minimizing `∑ t^p φ(r/t)` over them with `φ` the -`PowerMean{p}` penalty. Adding `maxbalance=true` replaces that objective within +transversal toward `t`, minimizing `∑ t^p ρ(z + log t)` over them with `ρ` the +`PowerMean{p}` penalty, which is least at `z = -log t`, where `r = t`. Adding `maxbalance=true` replaces that objective within each fully indecomposable block by its `p → ∞` limit, max-balancing: across every partition of a block's rows, the largest ratio in one direction equals the largest in the other, which also minimizes the block's largest ratio. The diff --git a/src/balanced.jl b/src/balanced.jl index d3aed69..3a382db 100644 --- a/src/balanced.jl +++ b/src/balanced.jl @@ -32,16 +32,17 @@ const BALANCED_RIDGE_GROWTH = 1e4 Return the hard cover of the square matrix `A` that is tight on its maximum-product transversals and pushes the coverage ratios -`r = |A[i,j]| / (a[i]*b[j])` of the other nonzero entries toward `target`: it -minimizes +`r = |A[i,j]| / (a[i]*b[j])` of the other nonzero entries toward `target`. In +terms of the log slack `z = -log(r)`, it minimizes - ∑ (r^p - 1 - p*log(r/target)*target^p) / p, + ∑ ((exp(-p*z) - 1)/p + target^p * z), the sum taken over the nonzero entries off the transversals, among the hard covers with `prod(a) * prod(b) == π*` (see [`cover_transversal(A)`](@ref -cover_transversal)). Each term is `target^p * ρ(r/target)` up to a constant, with -`ρ` the [`PowerMean{p}`](@ref) penalty, so it is least at `r = target`; the hard -constraint caps every ratio at one, and the transversal entries have ratio one. +cover_transversal)). Each term is `target^p * ρ(z + log(target))` up to a +constant, with `ρ` the [`PowerMean{p}`](@ref) penalty, so it is least at +`z = -log(target)`, where `r = target`; the hard constraint keeps every `z ≥ 0` +(every ratio at most one), and the transversal entries have `z = 0`. `0 < target <= 1` and `0 < p < ∞` are required; otherwise an `ArgumentError` is thrown. `cover_transversal(AbsLog{2}(), A)` is `cover_transversal(A)`. diff --git a/src/minimal_covers.jl b/src/minimal_covers.jl index 6dd6533..28e3855 100644 --- a/src/minimal_covers.jl +++ b/src/minimal_covers.jl @@ -9,9 +9,10 @@ a, stats = symcover_min(ρ, A; kwargs...) a, stats = symcover_min(A; kwargs...) -Return the ρ-minimal symmetric hard cover of `A`: the vector `a` minimizing -`∑ ρ(|A[i,j]|/(a[i]*a[j]))` subject to `a[i]*a[j] >= |A[i,j]|`. The -default penalty is `AbsLog{2}()`. +Return the symmetric hard cover of `A` that minimizes the penalty `ρ`: the +vector `a` minimizing `∑ ρ(log(a[i]*a[j]) - log|A[i,j]|)` over the nonzero +entries of `A`, subject to `a[i]*a[j] >= |A[i,j]|`. The default penalty is +`AbsLog{2}()`, which gives the ℓ₂-minimal cover. Supported ρ values: - `AbsLog{2}()`: native. @@ -94,9 +95,10 @@ symcover_min(A::AbstractMatrix; kwargs...) = symcover_min(AbsLog{2}(), A; kwargs a, b, stats = cover_min(ρ, A; kwargs...) a, b, stats = cover_min(A; kwargs...) -Return the ρ-minimal asymmetric hard cover of `A`: vectors `a`, `b` minimizing -`∑ ρ(|A[i,j]|/(a[i]*b[j]))` subject to `a[i]*b[j] >= |A[i,j]|`. The -default penalty is `AbsLog{2}()`. +Return the asymmetric hard cover of `A` that minimizes the penalty `ρ`: +vectors `a`, `b` minimizing `∑ ρ(log(a[i]*b[j]) - log|A[i,j]|)` over the +nonzero entries of `A`, subject to `a[i]*b[j] >= |A[i,j]|`. The default penalty +is `AbsLog{2}()`, which gives the ℓ₂-minimal cover. The objective and the constraints depend only on the products `a[i]*b[j]`, which do not change when `a` is multiplied by `c` and `b` divided by `c` on one diff --git a/src/soft_covers.jl b/src/soft_covers.jl index ef366fa..cd6efb8 100644 --- a/src/soft_covers.jl +++ b/src/soft_covers.jl @@ -8,8 +8,8 @@ a, stats = soft_symcover(ρ, A; kwargs...) a, stats = soft_symcover(A; kwargs...) -Return the scales `a` that minimize `∑ ρ(|A[i,j]|/(a[i]*a[j]))` for symmetric -`A`. Unlike a hard cover, this soft cover penalizes violations of +Return the scales `a` that minimize `∑ ρ(log(a[i]*a[j]) - log|A[i,j]|)` over +the nonzero entries of symmetric `A`. Unlike a hard cover, this soft cover penalizes violations of `a[i]*a[j] >= |A[i,j]|` rather than forbidding them. The default penalty is `PowerMean{2}()`. @@ -150,7 +150,8 @@ end a, b, stats = soft_cover(ρ, A; kwargs...) a, b, stats = soft_cover(A; kwargs...) -Return the scales `a`, `b` that minimize `∑ ρ(|A[i,j]|/(a[i]*b[j]))`. This is +Return the scales `a`, `b` that minimize `∑ ρ(log(a[i]*b[j]) - log|A[i,j]|)` +over the nonzero entries of `A`. This is the asymmetric counterpart of [`soft_symcover`](@ref): it penalizes violations of `a[i]*b[j] >= |A[i,j]|` rather than forbidding them. The default penalty is `PowerMean{2}()`. `stats` and the failure behavior are as for