From db0b246bad42493fbeb7b9d675b7b1ecce38f639 Mon Sep 17 00:00:00 2001 From: Wolfhart Feldmeier Date: Mon, 13 Mar 2023 12:15:17 +0100 Subject: [PATCH 1/2] add documentation for overwriting behaviour of in-place application of real-input fft plans --- src/definitions.jl | 57 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/src/definitions.jl b/src/definitions.jl index 1cf542b2..07cc393a 100644 --- a/src/definitions.jl +++ b/src/definitions.jl @@ -356,6 +356,25 @@ plan_irfft(x::AbstractArray{Complex{T}}, d::Integer, region; kws...) where {T} = Pre-plan an optimized inverse real-input FFT, similar to [`plan_rfft`](@ref) except for [`irfft`](@ref) and [`brfft`](@ref), respectively. The first three arguments have the same meaning as for [`irfft`](@ref). + +!!! note + In contrast to plans created by [`plan_ifft`](@ref), the application of + this plan via `mul!(A, P, Â)` will potentially **overwrite the input array** `Â` + in the case of multidimensional transforms! See example below + +# Examples + +``` +julia> begin + A = Matrix{Float64}(undef, 5, 3) + Â = randn(ComplexF64, 3, 3) + Â_orig = copy(Â) + P = plan_irfft(Â, size(A, 1)) + mul!(A, P, Â) + Â == Â_orig + end +false +``` """ plan_irfft @@ -566,6 +585,25 @@ fft Pre-plan an optimized real-input FFT, similar to [`plan_fft`](@ref) except for [`rfft`](@ref) instead of [`fft`](@ref). The first two arguments, and the size of the transformed result, are the same as for [`rfft`](@ref). + +!!! note + In contrast to plans created by [`plan_fft`](@ref), the application of the + inverse of this plan via `ldiv!(A, P, Â)` will potentially **overwrite the input array** + `Â` in the case of multidimensional transforms! See example below + +# Examples + +``` +julia> begin + A = Matrix{Float64}(undef, 5, 3) + Â = randn(ComplexF64, 3, 3) + Â_orig = copy(Â) + P = plan_rfft(A) + ldiv!(A, P, Â) + Â == Â_orig + end +false +``` """ plan_rfft @@ -576,5 +614,24 @@ Pre-plan an optimized real-input unnormalized transform, similar to [`plan_rfft`](@ref) except for [`brfft`](@ref) instead of [`rfft`](@ref). The first two arguments and the size of the transformed result, are the same as for [`brfft`](@ref). + +!!! note + In contrast to plans created by [`plan_bfft`](@ref), the application of + this plan via `mul!(A, P, Â)` will potentially **overwrite the input array** `Â` + in the case of multidimensional transforms! See example below + +# Examples + +``` +julia> begin + A = Matrix{Float64}(undef, 5, 3) + Â = randn(ComplexF64, 3, 3) + Â_orig = copy(Â) + P = plan_brfft(Â, size(A, 1)) + mul!(A, P, Â) + Â == Â_orig + end +false +``` """ plan_brfft From 45f3531309e0c8801743b931811be992ecccb02c Mon Sep 17 00:00:00 2001 From: Wolfhart Feldmeier Date: Tue, 25 Apr 2023 19:36:11 +0200 Subject: [PATCH 2/2] drop examples that cannot be doctested and clarify overwrite behaviour of plan_*fft --- src/definitions.jl | 45 +++------------------------------------------ 1 file changed, 3 insertions(+), 42 deletions(-) diff --git a/src/definitions.jl b/src/definitions.jl index 07cc393a..89e58506 100644 --- a/src/definitions.jl +++ b/src/definitions.jl @@ -360,21 +360,8 @@ three arguments have the same meaning as for [`irfft`](@ref). !!! note In contrast to plans created by [`plan_ifft`](@ref), the application of this plan via `mul!(A, P, Â)` will potentially **overwrite the input array** `Â` - in the case of multidimensional transforms! See example below + with undefined data in the case of multidimensional transforms! -# Examples - -``` -julia> begin - A = Matrix{Float64}(undef, 5, 3) - Â = randn(ComplexF64, 3, 3) - Â_orig = copy(Â) - P = plan_irfft(Â, size(A, 1)) - mul!(A, P, Â) - Â == Â_orig - end -false -``` """ plan_irfft @@ -589,21 +576,8 @@ size of the transformed result, are the same as for [`rfft`](@ref). !!! note In contrast to plans created by [`plan_fft`](@ref), the application of the inverse of this plan via `ldiv!(A, P, Â)` will potentially **overwrite the input array** - `Â` in the case of multidimensional transforms! See example below - -# Examples + `Â` with undefined data in the case of multidimensional transforms! -``` -julia> begin - A = Matrix{Float64}(undef, 5, 3) - Â = randn(ComplexF64, 3, 3) - Â_orig = copy(Â) - P = plan_rfft(A) - ldiv!(A, P, Â) - Â == Â_orig - end -false -``` """ plan_rfft @@ -618,20 +592,7 @@ the same as for [`brfft`](@ref). !!! note In contrast to plans created by [`plan_bfft`](@ref), the application of this plan via `mul!(A, P, Â)` will potentially **overwrite the input array** `Â` - in the case of multidimensional transforms! See example below - -# Examples + with undefined data in the case of multidimensional transforms! -``` -julia> begin - A = Matrix{Float64}(undef, 5, 3) - Â = randn(ComplexF64, 3, 3) - Â_orig = copy(Â) - P = plan_brfft(Â, size(A, 1)) - mul!(A, P, Â) - Â == Â_orig - end -false -``` """ plan_brfft