symmetric and circular padding

Author: nikopj

docs/src/reference.md

@@ -57,8 +57,10 @@ lpnormpool
 
 ```@docs
 pad_reflect
-pad_constant
+pad_symmetric
+pad_circular
 pad_repeat
+pad_constant
 pad_zeros
 ```
 

src/NNlib.jl

@@ -75,7 +75,7 @@ export maxpool, maxpool!, meanpool, meanpool!, lpnormpool, lpnormpool!,
     ∇maxpool, ∇maxpool!, ∇meanpool, ∇meanpool!, ∇lpnormpool, ∇lpnormpool!
 
 include("padding.jl")
-export pad_constant, pad_repeat, pad_reflect, pad_zeros
+export pad_constant, pad_repeat, pad_reflect, pad_zeros, pad_symmetric, pad_circular
 
 include("upsample.jl")
 export upsample_nearest, ∇upsample_nearest,

src/padding.jl

@@ -23,7 +23,7 @@ If `dims` is not given, it defaults to all dimensions.
 For integer `pad` input, it is applied on both sides
 on every dimension in `dims`.
 
-See also [`pad_zeros`](@ref), [`pad_reflect`](@ref) and [`pad_repeat`](@ref).
+See also [`pad_zeros`](@ref), [`pad_repeat`](@ref), [`pad_reflect`](@ref), [`pad_symmetric`](@ref), and [`pad_circular`](@ref).
 
 ```jldoctest
 julia> r = reshape(1:4, 2, 2)
@@ -174,7 +174,7 @@ on every dimension in `dims`. In this case, `dims`
 defaults to the first `ndims(x)-2` dimensions 
 (i.e. excludes the channel and batch dimension). 
 
-See also [`pad_reflect`](@ref) and [`pad_constant`](@ref).
+See also [`pad_reflect`](@ref), [`pad_symmetric`](@ref), [`pad_circular`](@ref), and [`pad_constant`](@ref).
 
 ```jldoctest
 julia> r = reshape(1:9, 3, 3)
@@ -235,7 +235,7 @@ on every dimension in `dims`. In this case, `dims`
 defaults to the first `ndims(x)-2` dimensions 
 (i.e. excludes the channel and batch dimension).
 
