blocksolver 0.8.3__cp38-cp38-win_amd64.whl → 0.8.5__cp38-cp38-win_amd64.whl

blocksolver/__init__.py

@@ -39,7 +39,7 @@ from .blqmr import (
     HAS_NUMBA,
 )
 
-__version__ = "0.8.3"
+__version__ = "0.8.5"
 __author__ = "Qianqian Fang"
 
 __all__ = [

blocksolver/blqmr.py

@@ -437,8 +437,101 @@ class BLQMRWorkspace:
 # Preconditioner Factory
 # =============================================================================
 
+# Type alias for precond_type
+PrecondType = Optional[Union[str, int]]
 
-def make_preconditioner(A: sparse.spmatrix, precond_type: str = "diag", **kwargs):
+
+def _parse_precond_type_for_fortran(precond_type: PrecondType) -> int:
+    """
+    Convert precond_type to Fortran integer code.
+
+    Returns
+    -------
+    int
+        0 = no preconditioning
+        2 = ILU
+        3 = diagonal/Jacobi
+    """
+    if precond_type is None or precond_type == "" or precond_type is False:
+        return 0
+
+    if isinstance(precond_type, int):
+        return precond_type
+
+    if isinstance(precond_type, str):
+        precond_lower = precond_type.lower()
+        if precond_lower in ("ilu", "ilu0", "ilut"):
+            return 2
+        elif precond_lower in ("diag", "jacobi"):
+            return 3
+        else:
+            # Unknown string, default to no preconditioning
+            warnings.warn(
+                f"Unknown precond_type '{precond_type}' for Fortran backend, using no preconditioning"
+            )
+            return 0
+
+    return 0
+
+
+def _get_preconditioner_for_native(A, precond_type: PrecondType, M1_provided):
+    """
+    Create preconditioner for native Python backend.
+
+    Parameters
+    ----------
+    A : sparse matrix
+        System matrix
+    precond_type : None, '', str, or int
+        Preconditioner type specification
+    M1_provided : preconditioner or None
+        User-provided preconditioner (takes precedence)
+
+    Returns
+    -------
+    M1 : preconditioner or None
+    """
+    # If user provided M1, use it
+    if M1_provided is not None:
+        return M1_provided
+
+    # No preconditioning requested
+    if precond_type is None or precond_type == "" or precond_type is False:
+        return None
+
+    # Integer codes (for compatibility)
+    if isinstance(precond_type, int):
+        if precond_type == 0:
+            return None
+        elif precond_type == 2:
+            precond_str = "ilu"
+        elif precond_type == 3:
+            precond_str = "diag"
+        else:
+            precond_str = "ilu"  # Default to ILU for other integers
+    else:
+        precond_str = precond_type
+
+    # Create preconditioner
+    try:
+        return make_preconditioner(A, precond_str)
+    except Exception as e:
+        # Fallback chain: try diag if ilu fails
+        if precond_str not in ("diag", "jacobi"):
+            try:
+                warnings.warn(
+                    f"Preconditioner '{precond_str}' failed: {e}, falling back to diagonal"
+                )
+                return make_preconditioner(A, "diag")
+            except Exception:
+                pass
+        warnings.warn(f"All preconditioners failed, proceeding without preconditioning")
+        return None
+
+
+def make_preconditioner(
+    A: sparse.spmatrix, precond_type: str = "diag", split: bool = False, **kwargs
+):
     """
     Create a preconditioner for iterative solvers.
 
@@ -449,25 +542,32 @@ def make_preconditioner(A: sparse.spmatrix, precond_type: str = "diag", **kwargs
     precond_type : str
         'diag' or 'jacobi': Diagonal (Jacobi) preconditioner
         'ilu' or 'ilu0': Incomplete LU with minimal fill
-        'ilut': Incomplete LU with threshold (better quality)
-        'lu': Full LU factorization (exact, use as reference)
-        'ssor': Symmetric SOR
+        'ilut': Incomplete LU with threshold
+        'lu': Full LU factorization
+    split : bool
+        If True, return sqrt(D) for split preconditioning (M1=M2=sqrt(D))
+        If False, return D for left preconditioning
     **kwargs : dict
-        Additional parameters for ILU:
-        - drop_tol: Drop tolerance (default: 1e-4 for ilut, 0 for ilu0)
-        - fill_factor: Fill factor (default: 10 for ilut, 1 for ilu0)
+        Additional parameters
 
     Returns
     -------
     M : preconditioner object
-        Preconditioner (use as M1 in blqmr)
+        For split Jacobi, use as: blqmr(A, b, M1=M, M2=M)
     """
     if precond_type in ("diag", "jacobi"):
         diag = A.diagonal().copy()
         diag[np.abs(diag) < 1e-14] = 1.0
-        return sparse.diags(
-            1.0 / diag, format="csr"
-        )  # Return inverse for preconditioning!
+
+        if split:
+            # For split preconditioning: return sqrt(D)
+            # Usage: M1 = M2 = sqrt(D), gives D^{-1/2} A D^{-1/2}
+            sqrt_diag = np.sqrt(diag)
+            return sparse.diags(sqrt_diag, format="csr")
+        else:
+            # For left preconditioning: return D
+            # Usage: M1 = D, M2 = None, gives D^{-1} A
+            return sparse.diags(diag, format="csr")
 
     elif precond_type == "ilu0":
         # ILU(0) - no fill-in, fast but may be poor quality
@@ -569,19 +669,43 @@ def _blqmr_python_impl(
         ws = workspace
         ws.reset()
 
-    # Setup preconditioner
-    if M1 is not None:
+    # Setup preconditioner - distinguish split vs left-only
+    use_split_precond = False
+    precond = None
+    precond_M1 = None
+    precond_M2 = None
+
+    if M1 is not None and M2 is not None:
+        # Split preconditioning: M1⁻¹ A M2⁻¹
+        use_split_precond = True
         if isinstance(M1, (_ILUPreconditioner, _LUPreconditioner)):
-            precond = SparsePreconditioner(M1, M2)
+            precond_M1 = SparsePreconditioner(M1, None)
         elif sparse.issparse(M1):
-            precond = SparsePreconditioner(M1, M2)
+            precond_M1 = SparsePreconditioner(M1, None)
         elif hasattr(M1, "solve"):
-            # Custom preconditioner with .solve() method
-            precond = M1  # Use directly
+            precond_M1 = M1
         else:
-            precond = DensePreconditioner(M1, M2)
-    else:
-        precond = None
+            precond_M1 = DensePreconditioner(M1, None)
+
+        if isinstance(M2, (_ILUPreconditioner, _LUPreconditioner)):
+            precond_M2 = SparsePreconditioner(M2, None)
+        elif sparse.issparse(M2):
+            precond_M2 = SparsePreconditioner(M2, None)
+        elif hasattr(M2, "solve"):
+            precond_M2 = M2
+        else:
+            precond_M2 = DensePreconditioner(M2, None)
+
+    elif M1 is not None:
+        # Left-only preconditioning: M1⁻¹ A
+        if isinstance(M1, (_ILUPreconditioner, _LUPreconditioner)):
+            precond = SparsePreconditioner(M1, None)
+        elif sparse.issparse(M1):
+            precond = SparsePreconditioner(M1, None)
+        elif hasattr(M1, "solve"):
+            precond = M1
+        else:
+            precond = DensePreconditioner(M1, None)
 
     if x0 is None:
         x = np.zeros((n, m), dtype=dtype)
@@ -608,7 +732,14 @@ def _blqmr_python_impl(
     else:
         np.subtract(B, A @ x, out=ws.vt)
 
-    if precond is not None:
+    # Apply preconditioner to initial residual
+    if use_split_precond:
+        # For split preconditioning, initial residual is just M1⁻¹ * (b - A*x0)
+        # because we're solving M1⁻¹ A M2⁻¹ y = M1⁻¹ b with y = M2*x
+        ws.vt[:] = precond_M1.solve(ws.vt)
+        if np.any(np.isnan(ws.vt)):
+            return x, 2, 1.0, 0, np.array([])
+    elif precond is not None:
         precond.solve(ws.vt, out=ws.vt)
         if np.any(np.isnan(ws.vt)):
             return x, 2, 1.0, 0, np.array([])
@@ -620,12 +751,19 @@ def _blqmr_python_impl(
 
     # Compute omega - standard norm WITH conjugation (Hermitian norm)
     # Fortran: omega(i,i,t3p)=sqrt(sum(conjg(v(:,i,t3p))*v(:,i,t3p)))
-    for i in range(m):
-        col = ws.v[:, i, t3p]
-        if is_complex_input:
-            ws.omega[i, i, t3p] = np.sqrt(np.sum(np.conj(col) * col).real)
-        else:
-            ws.omega[i, i, t3p] = np.sqrt(np.sum(col * col))
+    ws.omega[:, :, t3p].fill(0)
+    if is_complex_input:
+        np.fill_diagonal(
+            ws.omega[:, :, t3p],
+            np.sqrt(
+                np.einsum("ij,ij->j", np.conj(ws.v[:, :, t3p]), ws.v[:, :, t3p]).real
+            ),
+        )
+    else:
+        np.fill_diagonal(
+            ws.omega[:, :, t3p],
+            np.sqrt(np.einsum("ij,ij->j", ws.v[:, :, t3p], ws.v[:, :, t3p])),
+        )
 
     # taut = omega * beta
     ws.taot[:] = ws.omega[:, :, t3p] @ ws.beta[:, :, t3p]
@@ -634,9 +772,11 @@ def _blqmr_python_impl(
     if isquasires:
         # Fortran: Qres0=maxval(sqrt(sum(abs(conjg(taut)*taut),1))) for complex
         if is_complex_input:
-            Qres0 = np.max(np.sqrt(np.sum(np.abs(np.conj(ws.taot) * ws.taot), axis=0)))
+            Qres0 = np.max(
+                np.sqrt(np.einsum("ij,ij->j", np.conj(ws.taot), ws.taot).real)
+            )
         else:
-            Qres0 = np.max(np.sqrt(np.sum(ws.taot * ws.taot, axis=0)))
+            Qres0 = np.max(np.sqrt(np.einsum("ij,ij->j", ws.taot, ws.taot)))
     else:
         omegat = np.zeros((n, m), dtype=dtype)
         for i in range(m):
@@ -667,7 +807,16 @@ def _blqmr_python_impl(
             np.matmul(A, ws.v[:, :, t3], out=ws.Av)
 
         # Apply preconditioner
-        if precond is not None:
+        if use_split_precond:
+            # Split preconditioning: M1⁻¹ * A * M2⁻¹ * v
+            tmp = precond_M2.solve(ws.v[:, :, t3])  # M2⁻¹ * v
+            if A_is_sparse:
+                tmp = A @ tmp  # A * M2⁻¹ * v
+            else:
+                tmp = np.matmul(A, tmp)
+            ws.vt[:] = precond_M1.solve(tmp) - ws.v[:, :, t3n] @ ws.beta[:, :, t3].T
+        elif precond is not None:
+            # Left-only preconditioning: M⁻¹ * A * v
             precond.solve(ws.Av, out=ws.vt)
             ws.vt[:] = ws.vt - ws.v[:, :, t3n] @ ws.beta[:, :, t3].T
         else:
@@ -683,12 +832,21 @@ def _blqmr_python_impl(
         ws.beta[:, :, t3p] = R
 
         # Compute omega (standard Hermitian norm)
-        for i in range(m):
-            col = ws.v[:, i, t3p]
-            if is_complex_input:
-                ws.omega[i, i, t3p] = np.sqrt(np.sum(np.conj(col) * col).real)
-            else:
-                ws.omega[i, i, t3p] = np.sqrt(np.sum(col * col))
+        ws.omega[:, :, t3p].fill(0)
+        if is_complex_input:
+            np.fill_diagonal(
+                ws.omega[:, :, t3p],
+                np.sqrt(
+                    np.einsum(
+                        "ij,ij->j", np.conj(ws.v[:, :, t3p]), ws.v[:, :, t3p]
+                    ).real
+                ),
+            )
+        else:
+            np.fill_diagonal(
+                ws.omega[:, :, t3p],
+                np.sqrt(np.einsum("ij,ij->j", ws.v[:, :, t3p], ws.v[:, :, t3p])),
+            )
 
         # Compute intermediate matrices
         ws.tmp0[:] = ws.omega[:, :, t3n] @ ws.beta[:, :, t3].T
@@ -733,10 +891,10 @@ def _blqmr_python_impl(
         if isquasires:
             if is_complex_input:
                 Qres = np.max(
-                    np.sqrt(np.sum(np.abs(np.conj(ws.taot) * ws.taot), axis=0))
+                    np.sqrt(np.einsum("ij,ij->j", np.conj(ws.taot), ws.taot).real)
                 )
             else:
-                Qres = np.max(np.sqrt(np.sum(ws.taot * ws.taot, axis=0)))
+                Qres = np.max(np.sqrt(np.einsum("ij,ij->j", ws.taot, ws.taot)))
         else:
             tmp0_diag = np.zeros((m, m), dtype=dtype)
             for i in range(m):
@@ -768,6 +926,11 @@ def _blqmr_python_impl(
             break
 
     resv = resv[:iter_count]
+
+    # For split preconditioning, recover x = M2⁻¹ * y
+    if use_split_precond:
+        x = precond_M2.solve(x)
+
     result = x.real if not is_complex_input else x
     return result, flag, relres, iter_count, resv
 
@@ -787,7 +950,7 @@ def blqmr_solve(
     tol: float = 1e-6,
     maxiter: Optional[int] = None,
     droptol: float = 0.001,
-    use_precond: bool = True,
+    precond_type: PrecondType = "ilu",
     zero_based: bool = True,
 ) -> BLQMRResult:
     """
@@ -813,8 +976,12 @@ def blqmr_solve(
         Maximum iterations. Default is n.
     droptol : float, default 0.001
         Drop tolerance for ILU preconditioner (Fortran only).
-    use_precond : bool, default True
-        Whether to use ILU preconditioning.
+    precond_type : None, '', or str, default 'ilu'
+        Preconditioner type:
+        - None or '': No preconditioning
+        - 'ilu', 'ilu0', 'ilut': Incomplete LU
+        - 'diag', 'jacobi': Diagonal (Jacobi)
+        - For Fortran: integers 2 (ILU) or 3 (diagonal) also accepted
     zero_based : bool, default True
         If True, Ap and Ai use 0-based indexing (Python/C convention).
         If False, uses 1-based indexing (Fortran convention).
@@ -839,7 +1006,7 @@ def blqmr_solve(
             tol=tol,
             maxiter=maxiter,
             droptol=droptol,
-            use_precond=use_precond,
+            precond_type=precond_type,
             zero_based=zero_based,
         )
     else:
@@ -851,13 +1018,13 @@ def blqmr_solve(
             x0=x0,
             tol=tol,
             maxiter=maxiter,
-            use_precond=use_precond,
+            precond_type=precond_type,
             zero_based=zero_based,
         )
 
 
 def _blqmr_solve_fortran(
-    Ap, Ai, Ax, b, *, x0, tol, maxiter, droptol, use_precond, zero_based
+    Ap, Ai, Ax, b, *, x0, tol, maxiter, droptol, precond_type, zero_based
 ) -> BLQMRResult:
     """Fortran backend for blqmr_solve."""
     n = len(Ap) - 1
@@ -877,10 +1044,10 @@ def _blqmr_solve_fortran(
         Ap = Ap + 1
         Ai = Ai + 1
 
-    dopcond = 1 if use_precond else 0
+    pcond_type = _parse_precond_type_for_fortran(precond_type)
 
     x, flag, niter, relres = _blqmr.blqmr_solve_real(
-        n, nnz, Ap, Ai, Ax, b, maxiter, tol, droptol, dopcond
+        n, nnz, Ap, Ai, Ax, b, maxiter, tol, droptol, pcond_type
     )
 
     return BLQMRResult(
@@ -889,7 +1056,7 @@ def _blqmr_solve_fortran(
 
 
 def _blqmr_solve_native_csc(
-    Ap, Ai, Ax, b, *, x0, tol, maxiter, use_precond, zero_based
+    Ap, Ai, Ax, b, *, x0, tol, maxiter, precond_type, zero_based
 ) -> BLQMRResult:
     """Native Python backend for blqmr_solve with CSC input."""
     n = len(Ap) - 1
@@ -900,15 +1067,7 @@ def _blqmr_solve_native_csc(
 
     A = sparse.csc_matrix((Ax, Ai, Ap), shape=(n, n))
 
-    M1 = None
-    if use_precond:
-        try:
-            M1 = make_preconditioner(A, "ilu")
-        except Exception:
-            try:
-                M1 = make_preconditioner(A, "diag")  # FIX: Changed A_sp to A
-            except Exception:
-                M1 = None  # Fall back to no preconditioning
+    M1 = _get_preconditioner_for_native(A, precond_type, None)
 
     x, flag, relres, niter, resv = _blqmr_python_impl(
         A, b, tol=tol, maxiter=maxiter, M1=M1, x0=x0
@@ -929,13 +1088,18 @@ def blqmr_solve_multi(
     tol: float = 1e-6,
     maxiter: Optional[int] = None,
     droptol: float = 0.001,
-    use_precond: bool = True,
+    precond_type: PrecondType = "ilu",
     zero_based: bool = True,
 ) -> BLQMRResult:
     """
     Solve sparse linear system AX = B with multiple right-hand sides.
 
     Uses Fortran extension if available, otherwise falls back to pure Python.
+
+    Parameters
+    ----------
+    precond_type : None, '', or str, default 'ilu'
+        Preconditioner type (see blqmr_solve for details)
     """
     n = len(Ap) - 1
 
@@ -951,7 +1115,7 @@ def blqmr_solve_multi(
             tol=tol,
             maxiter=maxiter,
             droptol=droptol,
-            use_precond=use_precond,
+            precond_type=precond_type,
             zero_based=zero_based,
         )
     else:
@@ -962,13 +1126,13 @@ def blqmr_solve_multi(
             B,
             tol=tol,
             maxiter=maxiter,
-            use_precond=use_precond,
+            precond_type=precond_type,
             zero_based=zero_based,
         )
 
 
 def _blqmr_solve_multi_fortran(
-    Ap, Ai, Ax, B, *, tol, maxiter, droptol, use_precond, zero_based
+    Ap, Ai, Ax, B, *, tol, maxiter, droptol, precond_type, zero_based
 ) -> BLQMRResult:
     """Fortran backend for blqmr_solve_multi."""
     n = len(Ap) - 1
@@ -987,10 +1151,11 @@ def _blqmr_solve_multi_fortran(
         Ap = Ap + 1
         Ai = Ai + 1
 
-    dopcond = 1 if use_precond else 0
+    # Convert precond_type string to Fortran integer code
+    pcond_type = _parse_precond_type_for_fortran(precond_type)
 
     X, flag, niter, relres = _blqmr.blqmr_solve_real_multi(
-        n, nnz, nrhs, Ap, Ai, Ax, B, maxiter, tol, droptol, dopcond
+        n, nnz, nrhs, Ap, Ai, Ax, B, maxiter, tol, droptol, pcond_type
     )
 
     return BLQMRResult(
@@ -999,7 +1164,7 @@ def _blqmr_solve_multi_fortran(
 
 
 def _blqmr_solve_multi_native(
-    Ap, Ai, Ax, B, *, tol, maxiter, use_precond, zero_based
+    Ap, Ai, Ax, B, *, tol, maxiter, precond_type, zero_based
 ) -> BLQMRResult:
     """Native Python backend for blqmr_solve_multi."""
     n = len(Ap) - 1
@@ -1010,15 +1175,7 @@ def _blqmr_solve_multi_native(
 
     A = sparse.csc_matrix((Ax, Ai, Ap), shape=(n, n))
 
-    M1 = None
-    if use_precond:
-        try:
-            M1 = make_preconditioner(A, "ilu")
-        except Exception:
-            try:
-                M1 = make_preconditioner(A, "diag")  # FIX: Changed A_sp to A
-            except Exception:
-                M1 = None  # Fall back to no preconditioning
+    M1 = _get_preconditioner_for_native(A, precond_type, None)
 
     if B.ndim == 1:
         B = B.reshape(-1, 1)
@@ -1081,7 +1238,7 @@ def blqmr(
     residual: bool = False,
     workspace: Optional[BLQMRWorkspace] = None,
     droptol: float = 0.001,
-    use_precond: bool = True,
+    precond_type: PrecondType = "ilu",
 ) -> BLQMRResult:
     """
     Block Quasi-Minimal-Residual (BL-QMR) solver - main interface.
@@ -1097,9 +1254,10 @@ def blqmr(
     tol : float
         Convergence tolerance (default: 1e-6)
     maxiter : int, optional
-        Maximum iterations (default: n for Fortran, min(n, 20) for Python)
+        Maximum iterations (default: n)
     M1, M2 : preconditioner, optional
-        Preconditioner M = M1 @ M2 (Python backend only)
+        Custom preconditioners. If provided, precond_type is ignored.
+        M = M1 @ M2 for split preconditioning (Python backend only)
     x0 : ndarray, optional
         Initial guess
     residual : bool
@@ -1108,8 +1266,13 @@ def blqmr(
         Pre-allocated workspace (Python backend only)
     droptol : float, default 0.001
         Drop tolerance for ILU preconditioner (Fortran backend only)
-    use_precond : bool, default True
-        Whether to use ILU preconditioning (Fortran backend only)
+    precond_type : None, '', or str, default 'ilu'
+        Preconditioner type (ignored if M1 is provided):
+        - None or '': No preconditioning
+        - 'ilu', 'ilu0', 'ilut': Incomplete LU
+        - 'diag', 'jacobi': Diagonal (Jacobi)
+        - 'lu': Full LU (expensive, for debugging)
+        - For Fortran: integers 2 (ILU) or 3 (diagonal) also accepted
 
     Returns
     -------
@@ -1129,7 +1292,7 @@ def blqmr(
             maxiter=maxiter,
             x0=x0,
             droptol=droptol,
-            use_precond=use_precond,
+            precond_type=precond_type,
         )
     else:
         return _blqmr_native(
@@ -1142,7 +1305,7 @@ def blqmr(
             x0=x0,
             residual=residual,
             workspace=workspace,
-            use_precond=use_precond,
+            precond_type=precond_type,
         )
 
 
@@ -1154,7 +1317,7 @@ def _blqmr_fortran(
     maxiter: Optional[int],
     x0: Optional[np.ndarray],
     droptol: float,
-    use_precond: bool,
+    precond_type: PrecondType,
 ) -> BLQMRResult:
     """Fortran backend for blqmr()."""
     A_csc = sparse.csc_matrix(A)
@@ -1176,7 +1339,7 @@ def _blqmr_fortran(
     Ap_f = np.asfortranarray(Ap + 1, dtype=np.int32)
     Ai_f = np.asfortranarray(Ai + 1, dtype=np.int32)
 
-    dopcond = 1 if use_precond else 0
+    pcond_type = _parse_precond_type_for_fortran(precond_type)
 
     # Check if complex
     is_complex = np.iscomplexobj(A) or np.iscomplexobj(B)
@@ -1189,7 +1352,7 @@ def _blqmr_fortran(
             # Single RHS
             b_f = np.asfortranarray(B.ravel(), dtype=np.complex128)
             x, flag, niter, relres = _blqmr.blqmr_solve_complex(
-                n, nnz, Ap_f, Ai_f, Ax_f, b_f, maxiter, tol, droptol, dopcond
+                n, nnz, Ap_f, Ai_f, Ax_f, b_f, maxiter, tol, droptol, pcond_type
             )
             return BLQMRResult(
                 x=x.copy(), flag=int(flag), iter=int(niter), relres=float(relres)
@@ -1199,7 +1362,7 @@ def _blqmr_fortran(
             B_f = np.asfortranarray(B, dtype=np.complex128)
             nrhs = B_f.shape[1]
             X, flag, niter, relres = _blqmr.blqmr_solve_complex_multi(
-                n, nnz, nrhs, Ap_f, Ai_f, Ax_f, B_f, maxiter, tol, droptol, dopcond
+                n, nnz, nrhs, Ap_f, Ai_f, Ax_f, B_f, maxiter, tol, droptol, pcond_type
             )
             return BLQMRResult(
                 x=X.copy(), flag=int(flag), iter=int(niter), relres=float(relres)
@@ -1212,7 +1375,7 @@ def _blqmr_fortran(
             # Single RHS
             b_f = np.asfortranarray(B.ravel(), dtype=np.float64)
             x, flag, niter, relres = _blqmr.blqmr_solve_real(
-                n, nnz, Ap_f, Ai_f, Ax_f, b_f, maxiter, tol, droptol, dopcond
+                n, nnz, Ap_f, Ai_f, Ax_f, b_f, maxiter, tol, droptol, pcond_type
             )
             return BLQMRResult(
                 x=x.copy(), flag=int(flag), iter=int(niter), relres=float(relres)
@@ -1222,7 +1385,7 @@ def _blqmr_fortran(
             B_f = np.asfortranarray(B, dtype=np.float64)
             nrhs = B_f.shape[1]
             X, flag, niter, relres = _blqmr.blqmr_solve_real_multi(
-                n, nnz, nrhs, Ap_f, Ai_f, Ax_f, B_f, maxiter, tol, droptol, dopcond
+                n, nnz, nrhs, Ap_f, Ai_f, Ax_f, B_f, maxiter, tol, droptol, pcond_type
             )
             return BLQMRResult(
                 x=X.copy(), flag=int(flag), iter=int(niter), relres=float(relres)
@@ -1240,19 +1403,13 @@ def _blqmr_native(
     x0: Optional[np.ndarray],
     residual: bool,
     workspace: Optional[BLQMRWorkspace],
-    use_precond: bool,
+    precond_type: PrecondType,
 ) -> BLQMRResult:
     """Native Python backend for blqmr()."""
-    # Auto-create preconditioner if requested and not provided
-    if use_precond and M1 is None:
+    # Get preconditioner (user-provided M1 takes precedence)
+    if M1 is None:
         A_sp = sparse.csc_matrix(A) if not sparse.issparse(A) else A
-        try:
-            M1 = make_preconditioner(A_sp, "ilu")
-        except Exception:
-            try:
-                M1 = make_preconditioner(A_sp, "diag")
-            except Exception:
-                M1 = None  # Fall back to no preconditioning
+        M1 = _get_preconditioner_for_native(A_sp, precond_type, None)
 
     x, flag, relres, niter, resv = _blqmr_python_impl(
         A,

{blocksolver-0.8.3.dist-info → blocksolver-0.8.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: blocksolver
-Version: 0.8.3
+Version: 0.8.5
 Summary: Block Quasi-Minimal-Residual sparse linear solver
 Keywords: sparse,linear-algebra,iterative-solver,qmr,fortran,umfpack
 Author-Email: Qianqian Fang <q.fang@neu.edu>
@@ -49,7 +49,7 @@ Description-Content-Type: text/markdown
 - **Block QMR Algorithm**: Efficiently solves multiple right-hand sides simultaneously
 - **Complex Symmetric Support**: Designed for complex symmetric matrices (A = Aᵀ, not A = A†)
 - **Dual Backend**: Fortran extension for speed, Python fallback for portability
-- **ILU Preconditioning**: Built-in incomplete LU preconditioner for faster convergence
+- **Flexible Preconditioning**: ILU, diagonal (Jacobi), and split preconditioners
 - **SciPy Integration**: Works seamlessly with SciPy sparse matrices
 - **Optional Numba Acceleration**: JIT-compiled kernels for the Python backend
 
@@ -71,7 +71,7 @@ The BLQMR algorithm is an iterative Krylov subspace method specifically designed
 
 - **Three-term Lanczos Recurrence**: Builds an orthonormal basis for the Krylov subspace with short recurrences, minimizing memory usage.
 
-- **Block Updates**: Processes m right-hand sides simultaneously, with typical block sizes of 1-16.
+- **Block Updates**: Processes m right-hand sides simultaneously, with typical block sizes of 1-64.
 
 ### When to Use BLQMR
 
@@ -155,9 +155,9 @@ result = blqmr(A, b)
 
 # With options
 result = blqmr(A, b, 
-    tol=1e-8,           # Convergence tolerance
-    maxiter=1000,       # Maximum iterations
-    use_precond=True,   # Use ILU preconditioning
+    tol=1e-8,              # Convergence tolerance
+    maxiter=1000,          # Maximum iterations
+    precond_type='ilu',    # Preconditioner: 'ilu', 'diag', or None
 )
 ```
 
@@ -190,24 +190,29 @@ from blocksolver import blqmr
 A = create_helmholtz_matrix(frequency=1000)  # Your application
 b = np.complex128(source_term)
 
-result = blqmr(A, b, tol=1e-8)
+result = blqmr(A, b, tol=1e-8, precond_type='diag')
 ```
 
-### Custom Preconditioning
+### Preconditioning
 
-For the Python backend, you can provide custom preconditioners:
+BlockSolver supports multiple preconditioner types for both backends:
 
 ```python
 from blocksolver import blqmr, make_preconditioner
 
-# Create ILU preconditioner
-M1 = make_preconditioner(A, 'ilu')
+# Using precond_type parameter (works with both backends)
+result = blqmr(A, b, precond_type='ilu')    # Incomplete LU
+result = blqmr(A, b, precond_type='diag')   # Diagonal (Jacobi)
+result = blqmr(A, b, precond_type=None)     # No preconditioning
 
-# Or diagonal (Jacobi) preconditioner
-M1 = make_preconditioner(A, 'diag')
+# Custom preconditioner (Python backend only)
+M1 = make_preconditioner(A, 'ilu', drop_tol=1e-4, fill_factor=10)
+result = blqmr(A, b, M1=M1, precond_type=None)
 
-# Solve with custom preconditioner
-result = blqmr(A, b, M1=M1, use_precond=False)
+# Split preconditioning for symmetric systems (Python backend)
+# Preserves symmetry: M1^{-1} A M2^{-1}
+M = make_preconditioner(A, 'diag', split=True)  # Returns sqrt(D)
+result = blqmr(A, b, M1=M, M2=M, precond_type=None)
 ```
 
 ### SciPy-Compatible Interface
@@ -236,9 +241,9 @@ b = np.array([8., 45., -3., 3., 19.])
 
 result = blqmr_solve(Ap, Ai, Ax, b, 
     tol=1e-8,
-    droptol=0.001,      # ILU drop tolerance (Fortran only)
-    use_precond=True,
-    zero_based=True,    # 0-based indexing (default)
+    droptol=0.001,         # ILU drop tolerance (Fortran backend only)
+    precond_type='ilu',    # Preconditioner type
+    zero_based=True,       # 0-based indexing (default)
 )
 ```
 
@@ -257,7 +262,7 @@ Main solver interface.
 | `maxiter` | int | n | Maximum iterations |
 | `M1`, `M2` | preconditioner | None | Custom preconditioners (Python backend) |
 | `x0` | ndarray | None | Initial guess |
-| `use_precond` | bool | True | Use ILU preconditioning |
+| `precond_type` | str or None | 'ilu' | Preconditioner: 'ilu', 'diag', or None |
 | `droptol` | float | 0.001 | ILU drop tolerance (Fortran backend) |
 | `residual` | bool | False | Use true residual for convergence (Python) |
 | `workspace` | BLQMRWorkspace | None | Pre-allocated workspace (Python) |
@@ -274,21 +279,29 @@ Main solver interface.
 
 ### `blqmr_solve(Ap, Ai, Ax, b, **kwargs) -> BLQMRResult`
 
-Low-level CSC interface.
+Low-level CSC interface for single RHS.
 
 ### `blqmr_solve_multi(Ap, Ai, Ax, B, **kwargs) -> BLQMRResult`
 
-Multiple right-hand sides with CSC input.
+Low-level CSC interface for multiple right-hand sides.
 
 ### `blqmr_scipy(A, b, **kwargs) -> Tuple[ndarray, int]`
 
 SciPy-compatible interface returning `(x, flag)`.
 
-### `make_preconditioner(A, type) -> Preconditioner`
+### `make_preconditioner(A, precond_type, **kwargs) -> Preconditioner`
 
 Create a preconditioner for the Python backend.
 
-**Types:** `'diag'`/`'jacobi'`, `'ilu'`/`'ilu0'`, `'ssor'`
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `A` | sparse matrix | required | System matrix |
+| `precond_type` | str | required | 'diag', 'jacobi', 'ilu', 'ilu0', 'ilut', 'lu', 'ssor' |
+| `split` | bool | False | Return sqrt(D) for split preconditioning |
+| `drop_tol` | float | 1e-4 | Drop tolerance for ILUT |
+| `fill_factor` | float | 10 | Fill factor for ILUT |
+| `omega` | float | 1.0 | Relaxation parameter for SSOR |
 
 ### Utility Functions
 
@@ -301,13 +314,44 @@ from blocksolver import (
 )
 ```
 
+## Benchmarks
+
+### BLQMR vs Direct Solver (mldivide)
+
+Complex symmetric FEM matrices, 4 right-hand sides, tolerance 10⁻⁸, split Jacobi preconditioner:
+
+| Grid | Nodes | NNZ | mldivide | BLQMR | Speedup |
+|------|-------|-----|----------|-------|---------|
+| 20³ | 8,000 | 110K | 135ms | 115ms | **1.2×** |
+| 30³ | 27,000 | 384K | 1.36s | 373ms | **3.6×** |
+| 40³ | 64,000 | 922K | 6.40s | 947ms | **6.8×** |
+| 50³ | 125,000 | 1.8M | 25.9s | 1.76s | **14.7×** |
+
+### Block Size Efficiency
+
+With 64 RHS on a 8,000-node complex symmetric system:
+
+| Block Size | Iterations | Speedup vs Single |
+|------------|------------|-------------------|
+| 1 (point) | 10,154 | 1.0× |
+| 4 | 2,220 | 1.8× |
+| 8 | 956 | 2.0× |
+| 16 | 361 | 2.1× |
+| 32 | 178 | 2.2× |
+
+**Optimal block size**: 8-16 for most problems. Larger blocks have diminishing returns due to increased per-iteration cost.
+
+### Iteration Efficiency
+
+With 4 RHS, BLQMR uses only ~24% of total iterations compared to 4 separate single-RHS solves — achieving **super-linear block acceleration**.
+
 ## Performance Tips
 
-1. **Use the Fortran backend** when available (10-100× faster than Python)
+1. **Use the Fortran backend** when available (faster for large systems)
 
 2. **Enable preconditioning** for ill-conditioned systems:
    ```python
-   result = blqmr(A, b, use_precond=True)
+   result = blqmr(A, b, precond_type='ilu')
    ```
 
 3. **Batch multiple right-hand sides** instead of solving one at a time:
@@ -328,11 +372,18 @@ from blocksolver import (
 5. **Reuse workspace** for repeated solves with the same dimensions:
    ```python
    from blocksolver import BLQMRWorkspace
-   ws = BLQMRWorkspace(n, m)
+   ws = BLQMRWorkspace(n, m, dtype=np.complex128)
    for b in many_rhs:
        result = blqmr(A, b, workspace=ws)
    ```
 
+6. **Use split Jacobi for complex symmetric systems**:
+   ```python
+   # Preserves symmetry of preconditioned system
+   M = make_preconditioner(A, 'diag', split=True)
+   result = blqmr(A, b, M1=M, M2=M, precond_type=None)
+   ```
+
 ## Examples
 
 ### Diffuse Optical Tomography
@@ -360,10 +411,10 @@ def create_diffusion_matrix(nx, ny, D=1.0, mu_a=0.01, omega=1e9):
 
 # Setup problem
 A = create_diffusion_matrix(100, 100, omega=2*np.pi*100e6)
-sources = np.random.randn(10000, 16)  # 16 source positions
+sources = np.random.randn(10000, 16) + 0j  # 16 source positions
 
 # Solve for all sources at once
-result = blqmr(A, sources, tol=1e-8)
+result = blqmr(A, sources, tol=1e-8, precond_type='diag')
 print(f"Solved {sources.shape[1]} systems in {result.iter} iterations")
 ```
 
@@ -382,7 +433,7 @@ def solve_helmholtz(K, M, f, frequencies):
     for omega in frequencies:
         # A = K - ω²M (complex symmetric if K, M are symmetric)
         A = K - omega**2 * M
-        result = blqmr(A, f, tol=1e-10)
+        result = blqmr(A, f, tol=1e-10, precond_type='diag')
         solutions.append(result.x)
     return np.array(solutions)
 ```
@@ -401,12 +452,28 @@ brew install gcc suite-sparse                  # macOS
 pip install --no-cache-dir blocksolver
 ```
 
+### Check backend status
+
+```python
+from blocksolver import get_backend_info
+print(get_backend_info())
+# {'backend': 'binary', 'has_fortran': True, 'has_numba': True}
+```
+
 ### Slow convergence
 
-1. Enable preconditioning: `use_precond=True`
+1. Enable preconditioning: `precond_type='ilu'` or `precond_type='diag'`
 2. Reduce ILU drop tolerance: `droptol=1e-4` (Fortran backend)
 3. Check matrix conditioning with `np.linalg.cond(A.toarray())`
 
+### ILU factorization fails
+
+For indefinite or complex symmetric matrices, ILU may fail:
+```python
+# Fall back to diagonal preconditioner
+result = blqmr(A, b, precond_type='diag')
+```
+
 ### Memory issues with large systems
 
 1. Use the Fortran backend (more memory efficient)
@@ -415,7 +482,7 @@ pip install --no-cache-dir blocksolver
 
 ## License
 
-BSD-3-Clause / LGPL-3.0+ / GPL-3.0+ (tri-licensed)
+BSD-3-Clause or GPL-3.0+ (dual-licensed)
 
 ## Citation
 

blocksolver-0.8.5.dist-info/RECORD

@@ -0,0 +1,7 @@
+blocksolver-0.8.5.dist-info/METADATA,sha256=K7OUbJ-pEkHWX3Cvy9iz1_L1onkox-5T9YwOvCrCiSU,15985
+blocksolver-0.8.5.dist-info/WHEEL,sha256=vIXzP6jLUy4sdmrQppnovVBqmdfNCkEM0I7EHxeJ-zs,83
+blocksolver/_blqmr.cp38-win_amd64.pyd,sha256=7cNpd1gPUty299GF5MwRbxk4xjvsUAIEudDEfOVaB6Y,34366661
+blocksolver/_blqmr.cp38-win_amd64.dll.a,sha256=Nketjx2gg0CTuKGh2_z6lckLN0D1HR1uPudzY66SFOs,1696
+blocksolver/__init__.py,sha256=PZV19qS5YQDWdAcqgD6g0wW7KRKrdv1JuLDKmrnC6Es,1982
+blocksolver/blqmr.py,sha256=diRm-xD2-4r0W59WrRe-O26DHJgc32voCVQa0H5FCRk,46543
+blocksolver-0.8.5.dist-info/RECORD,,

blocksolver-0.8.3.dist-info/RECORD

@@ -1,7 +0,0 @@
-blocksolver-0.8.3.dist-info/METADATA,sha256=1JTScCC4OO3FBMqPtaG0OUlf5OnEHDetwDj7LPk9u9A,13264
-blocksolver-0.8.3.dist-info/WHEEL,sha256=vIXzP6jLUy4sdmrQppnovVBqmdfNCkEM0I7EHxeJ-zs,83
-blocksolver/_blqmr.cp38-win_amd64.pyd,sha256=854GKxQ4YgdNiVEIco_MjK38acsP8YpIUkzdAslpCTo,34345539
-blocksolver/_blqmr.cp38-win_amd64.dll.a,sha256=Nketjx2gg0CTuKGh2_z6lckLN0D1HR1uPudzY66SFOs,1696
-blocksolver/__init__.py,sha256=7lq88Nc2gqHTWAdpvj2zpVt8UHYgKpcVlgA1WzyEhFI,1982
-blocksolver/blqmr.py,sha256=TRVkXlJf2FXFiZkH6vawNEEq8jowJqG-S_QGwHMeR8U,41060
-blocksolver-0.8.3.dist-info/RECORD,,