Skip to content

Commit be66b8f

Browse files
authored
Add max_coverage_ratio (#91)
`max_coverage_ratio(a, b, A)` and `max_coverage_ratio(a, A)` return the largest coverage ratio `abs(A[i,j])/(a[i]*b[j])` over the nonzero entries of `A`: the quantitative form of `iscover`, and the factor by which a product must be scaled to become a cover tight at its worst entry. It accepts the same scales and storage types as `iscover`, and its result is unchanged by a change of units. The new export raises the version to 1.1.0. Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent c88a65a commit be66b8f

4 files changed

Lines changed: 135 additions & 4 deletions

File tree

‎Project.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
name = "MatrixCovers"
22
uuid = "727e6139-ff52-4636-a344-ed1d23e73ffc"
3-
version = "1.0.0"
3+
version = "1.1.0"
44
authors = ["Tim Holy <tim.holy@gmail.com> and contributors"]
55

66
[deps]

‎src/MatrixCovers.jl‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ using Random: Random, AbstractRNG, MersenneTwister
88
using SparseArrays: SparseArrays, SparseMatrixCSC, nnz, nonzeros, nzrange, rowvals, sparse, spzeros
99

1010
export AbsLog, AbsLinear, PowerMean
11-
export cover_objective, iscover
11+
export cover_objective, iscover, max_coverage_ratio
1212
export cover, cover!, symcover, symcover!
1313
export gramcover, gramcover!
1414
export soft_symcover, soft_symcover!, soft_cover, soft_cover!

‎src/iscover.jl‎

Lines changed: 60 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,14 +60,72 @@ function iscover(a::AbstractVector, A::AbstractMatrix; kwargs...)
6060
return iscover(a, a, A; kwargs...)
6161
end
6262

63+
"""
64+
max_coverage_ratio(a, b, A)
65+
max_coverage_ratio(a, A)
66+
67+
Return the largest coverage ratio `abs(A[i,j])/(a[i]*b[j])` over the nonzero
68+
entries of `A`. The two-argument form uses the symmetric cover `a*a'`, and
69+
requires `A` to be square.
70+
71+
`a` and `b` cover `A` exactly when the result `r` is at most one, so this is the
72+
quantitative form of [`iscover`](@ref). Scaling the product `a*b'` by `r` makes
73+
it a cover that is tight at the worst entry, whether `r` is above or below one;
74+
in the symmetric form that scaling is `sqrt(r)*a`.
75+
76+
Zero entries of `A` impose no constraint and are skipped. A nonzero entry over
77+
a zero product gives `Inf`, and a matrix with no nonzero entries gives zero.
78+
The ratio is unchanged when `A`, `a`, and `b` are rescaled together, as under a
79+
change of units.
80+
81+
`a` and `b` must be nonnegative, and their indices must match those of `A`, as
82+
for [`iscover`](@ref).
83+
84+
See also: [`iscover`](@ref), [`cover_objective`](@ref).
85+
86+
# Examples
87+
88+
```jldoctest
89+
julia> A = [1.0 2.0; 3.0 4.0];
90+
91+
julia> max_coverage_ratio([1.0, 1.0], [1.0, 2.0], A) # A[2,1] = 3 against a[2]*b[1] = 1
92+
3.0
93+
94+
julia> max_coverage_ratio([2.0, 2.0], A)
95+
1.0
96+
```
97+
"""
98+
function max_coverage_ratio(a::AbstractVector, b::AbstractVector, A::AbstractMatrix)
99+
eachindex(a) == axes(A, 1) ||
100+
throw(DimensionMismatch("indices of `a` must match row-indexing of `A`, got eachindex(a)=$(string(eachindex(a))), axes(A, 1)=$(string(axes(A, 1)))"))
101+
eachindex(b) == axes(A, 2) ||
102+
throw(DimensionMismatch("indices of `b` must match column-indexing of `A`, got eachindex(b)=$(string(eachindex(b))), axes(A, 2)=$(string(axes(A, 2)))"))
103+
_require_nonneg(a, "a"; fname=:max_coverage_ratio)
104+
_require_nonneg(b, "b"; fname=:max_coverage_ratio)
105+
T = promote_type(objective_type(A), objective_type(a), objective_type(b))
106+
worst = Ref(zero(T))
107+
foreach_support(A) do i, j, v
108+
ab = a[i] * b[j]
109+
r = iszero(ab) ? T(Inf) : T(v / ab)
110+
worst[] = max(worst[], r)
111+
end
112+
return worst[]
113+
end
114+
115+
function max_coverage_ratio(a::AbstractVector, A::AbstractMatrix)
116+
axes(A, 1) == axes(A, 2) ||
117+
throw(DimensionMismatch("max_coverage_ratio(a, A) requires a square matrix, got axes $(string(axes(A)))"))
118+
return max_coverage_ratio(a, a, A)
119+
end
120+
63121
_iscovered(p, v, rtol, atol) = iszero(atol) ? p >= v * (1 - rtol) : p >= v * (1 - rtol) - atol
64122

65-
function _require_nonneg(x::AbstractVector, name::String)
123+
function _require_nonneg(x::AbstractVector, name::String; fname::Symbol=:iscover)
66124
for i in eachindex(x)
67125
# Ask the value for zero because dimensional abstract element types may
68126
# not define `zero(eltype(x))`. This also rejects NaN.
69127
x[i] >= zero(x[i]) ||
70-
throw(ArgumentError("iscover requires nonnegative scales, got $name[$(string(i))] = $(string(x[i]))"))
128+
throw(ArgumentError("$fname requires nonnegative scales, got $name[$(string(i))] = $(string(x[i]))"))
71129
end
72130
return nothing
73131
end

‎test/iscover.jl‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,3 +90,76 @@
9090
@test !iscover(first(soft_symcover(AbsLinear{2}(), Asoft)), Asoft)
9191
end
9292
end
93+
94+
@testset "max_coverage_ratio" begin
95+
A = [1.0 2.0; 3.0 4.0]
96+
97+
@testset "the worst entry, and agreement with iscover" begin
98+
@test max_coverage_ratio([1.0, 3.0], [1.0, 2.0], A) == 1 # a*b' == A exactly
99+
@test max_coverage_ratio([1.0, 1.0], [1.0, 1.0], A) == 4
100+
@test max_coverage_ratio([8.0, 8.0], [1.0, 1.0], A) == 0.5
101+
for (a, b) in (([1.0, 3.0], [1.0, 2.0]), ([1.0, 1.0], [1.0, 1.0]), ([8.0, 8.0], [1.0, 1.0]))
102+
@test iscover(a, b, A) == (max_coverage_ratio(a, b, A) <= 1)
103+
# Scaling the product by the ratio gives a cover that is tight at the worst entry.
104+
r = max_coverage_ratio(a, b, A)
105+
@test max_coverage_ratio(r .* a, b, A) ≈ 1
106+
end
107+
end
108+
109+
@testset "symmetric form" begin
110+
Asym = [4.0 1.0; 1.0 3.0]
111+
a = [1.0, 1.0]
112+
@test max_coverage_ratio(a, Asym) == max_coverage_ratio(a, a, Asym) == 4
113+
r = max_coverage_ratio(a, Asym)
114+
@test max_coverage_ratio(sqrt(r) .* a, Asym) ≈ 1
115+
@test_throws DimensionMismatch max_coverage_ratio([1.0, 1.0], [1.0 2.0 3.0; 4.0 5.0 6.0])
116+
end
117+
118+
@testset "zero entries and zero scales" begin
119+
@test max_coverage_ratio([1.0, 0.0], [1.0, 0.0], [1.0 0.0; 0.0 0.0]) == 1
120+
@test max_coverage_ratio([1.0, 0.0], [1.0, 0.0], [1.0 0.0; 0.0 1.0]) == Inf
121+
@test max_coverage_ratio([1.0, 1.0], [1.0, 1.0], zeros(2, 2)) === 0.0
122+
@test max_coverage_ratio(zeros(2), zeros(2), zeros(2, 2)) === 0.0
123+
end
124+
125+
@testset "argument checks" begin
126+
@test_throws "max_coverage_ratio requires nonnegative scales" max_coverage_ratio([-1.0, 3.0], [1.0, 2.0], A)
127+
@test_throws "max_coverage_ratio requires nonnegative scales" max_coverage_ratio([1.0, 3.0], [NaN, 2.0], A)
128+
@test_throws DimensionMismatch max_coverage_ratio([1.0], [1.0, 2.0], A)
129+
@test_throws DimensionMismatch max_coverage_ratio([1.0, 3.0], [1.0], A)
130+
end
131+
132+
@testset "offset axes" begin
133+
Ao = OffsetArray(A, -1:0, 3:4)
134+
ao, bo = OffsetArray([1.0, 1.0], -1:0), OffsetArray([1.0, 2.0], 3:4)
135+
@test max_coverage_ratio(ao, bo, Ao) == max_coverage_ratio([1.0, 1.0], [1.0, 2.0], A) == 3
136+
@test_throws DimensionMismatch max_coverage_ratio([1.0, 1.0], [1.0, 2.0], Ao)
137+
end
138+
139+
@testset "element types" begin
140+
@test max_coverage_ratio(Float32[1, 1], Float32[1, 1], Float32[1 2; 3 4]) isa Float32
141+
@test max_coverage_ratio([1, 1], [1, 1], [1 2; 3 4]) === 4.0
142+
end
143+
144+
@testset "storage types agree with the dense reference: $(typeof(S))" for S in (
145+
sparse([1.0 2.0; 3.0 4.0]),
146+
Diagonal([2.0, 3.0]),
147+
SymTridiagonal([2.0, 3.0], [1.0]),
148+
Tridiagonal([1.0], [2.0, 3.0], [0.5]),
149+
Bidiagonal([2.0, 3.0], [1.0], :U),
150+
Symmetric(sparse([4.0 1.0; 1.0 3.0])))
151+
D = Matrix(S)
152+
for a in ([1.0, 1.0], [2.0, 0.5], [3.0, 3.0])
153+
@test max_coverage_ratio(a, a, S) == max_coverage_ratio(a, a, D)
154+
end
155+
end
156+
157+
@testset "units cancel" begin
158+
L = u"m"
159+
Au = [1.0/L^2 2.0/L^2; 2.0/L^2 4.0/L^2]
160+
@test max_coverage_ratio([1.0/L, 1.0/L], Au) === 4.0
161+
# A change of units on each coordinate leaves the ratio unchanged.
162+
d = [2.0, 0.25]
163+
@test max_coverage_ratio([1.0, 1.0] .* d, A .* (d * d')) ≈ max_coverage_ratio([1.0, 1.0], A)
164+
end
165+
end

0 commit comments

Comments
 (0)