RunMat
GitHub

View all functions

CategoryMath: Poly
GPUYes

What does the polyval function do in MATLAB / RunMat?

polyval(p, x) evaluates the polynomial defined by the coefficient vector p at every element of x. Coefficients follow MATLAB’s convention: p(1) is the highest-order term, p(end) is the constant term. Both real and complex inputs are supported, and the output matches the shape of x.

How does the polyval function behave in MATLAB / RunMat?

  • Accepts scalar, vector, or N-D coefficient inputs that have at most one non-singleton dimension.
  • Logical and integer coefficients are promoted to double precision; complex coefficients are kept exactly.
  • When p and x are real-valued and a provider is registered, RunMat issues a Horner-series GPU kernel via RunMat Accelerate. Mixed or complex inputs fall back to the reference CPU implementation, with purely real outputs re-uploaded to the device when residency makes sense.
  • polyval(p, x, [], mu) applies centering and scaling parameters from polyfit, evaluating the polynomial at (x - mu(1)) / mu(2).
  • [y, delta] = polyval(p, x, S, mu) computes prediction intervals using the structure S produced by polyfit. RunMat mirrors MATLAB rules: S must contain the fields R, normr, and df, and the interval collapses to zeros when df <= 0 or normr == 0.
  • Empty inputs yield empty outputs; an empty coefficient vector represents the zero polynomial.
  • MATLAB-compatible errors are raised for non-numeric inputs, invalid mu vectors, or malformed S structures.

polyval Function GPU Execution Behaviour

When a GPU provider is active, RunMat first attempts to evaluate the polynomial in device memory using a dedicated Horner kernel. Coefficients and inputs are uploaded automatically when required. If the call requests complex arithmetic, prediction intervals, or otherwise falls outside the GPU kernel’s contract, RunMat gathers to the host, executes the CPU implementation, and (for real-valued results) pushes the output back to the GPU so downstream kernels retain residency.

Examples of using the polyval function in MATLAB / RunMat

Evaluating a polynomial at scalar points

p = [2 -3 5];   % 2x^2 - 3x + 5
y = polyval(p, 4);

Expected output:

y = 21;

Evaluating across a vector of inputs

p = [1 0 -2 1];
x = linspace(-2, 2, 5);
y = polyval(p, x);

Expected output:

y = [ -3   2   1   0   5 ];

Evaluating a polynomial over a matrix grid

[X, Y] = meshgrid(-1:1);
Z = polyval([1 -3 2], X + Y);

Expected output (matching the shape of X and Y):

Z =
    12     6     2
     6     2     0
     2     0     0

Using centering and scaling parameters from polyfit

x = -2:2;
noise = 0.05 * randn(size(x));
[p, S, mu] = polyfit(x, sin(x) + noise, 3);
y = polyval(p, x, [], mu);

Expected output:

% y closely matches sin(x) + noise with polynomial smoothing

Computing prediction intervals with polyfit output

[p, S, mu] = polyfit((0:10)', exp((0:10)'/10), 3);
[y, delta] = polyval(p, 5, S, mu);

Expected output:

% y is the fitted value at x = 5
% delta is the 1σ prediction interval (standard error)

Handling complex coefficients and inputs

p = [1+2i, -3, 4i];
z = [-1+1i, 0, 1-2i];
y = polyval(p, z);

Expected output:

% Complex results that agree with MATLAB's polyval

Evaluating on a gpuArray input

x = gpuArray.linspace(-1, 1, 2048);
p = [1 0 1];
y = polyval(p, x);    % Runs on the GPU for real-valued inputs

Expected behaviour:

y is a gpuArray because the result is real-valued.

FAQ

Do coefficients need to be a row vector?

No. They can be row or column vectors (or any N-D shape with a single non-singleton dimension). The output always matches the shape of x.

What kinds of inputs are accepted?

Numeric scalars, vectors, matrices, N-D arrays, logical arrays, and complex data are all accepted. Logical and integer inputs are promoted to double precision automatically.

How do centering (mu) parameters work?

RunMat mirrors MATLAB: the polynomial is evaluated at (x - mu(1)) / mu(2). The mu vector must contain at least two finite values, and the scale mu(2) must be non-zero.

Why does [y, delta] = polyval(...) require the structure S?

The prediction interval comes from the QR factorization stored in S by polyfit. The structure must include the fields R, df, and normr; without them the interval cannot be computed.

What happens when df <= 0 or normr == 0?

The prediction interval collapses to zeros (RunMat matches MATLAB and Octave here). This typically occurs when the fit is exact or when there are insufficient degrees of freedom.

Can I keep results on the GPU?

Yes. RunMat re-uploads real-valued results to the active provider after the host evaluation. Complex outputs stay on the host until providers add complex buffer uploads.

Does polyval support sparse inputs?

Not yet. Dense inputs (including gpuArray tensors) are supported today. Sparse support will arrive once RunMat's sparse infrastructure stabilises.

See Also

polyfit, conv, deconv, poly, polyder, gpuArray, gather

Source & Feedback

  • Source: crates/runmat-runtime/src/builtins/math/poly/polyval.rs
  • Found an issue or behavioural difference? Open an issue with a minimal reproduction.