-See also [`pad_repeat`](@ref) and [`pad_constant`](@ref).
+See also [`pad_repeat`](@ref), [`pad_symmetric`](@ref), [`pad_circular`](@ref), and [`pad_constant`](@ref).
 
 ```jldoctest
 julia> r = reshape(1:9, 3, 3)
@@ -277,8 +277,127 @@ function pad_reflect(x::AbstractArray{F,N}, pad::NTuple{2,Int};
   return cat(xl, x, xr, dims = dims)
 end
 
+"""
+    pad_symmetric(x, pad::Tuple; [dims])
+    pad_symmetric(x, pad::Int; [dims])
+
+Pad the array `x` reflecting its values symmetrically across the border, i.e. the border values of `x` are present in the padding values, in contrast to [`pad_reflect`](@ref).
+
+`pad` can a tuple of integers `(l1, r1, ..., ln, rn)`
+of some length `2n` that specifies the left and right padding size
+for each of the dimensions in `dims`. If `dims` is not given, 
+it defaults to the first `n` dimensions.
+
+For integer `pad` input instead, it is applied on both sides
+on every dimension in `dims`. In this case, `dims` 
+defaults to the first `ndims(x)-2` dimensions 
+(i.e. excludes the channel and batch dimension).
+
+See also [`pad_repeat`](@ref), [`pad_reflect`](@ref), [`pad_circular`](@ref), and [`pad_constant`](@ref).
+
+```jldoctest
+julia> r = reshape(1:9, 3, 3)
+3×3 reshape(::UnitRange{Int64}, 3, 3) with eltype Int64:
+ 1  4  7
+ 2  5  8
+ 3  6  9
+
+julia> NNlib.pad_symmetric(r, (1,2,1,2))
+6×6 Matrix{Int64}:
+ 1  1  4  7  7  4
+ 1  1  4  7  7  4
+ 2  2  5  8  8  5
+ 3  3  6  9  9  6
+ 3  3  6  9  9  6
+ 2  2  5  8  8  5
+```
+"""
+function pad_symmetric(x::AbstractArray, pad::NTuple{M,Int}; 
+                     dims=1:M÷2) where M
+  length(dims) == M ÷ 2 ||
+    throw(ArgumentError("The number of dims should be equal to the number of padding dimensions"))
+  for (i, d) in enumerate(dims)
+    x = pad_symmetric(x, (pad[2i-1], pad[2i]); dims = d)
+  end  
+  return x
+end
+
+function pad_symmetric(x::AbstractArray{F,N}, pad::NTuple{2,Int}; 
+                     dims::Int = 1) where {F,N}
+  lpad, rpad = pad
+  
+  n = size(x, dims)
+  xl = selectdim(x, dims, lpad:-1:1)
+  xr = selectdim(x, dims, n:-1:n-rpad+1)
+  return cat(xl, x, xr, dims = dims)
+end
+
+"""
+    pad_circular(x, pad::Tuple; [dims])
+    pad_circular(x, pad::Int; [dims])
+
+Pad the array `x` "circularly" across the border by wrapping around values from the opposite side of `x`. 
+
+`pad` can a tuple of integers `(l1, r1, ..., ln, rn)`
+of some length `2n` that specifies the left and right padding size
+for each of the dimensions in `dims`. If `dims` is not given, 
+it defaults to the first `n` dimensions.
+
+For integer `pad` input instead, it is applied on both sides
+on every dimension in `dims`. In this case, `dims` 
+defaults to the first `ndims(x)-2` dimensions 
+(i.e. excludes the channel and batch dimension).
+
+The pad length in any dimension must not exceed the
+size of `x` in that dimension.
+
+See also [`pad_repeat`](@ref), [`pad_reflect`](@ref), [`pad_symmetric`](@ref), and [`pad_constant`](@ref).
+
+```jldoctest
+julia> r = reshape(1:9, 3, 3)
+3×3 reshape(::UnitRange{Int64}, 3, 3) with eltype Int64:
+ 1  4  7
+ 2  5  8
+ 3  6  9
+
+julia> NNlib.pad_circular(r, (1,2,1,2))
+6×6 Matrix{Int64}:
+ 9  3  6  9  3  6
+ 7  1  4  7  1  4
+ 8  2  5  8  2  5
+ 9  3  6  9  3  6
+ 7  1  4  7  1  4
+ 8  2  5  8  2  5
+```
+"""
+function pad_circular(x::AbstractArray, pad::NTuple{M,Int}; 
+                     dims=1:M÷2) where M
+  length(dims) == M ÷ 2 ||
+    throw(ArgumentError("The number of dims should be equal to the number of padding dimensions"))
+
+  for (i, d) in enumerate(dims)
+    x = pad_circular(x, (pad[2i-1], pad[2i]); dims = d)
+  end  
+  return x
+end
+
+function pad_circular(x::AbstractArray{F,N}, pad::NTuple{2,Int}; 
+                     dims::Int = 1) where {F,N}
+  lpad, rpad = pad
+  n = size(x, dims)
+
+  xl = selectdim(x, dims, n-lpad+1:n)
+  xr = selectdim(x, dims, 1:rpad)
+  return cat(xl, x, xr, dims = dims)
+end
+
 # convenience methods for symmetric and homogeneous padding
 pad_repeat(x::AbstractArray{F,N}, pad::Int; dims=1:N-2) where {F,N} =
   pad_repeat(x, ntuple(_ -> pad, 2length(dims)); dims = dims)
 pad_reflect(x::AbstractArray{F,N}, pad::Int; dims=1:N-2) where {F,N} =
   pad_reflect(x, ntuple(_ -> pad, 2length(dims)); dims = dims)
+pad_symmetric(x::AbstractArray{F,N}, pad::Int; dims=1:N-2) where {F,N} =
+  pad_symmetric(x, ntuple(_ -> pad, 2length(dims)); dims = dims)
+pad_circular(x::AbstractArray{F,N}, pad::Int; dims=1:N-2) where {F,N} =
+  pad_circular(x, ntuple(_ -> pad, 2length(dims)); dims = dims)
+

test/padding.jl

@@ -99,5 +99,53 @@ end
   @test pad_reflect(x, (2, 2, 2, 2), dims=(1,3)) ≈
           pad_reflect(x, 2, dims=(1,3))
 
-  gradtest(x -> pad_repeat(x, (2,2,2,2)), rand(2,2,2))
+  # pad_reflect needs larger test input as padding must 
+  # be strictly less than array size in that dimension
+  gradtest(x -> pad_reflect(x, (2,2,2,2)), rand(3,3,3))
+end
+
+@testset "padding symmetric" begin
+  y = pad_symmetric(reshape(1:9, 3, 3), (2,2), dims=2)
+  @test y ==  [ 4  1  1  4  7  7  4
+                5  2  2  5  8  8  5
+                6  3  3  6  9  9  6]
+
+  y = pad_symmetric(reshape(1:9, 3, 3), (2,2,2,2))
+  @test y ==   [5  2  2  5  8  8  5
+                4  1  1  4  7  7  4
+                4  1  1  4  7  7  4
+                5  2  2  5  8  8  5
+                6  3  3  6  9  9  6
+                6  3  3  6  9  9  6
+                5  2  2  5  8  8  5]
+
+  x = rand(4, 4, 4)  
+  
+  @test pad_symmetric(x, (2, 2, 2, 2), dims=(1,3)) ≈
+          pad_symmetric(x, 2, dims=(1,3))
+      
+  gradtest(x -> pad_symmetric(x, (2,2,2,2)), rand(2,2,2))
+end
+
+@testset "padding circular" begin
+  y = pad_circular(reshape(1:9, 3, 3), (2,2), dims=2)
+  @test y ==  [ 4  7  1  4  7  1  4
+                5  8  2  5  8  2  5
+                6  9  3  6  9  3  6]
+
+  y = pad_circular(reshape(1:9, 3, 3), (2,2,2,2))
+  @test y ==   [5  8  2  5  8  2  5
+                6  9  3  6  9  3  6
+                4  7  1  4  7  1  4
+                5  8  2  5  8  2  5
+                6  9  3  6  9  3  6
+                4  7  1  4  7  1  4
+                5  8  2  5  8  2  5]
+ 
+  x = rand(4, 4, 4)  
+  
+  @test pad_circular(x, (2, 2, 2, 2), dims=(1,3)) ≈
+          pad_circular(x, 2, dims=(1,3))
+      
+  gradtest(x -> pad_circular(x, (2,2,2,2)), rand(2,2,2))
 end