Table of Contents

Class FftEngine

Namespace
NumSharp
Assembly
NumSharp.dll

The contract of numpy.fft: one member per function that computes (16 of NumPy's 18; fftshift and ifftshift are rolls of the array object). An engine reaches it through Fft, and every public np.fft function makes C#'s conversions and calls one member (woven: a subclass operand arrives as its plain view, and the declared mechanism answers for the class).

public abstract class FftEngine
Inheritance
FftEngine
Derived
Inherited Members

Remarks

The default is DefaultFftEngine: NumPy's statements in NumPy's order (the length and norm checks, _cook_nd_args, _raw_fftnd's axis order, the Hermitian compositions, fftfreq's arithmetic) over three kernels that stand for NumPy's _pocketfft_umath ufuncs (complex to complex, real to complex, complex to real), computed by NumSharp's managed port of pocketfft, bit for bit with NumPy 2.4.2's on the double path.

Providing one. Derive from DefaultFftEngine and override its kernels to compute the transforms another way (MKL, FFTW, cuFFT) while NumPy's statements stay; derive from this class to replace whole functions. Assign the instance to Fft of the cached engine: it reaches every array bound to that engine, existing ones included.

Operands. A member receives plain arrays: the np.fft functions decide the numpy.matrix and numpy.char.chararray classes before they call it (NumPy's asarray drops both), so an override never sees those classes from them.

Results. NumSharp has one complex dtype (complex128, issue #569): where NumPy returns complex64 / float32 / float16 for a float32 / float16 input, the result dtype is complex128 / float64 and the values are NumPy's, rounded to NumPy's precision.

Methods

Fft(NDArray, int?, int, string, NDArray)

NumPy's np.fft.fft(a, n=None, axis=-1, norm=None, out=None): the one-dimensional discrete Fourier transform along axis.

public abstract NDArray Fft(NDArray a, int? n = null, int axis = -1, string norm = null, NDArray @out = null)

Parameters

a NDArray

The input, real or complex (a real input is taken as complex).

n int?

The transform length: the axis is cropped or zero-padded to it; null for the input's length.

axis int

The transformed axis (negative counts from the end).

norm string

null or "backward" (no scaling forward), "ortho" (1/sqrt(n)) or "forward" (1/n).

out NDArray

A pre-allocated output of the result's shape (its dtype a same_kind cast of complex128), or null.

Returns

NDArray

The transform, complex128 (out itself when given).

Exceptions

ValueError

n below 1 (Invalid number of FFT data points (0) specified.), an unknown norm, or an out of the wrong shape or read-only.

IndexError

axis out of range with n omitted (NumPy's a.shape[axis]: tuple index out of range).

AxisError

axis out of range with n given.

DTypePromotionError

A text input (result_type(a.real.dtype, 1.0) has no common DType).

TypeError

An out dtype the complex128 result cannot be cast to under same_kind (NumPy's UFuncTypeError text).

Fft2(NDArray, int[], int[], string, NDArray)

NumPy's np.fft.fft2(a, s=None, axes=(-2, -1), norm=None, out=None): Fftn(NDArray, int[], int[], string, NDArray) over the last two axes by default.

public abstract NDArray Fft2(NDArray a, int[] s = null, int[] axes = null, string norm = null, NDArray @out = null)

Parameters

a NDArray

The input, real or complex.

s int[]

The output length per transformed axis (-1 keeps the input's), or null for the input's.

axes int[]

The transformed axes; null stands for NumPy's default (-2, -1).

norm string

The normalization mode, as for Fft(NDArray, int?, int, string, NDArray).

out NDArray

A pre-allocated output handed to every one-dimensional transform (NumPy's out=out), or null.

Returns

NDArray

The transform, complex128.

Exceptions

ValueError

s and axes of different lengths (Shape and axes have different lengths.), a length below 1, an unknown norm, or an unfit out.

IndexError

An axis out of range (NumPy's take / tuple-index texts; a 0-d input: cannot do a non-empty take from an empty axes.).

AxisError

An axis out of range for a one-dimensional transform.

DTypePromotionError

A text input.

Fftfreq(long, double, string)

NumPy's np.fft.fftfreq(n, d=1.0, device=None): the sample frequencies of an n-point transform, [0, 1, ..., (n-1)//2, -(n//2), ..., -1] / (d * n).

public abstract NDArray Fftfreq(long n, double d = 1, string device = null)

Parameters

n long

The window length.

d double

The sample spacing.

device string

null or "cpu" (the Array API's device argument).

Returns

NDArray

A new float64 array of n frequencies.

Exceptions

ZeroDivisionError

n * d is zero (Python's float division by zero, checked first).

ValueError

A device other than "cpu", then a negative n (negative dimensions are not allowed).

Fftn(NDArray, int[], int[], string, NDArray)

NumPy's np.fft.fftn(a, s=None, axes=None, norm=None, out=None): the N-dimensional transform, one Fft(NDArray, int?, int, string, NDArray) per axis in reverse order (_raw_fftnd).

public abstract NDArray Fftn(NDArray a, int[] s = null, int[] axes = null, string norm = null, NDArray @out = null)

Parameters

a NDArray

The input, real or complex.

s int[]

The output length per transformed axis (-1 keeps the input's); null for the input's. Given without axes, the last len(s) axes are transformed.

axes int[]

The transformed axes, or null for all of them.

norm string

The normalization mode, as for Fft(NDArray, int?, int, string, NDArray).

out NDArray

A pre-allocated output handed to every one-dimensional transform, or null.

Returns

NDArray

The transform, complex128.

Exceptions

ValueError

Mismatched s / axes, a length below 1, an unknown norm, or an unfit out.

IndexError

An axis out of range.

AxisError

An axis out of range for a one-dimensional transform.

DTypePromotionError

A text input.

Hfft(NDArray, int?, int, string, NDArray)

NumPy's np.fft.hfft(a, n=None, axis=-1, norm=None, out=None): the transform of a signal with Hermitian symmetry, irfft(conjugate(a), n, axis, norm=_swap_direction(norm)); the output is real.

public abstract NDArray Hfft(NDArray a, int? n = null, int axis = -1, string norm = null, NDArray @out = null)

Parameters

a NDArray

The input (the half of a Hermitian-symmetric signal).

n int?

The output length; null for 2 * (m - 1).

axis int

The transformed axis.

norm string

The normalization mode, swapped before the inverse transform.

out NDArray

A pre-allocated real output irfft writes (NumPy 2.5; 2.4 handed irfft out=None), or null.

Returns

NDArray

The real result, float64 (out itself when given).

Exceptions

ValueError

A length below 1, or an unknown norm (the inverse's text).

IndexError

axis out of range with n omitted.

AxisError

axis out of range with n given.

TypeError

A text input (np.conjugate has no string loop).

Ifft(NDArray, int?, int, string, NDArray)

NumPy's np.fft.ifft(a, n=None, axis=-1, norm=None, out=None): the one-dimensional inverse discrete Fourier transform, ifft(fft(a)) == a to rounding.

public abstract NDArray Ifft(NDArray a, int? n = null, int axis = -1, string norm = null, NDArray @out = null)

Parameters

a NDArray

The input, real or complex.

n int?

The transform length (cropped or zero-padded); null for the input's length.

axis int

The transformed axis.

norm string

null or "backward" (1/n on the inverse), "ortho" or "forward" (no scaling on the inverse).

out NDArray

A pre-allocated output of the result's shape, or null.

Returns

NDArray

The inverse transform, complex128 (out itself when given).

Exceptions

ValueError

n below 1, an unknown norm (the inverse's text, with a space after "backward",), or an out of the wrong shape or read-only.

IndexError

axis out of range with n omitted.

AxisError

axis out of range with n given.

DTypePromotionError

A text input.

TypeError

An out dtype the complex128 result cannot be cast to under same_kind.

Ifft2(NDArray, int[], int[], string, NDArray)

NumPy's np.fft.ifft2(a, s=None, axes=(-2, -1), norm=None, out=None): Ifftn(NDArray, int[], int[], string, NDArray) over the last two axes by default, the out handed to the transforms (NumPy 2.5; 2.4 handed them out=None).

public abstract NDArray Ifft2(NDArray a, int[] s = null, int[] axes = null, string norm = null, NDArray @out = null)

Parameters

a NDArray

The input, real or complex.

s int[]

The output length per transformed axis, or null.

axes int[]

The transformed axes; null stands for (-2, -1).

norm string

The normalization mode, as for Ifft(NDArray, int?, int, string, NDArray).

out NDArray

A pre-allocated complex output, or null.

Returns

NDArray

The inverse transform, complex128 (out itself when given).

Exceptions

ValueError

Mismatched s / axes, a length below 1, or an unknown norm.

IndexError

An axis out of range.

AxisError

An axis out of range for a one-dimensional transform.

DTypePromotionError

A text input.

Ifftn(NDArray, int[], int[], string, NDArray)

NumPy's np.fft.ifftn(a, s=None, axes=None, norm=None, out=None): the N-dimensional inverse transform, one Ifft(NDArray, int?, int, string, NDArray) per axis in reverse order.

public abstract NDArray Ifftn(NDArray a, int[] s = null, int[] axes = null, string norm = null, NDArray @out = null)

Parameters

a NDArray

The input, real or complex.

s int[]

The output length per transformed axis, or null.

axes int[]

The transformed axes, or null for all of them.

norm string

The normalization mode, as for Ifft(NDArray, int?, int, string, NDArray).

out NDArray

A pre-allocated output handed to every one-dimensional transform, or null.

Returns

NDArray

The inverse transform, complex128.

Exceptions

ValueError

Mismatched s / axes, a length below 1, an unknown norm, or an unfit out.

IndexError

An axis out of range.

AxisError

An axis out of range for a one-dimensional transform.

DTypePromotionError

A text input.

Ihfft(NDArray, int?, int, string, NDArray)

NumPy's np.fft.ihfft(a, n=None, axis=-1, norm=None, out=None): the inverse of Hfft(NDArray, int?, int, string, NDArray), conjugate(rfft(a, n, axis, norm=_swap_direction(norm), out=out), out=out); the output is complex.

public abstract NDArray Ihfft(NDArray a, int? n = null, int axis = -1, string norm = null, NDArray @out = null)

Parameters

a NDArray

The real input.

n int?

The number of input points used; null for the input's length.

axis int

The transformed axis.

norm string

The normalization mode, swapped before the forward transform.

out NDArray

A pre-allocated complex output, threaded through rfft and the conjugate, or null.

Returns

NDArray

The half spectrum's conjugate, complex128 (out itself when given).

Exceptions

ValueError

A length below 1, an unknown norm, or an unfit out.

IndexError

axis out of range with n omitted.

AxisError

axis out of range with n given.

TypeError

A complex input (rfft's refusal).

DTypePromotionError

A text input.

TypeError

An out dtype the complex128 result cannot be cast to.

Irfft(NDArray, int?, int, string, NDArray)

NumPy's np.fft.irfft(a, n=None, axis=-1, norm=None, out=None): the inverse of Rfft(NDArray, int?, int, string, NDArray), a real output of n points from the half spectrum's first n // 2 + 1 terms.

public abstract NDArray Irfft(NDArray a, int? n = null, int axis = -1, string norm = null, NDArray @out = null)

Parameters

a NDArray

The half spectrum.

n int?

The output length; null for NumPy's 2 * (m - 1), m the input's length.

axis int

The transformed axis.

norm string

The normalization mode, as for Ifft(NDArray, int?, int, string, NDArray).

out NDArray

A pre-allocated output of length n on the axis (float64, or a same_kind cast of it such as complex128), or null.

Returns

NDArray

The real signal, float64 (out itself when given).

Exceptions

ValueError

n below 1 (an input of length 1 with n omitted gives 0), an unknown norm, or an unfit out.

IndexError

axis out of range with n omitted.

AxisError

axis out of range with n given.

DTypePromotionError

A text input.

TypeError

An out dtype the float64 result cannot be cast to under same_kind.

Irfft2(NDArray, int[], int[], string, NDArray)

NumPy's np.fft.irfft2(a, s=None, axes=(-2, -1), norm=None, out=None): Irfftn(NDArray, int[], int[], string, NDArray) over the last two axes by default, the out handed on (NumPy 2.5; 2.4 handed on out=None).

public abstract NDArray Irfft2(NDArray a, int[] s = null, int[] axes = null, string norm = null, NDArray @out = null)

Parameters

a NDArray

The input spectrum.

s int[]

The output length per transformed axis, or null.

axes int[]

The transformed axes; null stands for (-2, -1).

norm string

The normalization mode, as for Ifft(NDArray, int?, int, string, NDArray).

out NDArray

A pre-allocated real output for the final transform, or null.

Returns

NDArray

The real result, float64 (out itself when given).

Exceptions

ValueError

Mismatched s / axes, a length below 1, or an unknown norm.

IndexError

An axis out of range, or no axis to transform.

AxisError

An axis out of range for a one-dimensional transform.

DTypePromotionError

A text input.

Irfftn(NDArray, int[], int[], string, NDArray)

NumPy's np.fft.irfftn(a, s=None, axes=None, norm=None, out=None): Ifft(NDArray, int?, int, string, NDArray) over every transformed axis but the last, then Irfft(NDArray, int?, int, string, NDArray) over the last (a real output whose default length is 2 * (m - 1)).

public abstract NDArray Irfftn(NDArray a, int[] s = null, int[] axes = null, string norm = null, NDArray @out = null)

Parameters

a NDArray

The input spectrum.

s int[]

The output length per transformed axis, or null.

axes int[]

The transformed axes, or null for all of them.

norm string

The normalization mode, as for Ifft(NDArray, int?, int, string, NDArray).

out NDArray

A pre-allocated real output for the final transform, or null.

Returns

NDArray

The real result, float64.

Exceptions

ValueError

Mismatched s / axes, a length below 1, an unknown norm, or an unfit out.

IndexError

An axis out of range, or no axis to transform (NumPy's tuple / list index out of range).

AxisError

An axis out of range for a one-dimensional transform.

DTypePromotionError

A text input.

Rfft(NDArray, int?, int, string, NDArray)

NumPy's np.fft.rfft(a, n=None, axis=-1, norm=None, out=None): the one-dimensional transform of a real input, the non-negative-frequency half (n // 2 + 1 terms).

public abstract NDArray Rfft(NDArray a, int? n = null, int axis = -1, string norm = null, NDArray @out = null)

Parameters

a NDArray

The real input (a complex one is refused: NumPy's rfft has no complex loop).

n int?

The number of input points used (cropped or zero-padded); null for the input's length.

axis int

The transformed axis.

norm string

The normalization mode, as for Fft(NDArray, int?, int, string, NDArray).

out NDArray

A pre-allocated complex output of length n // 2 + 1 on the axis, or null.

Returns

NDArray

The half spectrum, complex128 (out itself when given).

Exceptions

ValueError

n below 1, an unknown norm, or an unfit out.

IndexError

axis out of range with n omitted.

AxisError

axis out of range with n given.

TypeError

A complex input (ufunc 'rfft_n_even' not supported for the input types, ..., rfft_n_odd for an odd n).

DTypePromotionError

A text input.

TypeError

An out dtype the complex128 result cannot be cast to under same_kind.

Rfft2(NDArray, int[], int[], string, NDArray)

NumPy's np.fft.rfft2(a, s=None, axes=(-2, -1), norm=None, out=None): Rfftn(NDArray, int[], int[], string, NDArray) over the last two axes by default.

public abstract NDArray Rfft2(NDArray a, int[] s = null, int[] axes = null, string norm = null, NDArray @out = null)

Parameters

a NDArray

The real input.

s int[]

The output length per transformed axis, or null.

axes int[]

The transformed axes; null stands for (-2, -1).

norm string

The normalization mode, as for Fft(NDArray, int?, int, string, NDArray).

out NDArray

A pre-allocated output, or null.

Returns

NDArray

The transform, complex128, the last axis halved.

Exceptions

ValueError

Mismatched s / axes, a length below 1, an unknown norm, or an unfit out.

IndexError

An axis out of range.

AxisError

An axis out of range for a one-dimensional transform.

TypeError

A complex input.

DTypePromotionError

A text input.

Rfftfreq(long, double, string)

NumPy's np.fft.rfftfreq(n, d=1.0, device=None): the non-negative sample frequencies of an n-point real transform, [0, 1, ..., n//2] / (d * n).

public abstract NDArray Rfftfreq(long n, double d = 1, string device = null)

Parameters

n long

The window length (a negative one gives an empty result, as NumPy's arange does).

d double

The sample spacing.

device string

null or "cpu".

Returns

NDArray

A new float64 array of n // 2 + 1 frequencies.

Exceptions

ZeroDivisionError

n * d is zero.

ValueError

A device other than "cpu".

Rfftn(NDArray, int[], int[], string, NDArray)

NumPy's np.fft.rfftn(a, s=None, axes=None, norm=None, out=None): Rfft(NDArray, int?, int, string, NDArray) over the last transformed axis, then Fft(NDArray, int?, int, string, NDArray) over the others in reverse order.

public abstract NDArray Rfftn(NDArray a, int[] s = null, int[] axes = null, string norm = null, NDArray @out = null)

Parameters

a NDArray

The real input.

s int[]

The output length per transformed axis (the last one is rfft's n), or null.

axes int[]

The transformed axes, or null for all of them.

norm string

The normalization mode, as for Fft(NDArray, int?, int, string, NDArray).

out NDArray

A pre-allocated output handed to every one-dimensional transform, or null.

Returns

NDArray

The transform, complex128, the last transformed axis halved.

Exceptions

ValueError

Mismatched s / axes, a length below 1, an unknown norm, or an unfit out.

IndexError

An axis out of range, or no axis to transform (a 0-d input, an empty axes: list index out of range).

AxisError

An axis out of range for a one-dimensional transform.

TypeError

A complex input.

DTypePromotionError

A text input.