RunMat
  • Pricing
RunMat
GitHub
GitHub
Sign inTry in browser
DesktopRuntimePhysicsCADAdministrationAgent

Get RunMat updates

New releases, guides and examples.

Product+
  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download
Math+
  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting
Physics+
  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA
Industries+
  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance
Learn+
  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students
Compare+
  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons
Company+
  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms

Product

  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download

Math

  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting

Physics

  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA

Industries

  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance

Learn

  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students

Compare

  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons

Company

  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms
GitHubXLinkedIn

© Dystr, Inc. · RunMat v0.7.1, Nov 17, 2026

RunMat® is a registered trademark of Dystr, Inc. MATLAB® is a registered trademark of The MathWorks, Inc. RunMat is not affiliated with, endorsed by, or sponsored by The MathWorks, Inc.

/
See all docs
Builtin Reference
    • chol
    • 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

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"`).
NameTypeRequiredDefaultDescription
ANumericArrayYes—Input matrix to factorize.
triangleStringScalarYes"upper"Triangle form (`"upper"` or `"lower"`).
ANumericArrayYes—Sparse input matrix to factorize.
outputFormStringScalarYes"matrix"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.
NameTypeDescription
RNumericArrayUpper or lower triangular Cholesky factor.
pNumericScalarFailure flag (0 means positive definite).
PNumericArraySparse 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
IdentifierWhenMessage
RunMat:chol:InvalidArgumentOption arguments or requested output count are invalid.chol supports a third permutation output only for sparse input
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

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     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;
    assert(norm(A * x - b) < 1e-8);
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'

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

Solve

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

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.

Getting started · Benchmarks · Pricing

Download RunMat

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

Download RunMatOpen Sandbox
On this page
  • Syntax
  • Inputs
  • Returns
  • Errors
  • Syntax
  • Behavior
  • Acceleration and residency
  • Implementation and validation
  • Examples
  • Upper-triangular Cholesky factor of a symmetric positive-definite matrix
  • Lower-triangular factor using the 'lower' option
  • Detecting a non-positive-definite matrix with the two-output form
  • Using the Cholesky factor to solve linear systems
  • Cholesky factor of a complex Hermitian positive-definite matrix
  • Running chol on a gpuArray
  • Using chol with coding agents
  • FAQ
  • Related Linalg functions
  • Factor
  • Structure
  • Solve
  • Ops
  • Source you can read
  • About RunMat