pinv — Compute Moore-Penrose pseudoinverses using SVD-based tolerance rules with MATLAB-compatible defaults.
pinv(A) computes pseudoinverses from singular-value decompositions using MATLAB-compatible default tolerance rules, with optional explicit tolerance overrides.
Syntax
X = pinv(A)
X = pinv(A, tol)Inputs
A- Type
Any- Required
- Yes
- Description
- Input matrix.
tol- Type
NumericScalar- Required
- No
- Description
- Singular-value threshold.
Returns
X- Type
NumericArray- Description
- Pseudoinverse of A.
Errors
RunMat:pinv:InvalidArgument- When
- Optional tolerance argument is malformed or outside accepted bounds.
- Message
pinv: invalid argument
RunMat:pinv:InvalidInput- When
- Input shape/type cannot be processed for pseudoinverse evaluation.
- Message
pinv: invalid input
RunMat:pinv:Internal- When
- Runtime fails while computing pseudoinverse or executing fallback/upload paths.
- Message
pinv: internal runtime failure
Behavior
Supports scalars, vectors, and higher-dimensional inputs that behave like matrices (trailing singleton dimensions are allowed; other higher ranks must be reshaped first).
Public MATLAB matrix classes are single and double. RunMat mode separately admits logical matrices and all eight real integer classes through named extensions; integer data must be exactly representable as binary64, the result is double, and wider values reject instead of rounding.
Optional second argument pinv(A, tol) treats values in tol as the user-specified cutoff for singular values. Entries ≤ tol contribute zeros in the diagonal of Σ⁺.
Complex matrices are handled in full complex arithmetic via A = U * Σ * Vᴴ.
Empty matrices return the appropriately sized zero matrix (size(pinv(A)) == fliplr(size(A))).
The result always has size n × m if the input is m × n.
RunMat preserves single or double floating class in the result, including complex inputs; its integer and logical input extensions produce double. Nonfinite inputs produce NaN-valued results instead of entering the SVD solver.
A typed-integer tolerance is a separate RunMat extension because the public scalar tolerance does not enumerate integer classes. It must be exactly representable as binary64 before threshold computation; logical tolerance is independently gated.
Resident integer input bypasses floating provider pseudoinverse kernels, gathers through its exact owner, and restores the double result to that owner when supported.
Acceleration and residency
Invokes the acceleration provider's pinv hook when available; the current WGPU backend gathers to the host, runs the shared SVD implementation, and re-uploads the result to keep downstream residency intact.
When a GPU acceleration provider is active, RunMat offers the operation through its pinv hook, passing along any explicit tolerance. Providers may implement a native GPU kernel; otherwise, they can gather to the host, invoke the shared SVD routine, and re-upload the result. The shipping WGPU backend follows this gather/compute/upload pattern today, so downstream GPU work retains residency without MATLAB-level changes.
Explicit residency management is rarely required. When inputs already live on the GPU and the provider implements pinv, the builtin executes entirely on the device. Providers without a native kernel (including the current WGPU backend) transparently download the matrix, run the shared CPU path, and re-upload the result so the caller continues working with a GPU tensor. gpuArray remains available for MATLAB compatibility or to seed GPU residency explicitly.
Implementation and validation
Original GPU declarations: precisions f32, f64; elementwise false; reduction false; broadcasting none.
Original fusion declarations: elementwise false; reduction false; max inputs 1; constants uniform.
Examples
Finding the pseudoinverse of a tall matrix
A = [1 0; 0 0; 0 1];
X = pinv(A)Expected output:
X =
1 0 0
0 0 1Solving an overdetermined least-squares problem
A = [1 1; 1 2; 1 3];
b = [1; 0; 0];
x = pinv(A) * bExpected output:
x = [1.3333; -0.5000]Suppressing small singular values with a custom tolerance
A = diag([1, 1e-10]);
X = pinv(A, 1e-6)Expected output:
X =
1 0
0 0Pseudoinverse of a rank-deficient square matrix
A = [1 2; 2 4];
X = pinv(A)Expected output:
X =
0.0400 0.0800
0.0800 0.1600Pseudoinverse of a complex diagonal matrix
A = diag([2+1i, 3-2i]);
X = pinv(A)Expected output:
X =
0.4000 - 0.2000i 0
0 0.2308 + 0.1538iUsing pinv with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how pinv changes the result.
Run a small pinv example, explain the result, then change one input and compare the output.
FAQ
How is pinv different from inv?⌄
inv(A) requires A to be square and full rank. pinv(A) works for any matrix shape and produces the minimum-norm solution even when A is singular or rectangular.
What tolerance does pinv use by default?⌄
RunMat matches MATLAB: max(size(A)) * eps(max(s)), where s are the singular values. Values below this threshold are treated as zero when forming Σ⁺.
Can I recover the rank from the pseudoinverse?⌄
Yes. Count the singular values greater than the effective tolerance (rank returns this directly). The same tolerance drives both pinv and rank.
Does pinv support complex inputs?⌄
Absolutely. Complex matrices use a full complex SVD with conjugate transposes, matching MATLAB's definition.
Will calling pinv move my data off the GPU?⌄
Only if the active provider lacks a native implementation. In that case RunMat gathers, computes, and re-uploads for you. Providers may expose native kernels to keep the entire computation on the device.
Is pinv(A) * b equivalent to A \\ b?⌄
For full-rank systems, yes. A \\ b is typically faster and more numerically stable, but pinv remains useful for ill-conditioned or rank-deficient problems where the pseudoinverse is desired.
Related Linalg functions
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Factor
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
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 pinv is executed, line by line, in Rust.
- View the source for pinv 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.