API Reference¶

def cholesky(cov: Matrix, rhs: Vector | Matrix | None = None) -> Vector | Matrix:
    """Compute the upper triangular Cholesky factor of a covariance matrix.

    Returns the upper triangular factor R such that R.T @ R = cov.

    Args:
        cov: A positive definite covariance matrix of shape (n, n).
        rhs: Deprecated. When provided the system ``cov @ x = rhs`` is solved
            and *x* is returned; use :func:`cholesky_solve` instead. This
            parameter will be removed in 1.0.

    Returns:
        The upper triangular Cholesky factor R when *rhs* is ``None``, or the
        solution x to ``cov @ x = rhs`` otherwise (deprecated).

    Raises:
        np.linalg.LinAlgError: When *rhs* is ``None`` and *cov* is not
            positive-definite, or when *rhs* is given and both Cholesky and
            LU-based solves fail.

    Warns:
        DeprecationWarning: When *rhs* is given.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import cholesky
        >>> cov = np.array([[4.0, 2.0], [2.0, 5.0]])
        >>> R = cholesky(cov)
        >>> np.allclose(R.T @ R, cov)
        True
    """
    if rhs is None:
        return cast("Matrix", _cholesky(cov).transpose())
    warnings.warn(
        "Passing 'rhs' to cholesky() is deprecated and will be removed in 1.0; use cholesky_solve(cov, rhs) instead.",
        DeprecationWarning,
        stacklevel=2,
    )
    return cholesky_solve(cov, rhs)

def cholesky_solve(cov: Matrix, rhs: Vector | Matrix) -> Vector | Matrix:
    """Solve ``cov @ x = rhs`` using the Cholesky decomposition.

    The Cholesky factorisation is attempted first for numerical stability;
    when *cov* is not positive-definite the solve falls back to LU
    decomposition.

    Args:
        cov: A positive definite covariance matrix of shape (n, n).
        rhs: Right-hand side vector of length n or matrix of shape (n, k).

    Returns:
        The solution x to ``cov @ x = rhs`` with the same shape as *rhs*.

    Raises:
        np.linalg.LinAlgError: When both the Cholesky and LU-based solves fail.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import cholesky_solve
        >>> cholesky_solve(np.eye(2), np.array([1.0, 2.0])).tolist()
        [1.0, 2.0]
        >>> cholesky_solve(np.array([[4.0, 0.0], [0.0, 9.0]]), np.array([8.0, 27.0])).tolist()
        [2.0, 3.0]
    """
    try:
        upper = _cholesky(cov).transpose()
        return cast("Vector | Matrix", np.linalg.solve(upper, np.linalg.solve(upper.T, rhs)))
    except np.linalg.LinAlgError:
        return cast("Vector | Matrix", np.linalg.solve(cov, rhs))

def is_positive_definite(matrix: Matrix) -> bool:
    """Return True if *matrix* is symmetric positive-definite, False otherwise.

    The check is performed via an attempted Cholesky decomposition — the most
    numerically reliable way to test positive-definiteness for symmetric matrices.

    This function is side-effect-free: it raises no exceptions and emits no
    warnings.  It is suitable for use as a guard before passing a matrix to a
    linear solver.

    Args:
        matrix: Square matrix to test.

    Returns:
        ``True`` if the matrix is positive-definite, ``False`` otherwise.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import is_positive_definite
        >>> is_positive_definite(np.eye(3))
        True
        >>> is_positive_definite(np.array([[1.0, 2.0], [2.0, 1.0]]))
        False
        >>> is_positive_definite(np.array([[1.0, 0.5], [0.5, 1.0]]))
        True
    """
    try:
        cholesky(matrix)
    except np.linalg.LinAlgError:
        return False
    else:
        return True

def eigh(matrix: Matrix) -> tuple[Vector, Matrix]:
    """Compute eigendecomposition of a real symmetric or Hermitian matrix.

    Rows and columns with non-finite diagonal entries are excluded before
    decomposition.

    Args:
        matrix: Square symmetric/Hermitian input matrix.

    Returns:
        A tuple ``(eigenvalues, eigenvectors)`` as returned by ``np.linalg.eigh``
        on the valid submatrix. Eigenvalues are sorted in ascending order.
    """
    _, submatrix = valid(matrix)
    return np.linalg.eigh(submatrix)

