Merge branch 'docstrings' into signature_checking

pymatsolver/direct/mumps.py

@@ -2,12 +2,38 @@
 from mumps import Context
 
 class Mumps(Base):
-    """
-    Mumps solver
+    """The MUMPS direct solver.
+
+    This solver uses the python-mumps wrappers to factorize a sparse matrix, and use that factorization for solving.
+
+    Parameters
+    ----------
+    A
+        Matrix to solve with.
+    ordering : str, default 'metis'
+        Which ordering algorithm to use. See the `python-mumps` documentation for more details.
+    is_symmetric : bool, optional
+        Whether the matrix is symmetric. By default, it will perform some simple tests to check for symmetry, and
+        default to ``False`` if those fail.
+    is_positive_definite : bool, optional
+        Whether the matrix is positive definite.
+    check_accuracy : bool, optional
+        Whether to check the accuracy of the solution.
+    check_rtol : float, optional
+        The relative tolerance to check against for accuracy.
+    check_atol : float, optional
+        The absolute tolerance to check against for accuracy.
+    accuracy_tol : float, optional
+        Relative accuracy tolerance.
+        .. deprecated:: 0.3.0
+            `accuracy_tol` will be removed in pymatsolver 0.4.0. Use `check_rtol` and `check_atol` instead.
+    **kwargs
+        Extra keyword arguments. If there are any left here a warning will be raised.
     """
     _transposed = False
 
-    def __init__(self, A, ordering=None, is_symmetric=None, is_positive_definite=False, is_hermitian=None, check_accuracy=False, check_rtol=1e-6, check_atol=0, accuracy_tol=None, **kwargs):
+    def __init__(self, A, ordering=None, is_symmetric=None, is_positive_definite=False, check_accuracy=False, check_rtol=1e-6, check_atol=0, accuracy_tol=None, **kwargs):
+        is_hermitian = kwargs.pop('is_hermitian', False)
         super().__init__(A, is_symmetric=is_symmetric, is_positive_definite=is_positive_definite, is_hermitian=is_hermitian, check_accuracy=check_accuracy, check_rtol=check_rtol, check_atol=check_atol, accuracy_tol=accuracy_tol, **kwargs)
         if ordering is None:
             ordering = "metis"
@@ -23,6 +49,12 @@ def _set_A(self, A):
 
     @property
     def ordering(self):
+        """The ordering algorithm to use.
+
+        Returns
+        -------
+        str
+        """
         return self._ordering
 
     @ordering.setter
@@ -48,6 +80,14 @@ def transpose(self):
         return trans_obj
 
     def factor(self, A=None):
+        """(Re)factor the A matrix.
+
+        Parameters
+        ----------
+        A : scipy.sparse.spmatrix
+            The matrix to be factorized. If a previous factorization has been performed, this will
+            reuse the previous factorization's analysis.
+        """
         reuse_analysis = False
         if A is not None:
             self._set_A(A)

pymatsolver/direct/pardiso.py

@@ -3,15 +3,37 @@
 from pydiso.mkl_solver import set_mkl_pardiso_threads, get_mkl_pardiso_max_threads
 
 class Pardiso(Base):
-    """
-    Pardiso Solver
-
-        https://github.com/simpeg/pydiso
-
-
-    documentation::
-
-        http://www.pardiso-project.org/
+    """The Pardiso direct solver.
+
+    This solver uses the `pydiso` Intel MKL wrapper to factorize a sparse matrix, and use that
+    factorization for solving.
+
+    Parameters
+    ----------
+    A : scipy.sparse.spmatrix
+        Matrix to solve with.
+    n_threads : int, optional
+        Number of threads to use for the `Pardiso` routine in Intel's MKL.
+    is_symmetric : bool, optional
+        Whether the matrix is symmetric. By default, it will perform some simple tests to check for symmetry, and
+        default to ``False`` if those fail.
+    is_positive_definite : bool, optional
+        Whether the matrix is positive definite.
+    is_hermitian : bool, optional
+        Whether the matrix is hermitian. By default, it will perform some simple tests to check, and default to
+        ``False`` if those fail.
+    check_accuracy : bool, optional
+        Whether to check the accuracy of the solution.
+    check_rtol : float, optional
+        The relative tolerance to check against for accuracy.
+    check_atol : float, optional
+        The absolute tolerance to check against for accuracy.
+    accuracy_tol : float, optional
+        Relative accuracy tolerance.
+        .. deprecated:: 0.3.0
+            `accuracy_tol` will be removed in pymatsolver 0.4.0. Use `check_rtol` and `check_atol` instead.
+    **kwargs
+        Extra keyword arguments. If there are any left here a warning will be raised.
     """
 
     _transposed = False
@@ -66,6 +88,14 @@ def _matrixType(self):
                 return 13
 
     def factor(self, A=None):
+        """(Re)factor the A matrix.
+
+        Parameters
+        ----------
+        A : scipy.sparse.spmatrix
+            The matrix to be factorized. If a previous factorization has been performed, this will
+            reuse the previous factorization's analysis.
+        """
         if A is not None and self.A is not A:
             self._A = A
             self.solver.refactor(self.A)
@@ -85,9 +115,13 @@ def transpose(self):
 
     @property
     def n_threads(self):
-        """
-        Number of threads to use for the Pardiso solver routine. This property
-        is global to all Pardiso solver objects for a single python process.
+        """Number of threads to use for the Pardiso solver routine.
+
+        This property is global to all Pardiso solver objects for a single python process.
+
+        Returns
+        -------
+        int
         """
         return get_mkl_pardiso_max_threads()
 

pymatsolver/iterative.py

@@ -15,7 +15,34 @@
 SolverBiCG = WrapIterative(bicgstab, name="SolverBiCG")
 
 class BiCGJacobi(Base):
-    """Bicg Solver with Jacobi preconditioner"""
+    """Diagonal pre-conditioned BiCG solver.
+
+    Parameters
+    ----------
+    A : matrix
+        The matrix to solve, must have a ``diagonal()`` method.
+    symmetric: boolean, optional
+        .. deprecated:: 0.3.0
+            `symmetric` is deprecated. It is unused, and will be removed in pymatsolver 0.4.0.
+    maxiter : int, optional
+        The maximum number of BiCG iterations to perform.
+    rtol : float, optional
+        The relative tolerance for the BiCG solver to terminate.
+    atol : float, optional
+        The absolute tolerance for the BiCG solver to terminate.
+    check_accuracy : bool, optional
+        Whether to check the accuracy of the solution.
+    check_rtol : float, optional
+        The relative tolerance to check against for accuracy.
+    check_atol : float, optional
+        The absolute tolerance to check against for accuracy.
+    accuracy_tol : float, optional
+        Relative accuracy tolerance.
+        .. deprecated:: 0.3.0
+            `accuracy_tol` will be removed in pymatsolver 0.4.0. Use `check_rtol` and `check_atol` instead.
+    **kwargs
+        Extra keyword arguments passed to the base class.
+    """
 
     def __init__(self, A, symmetric=None, maxiter=1000, rtol=1E-6, atol=0.0, check_accuracy=False, check_rtol=1e-6, check_atol=0, accuracy_tol=None, **kwargs):
         if symmetric is not None: