docs: def bidiagonalize_real_matrix_pair_with_symmetric_products(
          mat1: np.ndarray,
          mat2: np.ndarray,
          *,
          rtol: float = 1e-5,
          atol: float = 1e-8,
          check_preconditions: bool = True) -> Tuple[np.ndarray, np.ndarray]:
      """Finds orthogonal matrices that diagonalize both mat1 and mat2.
  
      Requires mat1 and mat2 to be real.
      Requires mat1.T @ mat2 to be symmetric.
      Requires mat1 @ mat2.T to be symmetric.
  
      Args:
          mat1: One of the real matrices.
          mat2: The other real matrix.
          rtol: Relative numeric error threshold.
          atol: Absolute numeric error threshold.
          check_preconditions: If set, verifies that the inputs are real, and that
              mat1.T @ mat2 and mat1 @ mat2.T are both symmetric. Defaults to set.
  
      Returns:
          A tuple (L, R) of two orthogonal matrices, such that both L @ mat1 @ R
          and L @ mat2 @ R are diagonal matrices.
  
      Raises:
          ValueError: Matrices don't meet preconditions (e.g. not real).
      """
  
      if check_preconditions:
          if np.any(np.imag(mat1) != 0):
              raise ValueError('mat1 must be real.')
          if np.any(np.imag(mat2) != 0):
              raise ValueError('mat2 must be real.')
          if not predicates.is_hermitian(mat1.dot(mat2.T), rtol=rtol, atol=atol):
              raise ValueError('mat1 @ mat2.T must be symmetric.')
          if not predicates.is_hermitian(mat1.T.dot(mat2), rtol=rtol, atol=atol):
              raise ValueError('mat1.T @ mat2 must be symmetric.')
  
      # Use SVD to bi-diagonalize the first matrix.
      base_left, base_diag, base_right = _svd_handling_empty(np.real(mat1))
      base_diag = np.diag(base_diag)
  
      # Determine where we switch between diagonalization-fixup strategies.
      dim = base_diag.shape[0]
      rank = dim
      while rank > 0 and tolerance.all_near_zero(base_diag[rank - 1, rank - 1],
                                                 atol=atol):
          rank -= 1
      base_diag = base_diag[:rank, :rank]
  
      # Try diagonalizing the second matrix with the same factors as the first.
      semi_corrected = base_left.T.dot(np.real(mat2)).dot(base_right.T)
  
      # Fix up the part of the second matrix's diagonalization that's matched
      # against non-zero diagonal entries in the first matrix's diagonalization
      # by performing simultaneous diagonalization.
      overlap = semi_corrected[:rank, :rank]
      overlap_adjust = diagonalize_real_symmetric_and_sorted_diagonal_matrices(
          overlap,
          base_diag,
          rtol=rtol,
          atol=atol,
          check_preconditions=check_preconditions)
  
      # Fix up the part of the second matrix's diagonalization that's matched
      # against zeros in the first matrix's diagonalization by performing an SVD.
      extra = semi_corrected[rank:, rank:]
      extra_left_adjust, _, extra_right_adjust = _svd_handling_empty(extra)
  
      # Merge the fixup factors into the initial diagonalization.
      left_adjust = combinators.block_diag(overlap_adjust, extra_left_adjust)
      right_adjust = combinators.block_diag(overlap_adjust.T,
                                            extra_right_adjust)
      left = left_adjust.T.dot(base_left.T)
      right = base_right.T.dot(right_adjust.T)
  
      return left, right