def eigvalsh(matrix: Matrix) -> Vector:
    """Return eigenvalues of a real symmetric or Hermitian matrix.

    Rows and columns with non-finite diagonal entries are excluded before
    decomposition.

    Args:
        matrix: Square symmetric/Hermitian input matrix.

    Returns:
        Eigenvalues of the valid submatrix in ascending order.
    """
    eigenvalues, _ = eigh(matrix)
    return eigenvalues

def eigvals(matrix: Matrix) -> Vector | npt.NDArray[np.complex128]:
    """Return the eigenvalues of a square matrix.

    This routine supports general (non-symmetric) square matrices and may
    return complex eigenvalues.

    Args:
        matrix: Square input matrix.

    Returns:
        Eigenvalues of ``matrix`` as returned by ``numpy.linalg.eigvals``.

    Raises:
        NotAMatrixError: If *matrix* is not two-dimensional.
        NonSquareMatrixError: If *matrix* is not square.
    """
    if matrix.ndim != 2:
        raise NotAMatrixError(matrix.ndim, func="eigvals")

    if matrix.shape[0] != matrix.shape[1]:
        raise NonSquareMatrixError(matrix.shape[0], matrix.shape[1])

    return cast("Vector | npt.NDArray[np.complex128]", np.linalg.eigvals(matrix))

def qr(matrix: Matrix) -> tuple[Matrix, Matrix]:
    """Compute the reduced QR decomposition of a 2-D matrix.

    Args:
        matrix: Input matrix with shape ``(m, n)``.

    Returns:
        A tuple ``(Q, R)`` matching ``np.linalg.qr(matrix, mode="reduced")``.

    Raises:
        NotAMatrixError: If ``matrix`` is not two-dimensional.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import qr
        >>> q, r = qr(np.array([[1.0, 2.0], [3.0, 4.0]]))
        >>> np.allclose(q @ r, np.array([[1.0, 2.0], [3.0, 4.0]]))
        True
    """
    if matrix.ndim != 2:
        raise NotAMatrixError(matrix.ndim, func="qr")

    return np.linalg.qr(matrix, mode="reduced")

def svd(matrix: Matrix) -> tuple[Matrix, Matrix, Matrix]:
    """Compute the compact singular value decomposition of a matrix.

    This is a thin wrapper around ``numpy.linalg.svd`` with
    ``full_matrices=False``.

    Args:
        matrix: Input matrix of shape ``(m, n)``.

    Returns:
        Tuple ``(u, s, vt)`` such that ``matrix == u @ np.diag(s) @ vt``.
    """
    return np.linalg.svd(matrix, full_matrices=False)

def svd_k(matrix: Matrix, k: int) -> tuple[Matrix, Vector, Matrix]:
    """Compute the truncated rank-``k`` singular value decomposition.

    Returns the ``k`` leading singular triplets — the best rank-``k``
    approximation of *matrix* in both the spectral and Frobenius norms
    (Eckart-Young). This is an *exact* truncation: the full compact SVD is
    computed and sliced, so the result is deterministic and matches
    :func:`numpy.linalg.svd` on the leading components. Like :func:`svd`, it is
    a raw decomposition and is **not** NaN-aware; clean non-finite entries
    first.

    Args:
        matrix: Input matrix of shape ``(m, n)``.
        k: Number of leading singular triplets to keep. Must be between 1 and
            ``min(m, n)``.

    Returns:
        Tuple ``(u, s, vt)`` with shapes ``(m, k)``, ``(k,)`` and ``(k, n)``,
        such that ``u @ np.diag(s) @ vt`` is the best rank-``k`` approximation
        of *matrix*. Singular values are in descending order.

    Raises:
        InvalidComponentsError: If *k* is smaller than 1 or larger than
            ``min(m, n)``.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import svd_k
        >>> matrix = np.diag([3.0, 2.0, 1.0]) @ np.ones((3, 4))
        >>> u, s, vt = svd_k(matrix, k=1)
        >>> u.shape, s.shape, vt.shape
        ((3, 1), (1,), (1, 4))

        The leading triplets agree with the full SVD:

        >>> u_full, s_full, vt_full = np.linalg.svd(matrix, full_matrices=False)
        >>> bool(np.allclose(s, s_full[:1]))
        True

        ``svd_k(matrix, min(m, n))`` reconstructs the matrix exactly:

        >>> u, s, vt = svd_k(matrix, k=3)
        >>> bool(np.allclose(u @ np.diag(s) @ vt, matrix))
        True
    """
    max_components = min(matrix.shape)
    if not 1 <= k <= max_components:
        raise InvalidComponentsError(k, max_components)

    u, s, vt = np.linalg.svd(matrix, full_matrices=False)
    return u[:, :k], s[:k], vt[:k, :]

def pca(returns: Matrix, n_components: int = 10) -> PCA:
    """Compute the first n principal components for a return matrix using SVD.

    Unlike most functions in this package, ``pca`` is not NaN-aware: *returns*
    must contain only finite values. Clean or impute missing data first.

    Args:
        returns: Array of asset returns with shape (n_samples, n_assets).
            Must not contain NaN or infinite values.
        n_components: Number of principal components to extract. Must be
            between 1 and ``min(n_samples, n_assets)``. Defaults to 10.

    Raises:
        InvalidComponentsError: If *n_components* is smaller than 1 or larger
            than ``min(n_samples, n_assets)``.

    Returns:
        PCA named tuple containing:
            - explained_variance: Ratio of variance explained by each component
            - factors: Factor returns (scores)
            - exposure: Factor exposures (loadings)
            - cov: Factor covariance matrix
            - systematic: Returns explained by factors
            - idiosyncratic: Residual returns

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import pca
        >>> np.random.seed(42)
        >>> returns = np.random.randn(100, 10)
        >>> result = pca(returns, n_components=3)
        >>> bool(result.explained_variance[0] > result.explained_variance[1])
        True
        >>> factor_corr = np.corrcoef(result.factors.T)
        >>> bool(np.allclose(factor_corr, np.eye(3), atol=0.1))
        True
        >>> VtV = result.exposure @ result.exposure.T
        >>> bool(np.allclose(VtV, np.eye(3), atol=1e-10))
        True
        >>> all(result.explained_variance[i] >= result.explained_variance[i+1]
        ...     for i in range(len(result.explained_variance)-1))
        True
        >>> reconstructed = result.factors @ result.exposure
        >>> centered_systematic = result.systematic - returns.mean(axis=0)
        >>> bool(np.allclose(reconstructed, centered_systematic, atol=1e-10))
        True

    """
    max_components = min(returns.shape)
    if not 1 <= n_components <= max_components:
        raise InvalidComponentsError(n_components, max_components)

    x_mean = returns.mean(axis=0)
    x_centered = returns - x_mean

    u, s_full, vt = svd(x_centered)

    u = u[:, :n_components]
    s = s_full[:n_components]
    vt = vt[:n_components, :]

    factors: Matrix = u * s
    exposure: Matrix = vt
    explained_variance: Matrix = (s**2) / np.sum(s_full**2)
    cov: Matrix = np.atleast_2d(np.cov(factors.T))
    systematic: Matrix = factors @ vt + x_mean
    idiosyncratic: Matrix = x_centered - factors @ vt

    return PCA(
        explained_variance=explained_variance,
        factors=factors,
        exposure=exposure,
        cov=cov,
        systematic=systematic,
        idiosyncratic=idiosyncratic,
    )

