RunMat
GitHub

chol — Compute Cholesky factorizations in MATLAB and RunMat.

chol(A) computes a Cholesky factorization of Hermitian positive-definite matrix A. By default it returns upper-triangular R such that R' * R = A; [R, p] reports success (p = 0) or failure index, matching MATLAB and RunMat.

Syntax

R = chol(A)
R = chol(A, triangle)
[R, p] = chol(A)
[R, p] = chol(A, triangle)

Inputs

NameTypeRequiredDefaultDescription
ANumericArrayYes—Input matrix to factorize.
triangleStringScalarYes"upper"Triangle form (`"upper"` or `"lower"`).

Returns

NameTypeDescription
RNumericArrayUpper or lower triangular Cholesky factor.
pNumericScalarFailure flag (0 means positive definite).

Returned values from chol depend on how many outputs the caller requests.

Errors

IdentifierWhenMessage
RunMat:chol:InvalidArgumentOption arguments or requested output count are invalid.chol currently supports at most two outputs
RunMat:chol:InvalidInputInput is unsupported or not a square matrix.chol: expected a square numeric matrix
RunMat:chol:NotPositiveDefiniteSingle-output form receives a matrix that is not positive definite.Matrix must be positive definite.
RunMat:chol:InternalRuntime cannot materialize Cholesky outputs.chol: internal runtime failure

How chol works

  • 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.

Does RunMat run chol on the GPU?

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

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:

R =
     1     2
     0     0

p =
     2

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

Cholesky factor of a complex Hermitian positive-definite matrix

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

Expected output:

R =
    2.2361   0.4472 -0.8944i
         0   1.7321

p =
     0

Running chol on a gpuArray

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

Expected output:

ans =
    'gpuArray'

How RunMat validates chol

chol delegates to LAPACK's dpotrf/zpotrf when the lapack-backed-linalg feature is enabled and falls back to an in-repo Cholesky implementation otherwise. Both paths share the same test suite. The GPU provider hook reuploads the CPU-computed factor so device residency is preserved without a separate GPU Cholesky kernel.

See Correctness & Trust for the full methodology and coverage table.

Using chol with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how chol changes the result.

Run a small chol example, explain the result, then change one input and compare the output.

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.

What does chol compute?⌄

— The Cholesky factorization of a Hermitian positive-definite matrix A: a triangular factor whose product with its conjugate transpose reconstructs A. The default form returns an upper-triangular R with R' * R = A; the 'lower' form returns L with L * L' = A. It is roughly twice as fast as lu and preferred whenever symmetry and positive-definiteness are guaranteed.

How do I use chol to test whether a matrix is positive definite?⌄

— Call the two-output form and check the flag: [~, p] = chol(A); isPD = (p == 0);. This avoids the error that the single-output form throws on indefinite inputs, and it is substantially faster than computing all eigenvalues with eig.

Factor

eig · lu · qr · svd

Solve

cond · det · inv · linsolve · norm · pinv · rank · rcond · rref

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how chol is executed, line by line, in Rust.

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.

Getting started · Benchmarks · Pricing

Download RunMat

Download RunMat for full performance, or use RunMat in your browser for zero setup.

Download RunMatTry in your browser