jax-ml/jax · error · ValueError

Unknown polar decomposition method {method}.

Error message

Unknown polar decomposition method {method}.

What it means

jax.scipy.linalg.polar accepts only method='qdwh' or method='svd'. The dispatch chain ends in an else branch raising ValueError('Unknown polar decomposition method {method}.') for anything else. Unlike SciPy (which has no method parameter), JAX exposes the algorithm choice explicitly.

Source

Thrown at jax/_src/scipy/linalg.py:2042

    elif m < n and side == "left":
      a = a.T.conj()
      unitary, posdef, _, _ = qdwh.qdwh(a, is_hermitian=False, eps=eps)
      posdef = posdef.T.conj()
      unitary = unitary.T.conj()
    else:
      raise NotImplementedError("method='qdwh' only supports mxn matrices "
                                "where m < n where side='right' and m >= n "
                                f"side='left', got {a.shape} with {side=}")
  elif method == "svd":
    u_svd, s_svd, vh_svd = lax_linalg.svd(a, full_matrices=False)
    s_svd = s_svd.astype(u_svd.dtype)
    unitary = u_svd @ vh_svd
    if side == "right":
      posdef = (vh_svd.T.conj() * s_svd[None, :]) @ vh_svd
    else:
      posdef = (u_svd * s_svd[None, :]) @ (u_svd.T.conj())
  else:
    raise ValueError(f"Unknown polar decomposition method {method}.")
  return unitary, posdef


@jit(static_argnames=('side', 'method'))
def polar(a: ArrayLike, side: str = 'right', *, method: str = 'qdwh', eps: float | None = None,
          max_iterations: int | None = None) -> tuple[Array, Array]:
  r"""Computes the polar decomposition.

  Given the :math:`m \times n` matrix :math:`a`, returns the factors of the polar
  decomposition :math:`u` (also :math:`m \times n`) and :math:`p` such that
  :math:`a = up` (if side is ``"right"``; :math:`p` is :math:`n \times n`) or
  :math:`a = pu` (if side is ``"left"``; :math:`p` is :math:`m \times m`),
  where :math:`p` is positive semidefinite.  If :math:`a` is nonsingular,
  :math:`p` is positive definite and the
  decomposition is unique. :math:`u` has orthonormal columns unless
  :math:`n > m`, in which case it has orthonormal rows.

  Writing the SVD of :math:`a` as

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Use method='qdwh' (default, faster on TPU/GPU) or method='svd'
2. Omit method entirely to get the default

Example fix

# before
U, H = polar(a, method='newton')
# after
U, H = polar(a, method='qdwh')  # or method='svd'

METHODS = ('qdwh', 'svd')
if method not in METHODS:
    raise ValueError(f"method must be one of {METHODS}, got {method!r}")
U, H = polar(a, method=method)

try:
    polar(a, method=method)
except ValueError as e:
    if 'Unknown polar decomposition' in str(e):
        method = 'svd'; polar(a, method=method)
    else: raise

When it happens

Trigger: Calling polar(a, method='hartung'/'newton'/'numpy'/...) or any string other than 'qdwh' or 'svd'.

Common situations: Assuming SciPy-style or other iterative polar algorithms exist; passing a config variable that is None or misspelled.

Related errors

• The argument `side` must be either 'right' or 'left'.
• `compute_on`'s compute_type argument must be a string.
• Argument '{x}' of type '{typ}' is not a valid JAX type
• Argument '{arg}' of type {type(arg)} is not a valid JAX type
• Expected kind to be a dtype, string, or tuple; got {kind=}

AI-assisted analysis of jax-ml/jax@1e1c6a8fc0 (2026-08-27). Data as JSON: /api/errors/eb734c77555be8d2. Report an issue: GitHub.