def power_iteration(
    operator: Matrix | SupportsMatvec | Callable[[Vector], Vector],
    *,
    n: int | None = None,
    n_iter: int = 1000,
    tol: float = 1e-9,
    seed: int | None = None,
) -> tuple[float, Vector]:
    """Estimate the dominant eigenpair of a real symmetric operator.

    Repeatedly applies *operator* to a random unit vector, renormalizing each
    step, until the Rayleigh-quotient eigenvalue estimate stops changing. The
    iterate converges to the eigenvector whose eigenvalue is largest in
    magnitude; the matching eigenvalue (returned with its sign) comes from the
    Rayleigh quotient ``v.T @ (operator @ v)``.

    *operator* may be given three ways, so the leading eigenvalue can be
    estimated **matrix-free** (e.g. the Lipschitz constant of a gradient step):

    * a dense symmetric ``(n, n)`` array;
    * any :class:`~cvx.linalg.SymmetricOperator` (its :meth:`matvec` and ``n``
      drive the iteration, so no ``n x n`` matrix is formed); or
    * a callable ``v -> A @ v`` together with the dimension *n*.

    Each iteration costs a single application, so this is far cheaper than a full
    :func:`~cvx.linalg.eigh` when only the leading eigenpair is needed and there
    is a clear spectral gap. Symmetry is assumed; only the result's
    interpretation as an eigenpair relies on it. Like :func:`~cvx.linalg.svd`,
    this is a raw primitive and is **not** NaN-aware.

    Args:
        operator: A symmetric matrix, a :class:`~cvx.linalg.SymmetricOperator`,
            or a callable applying it to a vector.
        n: Dimension of the operator. Required when *operator* is a bare callable;
            ignored otherwise (taken from the array shape or the operator's ``n``).
        n_iter: Maximum number of iterations. Defaults to 1000.
        tol: Convergence tolerance on the relative change of the eigenvalue
            estimate between iterations. Defaults to ``1e-9``.
        seed: Seed for the random starting vector, for reproducibility. If
            ``None``, uses the current NumPy random state.

    Returns:
        Tuple ``(eigenvalue, eigenvector)`` where *eigenvalue* is the signed
        dominant eigenvalue estimate (a ``float``) and *eigenvector* is the
        corresponding unit-norm eigenvector. The eigenvector sign is arbitrary.

    Raises:
        NotAMatrixError: If *operator* is an array that is not 2-D.
        NonSquareMatrixError: If *operator* is an array that is not square.
        ValueError: If *operator* is a bare callable and *n* is not given.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import power_iteration
        >>> matrix = np.diag([3.0, 2.0, 1.0])
        >>> eigenvalue, eigenvector = power_iteration(matrix, seed=0)
        >>> bool(np.isclose(eigenvalue, 3.0))
        True
        >>> bool(np.isclose(abs(eigenvector[0]), 1.0))
        True

        It runs matrix-free on a :class:`~cvx.linalg.SymmetricOperator`, so the
        leading eigenvalue of ``M.T @ M`` needs no ``n x n`` matrix:

        >>> from cvx.linalg import GramOperator
        >>> rng = np.random.default_rng(0)
        >>> M = rng.standard_normal((20, 5))
        >>> lam, _ = power_iteration(GramOperator(M), seed=0)
        >>> bool(np.isclose(lam, np.linalg.eigvalsh(M.T @ M)[-1]))
        True
    """
    apply, dim = _resolve(operator, n)

    rng = np.random.default_rng(seed)
    v = rng.standard_normal((dim,))
    v = v / np.linalg.norm(v)

    eigenvalue = float(v @ apply(v))
    for _ in range(n_iter):
        w = apply(v)
        norm = float(np.linalg.norm(w))
        if norm < 1e-15:
            # operator annihilates the iterate: the dominant eigenvalue is zero.
            return 0.0, v
        v = w / norm
        new_eigenvalue = float(v @ apply(v))
        if abs(new_eigenvalue - eigenvalue) <= tol * max(1.0, abs(new_eigenvalue)):
            return new_eigenvalue, v
        eigenvalue = new_eigenvalue

    return eigenvalue, v

