pylops.signalprocessing.Convolve1D¶

class pylops.signalprocessing.Convolve1D(dims, h, offset=0, axis=-1, method=None, dtype='float64', name='C')[source]¶

1D convolution operator.

Apply one-dimensional convolution with i) a compact filter (shorter than input signal) or ii) an extended filter (larger than input signal) to model (and data) along an axis of a multi-dimensional array.

Parameters:

dimslist or int: Number of samples for each dimension of the model
hnumpy.ndarray: Filter to be convolved to input signal. Either a 1d array, which is applied to every 1d slice of the model taken along axis, or an array with the same number of dimensions as the model, which allows using a different filter for each slice. In the latter case the filter may also be larger than the model along the dimensions other than axis, provided the model has size 1 along those dimensions: the forward then broadcasts the model over them and the adjoint sums over them.
offsetint: Index of the center of the filter
axisint, optional: Added in version 2.0.0.

Axis along which convolution is applied
methodstr, optional: Method used to calculate the convolution (direct, fft, or overlapadd). Note that only direct and fft are allowed for a one-dimensional model, whilst fft and overlapadd are allowed for a multi-dimensional model. If None, the method is chosen automatically (direct for 1-dimensional inputs and fft for N-dimensional inputs)
dtypestr, optional: Type of elements in input array.
namestr, optional: Added in version 2.0.0.

Name of operator (to be used by pylops.utils.describe.describe)

Attributes:

nhint

Length of the filter

hstarnumpy.ndarray

Time-reversed filter used in adjoint

convfunccallable

Function handler used to perform convolution

dimstuple

Shape of the array after the adjoint, but before flattening.

For example, x_reshaped = (Op.H * y.ravel()).reshape(Op.dims).

dimsdtuple

Shape of the array after the forward, but before flattening. Obtained by broadcasting dims against the shape of h over the dimensions other than axis, whose size is that of the model for a compact filter and that of the filter for an extended one. Same as dims for a 1d compact filter.

shapetuple

Operator shape.

Raises:

ValueError: If offset is bigger than the size along axis of the filter (compact filter) or of the model (extended filter), minus one
ValueError: If method provided is not allowed
ValueError: If h has neither 1 nor len(dims) dimensions
ValueError: If the shape of h cannot be broadcast against dims over the dimensions other than axis

Notes

The Convolve1D operator applies convolution between the input signal \(x(t)\) and a filter kernel \(h(t)\) in forward model:

\[y(t) = \int\limits_{-\infty}^{\infty} h(t-\tau) x(\tau) \,\mathrm{d}\tau\]

This operation can be discretized as follows

\[y[n] = \sum_{m=-\infty}^{\infty} h[n-m] x[m]\]

as well as performed in the frequency domain.

\[Y(f) = \mathscr{F} (h(t)) * \mathscr{F} (x(t))\]

For one dimensional inputs, Convolve1D operator uses scipy.signal.convolve, which automatically chooses the best domain for the operation to be carried out. For signals in 2 or more dimensions, the default is instead the fft implementation scipy.signal.fftconvolve, as this routine efficently operates on multi-dimensional arrays; the overlap-add implementation scipy.signal.oaconvolve can be selected via the method parameter, and may be faster when the filter is much shorter than the signal.

As the adjoint of convolution is correlation, Convolve1D operator applies correlation in the adjoint mode.

In time domain:

\[x(t) = \int\limits_{-\infty}^{\infty} h(t+\tau) x(\tau) \,\mathrm{d}\tau\]

or in frequency domain:

\[y(t) = \mathscr{F}^{-1} (H(f)^* * X(f))\]

Methods

`__init__`(dims, h[, offset, axis, method, ...])
`adjoint`()
`apply_columns`(cols)	Apply subset of columns of operator
`cond`([uselobpcg])	Condition number of linear operator.
`conj`()	Complex conjugate operator
`div`(y[, niter, densesolver])	Solve the linear problem \(\mathbf{y}=\mathbf{A}\mathbf{x}\).
`dot`(x)	Matrix-matrix or matrix-vector multiplication.
`eigs`([neigs, symmetric, niter, uselobpcg])	Most significant eigenvalues of linear operator.
`matmat`(X[, pool])	Matrix-matrix multiplication.
`matvec`(x)	Matrix-vector multiplication.
`reset_count`()	Reset counters
`rmatmat`(X[, pool])	Matrix-matrix multiplication.
`rmatvec`(x)	Adjoint matrix-vector multiplication.
`todense`([backend])	Return dense matrix.
`toimag`([forw, adj])	Imag operator
`toreal`([forw, adj])	Real operator
`tosparse`()	Return sparse matrix.
`trace`([neval, method, backend])	Trace of linear operator.
`transpose`()