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
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Input matrix. |
tol | NumericScalar | No | — | Singular-value threshold. |
Returns
| Name | Type | Description |
|---|---|---|
X | NumericArray | Pseudoinverse of A. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:pinv:InvalidArgument | Optional tolerance argument is malformed or outside accepted bounds. | pinv: invalid argument |
RunMat:pinv:InvalidInput | Input shape/type cannot be processed for pseudoinverse evaluation. | pinv: invalid input |
RunMat:pinv:Internal | Runtime fails while computing pseudoinverse or executing fallback/upload paths. | pinv: internal runtime failure |
How pinv works
- Supports scalars, vectors, and higher-dimensional inputs that behave like matrices (trailing singleton dimensions are allowed; other higher ranks must be reshaped first).
- Logical and integer inputs are promoted to
doublebefore the SVD, matching MATLAB semantics. - Optional second argument
pinv(A, tol)treats values intolas the user-specified cutoff for singular values. Entries ≤tolcontribute 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 × mif the input ism × n.
Does RunMat run pinv on the GPU?
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.
GPU memory and residency
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.
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.1667
-0.5000Suppressing 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
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. 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 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.