def solve(
    matrix: Matrix,
    rhs: Vector | Matrix,
    cond_threshold: float = DEFAULT_COND_THRESHOLD,
) -> Vector | Matrix:
    """Solve a linear system restricted to the valid submatrix.

    Rows and columns with non-finite diagonal entries are excluded from the
    solve; the corresponding positions in the result are set to NaN.  Cholesky
    decomposition is attempted first for numerical stability and falls back to
    LU decomposition for non-positive-definite matrices.  When the condition
    number of the valid sub-matrix exceeds *cond_threshold*, an
    ``IllConditionedMatrixWarning`` is emitted.

    Args:
        matrix: Square coefficient matrix of shape ``(n, n)``.
        rhs: Right-hand side vector of length ``n`` or matrix of shape ``(n, k)``.
        cond_threshold: Condition-number threshold above which a warning is
            emitted. Defaults to ``1e12``.

    Returns:
        A solution array with the same shape as ``rhs``. Entries mapped to
        invalid rows or columns are returned as ``NaN``.

    Raises:
        NonSquareMatrixError: If the matrix is not square.
        DimensionMismatchError: If the leading dimension of ``rhs`` does not
            match the matrix dimension.
        SingularMatrixError: If the valid sub-matrix is singular.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import solve
        >>> solve(np.eye(2), np.array([1.0, 2.0])).tolist()
        [1.0, 2.0]

        NaN-masked entries are skipped:

        >>> matrix = np.array([[4.0, 0.0], [0.0, np.nan]])
        >>> solve(matrix, np.array([8.0, 1.0])).tolist()
        [2.0, nan]

        Matrix right-hand sides are supported:

        >>> solve(np.eye(2), np.array([[1.0, 2.0], [3.0, 4.0]])).tolist()
        [[1.0, 2.0], [3.0, 4.0]]
    """
    if matrix.shape[0] != matrix.shape[1]:
        raise NonSquareMatrixError(matrix.shape[0], matrix.shape[1])

    if rhs.shape[0] != matrix.shape[0]:
        raise DimensionMismatchError(rhs.shape[0], matrix.shape[0])

    solution = np.full(rhs.shape, np.nan)
    mask, submatrix = valid(matrix)

    if mask.any():
        _check_and_warn_condition(submatrix, cond_threshold)
        try:
            solution[mask] = _cholesky_solve(submatrix, rhs[mask])
        except np.linalg.LinAlgError as exc:
            raise SingularMatrixError(str(exc)) from exc

    return solution

def lstsq(
    matrix: Matrix,
    rhs: Vector,
    cond_threshold: float = DEFAULT_COND_THRESHOLD,
) -> tuple[Vector, Vector, int, Vector]:
    """Solve an overdetermined or underdetermined system in the least-squares sense.

    Rows where any entry in *matrix* or the corresponding entry in *rhs* is
    non-finite are excluded before solving.  The returned solution vector
    always has length equal to the number of columns in *matrix*.  When the
    effective condition number of the valid sub-matrix exceeds
    *cond_threshold*, an ``IllConditionedMatrixWarning`` is emitted.

    Args:
        matrix: Coefficient matrix of shape ``(m, n)``.
        rhs: Right-hand side vector of length ``m``.
        cond_threshold: Condition-number threshold above which a warning is
            emitted. Defaults to ``1e12``.

    Returns:
        A four-tuple ``(x, residuals, rank, sv)`` matching the convention of
        :func:`numpy.linalg.lstsq`:

        - ``x`` — least-squares solution of shape ``(n,)``.
        - ``residuals`` — sum of squared residuals; empty when the solution is
          not unique or all rows are invalid.
        - ``rank`` — effective rank of the valid sub-matrix.
        - ``sv`` — singular values of the valid sub-matrix in descending order.

    Raises:
        DimensionMismatchError: If ``rhs`` length does not match the number of
            rows in *matrix*.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import lstsq
        >>> A = np.array([[1.0, 1.0], [1.0, 2.0], [1.0, 3.0]])
        >>> b = np.array([6.0, 5.0, 7.0])
        >>> x, res, rank, sv = lstsq(A, b)
        >>> int(rank)
        2

        NaN rows are silently dropped:

        >>> A_nan = np.array([[1.0, 1.0], [np.nan, 2.0], [1.0, 3.0]])
        >>> b_nan = np.array([6.0, 5.0, 7.0])
        >>> x2, _, rank2, _ = lstsq(A_nan, b_nan)
        >>> int(rank2)
        2
    """
    if rhs.shape[0] != matrix.shape[0]:
        raise DimensionMismatchError(rhs.shape[0], matrix.shape[0])

    n_cols = matrix.shape[1]

    # Filter rows that contain any non-finite value in matrix or rhs.
    row_mask = np.isfinite(matrix).all(axis=1) & np.isfinite(rhs)
    sub_matrix = matrix[row_mask]
    sub_rhs = rhs[row_mask]

    if sub_matrix.shape[0] == 0:
        return np.full(n_cols, np.nan), np.array([]), 0, np.array([])

    x, residuals, rank, sv = np.linalg.lstsq(sub_matrix, sub_rhs, rcond=None)

    _warn_ill_conditioned(_condition_number(sv), cond_threshold)

    return (
        x.astype(np.float64, copy=False),
        residuals.astype(np.float64, copy=False),
        int(rank),
        sv.astype(np.float64, copy=False),
    )

