diff --git a/docs/src/objectives.md b/docs/src/objectives.md index 8532ada..45b837d 100644 --- a/docs/src/objectives.md +++ b/docs/src/objectives.md @@ -87,7 +87,9 @@ covers that are tight on a maximum-product transversal (see `target` ratio `t`, it instead pushes the ratios of the entries off the 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 +each fully indecomposable block by its limit as `t → 0` and then `p → ∞`, +max-balancing (at a fixed `t`, large `p` alone need not reach this limit when a +block holds ratios below `t`): 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 `PowerMean{p}` objective then fixes only the scales between blocks. A soft cover has no constraint to diff --git a/src/balanced.jl b/src/balanced.jl index 3a382db..151b27d 100644 --- a/src/balanced.jl +++ b/src/balanced.jl @@ -30,62 +30,90 @@ const BALANCED_RIDGE_GROWTH = 1e4 """ 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 -`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 +Return a hard cover of the square matrix `A` whose aim is to make the scaled +matrix `A ./ (a .* b')` as diagonally dominant as possible, given a permutation +that puts a maximum-product transversal on the diagonal. The cover is tight on +the maximum-product transversals, so their entries scale to magnitude one, and +it pushes the coverage ratios `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 ∑ ((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 * ρ(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)`. - -The objective is strictly convex in the products `a[i]*b[j]`, so they are -unique on the support of `A`. As for `cover_transversal(A)`, they do not depend -on which maximum-product transversal is used, they are scale-covariant, and the -factors use the balance convention of [`cover_min`](@ref). +cover_transversal)). Each term is least at `r = target`, and the hard +constraint keeps every ratio at most one. `0 < target <= 1` and `0 < p < ∞` are +required; otherwise an `ArgumentError` is thrown. +`cover_transversal(AbsLog{2}(), A)` is `cover_transversal(A)`. + +The products `a[i]*b[j]` are unique on the support of `A`. As for +`cover_transversal(A)`, they do not depend on which maximum-product transversal +is used, they are scale-covariant, and the factors use the balance convention +of [`cover_min`](@ref). With `target = 1`, every ratio is pushed up to one, as far as the constraints -allow. With small `target`, the ratios within each block of a block-triangular -form of `A` balance in the sense of the `p`-power mean, and the entries joining -different blocks are pushed toward `target`; at the minimizer, the `p`-power -mean of the ratios of the entries crossing such a cut equals `target` whenever -none of them has ratio one. Large `p` approaches the cover that minimizes the -largest ratio within each block. - -With `maxbalance=true`, the criterion within each fully indecomposable block of -`A` is the `p → ∞` limit of the objective (Hook, Pestana, Tisseur & Hogg, SIAM -J. Matrix Anal. Appl. 40:320–346, 2019, Theorem 3.2): the scales are -*max-balanced* within each block. Let `σ` be a maximum-product transversal, -and let an entry `A[i,j]` off it lead from row `i` to the row `k` with -`σ[k] == j`. For every partition of the rows of a block into two nonempty sets -`I` and `K`, the largest ratio of an entry leading from `I` to `K` equals the -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 -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 -blocks all lead out of, the `p`-power mean of the ratios of those entries -equals `target` whenever none of them has ratio one. -The result is a hard cover tight on the maximum-product transversals, and its -products are unique on the support and scale-covariant. +allow. With small `target`, the entries joining different blocks of a +block-triangular form of `A` are pushed toward `target`, while within each block +the scales approach those that minimize the sum of `r^p` over the block's +entries off the transversal. + +With `maxbalance=true`, the scales within each fully indecomposable block of `A` +are instead *max-balanced*, which minimizes the largest ratio within the block; +`ρ` and `target` then fix only the scales between blocks. Raising `p` at a fixed +`target` need not approach this result. `stats` is a [`BalancedCoverStats`](@ref MatrixCovers.BalancedCoverStats). The solver warns when [`MatrixCovers.converged(stats)`](@ref MatrixCovers.converged) is `false`; the result is then still a hard cover tight on the maximum-product transversals. +`A` must be square and structurally nonsingular. Narrower element types than +`Float64` are computed in `Float64` and narrowed, with the coverage certified +afterwards. + +See also: [`cover_transversal!`](@ref), [`PowerMean`](@ref). + # Extended help +## Characterization + +Each term of the objective is `target^p * ρ(z + log(target))` up to a constant, +with `ρ` the [`PowerMean{p}`](@ref) penalty, so it is least at +`z = -log(target)`. The hard constraint keeps every `z ≥ 0`, and the transversal +entries have `z = 0`. The objective is strictly convex in the products +`a[i]*b[j]`, which makes them unique on the support. + +Let `σ` be a maximum-product transversal; an entry `A[i,j]` off it *leads* from +row `i` to the row `k` with `σ[k] == j`. At the minimizer, the `p`-power mean of +the ratios of the entries crossing a cut between blocks of a block-triangular +form of `A` equals `target` whenever none of them has ratio one. + +Within each block, as `target → 0`, the scales approach those that minimize the +sum of `r^p` over the block's entries off the transversal, subject to the same +constraints. When no constraint binds, these are the *`p`-balanced* scales of +Hook, Pestana, Tisseur & Hogg (SIAM J. Matrix Anal. Appl. 40:320–346, 2019), +whose Theorem 3.2 shows that they approach the max-balanced scales of +`maxbalance=true` as `p → ∞`. At a fixed `target`, large `p` does not approach +them: where a block holds ratios below `target` and the entries leading out of +some set of its rows differ in number from those leading in, the minimizer +raises some of these ratios to about `target`. + +With `maxbalance=true`, for every partition of the rows of a fully +indecomposable block into two nonempty sets `I` and `K`, the largest ratio of an +entry leading from `I` to `K` equals the 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. The scales between blocks minimize the objective 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 blocks all lead out of, the `p`-power mean of the ratios of those entries +equals `target` whenever none of them has ratio one. The products are unique on +the support and scale-covariant. + +## Algorithm + As for `cover_transversal(A)`, tightness on a maximum-product transversal `σ` leaves the row log scales as unknowns, with one constraint `d ≥ 0` on the log slack `d = -log(r)` of each entry off the transversal. Starting from the @@ -115,6 +143,8 @@ dense random matrices the cost then grows about as `n^2.4` and is comparable to that of finding the transversal. The active-set Newton method then runs with one scale per block. +## Keywords + `tol` (default `1e-9`) is the stopping tolerance: the groups are stationary when the derivative of the objective with respect to each group's scale is at most `tol` times the sum of the magnitudes of its terms, or when roundoff keeps the @@ -130,12 +160,6 @@ accurate. The Newton systems have condition numbers of order `target^(-p)` times that of the graph, and of order `r^(-p)` where cycles of entries hold ratios `r` far below `target`, so a very small `target^p` or a large `p` degrades the linear solves and the convergence. - -`A` must be square and structurally nonsingular. Narrower element types than -`Float64` are computed in `Float64` and narrowed, with the coverage certified -afterwards. - -See also: [`cover_transversal!`](@ref), [`PowerMean`](@ref). """ function cover_transversal(ρ::PowerMean{p}, A::AbstractMatrix; target::Real=1e-2, maxbalance::Bool=false, diff --git a/src/heuristic_covers.jl b/src/heuristic_covers.jl index 71c3207..a6be949 100644 --- a/src/heuristic_covers.jl +++ b/src/heuristic_covers.jl @@ -115,7 +115,7 @@ entry is covered, and then applies `maxiter` improvement passes. nonsingular. Defaults: `cgiter=20`, `maxiter=5`. - `:unconstrained` approximates the unconstrained least-squares fit of the log scales and is scale-covariant (typically at the cost of - permutation-equivariance). `:covariant` is a deprecated alias. Defaults: `cgiter=16`, `maxiter=3`. + permutation-equivariance). Defaults: `cgiter=16`, `maxiter=3`. - `:geomean` makes the result permutation-equivariant up to floating-point round-off (typically at the cost of scale-covariance). Defaults as for `:unconstrained`. @@ -224,7 +224,7 @@ end function _cover!(a::AbstractVector, b::AbstractVector, A::AbstractMatrix; maxiter::Union{Int,Nothing}=nothing, cgiter::Union{Int,Nothing}=nothing, start::Symbol=:auto, fname::Symbol=:cover) - start = _normalize_cover_start(start) + _check_cover_start(start) T = float(promote_type(eltype(a), eltype(b))) if start === :auto || start === :transversal if length(axes(A, 1)) == length(axes(A, 2)) @@ -282,12 +282,7 @@ end # The starting points `cover!` accepts. const COVER_STARTS = (:auto, :transversal, :unconstrained, :geomean) -# Validate `start` and map the deprecated `:covariant` to `:unconstrained`. -function _normalize_cover_start(start::Symbol) - if start === :covariant - Base.depwarn("`start=:covariant` is deprecated; use `start=:unconstrained`", :cover) - return :unconstrained - end +function _check_cover_start(start::Symbol) start in COVER_STARTS || throw(ArgumentError("unknown start :$start; expected one of :auto, :transversal, :unconstrained, :geomean")) return start diff --git a/src/initializers.jl b/src/initializers.jl index 5e24285..3753abd 100644 --- a/src/initializers.jl +++ b/src/initializers.jl @@ -81,7 +81,6 @@ Build an asymmetric starting point for [`cover_min`](@ref) or - `:unconstrained` — the scale-covariant start of [`cover`](@ref) that approximates the unconstrained least-squares fit, without conjugate-gradient refinement. It agrees with `:geomean` on complete support. - `:covariant` is a deprecated alias. - `:hardcover` — the result of [`cover`](@ref), which is already a cover, so `feasible` is ignored. Additional keywords (`maxiter`, `cgiter`, `start`) are passed to `cover`; the other strategies accept none. @@ -112,10 +111,6 @@ function initialize_cover!(a::AbstractVector, b::AbstractVector, A::AbstractMatr strategy::Symbol=:hardcover, feasible::Symbol=:inflate, kwargs...) axes(A, 1) == eachindex(a) || throw(DimensionMismatch("indices of `a` must match row-indexing of `A`, got eachindex(a)=$(string(eachindex(a))), axes(A, 1)=$(string(axes(A, 1)))")) axes(A, 2) == eachindex(b) || throw(DimensionMismatch("indices of `b` must match column-indexing of `A`, got eachindex(b)=$(string(eachindex(b))), axes(A, 2)=$(string(axes(A, 2)))")) - if strategy === :covariant - Base.depwarn("`strategy=:covariant` is deprecated; use `strategy=:unconstrained`", :initialize_cover) - strategy = :unconstrained - end if strategy === :hardcover cover!(a, b, A; kwargs...) elseif strategy === :geomean diff --git a/test/heuristic_covers.jl b/test/heuristic_covers.jl index 7239615..a291c1f 100644 --- a/test/heuristic_covers.jl +++ b/test/heuristic_covers.jl @@ -541,16 +541,6 @@ end @test_throws "unknown start :nope; expected one of :auto, :transversal, :unconstrained, :geomean" cover!(abuf, bbuf, B; start=:nope) end -@testset "deprecated :covariant start" begin - A = exp.(randn(StableRNG(7), 6, 4)) - a0, b0 = cover(A; start=:unconstrained) - @test_deprecated "`start=:covariant` is deprecated; use `start=:unconstrained`" cover(A; start=:covariant) - @test (@test_deprecated cover(A; start=:covariant)) == (a0, b0) - ai, bi = initialize_cover(A; strategy=:unconstrained, feasible=:boost) - @test_deprecated "`strategy=:covariant` is deprecated; use `strategy=:unconstrained`" initialize_cover(A; strategy=:covariant, feasible=:boost) - @test (@test_deprecated initialize_cover(A; strategy=:covariant, feasible=:boost)) == (ai, bi) -end - @testset "cover: transversal start" begin # Largest product over transversals, and whether the cover is tight on every # entry of a maximum-product transversal (`∑ log a + ∑ log b == log π*`).