Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/src/objectives.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
118 changes: 71 additions & 47 deletions src/balanced.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand Down
11 changes: 3 additions & 8 deletions src/heuristic_covers.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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))
Expand Down Expand Up @@ -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
Expand Down
5 changes: 0 additions & 5 deletions src/initializers.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
10 changes: 0 additions & 10 deletions test/heuristic_covers.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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 π*`).
Expand Down
Loading