def inv(
    matrix: Matrix,
    cond_threshold: float = DEFAULT_COND_THRESHOLD,
) -> Matrix:
    """Invert a matrix restricted to the valid submatrix.

    Rows and columns with non-finite diagonal entries are excluded from the
    inversion; the corresponding rows and columns in the result are set to NaN.
    When the condition number of the valid sub-matrix exceeds *cond_threshold*,
    an ``IllConditionedMatrixWarning`` is emitted.

    Args:
        matrix: Square matrix to invert.
        cond_threshold: Condition-number threshold above which a warning is
            emitted. Defaults to ``1e12``.

    Returns:
        An inverted matrix with the same shape as *matrix*. Rows and columns
        mapped to invalid entries are returned as ``NaN``.

    Raises:
        NonSquareMatrixError: If the matrix is not square.
        SingularMatrixError: If the valid sub-matrix is singular.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import inv
        >>> np.allclose(inv(np.eye(2)), np.eye(2))
        True

        NaN-masked entries are skipped:

        >>> matrix = np.array([[4.0, 0.0], [0.0, np.nan]])
        >>> result = inv(matrix)
        >>> float(result[0, 0])
        0.25
        >>> bool(np.isnan(result[0, 1]) and np.isnan(result[1, 0]) and np.isnan(result[1, 1]))
        True
    """
    if matrix.shape[0] != matrix.shape[1]:
        raise NonSquareMatrixError(matrix.shape[0], matrix.shape[1])

    n = matrix.shape[0]
    result = np.full((n, n), np.nan)
    mask, submatrix = valid(matrix)

    if mask.any():
        _check_and_warn_condition(submatrix, cond_threshold)
        try:
            sub_inv = np.linalg.inv(submatrix)
        except np.linalg.LinAlgError as exc:
            raise SingularMatrixError(str(exc)) from exc

        idx = np.where(mask)[0]
        result[np.ix_(idx, idx)] = sub_inv

    return result

def norm(
    x: Vector | Matrix,
    ord: int | float | Literal["fro", "nuc"] | None = None,  # noqa: A002  # mirrors np.linalg.norm public API
) -> float:
    """Compute the norm of a vector or matrix, ignoring non-finite entries.

    Non-finite entries (NaN, inf) are treated as zero before computing the norm,
    so they contribute nothing to the result. Supports all ``ord`` values accepted
    by ``np.linalg.norm``.

    Args:
        x: Input array (1-D vector or 2-D matrix).
        ord: Order of the norm. See ``np.linalg.norm`` for valid values.
            Common choices: ``None`` (default 2-norm for vectors, Frobenius for
            matrices), ``1``, ``2``, ``np.inf``, ``'fro'``, ``'nuc'``.

    Returns:
        The norm as a float.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import norm
        >>> norm(np.array([3.0, np.nan, 4.0]))
        5.0
        >>> norm(np.array([[1.0, np.nan], [np.nan, 1.0]]), ord='fro')
        1.4142135623730951
    """
    return float(np.linalg.norm(np.where(np.isfinite(x), x, 0.0), ord=ord))

def a_norm(vector: Vector, matrix: Matrix | None = None) -> float:
    """Calculate the generalized norm of a vector with respect to a matrix.

    Args:
        vector: The input vector.
        matrix: Optional square matrix defining the quadratic form.

    Returns:
        The Euclidean norm of the finite vector entries, or ``sqrt(v.T @ A @ v)``
        after dropping rows and columns whose diagonal entries are not finite.

    Raises:
        NonSquareMatrixError: If the matrix is not square.
        DimensionMismatchError: If the vector length does not match the matrix dimension.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import a_norm
        >>> a_norm(np.array([3.0, 4.0]))
        5.0
    """
    if matrix is None:
        return float(np.linalg.norm(vector[np.isfinite(vector)], 2))

    _validate_square(vector, matrix)

    mask, submatrix = valid(matrix)
    if mask.any():
        filtered_vector = vector[mask]
        return float(np.sqrt(filtered_vector @ submatrix @ filtered_vector))

    return float("nan")

