From: Matthias Maier Date: Thu, 9 Apr 2015 12:29:51 +0000 (+0200) Subject: Augment documentation X-Git-Tag: v8.3.0-rc1~242^2~12 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7b45f36511fc64c99f8fdb93f7e898615a0f8dcc;p=dealii.git Augment documentation --- diff --git a/doc/doxygen/options.dox.in b/doc/doxygen/options.dox.in index 15949df433..ba60985bbf 100644 --- a/doc/doxygen/options.dox.in +++ b/doc/doxygen/options.dox.in @@ -155,17 +155,25 @@ INCLUDE_FILE_PATTERNS = # not configured PREDEFINED = DOXYGEN=1 \ DEBUG=1 \ + DEAL_II_USE_MT_POSIX=1 \ + DEAL_II_WITH_ARPACK=1 \ + DEAL_II_WITH_BOOST=1 \ + DEAL_II_WITH_CXX11=1 \ + DEAL_II_WITH_HDF5=1 \ + DEAL_II_WITH_LAPACK=1 \ + DEAL_II_WITH_METIS=1 \ + DEAL_II_WITH_MPI=1 \ + DEAL_II_WITH_MUPARSER=1 \ + DEAL_II_WITH_NETCDF=1 \ + DEAL_II_WITH_OPENCASCADE=1 \ + DEAL_II_WITH_P4EST=1 \ DEAL_II_WITH_PETSC=1 \ DEAL_II_WITH_SLEPC=1 \ - DEAL_II_WITH_TRILINOS=1 \ - DEAL_II_WITH_OPENCASCADE=1 \ DEAL_II_WITH_THREADS=1 \ - DEAL_II_USE_MT_POSIX=1 \ - DEAL_II_WITH_ARPACK=1 \ - DEAL_II_WITH_METIS=1 \ - DEAL_II_WITH_MUPARSER=1 \ - DEAL_II_WITH_P4EST=1 \ - DEAL_II_WITH_MPI=1 + DEAL_II_WITH_TRILINOS=1 \ + DEAL_II_WITH_TRILINOS =1 \ + DEAL_II_WITH_UMFPACK=1 \ + DEAL_II_WITH_ZLIB=1 # do not expand exception declarations EXPAND_AS_DEFINED = DeclException0 \ diff --git a/include/deal.II/lac/linear_operator.h b/include/deal.II/lac/linear_operator.h index e437d30402..e25adfde10 100644 --- a/include/deal.II/lac/linear_operator.h +++ b/include/deal.II/lac/linear_operator.h @@ -48,9 +48,9 @@ LinearOperator linop (const Matrix &); /** * A class to store the abstract concept of a linear operator. * - * The class essentially consists of std::function objects * that - * store the knowledge of how to apply the linear operator by implementing the - * abstract @ref Matrix interface: + * The class essentially consists of std::function objects + * that store the knowledge of how to apply the linear operator by + * implementing the abstract @ref Matrix interface: * @code * std::function vmult; * std::function vmult_add; @@ -58,16 +58,16 @@ LinearOperator linop (const Matrix &); * std::function Tvmult_add; * @endcode * - * But, in contrast to a usual matrix object, the domain and range of the linear - * operator are also bound to the LinearOperator class on the type - * level. Because of this, the LinearOperator has two - * additional function objects + * But, in contrast to a usual matrix object, the domain and range of the + * linear operator are also bound to the LinearOperator class on the type + * level. Because of this, LinearOperator <@tref Range, @tref + * Domain> has two additional function objects * @code * std::function reinit_range_vector; * std::function reinit_domain_vector; * @endcode * that store the knowledge how to initialize (resize + internal data structures) - * an arbitrary vector of the Range and Domain space. + * an arbitrary vector of the @tref Range and @tref Domain space. * * The primary purpose of this class is to provide syntactic sugar for * complex matrix-vector operations and free the user from having to @@ -95,16 +95,16 @@ LinearOperator linop (const Matrix &); * support, i.e., if DEAL_II_WITH_CXX11 is enabled during * cmake configure. * - * @author: Luca Heltai, Matthias Maier, 2015 + * @author Luca Heltai, Matthias Maier, 2015 */ template class LinearOperator { public: /** - * Create an empty LinearOperator object. All std::function objects are - * initialized with default variants that throw an exception upon - * invocation. + * Create an empty LinearOperator object. All std::function + * member objects are initialized with default variants that throw an + * exception upon invocation. */ LinearOperator () { @@ -166,37 +166,38 @@ public: } /** - * Application of the LinearOperator object to a vector @p u of the - * Domain space giving a vector @p v of the Range space. + * Application of the LinearOperator object to a vector u of the @tref + * Domain space giving a vector v of the @tref Range space. */ std::function vmult; /** - * Application of the LinearOperator object to a vector @p u of the - * Domain space. The result is added to the vector @p v. + * Application of the LinearOperator object to a vector u of the @tref + * Domain space. The result is added to the vector v. */ std::function vmult_add; /** - * Application of the transpose LinearOperator object to a vector @p u of - * the Range space giving a vector @p v of the Domain space. + * Application of the transpose LinearOperator object to a vector u of + * the @tref Range space giving a vector v of the @tref Domain + * space. */ std::function Tvmult; /** * Application of the transpose LinearOperator object to a vector @p u of - * the Range space. The result is added to the vector @p v. + * the @tref Range space.The result is added to the vector @p v. */ std::function Tvmult_add; /** - * Initializes a vector of the Range space to be directly usable as the - * destination parameter in an application of vmult. Similar to the - * reinit functions of the vector classes, the boolean determines whether - * a fast initalization is done, i.e., if it is set to false the content - * of the vector is set to 0. + * Initializes a vector v of the Range space to be directly usable + * as the destination parameter in an application of vmult. Similar to + * the reinit functions of the vector classes, the boolean determines + * whether a fast initalization is done, i.e., if it is set to false the + * content of the vector is set to 0. */ - std::function reinit_range_vector; + std::function reinit_range_vector; /** * Initializes a vector of the Domain space to be directly usable as the @@ -205,24 +206,24 @@ public: * initalization is done, i.e., if it is set to false the content of the * vector is set to 0. */ - std::function reinit_domain_vector; + std::function reinit_domain_vector; /** - * A memory object for vectors of Range space used for intermediate - * storage during computations in vmult, etc. + * A memory object for vectors of @tref Range space used for intermediate + * storage during computations in @ref vmult, etc. */ mutable GrowingVectorMemory range_vector_memory; /** - * A memory object for vectors of Domain space used for intermediate - * storage during computations in vmult, etc. + * A memory object for vectors of @tref Domain space used for intermediate + * storage during computations in @ref vmult, etc. */ mutable GrowingVectorMemory domain_vector_memory; /** - * Addition with a LinearOperator @p second_op with the same Domain - * and Range. + * Addition with a LinearOperator @p second_op with the same @tref Domain + * and @tref Range. */ LinearOperator & operator+=(const LinearOperator &second_op) @@ -232,8 +233,8 @@ public: } /** - * Subtraction with a LinearOperator @p second_op with the same Domain - * and Range. + * Subtraction with a LinearOperator @p second_op with the same @tref Domain + * and @tref Range. */ LinearOperator & operator-=(const LinearOperator &second_op) @@ -243,8 +244,8 @@ public: } /** - * Concatenation of the LinearOperator with an endormorphism @p second_op - * on the Domain space. + * Concatenation of the LinearOperator with an endomorphism @p second_op + * on the @tref Domain space. */ LinearOperator & operator*=(const LinearOperator &second_op) @@ -257,6 +258,8 @@ public: /** + * \relates LinearOperator + * * Addition of two linear operators @p first_op and @p second_op given * by $(\text{first_op}+\text{second_op})x:=\text{first_op}(x)+\text{second_op}(x)$ */ @@ -302,6 +305,8 @@ operator+(const LinearOperator &first_op, /** + * \relates LinearOperator + * * Subtraction of two linear operators @p first_op and @p second_op given * by $(\text{first_op}-\text{second_op})x:=\text{first_op}(x)-\text{second_op}(x)$ */ @@ -316,6 +321,8 @@ operator-(const LinearOperator &first_op, /** + * \relates LinearOperator + * * Concatenation of two linear operators @p first_op and @p second_op given * by $(\text{first_op}*\text{second_op})x:=\text{first_op}(\text{second_op}(x))$ */ @@ -380,15 +387,18 @@ operator*(const LinearOperator &first_op, /** - * Scalar multiplication of a ScalarOperator object from the left. + * \relates LinearOperator * - * The Domain and Range types must implement the following + * Scalar multiplication of a ScalarOperator object @p op with @p + * number from the left. + * + * The @tref Domain and @tref Range types must implement the following * operator*= member functions accepting the appropriate * scalar Number type for rescaling: * * @code - * Domain & operator *=(Number); - * Range & operator *=(Number); + * Domain & operator *=(Domain::value_type); + * Range & operator *=(Range::value_type); * @endcode */ template @@ -436,14 +446,16 @@ operator*(typename Range::value_type number, /** + * \relates LinearOperator + * * Scalar multiplication of a ScalarOperator object from the right. * - * The Domain and Range types must implement the following + * The @tref Domain and @tref Range types must implement the following * operator*= member functions for rescaling: * * @code - * Domain & operator *=(Number); - * Range & operator *=(Number); + * Domain & operator *=(Domain::value_type); + * Range & operator *=(Range::value_type); * @endcode */ template @@ -460,7 +472,9 @@ operator*(const LinearOperator &op, /** - * Returns the transpose linear operations of @p op. + * \relates LinearOperator + * + * Returns the transpose linear operations of @ref op. */ template LinearOperator @@ -481,12 +495,14 @@ transpose_linop(const LinearOperator &op) /** + * \relates LinearOperator + * * Returns a LinearOperator that is the identity of the vector space - * Domain. + * @tref Range. * - * The function takes an std::function object @p - * exemplar as an argument to initialize the reinit_range_vector - * and reinit_domain_vector objects of the LinearOperator object. + * The function takes an std::function object @ref exemplar as + * an argument to initialize the reinit_range_vector and + * reinit_domain_vector objects of the LinearOperator object. */ template LinearOperator @@ -522,6 +538,8 @@ identity_linop(const std::function &exemplar) /** + * \relates LinearOperator + * * Returns an object representing the inverse of the LinearOperator @p op. * * The function takes references @p solver and @p preconditioner to an @@ -532,8 +550,8 @@ identity_linop(const std::function &exemplar) * The LinearOperator object that is created stores a reference to @p * solver and @p preconditioner. Thus, both objects must remain a valid * reference for the whole lifetime of the LinearOperator object. Internal - * data structures of the @p solver object will be modified upon invocation - * of vmult or Tvmult. + * data structures of the @p solver object will be modified upon + * invocation of vmult or Tvmult. */ template LinearOperator @@ -590,14 +608,15 @@ inverse_linop(Solver &solver, } - /** + * \relates LinearOperator + * * A function that encapsulates a given collection @p ops of * LinearOperators into a block structure. Hereby, it is assumed that Range - * and Domain are blockvectors, i.e., derived from @ref - * BlockVectorBase. The individual linear operators in @p - * ops must act on a the underlying vector type of the block vectors, i.e., - * on Domain::BlockType yielding a result in Range::BlockType. + * and Domain are blockvectors, i.e., derived from @ref BlockVectorBase. + * The individual linear operators in @p ops must act on a the underlying + * vector type of the block vectors, i.e., on Domain::BlockType yielding a + * result in Range::BlockType. * * The list @p ops is best passed as an initializer list. Consider for * example a linear operator block (acting on Vector) @@ -700,12 +719,15 @@ block_linop(const std::arrayRange::reinit() with the result of + * Matrix::m(). This class is specialized for more complicated * data structures, such as TrilinosWrappers::MPI::Vector, etc. */ template @@ -726,12 +748,15 @@ public: /** + * \relates LinearOperator + * * A factory class that is responsible for the creation of a * reinit_domain_vector object for a given pair of vector type Domain and * matrix type Matrix. * - * The generic version of this class just calls Domain::reinit() with the - * result of Matrix::n(). This class is specialized for more complicated + * The generic version of this class just calls + * Domain::reinit() with the result of + * Matrix::n(). This class is specialized for more complicated * data structures, such as TrilinosWrappers::MPI::Vector, etc. */ template @@ -866,6 +891,8 @@ namespace /** + * \relates LinearOperator + * * A function that encapsulates generic @p matrix objects that act on a * compatible Vector type into a LinearOperator. The LinearOperator object * that is created stores a reference to the matrix object. Thus, @p matrix @@ -917,7 +944,7 @@ namespace * vmult and Tvmult (requiring intermediate * storage). * - * @author: Matthias Maier, 2015 + * @author Matthias Maier, 2015 */ template , typename Domain = Range, @@ -930,6 +957,8 @@ LinearOperator linop(const Matrix &matrix) /** + * \relates LinearOperator + * * Variant of above function that takes an Exemplar object @p exemplar as * an additional reference. This object is used to populate the * reinit_domain_vector and reinit_range_vector function objects. The @@ -939,7 +968,7 @@ LinearOperator linop(const Matrix &matrix) * (that typically do not expose any information about the underlying * matrix). * - * @author: Matthias Maier, 2015 + * @author Matthias Maier, 2015 */ template , typename Domain = Range,