Documented the pyamgcl wrapper classes

pyamgcl/pyamgcl.cpp

@@ -82,16 +82,12 @@ struct make_solver {
         return boost::get<1>(cnv);
     }
 
-    std::string str() const {
+    std::string repr() const {
         std::ostringstream buf;
-        buf << S.amg();
+        buf << "pyamgcl solver\n" << S.amg();
         return buf.str();
     }
 
-    std::string repr() const {
-        return "amgcl: " + str();
-    }
-
     private:
         int n;
         amgcl::runtime::make_solver< amgcl::backend::builtin<double> > S;
@@ -123,16 +119,12 @@ struct make_preconditioner {
         return result;
     }
 
-    std::string str() const {
+    std::string repr() const {
         std::ostringstream buf;
-        buf << P;
+        buf << "pyamgcl preconditioner\n" << P;
         return buf.str();
     }
 
-    std::string repr() const {
-        return "amgcl: " + str();
-    }
-
     private:
         int n;
         amgcl::runtime::amg< amgcl::backend::builtin<double> > P;
@@ -194,7 +186,6 @@ BOOST_PYTHON_MODULE(pyamgcl_ext)
                 "Creates iterative solver preconditioned by AMG"
              )
             )
-        .def("__str__",    &make_solver::str)
         .def("__repr__",   &make_solver::repr)
         .def("__call__",   &make_solver::solve, args("rhs"),
                 "Solve the problem for the given RHS")
@@ -226,7 +217,6 @@ BOOST_PYTHON_MODULE(pyamgcl_ext)
                 "Creates AMG hierarchy to be used as a preconditioner"
              )
             )
-        .def("__str__",    &make_preconditioner::str)
         .def("__repr__",   &make_preconditioner::repr)
         .def("__call__",   &make_preconditioner::apply,
                 "Apply preconditioner to the given vector")

pyamgcl/pyamgcl.py

@@ -4,13 +4,37 @@
 from scipy.sparse.linalg import LinearOperator
 
 class make_solver:
+    """
+    Iterative solver preconditioned by algebraic multigrid
+
+    The class builds algebraic multigrid hierarchy for the given matrix and
+    uses the hierarchy as a preconditioner for the specified iterative solver.
+    """
+
     def __init__(self,
             A,
             coarsening=pyamgcl_ext.coarsening.smoothed_aggregation,
             relaxation=pyamgcl_ext.relaxation.spai0,
             solver=pyamgcl_ext.solver_type.bicgstabl,
             prm={}
             ):
+        """
+        Class constructor.
+
+        Creates algebraic multigrid hierarchy.
+
+        Parameters
+        ----------
+        A : the system matrix in scipy.sparse format
+        coarsening : {ruge_stuben, aggregation, *smoothed_aggregation*, smoothed_aggr_emin}
+            The coarsening type to use for construction of the multigrid
+            hierarchy.
+        relaxation : {damped_jacobi, gauss_seidel, chebyshev, *spai0*, ilu0}
+            The relaxation scheme to use for multigrid cycles.
+        solver : {cg, bicgstab, *bicgstabl*, gmres}
+            The iterative solver to use.
+        prm : dictionary with amgcl parameters
+        """
         Acsr = A.tocsr()
 
         self.S = pyamgcl_ext.make_solver(
@@ -20,19 +44,48 @@ def __init__(self,
                 Acsr.data.astype(numpy.float64)
                 )
 
-    def __str__(self):
-        return self.S.__str__()
+    def __repr__(self):
+        """
+        Provides information about the multigrid hierarchy.
+        """
+        return self.S.__repr__()
 
     def __call__(self, rhs):
+        """
+        Solves the system for the given right-hand side.
+
+        Parameters
+        ----------
+        rhs : the right-hand side
+        """
         return self.S(rhs.astype(numpy.float64))
 
 class make_preconditioner(LinearOperator):
+    """
+    Algebraic multigrid hierarchy that may be used as a preconditioner with
+    scipy iterative solvers.
+    """
     def __init__(self,
             A,
             coarsening=pyamgcl_ext.coarsening.smoothed_aggregation,
             relaxation=pyamgcl_ext.relaxation.spai0,
             prm={}
             ):
+        """
+        Class constructor.
+
+        Creates algebraic multigrid hierarchy.
+
+        Parameters
+        ----------
+        A : the system matrix in scipy.sparse format
+        coarsening : {ruge_stuben, aggregation, *smoothed_aggregation*, smoothed_aggr_emin}
+            The coarsening type to use for construction of the multigrid
+            hierarchy.
+        relaxation : {damped_jacobi, gauss_seidel, chebyshev, *spai0*, ilu0}
+            The relaxation scheme to use for multigrid cycles.
+        prm : dictionary with amgcl parameters
+        """
         Acsr = A.tocsr()
 
         self.P = pyamgcl_ext.make_preconditioner(
@@ -44,9 +97,15 @@ def __init__(self,
 
         LinearOperator.__init__(self, A.shape, self.P)
 
-    def __str__(self):
-        return self.P.__str__()
+    def __repr__(self):
+        """
+        Provides information about the multigrid hierarchy.
+        """
+        return self.P.__repr__()
 
-    def __call__(self, rhs):
-        return self.P(rhs.astype(numpy.float64))
+    def __call__(self, x):
+        """
+        Preconditions the given vector.
+        """
+        return self.P(x.astype(numpy.float64))