RunMat
GitHub

View all functions

CategoryMath: Linalg & Factor
BLAS/LAPACK

What does the chol function do in MATLAB / RunMat?

chol(A) computes a Cholesky factorization of a Hermitian positive-definite matrix A. By default, it returns the upper-triangular factor R satisfying R' * R = A. The two-output form [R, p] = chol(A) reports whether the factorization succeeded: p = 0 for success, and otherwise p equals the index of the first leading principal minor that is not positive definite.

How does the chol function behave in MATLAB / RunMat?

  • Single output (chol(A)): Returns the upper-triangular factor. If A is not positive definite, a MATLAB-compatible error ("Matrix must be positive definite.") is raised.
  • Two outputs ([R, p] = chol(A)): Returns the factor R and a flag p. When p > 0, R contains the partial factorization up to the (p-1)-th column.
  • Lower form (chol(A, 'lower')): Returns a lower-triangular factor L such that L * L' = A. The two-output variant [L, p] = chol(A, 'lower') follows the same failure semantics.
  • The option 'upper' is accepted for completeness and matches the default behaviour.
  • Real logical inputs are promoted to double precision. Complex inputs must be Hermitian positive definite (HPD); the factor preserves complex values.
  • Scalar and 0×0 inputs are supported. chol([]) returns an empty matrix with p = 0.

chol Function GPU Execution Behaviour

When RunMat Accelerate is active, the planner keeps gpuArray inputs on device and asks the registered provider for a chol factorization. Providers that implement the hook (the WGPU and in-process backends included) return the MATLAB-compatible flag p while leaving the triangular factor resident on the GPU. If the provider lacks that hook or the matrix uses an unsupported precision/type, RunMat gathers the data, executes the CPU implementation, and re-uploads the factor when a provider is present. The flag output is always materialised as a host scalar.

Examples of using the chol function in MATLAB / RunMat

Upper-triangular Cholesky factor of a symmetric positive-definite matrix

A = [4 12 -16; 12 37 -43; -16 -43 98];
R = chol(A);

Expected output:

R =
     2     6    -8
     0     1    -5
     0     0     3

Lower-triangular factor using the 'lower' option

A = [25 15 -5; 15 18  0; -5 0 11];
L = chol(A, 'lower');

Expected output:

L =
     5     0     0
     3     3     0
    -1     1     3

Detecting a non-positive-definite matrix with the two-output form

A = [1 2; 2 1];
[R, p] = chol(A);

Expected output:

p =
     2

R =
     1     2
     0     0

Using the Cholesky factor to solve linear systems

A = [10 2 3; 2 9 1; 3 1 7];
b = [1; 2; 3];
[R, p] = chol(A);
if p == 0
    y = R' \ b;
    x = R \ y;
end

x is the solution to A * x = b.

Cholesky factor of a complex Hermitian positive-definite matrix

A = [5 1-2i; 1+2i 4];
[R, p] = chol(A);

Expected output:

p =
     0

R =
    2.2361   0.2236 -0.8944i
         0   1.9849 +0.5046i

Running chol on a gpuArray

G = gpuArray([6 2; 2 5]);
[R, p] = chol(G);
class(R)

Expected output:

p =
     0

ans =
    'gpuArray'

When no GPU provider is registered, RunMat automatically gathers the input, performs the host factorization, and leaves the results on the host.

FAQ

What does the second output p mean?

p is zero when the factorization succeeds. Otherwise, it is the index of the first leading principal minor that is not positive definite. The returned factor contains the partial result up to that point.

How do I request the lower-triangular factor?

Pass 'lower' (case-insensitive) as the second argument: [L, p] = chol(A, 'lower'). The default behaviour (chol(A)) returns the upper-triangular factor.

Why do I get an error when using a single output on an indefinite matrix?

The single-output form matches MATLAB and throws an error when the matrix is not positive definite. Use the two-output form [R, p] to obtain the partial factor and inspect p without raising an error.

Does chol accept sparse matrices?

Not yet. RunMat currently implements the dense MATLAB semantics. Sparse support is planned in a future release.

Can I pass logical or integer arrays?

Yes. They are promoted to double precision before factorization, matching MATLAB behaviour.

Do complex inputs need to be Hermitian?

Yes. chol operates on Hermitian positive-definite matrices. If the matrix is not Hermitian, p will be non-zero in the two-output form, and the single-output form raises an error.

How should I interpret the result when p > 0?

Only the leading (p-1) columns/rows of the factor are valid. The remaining portions are zeros, mirroring MATLAB’s contract.

Does the GPU path return the same flag p?

Yes. Providers report the MATLAB-compatible failure index, and RunMat converts it into the scalar second output.

Is the factor unique?

The standard Cholesky factorization returns an upper-triangular matrix with positive diagonal entries. The lower-triangular form is the conjugate transpose of the upper form and is likewise unique under the same assumptions.

How should I choose between chol and lu/qr?

Use chol when the matrix is Hermitian positive definite—its triangular factors are cheaper to compute and exploit symmetry. Use lu or qr for more general matrices.

See Also

lu, qr, gpuArray, gather

Source & Feedback