filter — Apply a causal FIR or IIR digital filter along a selected array dimension.
filter(b, a, x) applies the difference equation specified by numerator coefficients b and denominator coefficients a. It operates along the first nonsingleton dimension unless dim is supplied. The optional zi supplies initial state; a second requested output returns final state for a later chunk.
Syntax
y = filter(b, a, x)
y = filter(b, a, x, zi)
y = filter(b, a, x, zi, dim)
[y, zf] = filter(b, a, x)
[y, zf] = filter(b, a, x, zi)
[y, zf] = filter(b, a, x, zi, dim)Inputs
b- Type
Any- Required
- Yes
- Description
- Numerator coefficient vector.
a- Type
Any- Required
- Yes
- Description
- Denominator coefficient vector.
x- Type
Any- Required
- Yes
- Description
- Signal values to filter.
zi- Type
Any- Required
- No
- Default
[]- Description
- Initial filter state (use [] for default zero state).
dim- Type
NumericScalar- Required
- No
- Default
first non-singleton dimension- Description
- Dimension to operate along.
Returns
y- Type
NumericArray- Description
- Filtered signal output.
zf- Type
NumericArray- Description
- Final filter state for warm-starting a subsequent call.
Returned values from filter depend on how many outputs the caller requests.
Errors
RunMat:filter:ArgCount- When
- More than five input arguments are provided.
- Message
filter: expected between three and five input arguments
RunMat:filter:InvalidDimension- When
- dim is missing, non-numeric, non-integer, or less than one.
- Message
filter: dimension must be numeric and >= 1
RunMat:filter:EmptyDenominator- When
- Denominator coefficient vector is empty.
- Message
filter: denominator coefficients cannot be empty
Coefficients, dimensions, and state
b and a must be nonempty vectors and a(1) must be nonzero. RunMat divides both coefficient vectors by a(1) before filtering.
A matrix is filtered column-wise by default. filter(b,a,x,zi,dim) selects another dimension; a dimension beyond ndims(x) is a length-one axis.
zi has the same shape as the returned zf: filter order first, followed by the dimensions of x not being filtered. [] selects zero initial state. For vector input, zf is a column vector.
For empty x, the output signal is empty and final state equals the supplied or zero initial state. Complex coefficients, signals, and states are supported.
The default call returns y; [y,zf] = filter(...) also returns the final state. Pass zf as zi to continue filtering the next chunk.
Classes and execution
Single signal inputs produce single outputs; double, integer, and logical signals produce double outputs. Floating filter arithmetic follows the runtime's coefficient and signal conversion rules; wide-integer rounding at this numerical boundary is not an exact-integer computation.
A real resident signal can use its owning provider's iir_filter operation when the coefficient, state, dimension, and physical-class requirements are met. Complex forms and unsupported provider operations use the host reference path. Operational provider errors are returned with their cause; they are not retried as host computation.
The operation is a fusion boundary. Runtime placement and provider capabilities determine whether the result stays resident; GPU support does not imply that every input form is device-resident.
Examples
Smooth a signal with an FIR average
b = ones(1,3)/3; a = 1; x = [1 5 2 0 3]; y = filter(b,a,x)Expected output:
y =
0.3333 2.0000 2.6667 2.3333 1.6667Apply a first-order IIR low-pass filter
alpha = 0.8; b = 1-alpha; a = [1 -alpha]; imp = [1 zeros(1,4)]; y = filter(b,a,imp)Expected output:
y =
0.2000 0.1600 0.1280 0.1024 0.0819Continue filtering from a saved state
b = ones(1,3)/3; a = 1; x1 = [1 5 2]; [y1,zf] = filter(b,a,x1); x2 = [0 3]; [y2,zf2] = filter(b,a,x2,zf); y1, zf, y2, zf2Expected output:
y1 = [0.3333 2.0000 2.6667]
zf = [2.3333; 0.6667]
y2 = [2.3333 1.6667]
zf2 = [1.0000; 1.0000]Filter across matrix rows
X = [1 2 3 4; 0 1 0 1]; b = [1 -1]; a = 1; Y = filter(b,a,X,[],2)Expected output:
Y =
1 1 1 1
0 1 -1 1Filter complex-valued data
b = [1 1i]; a = 1; t = 0:3; x = exp(1i*pi/4*t); y = filter(b,a,x)Expected output:
y =
1.0000 + 0.0000i 0.7071 + 1.7071i -0.7071 + 1.7071i -1.7071 + 0.7071iFilter a real resident signal
g = gpuArray([1 5 2 0 3]); b = ones(1,3)/3; a = 1; [y_gpu,zf_gpu] = filter(b,a,g); y = gather(y_gpu)Expected output:
y =
0.3333 2.0000 2.6667 2.3333 1.6667Using filter with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how filter changes the result.
Run a small filter example, explain the result, then change one input and compare the output.
FAQ
What if a(1) is not one?⌄
Both coefficient vectors are normalized by the nonzero leading denominator coefficient.
How large must zi be?⌄
It matches zf: filter order first, then the dimensions not being filtered. Use [] for zero state.
Can dim exceed ndims(x)?⌄
Yes. A missing higher axis is treated as length one.
Does the filter support complex inputs?⌄
Yes. Complex arithmetic uses the host reference route when the resident operation lacks that form.
Must I initialize GPU filtering?⌄
No. RunMat selects the owning provider when its real-valued iir_filter form is available; unsupported forms follow the host path.
What happens for an empty signal?⌄
The signal output is empty and final state retains the initial or zero state.
Can I pass integer or logical samples?⌄
Yes. They enter floating filter arithmetic and produce double output; this conversion is not exact wide-integer arithmetic.
How do I filter a stream in chunks?⌄
Request [y,zf] for each chunk and pass that zf as the next call's zi.
Related Math functions
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Elementwise
abs · angle · besselj · bsxfun · complex · conj · double · eps · erf · erfcinv · exp · expm1 · flintmax · gamma · gammaln · heaviside · hypot · imag · int16 · int32 · int64 · int8 · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · times · typecast · uint16 · uint32 · uint64 · uint8
Optim
acceptancesa · annealingboltz · annealingfast · coneprog · crossoverarithmetic · crossoverheuristic · crossoverintermediate · crossoverlaplace · crossoverscattered · crossoversinglepoint · crossovertwopoint · eqnproblem · EquationProblem.solve · EquationProblem.subsasgn · EquationProblem.subsref · evaluate · fgoalattain · fitscalingprop · fitscalingrank · fitscalingshiftlinear · fitscalingtop · fminbnd · fmincon · fminimax · fminsearch · fminunc · fseminf · fsolve · fzero · ga · gacreationlinearfeasible · gacreationnonlinearfeasible · gacreationsobol · gacreationuniform · gacreationuniformint · gaplotbestf · gaplotbestindiv · gaplotdistance · gaplotexpectation · gaplotgenealogy · gaplotmaxconstr · gaplotrange · gaplotscorediversity · gaplotscores · gaplotselection · gaplotstopping · integerConstraint · integral · intlinprog · linprog · lsqcurvefit · lsqlin · LsqlinWarmStart.subsasgn · LsqlinWarmStart.subsref · lsqnonlin · lsqnonneg · mutationadaptfeasible · mutationgaussian · mutationpositivebasis · mutationpower · mutationuniform · optimexpr · optimget · OptimizationConstraint.evaluate · OptimizationConstraint.subsasgn · OptimizationConstraint.subsref · OptimizationExitflag.double · OptimizationExitflag.eq · OptimizationExitflag.ne · OptimizationExitflag.string · OptimizationExpression.acos · OptimizationExpression.acosh · OptimizationExpression.acot · OptimizationExpression.acoth · OptimizationExpression.acsc · OptimizationExpression.acsch · OptimizationExpression.asec · OptimizationExpression.asech · OptimizationExpression.asin · OptimizationExpression.asinh · OptimizationExpression.atan · OptimizationExpression.atanh · OptimizationExpression.cat · OptimizationExpression.cos · OptimizationExpression.cosh · OptimizationExpression.cot · OptimizationExpression.coth · OptimizationExpression.csc · OptimizationExpression.csch · OptimizationExpression.ctranspose · OptimizationExpression.cumprod · OptimizationExpression.cumsum · OptimizationExpression.diag · OptimizationExpression.diff · OptimizationExpression.dot · OptimizationExpression.eq · OptimizationExpression.evaluate · OptimizationExpression.exp · OptimizationExpression.ge · OptimizationExpression.horzcat · OptimizationExpression.ldivide · OptimizationExpression.le · OptimizationExpression.log · OptimizationExpression.mean · OptimizationExpression.minus · OptimizationExpression.mldivide · OptimizationExpression.mpower · OptimizationExpression.mrdivide · OptimizationExpression.mtimes · OptimizationExpression.norm · OptimizationExpression.plus · OptimizationExpression.power · OptimizationExpression.prod · OptimizationExpression.rdivide · OptimizationExpression.reshape · OptimizationExpression.sec · OptimizationExpression.sech · OptimizationExpression.sin · OptimizationExpression.sinh · OptimizationExpression.sqrt · OptimizationExpression.subsasgn · OptimizationExpression.subsref · OptimizationExpression.sum · OptimizationExpression.tan · OptimizationExpression.tanh · OptimizationExpression.times · OptimizationExpression.trace · OptimizationExpression.transpose · OptimizationExpression.uminus · OptimizationExpression.uplus · OptimizationExpression.vertcat · OptimizationExpression.zeros · OptimizationExpression.zerosLike · OptimizationProblem.solve · OptimizationProblem.subsasgn · OptimizationProblem.subsref · OptimizationVariable.subsasgn · OptimizationVariable.subsref · optimoptions · optimplotconstrviolation · optimplotfirstorderopt · optimplotfunccount · optimplotfval · optimplotfvalconstr · optimplotmilp · optimplotstepsize · optimplotx · optimproblem · optimset · optimvar · optimwarmstart · particleswarm · patternsearch · psplotbestf · psplotbestx · psplotfuncount · psplotmaxconstr · psplotmeshsize · pswcreationuniform · pswplotbestf · quad · quadprog · QuadprogWarmStart.subsasgn · QuadprogWarmStart.subsref · saplotbestf · saplotbestx · saplotf · saplotstopping · saplottemperature · saplotx · savemilpsolutions · secondordercone · selectionremainder · selectionroulette · selectionstochunif · selectiontournament · selectionuniform · simulannealbnd · solve · surrogateopt · surrogateoptplot · temperatureboltz · temperatureexp · temperaturefast
Trigonometry
acos · acosd · acosh · acotd · acscd · asecd · asin · asind · asinh · atan · atan2 · atan2d · atand · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Reduction
all · any · bounds · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · maxk · mean · median · min · mink · movmax · movmean · movmedian · movmin · movprod · movstd · movsum · movvar · nnz · prod · rms · std · sum · trapz · var
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Factor
chol · decomposition · decomposition.ctranspose · decomposition.mldivide · decomposition.mrdivide · decomposition.mtimes · decomposition.rdivide · decomposition.subsref · decomposition.times · decomposition.uminus · decomposition.uplus · eig · eigs · gmres · ichol · ilu · lu · ordeig · ordqz · ordschur · pcg · qr · qz · rsf2csf · schur · svd
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Interpolation
griddedInterpolant · griddedInterpolant.subsref · interp1 · interp1q · interp2 · pchip · ppval · spline
Integer Division
Source you can read
Every RunMat function's source is public. Read exactly how filter is executed, line by line, in Rust.
- View the source for filter in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.