Add docstrings to LowRankFun and PartialInverseOperator (#219)

* docstrings for LowRankFun and PartialInverseOperator

* condense PartialInverseOperator methods

* fix off-by-one in basisfunction

* error checks in basisfunction

* undo basisfunction off-by-one

Author: jishnub

Project.toml

@@ -1,6 +1,6 @@
 name = "ApproxFunBase"
 uuid = "fbd15aa5-315a-5a7d-a8a4-24992e37be05"
-version = "0.7.13"
+version = "0.7.14"
 
 [deps]
 AbstractFFTs = "621f4979-c628-5d54-868e-fcf4e3e8185c"

src/Multivariate/LowRankFun.jl

@@ -5,7 +5,19 @@
 export LowRankFun
 
 """
-`LowRankFun` gives an approximation to a bivariate function in low rank form.
+    LowRankFun
+
+Return an approximation to a bivariate function in low rank form.
+
+# Examples
+```jldoctest
+julia> f = (x,y) -> x^2 * y^3;
+
+julia> L = LowRankFun(f, Chebyshev() ⊗ Chebyshev());
+
+julia> L(0.1, 0.2) ≈ f(0.1, 0.2)
+true
+```
 """
 mutable struct LowRankFun{S<:Space,M<:Space,SS<:AbstractProductSpace,T<:Number} <: BivariateFun{T}
     A::Vector{VFun{S,T}}
@@ -30,6 +42,7 @@ LowRankFun(A::Vector{VFun{S,T}},B::Vector{VFun{M,V}}) where {S,M,T,V} =
     LowRankFun(strictconvert(Vector{VFun{S,promote_type(T,V)}},A),
                strictconvert(Vector{VFun{M,promote_type(T,V)}},B),
                space(first(A))⊗space(first(B)))
+
 rank(f::LowRankFun) = length(f.A)
 size(f::LowRankFun,k::Integer) = k==1 ? mapreduce(length,max,f.A) : mapreduce(length,max,f.B)
 size(f::LowRankFun) = size(f,1),size(f,2)

src/Operators/general/PartialInverseOperator.jl

@@ -1,7 +1,63 @@
 export PartialInverseOperator
 
+"""
+    PartialInverseOperator(O::Operator[, bandwidths = bandwidths(O)])
 
-struct PartialInverseOperator{T<:Number,CO<:CachedOperator,BI} <: Operator{T}
+Return an approximate estimate for `inv(O)`, such that `PartialInverseOperator(O) * O` is banded, and
+is approximately `I` up to a bandwidth that is one less than the sum of the bandwidths
+of `O` and `PartialInverseOperator(O)`.
+
+!!! note
+    Only upper triangular operators are supported as of now.
+
+# Examples
+
+```jldoctest
+julia> C = Conversion(Chebyshev(), Ultraspherical(1));
+
+julia> bandwidths(C)
+(0, 2)
+
+julia> P = PartialInverseOperator(C);
+
+julia> bandwidths(P)
+(0, 2)
+
+julia> P * C
+TimesOperator : Chebyshev() → Chebyshev()
+ 1.0  0.0  0.0  0.0  -0.5    ⋅     ⋅     ⋅     ⋅     ⋅   ⋅
+  ⋅   1.0  0.0  0.0   0.0  -1.0    ⋅     ⋅     ⋅     ⋅   ⋅
+  ⋅    ⋅   1.0  0.0   0.0   0.0  -1.0    ⋅     ⋅     ⋅   ⋅
+  ⋅    ⋅    ⋅   1.0   0.0   0.0   0.0  -1.0    ⋅     ⋅   ⋅
+  ⋅    ⋅    ⋅    ⋅    1.0   0.0   0.0   0.0  -1.0    ⋅   ⋅
+  ⋅    ⋅    ⋅    ⋅     ⋅    1.0   0.0   0.0   0.0  -1.0  ⋅
+  ⋅    ⋅    ⋅    ⋅     ⋅     ⋅    1.0   0.0   0.0   0.0  ⋱
+  ⋅    ⋅    ⋅    ⋅     ⋅     ⋅     ⋅    1.0   0.0   0.0  ⋱
+  ⋅    ⋅    ⋅    ⋅     ⋅     ⋅     ⋅     ⋅    1.0   0.0  ⋱
+  ⋅    ⋅    ⋅    ⋅     ⋅     ⋅     ⋅     ⋅     ⋅    1.0  ⋱
+  ⋅    ⋅    ⋅    ⋅     ⋅     ⋅     ⋅     ⋅     ⋅     ⋅   ⋱
+
+julia> P = PartialInverseOperator(C, (0, 4));
+
+julia> bandwidths(P)
+(0, 4)
+
+julia> P * C
+TimesOperator : Chebyshev() → Chebyshev()
+ 1.0  0.0  0.0  0.0  0.0  0.0  -0.5    ⋅     ⋅     ⋅   ⋅
+  ⋅   1.0  0.0  0.0  0.0  0.0   0.0  -1.0    ⋅     ⋅   ⋅
+  ⋅    ⋅   1.0  0.0  0.0  0.0   0.0   0.0  -1.0    ⋅   ⋅
+  ⋅    ⋅    ⋅   1.0  0.0  0.0   0.0   0.0   0.0  -1.0  ⋅
+  ⋅    ⋅    ⋅    ⋅   1.0  0.0   0.0   0.0   0.0   0.0  ⋱
+  ⋅    ⋅    ⋅    ⋅    ⋅   1.0   0.0   0.0   0.0   0.0  ⋱
+  ⋅    ⋅    ⋅    ⋅    ⋅    ⋅    1.0   0.0   0.0   0.0  ⋱
+  ⋅    ⋅    ⋅    ⋅    ⋅    ⋅     ⋅    1.0   0.0   0.0  ⋱
+  ⋅    ⋅    ⋅    ⋅    ⋅    ⋅     ⋅     ⋅    1.0   0.0  ⋱
+  ⋅    ⋅    ⋅    ⋅    ⋅    ⋅     ⋅     ⋅     ⋅    1.0  ⋱
+  ⋅    ⋅    ⋅    ⋅    ⋅    ⋅     ⋅     ⋅     ⋅     ⋅   ⋱
+```
+"""
+struct PartialInverseOperator{T<:Number,CO<:CachedOperator,BI<:Tuple{Any,Any}} <: Operator{T}
     cache::CO
     bandwidths::BI
 end
@@ -11,10 +67,12 @@ function PartialInverseOperator(CO::CachedOperator{T},bandwidths) where T<:Numbe
     return PartialInverseOperator{T,typeof(CO),typeof(bandwidths)}(CO,bandwidths)
 end
 
-PartialInverseOperator(B::Operator, bandwidths) = PartialInverseOperator(cache(B), bandwidths)
-PartialInverseOperator(B::Operator) = PartialInverseOperator(B, bandwidths(B))
+function PartialInverseOperator(B::Operator, bandwidths = bandwidths(B))
+    PartialInverseOperator(cache(B), bandwidths)
+end
 
-convert(::Type{Operator{T}},A::PartialInverseOperator) where {T}=PartialInverseOperator(strictconvert(Operator{T},A.cache), A.bandwidths)
+convert(::Type{Operator{T}},A::PartialInverseOperator) where {T} =
+    PartialInverseOperator(strictconvert(Operator{T},A.cache), A.bandwidths)
 
 domainspace(P::PartialInverseOperator)=rangespace(P.cache)
 rangespace(P::PartialInverseOperator)=domainspace(P.cache)
@@ -60,7 +118,7 @@ end
 
 ## These are both hacks that apparently work
 
-function BandedMatrix(S::SubOperator{T,PP,Tuple{UnitRange{Int},UnitRange{Int}}}) where {T,PP<:PartialInverseOperator}
+function BandedMatrix(S::SubOperator{T,<:PartialInverseOperator,Tuple{UnitRange{Int},UnitRange{Int}}}) where {T}
     kr,jr = parentindices(S)
     P = parent(S)
     #ret = BandedMatrix{eltype(S)}(undef, size(S), bandwidths(S))

src/onehotvector.jl

@@ -1,11 +1,21 @@
 struct OneHotVector{T} <: AbstractVector{T}
 	n :: Int
 	len :: Int
+
+	function OneHotVector{T}(n, len) where {T}
+		len >= 0 || throw(ArgumentError("length must be non-negative"))
+		0 <= n <= len || throw(ArgumentError("index must be <= length"))
+		new{T}(n, len)
+	end
 end
 OneHotVector(n, len = n) = OneHotVector{Float64}(n, len)
 Base.size(v::OneHotVector) = (v.len,)
 Base.length(v::OneHotVector) = v.len
 function Base.getindex(v::OneHotVector{T}, i::Int) where {T}
 	i == v.n ? one(T) : zero(T)
 end
-basisfunction(sp, k) = Fun(sp, OneHotVector(k))
+# assume that the basis label starts at zero
+function basisfunction(sp, k)
+	k >= 0 || throw(ArgumentError("basis label must be non-negative, received $k"))
+	Fun(sp, OneHotVector(k))
+end

test/SpacesTest.jl

@@ -163,6 +163,13 @@ using LinearAlgebra
             @test ℯ^f == exp(f)
             @test values(ℯ^f) == exp.(values(f))
         end
+
+        # trivial sanity tests for PartialInverseOperator
+        @testset "PartialInverseOperator" begin
+            C = Conversion(PointSpace(1:3), PointSpace(1:3))
+            P = PartialInverseOperator(C)
+            @test AbstractMatrix(P * C) == I(size(C,1))
+        end
     end
 
     @testset "DiracSpace" begin