Skip to content

Commit

Permalink
Moving to sphinx for documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@ddemidov
ddemidov committed Jan 18, 2016
1 parent ae780c7 commit c3a717a
Show file tree
Hide file tree
Showing 35 changed files with 1,811 additions and 2,238 deletions.
2 changes: 1 addition & 1 deletion CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ add_subdirectory(tests)
set(BUILD_SHARED_LIBS ON)
add_subdirectory(lib)
add_subdirectory(examples)
add_subdirectory(doc)
add_subdirectory(docs)
add_subdirectory(pyamgcl)

#----------------------------------------------------------------------------
Expand Down
567 changes: 15 additions & 552 deletions README.md
View file

Large diffs are not rendered by default.

23 changes: 12 additions & 11 deletions amgcl/backend/builtin.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -313,10 +313,13 @@ crs<V, C, P> inverse(const crs<V, C, P> &A) {
return Ainv;
}

/// Builtin backend.
/**
* \param real Value type.
* \ingroup backends
* The builtin backend does not have any dependencies except for the
* <a href="http://www.boost.org">Boost</a> libraries, and uses OpenMP for
* parallelization. Matrices are stored in the CRS format, and vectors are
* instances of ``std::vector<value_type>``. There is no usual overhead of
* moving the constructed hierarchy to the builtin backend, since the backend
* is used internally during setup.
*/
template <typename ValueType>
struct builtin {
Expand All @@ -332,7 +335,7 @@ struct builtin {
typedef std::vector<value_type> matrix_diagonal;
typedef solver::skyline_lu<value_type> direct_solver;

/// Backend parameters.
/// The backend has no parameters.
struct params {
params() {}
params(const boost::property_tree::ptree&) {}
Expand All @@ -341,32 +344,30 @@ struct builtin {

static std::string name() { return "builtin"; }

/// Copy matrix.
/** This is a noop for builtin backend. */
// Copy matrix. This is a noop for builtin backend.
static boost::shared_ptr<matrix>
copy_matrix(boost::shared_ptr<matrix> A, const params&)
{
return A;
}

/// Copy vector to builtin backend.
// Copy vector to builtin backend.
template <class T>
static boost::shared_ptr< std::vector<T> >
copy_vector(const std::vector<T> &x, const params&)
{
return boost::make_shared< std::vector<T> >(x);
}

/// Copy vector to builtin backend.
/** This is a noop for builtin backend. */
// Copy vector to builtin backend. This is a noop for builtin backend.
template <class T>
static boost::shared_ptr< std::vector<T> >
copy_vector(boost::shared_ptr< std::vector<T> > x, const params&)
{
return x;
}

/// Create vector of the specified size.
// Create vector of the specified size.
static boost::shared_ptr<vector>
create_vector(size_t size, const params&)
{
Expand Down Expand Up @@ -399,7 +400,7 @@ struct builtin {
}
};

/// Create direct solver for coarse level
// Create direct solver for coarse level
static boost::shared_ptr<direct_solver>
create_solver(boost::shared_ptr<matrix> A, const params&) {
return boost::make_shared<direct_solver>(*A);
Expand Down
28 changes: 14 additions & 14 deletions amgcl/backend/vexcl.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,13 +45,13 @@ THE SOFTWARE.
namespace amgcl {
namespace backend {

/// VexCL backend
/**
* This is a backend that uses types defined in the VexCL GPGPU library
* (https://github.com/ddemidov/vexcl).
*
* \param real Value type.
* \ingroup backends
* The backend uses the <a href="https://github.com/ddemidov/vexcl">VexCL</a>
* library for accelerating solution on the modern GPUs and multicore
* processors with the help of OpenCL or CUDA technologies.
* The VexCL backend stores the system matrix as ``vex::SpMat<real>`` and
* expects the right hand side and the solution vectors to be instances of the
* ``vex::vector<real>`` type.
*/
template <typename real>
struct vexcl {
Expand All @@ -65,10 +65,10 @@ struct vexcl {

struct provides_row_iterator : boost::false_type {};

/// Backend parameters.
/// The VexCL backend parameters.
struct params {
/// Command queues that identify compute devices to use with VexCL.
std::vector< vex::backend::command_queue > q;

std::vector< vex::backend::command_queue > q; ///< Command queues that identify compute devices to use with VexCL.

params() {}

Expand All @@ -93,7 +93,7 @@ struct vexcl {

static std::string name() { return "vexcl"; }

/// Copy matrix from builtin backend.
// Copy matrix from builtin backend.
static boost::shared_ptr<matrix>
copy_matrix(boost::shared_ptr< typename builtin<real>::matrix > A, const params &prm)
{
Expand All @@ -108,7 +108,7 @@ struct vexcl {
return boost::make_shared<matrix>(prm.context(), rows(*A), cols(*A), Aptr, Acol, Aval);
}

/// Copy vector from builtin backend.
// Copy vector from builtin backend.
static boost::shared_ptr<vector>
copy_vector(typename builtin<real>::vector const &x, const params &prm)
{
Expand All @@ -117,14 +117,14 @@ struct vexcl {
return boost::make_shared<vector>(prm.context(), x);
}

/// Copy vector from builtin backend.
// Copy vector from builtin backend.
static boost::shared_ptr<vector>
copy_vector(boost::shared_ptr< typename builtin<real>::vector > x, const params &prm)
{
return copy_vector(*x, prm);
}

/// Create vector of the specified size.
// Create vector of the specified size.
static boost::shared_ptr<vector>
create_vector(size_t size, const params &prm)
{
Expand Down Expand Up @@ -166,7 +166,7 @@ struct vexcl {
};


/// Create direct solver for coarse level
// Create direct solver for coarse level
static boost::shared_ptr<direct_solver>
create_solver(boost::shared_ptr< typename builtin<real>::matrix > A, const params &prm)
{
Expand Down
85 changes: 54 additions & 31 deletions amgcl/make_solver.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ THE SOFTWARE.

namespace amgcl {

/// Convenience class that wraps a preconditioner and an iterative solver
/// Convenience class that bundles together a preconditioner and an iterative solver.
template <
class Precond,
class IterativeSolver
Expand All @@ -58,9 +58,12 @@ class make_solver {

typedef typename math::scalar_of<value_type>::type scalar_type;

/** Combined parameters of the bundled preconditioner and the iterative
* solver.
*/
struct params {
typename Precond::params precond;
typename IterativeSolver::params solver;
typename Precond::params precond; ///< Preconditioner parameters.
typename IterativeSolver::params solver; ///< Iterative solver parameters.

params() {}

Expand All @@ -69,8 +72,7 @@ class make_solver {
AMGCL_PARAMS_IMPORT_CHILD(p, solver)
{}

void get(
boost::property_tree::ptree &p,
void get( boost::property_tree::ptree &p,
const std::string &path = ""
) const
{
Expand All @@ -79,7 +81,7 @@ class make_solver {
}
} prm;

/// Constructs the preconditioner and creates iterative solver.
/** Sets up the preconditioner and creates the iterative solver. */
template <class Matrix>
make_solver(
const Matrix &A,
Expand All @@ -91,7 +93,8 @@ class make_solver {
S(backend::rows(A), prm.solver, bprm)
{}

/// Constructs the preconditioner and creates iterative solver.
// Constructs the preconditioner and creates iterative solver.
// Takes shared pointer to the matrix in internal format.
make_solver(
boost::shared_ptr<build_matrix> A,
const params &prm = params(),
Expand All @@ -102,18 +105,19 @@ class make_solver {
S(backend::rows(*A), prm.solver, bprm)
{}

/// Solves the linear system for the given system matrix.
/**
* \param A System matrix.
* \param rhs Right-hand side.
* \param x Solution vector.
/** Computes the solution for the given system matrix \p A and the
* right-hand side \p rhs. Returns the number of iterations made and
* the achieved residual as a ``boost::tuple``. The solution vector
* \p x provides initial approximation in input and holds the computed
* solution on output.
*
* The system matrix may differ from the matrix used for the AMG
* preconditioner construction. This may be used for the solution of
* non-stationary problems with slowly changing coefficients. There is
* a strong chance that AMG built for one time step will act as a
* reasonably good preconditioner for several subsequent time steps
* \cite Demidov2012.
* \rst
* The system matrix may differ from the matrix used during
* initialization. This may be used for the solution of non-stationary
* problems with slowly changing coefficients. There is a strong chance
* that a preconditioner built for a time step will act as a reasonably
* good preconditioner for several subsequent time steps [DeSh12]_.
* \endrst
*/
template <class Matrix, class Vec1, class Vec2>
boost::tuple<size_t, scalar_type> operator()(
Expand All @@ -129,10 +133,10 @@ class make_solver {
return S(A, P, rhs, x);
}

/// Solves the linear system for the given right-hand side.
/**
* \param rhs Right-hand side.
* \param x Solution vector.
/** Computes the solution for the given right-hand side \p rhs.
* Returns the number of iterations made and the achieved residual as a
* ``boost::tuple``. The solution vector \p x provides initial
* approximation in input and holds the computed solution on output.
*/
template <class Vec1, class Vec2>
boost::tuple<size_t, scalar_type> operator()(
Expand All @@ -147,10 +151,29 @@ class make_solver {
return S(P, rhs, x);
}

/// Acts as a preconditioner.
/**
* \param rhs Right-hand side.
* \param x Solution vector.
/** Acts as a preconditioner. That is, applies the solver to the
* right-hand side \p rhs to get the solution \p x with zero initial
* approximation. Iterative methods usually use estimated residual for
* exit condition. For some problems the value of the estimated
* residual can get too far from the true residual due to round-off
* errors. Nesting iterative solvers in this way may allow to shave
* the last bits off the error. The method should not be used directly
* but rather allows nesting ``make_solver`` classes as in the
* following example:
*
* \rst
* .. code-block:: cpp
*
* typedef amgcl::make_solver<
* amgcl::make_solver<
* amgcl::amg<
* Backend, amgcl::coarsening::smoothed_agregation, amgcl::relaxation::spai0
* >,
* amgcl::solver::cg<Backend>
* >,
* amgcl::solver::cg<Backend>
* > NestedSolver;
* \endrst
*/
template <class Vec1, class Vec2>
void apply(
Expand All @@ -166,27 +189,27 @@ class make_solver {
(*this)(rhs, x);
}

/// Reference to the constructed AMG hierarchy.
/// Returns reference to the constructed preconditioner.
const Precond& precond() const {
return P;
}

/// Reference to the iterative solver.
/// Returns reference to the constructed iterative solver.
const IterativeSolver& solver() const {
return S;
}

/// The system matrix in the backend format.
/// Returns the system matrix in the backend format.
typename Precond::matrix const& system_matrix() const {
return P.system_matrix();
}

/// Fills the property tree with the actual parameters used.
/// Stores the parameters used during construction into the property tree \p p.
void get_params(boost::property_tree::ptree &p) const {
prm.get(p);
}

/// Size of the system matrix.
/// Returns the size of the system matrix.
size_t size() const {
return n;
}
Expand Down

0 comments on commit c3a717a

Please sign in to comment.