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)
[R, p, P] = chol(S)
[R, p, P] = chol(S, outputForm)
[R, p, P] = chol(S, triangle, outputForm)Inputs
A- Type
NumericArray- Required
- Yes
- Description
- Input matrix to factorize.
triangle- Type
StringScalar- Required
- Yes
- Default
"upper"- Description
- Triangle form (`"upper"` or `"lower"`).
A- Type
NumericArray- Required
- Yes
- Description
- Sparse input matrix to factorize.
outputForm- Type
StringScalar- Required
- Yes
- Default
"matrix"- Description
- Sparse permutation form (`"matrix"` or `"vector"`).
Returns
R- Type
NumericArray- Description
- Upper or lower triangular Cholesky factor.
p- Type
NumericScalar- Description
- Failure flag (0 means positive definite).
P- Type
NumericArray- Description
- Sparse fill-reducing permutation matrix or vector.
Returned values from chol depend on how many outputs the caller requests.
Errors
RunMat:chol:InvalidArgument- When
- Option arguments or requested output count are invalid.
- Message
chol supports a third permutation output only for sparse input
RunMat:chol:InvalidInput- When
- Input is unsupported or not a square matrix.
- Message
chol: expected a square numeric matrix
RunMat:chol:NotPositiveDefinite- When
- Single-output form receives a matrix that is not positive definite.
- Message
Matrix must be positive definite.
RunMat:chol:Internal- When
- Runtime cannot materialize Cholesky outputs.
- Message
chol: internal runtime failure
Syntax
R = chol(A)
R = chol(A, triangle)
[R, flag] = chol(___)
[R, flag, P] = chol(S)
[R, flag, p] = chol(S, 'vector')
A is a square Hermitian (or real symmetric) matrix that is expected to be positive definite. Logical and integer inputs are promoted to double; complex inputs must satisfy A == A'.
triangle is 'upper' (the default) or 'lower'. chol(A, 'upper') returns an upper-triangular R with R' * R = A; chol(A, 'lower') returns a lower-triangular L with L * L' = A. Both encode the same factorization.
flag is the optional second output. It equals 0 when the factorization succeeds; otherwise it is the index of the first leading principal minor that failed the positive-definiteness test, and only the leading flag - 1 columns of the factor are valid. Using the two-output form suppresses the error that the single-output form raises.
For sparse S, the factor remains sparse. The three-output form applies an approximate-minimum-degree preordering and returns it as a sparse permutation matrix by default or a one-based row vector with 'vector'.
Behavior
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.
Typed-integer and logical matrices are mode-gated RunMat extensions. Integer values from all eight classes must lie within the exact-integer binary64 range and produce a double factor.
Single input preserves single output. Complex inputs must be Hermitian positive definite (HPD), and the factor preserves complex values.
Only the selected upper or lower triangle determines the factorization; values in the opposite triangle are ignored.
Sparse input is factored by the managed simplicial CSC owner. With three outputs, P' * S * P = R' * R (or S(p,p) = R' * R for vector output); lower form uses the corresponding L * L' identity.
Scalar and 0×0 inputs are supported. chol([]) returns an empty matrix with p = 0.
Acceleration and residency
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.
Uses provider chol hook when available, otherwise gathers to host and re-uploads the factor.
Implementation and validation
Dense chol uses the canonical dense Cholesky owner. Sparse chol uses an invocation-owned left-looking simplicial CSC factor: source topology stays borrowed, fill growth and AMD scratch are admitted before allocation, and the published sparse factor and permutation own exact retained claims.
The resident provider path remains the canonical dense GPU route. Sparse inputs execute on the managed host owner and are not counted as GPU execution.
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 3Lower-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 3Detecting 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 =
2Using 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;
assert(norm(A * x - b) < 1e-8);
endCholesky 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 =
0Running chol on a gpuArray
G = gpuArray([6 2; 2 5]);
[R, p] = chol(G);
class(R)Expected output:
ans =
'gpuArray'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?⌄
Yes. Sparse single, double, and complex matrices use a managed CSC Cholesky factorization. Request a third output to enable fill-reducing ordering; pass 'vector' to return the one-based permutation vector.
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.
Related Linalg functions
Factor
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
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Source you can read
Every RunMat function's source is public. Read exactly how chol is executed, line by line, in Rust.
- View the source for chol 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.