roots — Compute polynomial roots from coefficient vectors with MATLAB-compatible ordering and complex output behavior.
roots(p) returns the zeros of the polynomial whose coefficients are listed in p from highest to lowest degree. Results are returned as a column vector and may be complex, following MATLAB-compatible companion-matrix semantics.
Syntax
r = roots(c)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
c | Any | Yes | — | Polynomial coefficient vector in descending power order. |
Returns
| Name | Type | Description |
|---|---|---|
r | Any | Roots of the polynomial as a column vector. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:roots:InvalidInput | Input cannot be interpreted as a numeric coefficient vector. | roots: invalid input |
RunMat:roots:Internal | Runtime fails while building companion matrix outputs or solving eigenvalues. | roots: internal runtime failure |
How roots works
- Leading zeros in the coefficient vector are discarded before solving. If all coefficients are zero, the result is an empty column vector.
- Constant polynomials (degree 0) produce an empty output because they have no finite roots.
- Linear polynomials return the single solution
-b/a. Higher-degree polynomials are solved via the eigenvalues of the companion matrix. - Real coefficients can generate complex conjugate root pairs. Small imaginary round-off terms are rounded to zero to match MATLAB formatting.
- Input vectors can be row or column vectors. Higher-dimensional arrays are rejected.
- The MATLAB-compatible coefficient classes are single and double, real or complex. RunMat mode additionally admits all eight integer classes when every coefficient is exactly representable in binary64; otherwise it raises
RunMat:compatibility:RootsIntegerCoefficientsExtensionbefore solving.
Does RunMat run roots on the GPU?
RunMat gathers GPU-resident coefficient vectors to the host because the companion matrix eigenvalue computation presently runs only on the CPU. The output is produced on the host as well. When future providers supply a dedicated polynomial root solver, the builtin can be updated to keep residency on-device transparently.
Examples
Finding roots of a quadratic polynomial
p = [1 -3 2];
r = roots(p)Expected output:
r =
2
1Computing roots that include repeated factors
p = [1 -2 1 0]; % (x - 1)^2 * x
r = roots(p)Expected output:
r =
1
1
0Handling leading zeros in the coefficient vector
p = [0 0 1 -4];
r = roots(p)Expected output:
r =
4Calculating complex roots from real coefficients
p = [1 0 1];
r = roots(p)Expected output:
r =
0.0000 + 1.0000i
0.0000 - 1.0000iSolving roots of a polynomial stored on the GPU
p = gpuArray([1 0 -9 0]);
r = roots(p)Expected output:
r =
3.0000
-3.0000
0Using roots with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how roots changes the result.
Run a small roots example, explain the result, then change one input and compare the output.
FAQ
What shape must the coefficient vector have?⌄
roots accepts row vectors, column vectors, or 1-D arrays. Higher-dimensional tensors are rejected with an error.
How are leading zeros handled?⌄
Leading zeros are removed before solving. If all coefficients are zero, roots returns an empty column vector.
Does roots preserve the data type of the coefficients?⌄
Single and double coefficients enter the floating companion-matrix solver. Integer coefficients are a checked RunMat extension: exact binary64 values are admitted, values outside that boundary reject, and the output is double or complex double.
Are the roots sorted?⌄
Roots are returned in the order supplied by the eigenvalue computation (typically descending magnitude). MATLAB also does not sort the roots.
Can I run roots entirely on the GPU?⌄
Not yet. RunMat gathers coefficients from the GPU, solves the companion matrix on the CPU, and returns a host-resident vector. When GPU providers add a polynomial root solver, this builtin will automatically route to it.
How does RunMat handle numerical round-off?⌄
Small imaginary components (|imag| ≤ 1e-10·(1 + |real|)) are rounded to zero so that near-real roots are displayed as real numbers, matching MATLAB formatting.
Related Math functions
Elementwise
abs · angle · bsxfun · complex · conj · double · erf · erfcinv · exp · expm1 · factorial · flintmax · gamma · gammaln · heaviside · hypot · idivide · imag · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · swapbytes · times · typecast · uint16 · uint32 · uint8
Trigonometry
acos · acosh · asin · asinh · atan · atan2 · 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
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Optim
coneprog · fminbnd · fminunc · fsolve · fzero · integral · linprog · lsqcurvefit · lsqnonlin · optimoptions · optimset · quad · secondordercone
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how roots is executed, line by line, in Rust.
- View the source for roots in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 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.