def inv_a_norm(
    vector: Vector,
    matrix: Matrix | None = None,
    cond_threshold: float = DEFAULT_COND_THRESHOLD,
) -> float:
    """Calculate the inverse A-norm of a vector using an optional matrix.

    If ``matrix`` is ``None``, returns the Euclidean norm of finite entries.
    Otherwise computes ``sqrt(v.T @ A^{-1} @ v)`` on the valid submatrix,
    attempting Cholesky decomposition first for numerical stability and
    falling back to LU decomposition for non-positive-definite matrices.
    When the condition number of the valid sub-matrix exceeds *cond_threshold*,
    an ``IllConditionedMatrixWarning`` is emitted.

    Args:
        vector: The input vector.
        matrix: Optional square matrix defining the quadratic form.
        cond_threshold: Condition-number threshold above which a warning is
            emitted. Defaults to ``1e12``.

    Returns:
        The Euclidean norm of the finite vector entries, or
        ``sqrt(v.T @ A^{-1} @ v)`` after dropping rows and columns whose
        diagonal entries are not finite. Returns ``nan`` when no valid entries
        exist.

    Raises:
        NonSquareMatrixError: If the matrix is not square.
        DimensionMismatchError: If the vector length does not match the matrix dimension.
        SingularMatrixError: If the valid sub-matrix is singular.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import inv_a_norm
        >>> inv_a_norm(np.array([3.0, 4.0]))
        5.0
    """
    if matrix is None:
        return float(np.linalg.norm(vector[np.isfinite(vector)], 2))

    _validate_square(vector, matrix)

    mask, submatrix = valid(matrix)
    if mask.any():
        _check_and_warn_condition(submatrix, cond_threshold)
        filtered_vector = vector[mask]
        try:
            solved = _cholesky_solve(submatrix, filtered_vector)
        except np.linalg.LinAlgError as exc:
            raise SingularMatrixError(str(exc)) from exc
        return float(np.sqrt(np.dot(filtered_vector, solved)))

    return float("nan")

def cond(matrix: Matrix, p: int | float | Literal["fro", "nuc"] | None = None) -> float:
    """Return the condition number of a matrix.

    Returns ``nan`` if the matrix contains any non-finite (NaN or inf) entries.
    Otherwise delegates to :func:`numpy.linalg.cond`.

    Args:
        matrix: Input matrix.
        p: Order of the norm used to compute the condition number.
            Accepts the same values as :func:`numpy.linalg.cond`
            (``None``, ``1``, ``-1``, ``2``, ``-2``, ``numpy.inf``,
            ``-numpy.inf``, ``'fro'``).  Defaults to ``None`` which
            corresponds to the 2-norm (largest singular value divided by
            the smallest).

    Returns:
        The condition number as a ``float``, or ``nan`` when the matrix
        contains non-finite entries.

    Examples:
        >>> import numpy as np
        >>> cond(np.eye(3))
        1.0
        >>> import math
        >>> math.isnan(cond(np.array([[float('nan'), 1.0], [1.0, 2.0]])))
        True
        >>> cond(np.diag([1.0, 1e10]), p=1)
        10000000000.0
    """
    if not np.all(np.isfinite(matrix)):
        return float("nan")
    return float(np.linalg.cond(matrix, p=p))

def det(
    matrix: Matrix,
    cond_threshold: float = DEFAULT_COND_THRESHOLD,
) -> float:
    """Return the determinant of a square matrix.

    Rows and columns with non-finite diagonal entries are excluded before the
    computation; when no valid rows or columns remain the function returns
    ``nan``.  When the condition number of the valid sub-matrix exceeds
    *cond_threshold*, an ``IllConditionedMatrixWarning`` is emitted.

    Args:
        matrix: Square input matrix.
        cond_threshold: Condition-number threshold above which a warning is
            emitted. Defaults to ``1e12``.

    Returns:
        The determinant of the valid sub-matrix, or ``nan`` when no valid
        entries exist.

    Raises:
        NonSquareMatrixError: If the matrix is not square.

    Example:
        >>> import numpy as np
        >>> from cvx.linalg import det
        >>> det(np.eye(3))
        1.0

        NaN-masked entries are skipped:

        >>> matrix = np.array([[2.0, 0.0], [0.0, np.nan]])
        >>> det(matrix)
        2.0
    """
    if matrix.shape[0] != matrix.shape[1]:
        raise NonSquareMatrixError(matrix.shape[0], matrix.shape[1])

    mask, submatrix = valid(matrix)

    if not mask.any():
        return _SENTINEL

    _check_and_warn_condition(submatrix, cond_threshold)
    return float(np.linalg.det(submatrix))