From 1b73d25b7f5e91518eb0ebdf3fcb5f137f10069f Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Tue, 17 Jan 2006 23:42:23 +0000 Subject: [PATCH] More documentation work. git-svn-id: https://svn.dealii.org/trunk@12072 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/base/include/base/function.h | 4 ++ .../base/include/base/function_derivative.h | 1 + deal.II/base/include/base/function_lib.h | 24 +++++++- deal.II/base/include/base/function_parser.h | 1 + deal.II/base/include/base/function_time.h | 4 ++ .../base/include/base/memory_consumption.h | 1 + deal.II/base/include/base/multithread_info.h | 7 ++- deal.II/base/include/base/polynomial_space.h | 2 + deal.II/base/include/base/polynomials_bdm.h | 2 - .../base/include/base/quadrature_selector.h | 3 +- deal.II/base/include/base/smartpointer.h | 1 + deal.II/base/include/base/subscriptor.h | 2 + deal.II/base/include/base/thread_management.h | 2 + deal.II/doc/doxygen/headers/functions.h | 57 +++++++++++++++++++ deal.II/doc/doxygen/headers/memory.h | 35 ++++++++++++ deal.II/doc/doxygen/headers/multithreading.h | 46 +++++++++++++++ deal.II/doc/doxygen/headers/quadrature.h | 8 +++ 17 files changed, 194 insertions(+), 6 deletions(-) create mode 100644 deal.II/doc/doxygen/headers/functions.h create mode 100644 deal.II/doc/doxygen/headers/memory.h create mode 100644 deal.II/doc/doxygen/headers/multithreading.h diff --git a/deal.II/base/include/base/function.h b/deal.II/base/include/base/function.h index d42de79112..64de7c90f1 100644 --- a/deal.II/base/include/base/function.h +++ b/deal.II/base/include/base/function.h @@ -93,6 +93,7 @@ template class Vector; * are a priori known (for example, dim elements), you might * consider using the TensorFunction class instead. * + * @ingroup functions * @author Wolfgang Bangerth, 1998, 1999 */ template @@ -360,6 +361,7 @@ class Function : public FunctionTime, * This function is of use when you want to implement homogeneous boundary * conditions, or zero initial conditions. * + * @ingroup functions * @author Wolfgang Bangerth, 1998, 1999 */ template @@ -488,6 +490,7 @@ class ZeroFunction : public Function * in all its components, which might not be overly useful a feature * in most cases, however. * + * @ingroup functions * @author Wolfgang Bangerth, 1998, 1999 */ template @@ -584,6 +587,7 @@ class ConstantFunction : public ZeroFunction * VectorTools::integrate_difference, where it allows to integrate * only one component. * + * @ingroup functions * @author Guido Kanschat, 2000 */ template diff --git a/deal.II/base/include/base/function_derivative.h b/deal.II/base/include/base/function_derivative.h index 8b55a785d8..ef1a240dcf 100644 --- a/deal.II/base/include/base/function_derivative.h +++ b/deal.II/base/include/base/function_derivative.h @@ -31,6 +31,7 @@ * schemes). Experimenting with h and the difference scheme may be * necessary to obtain sufficient results. * + * @ingroup functions * @author Guido Kanschat, 2000 */ template diff --git a/deal.II/base/include/base/function_lib.h b/deal.II/base/include/base/function_lib.h index 5088858d66..c8ce204000 100644 --- a/deal.II/base/include/base/function_lib.h +++ b/deal.II/base/include/base/function_lib.h @@ -23,8 +23,10 @@ * Namespace implementing some concrete classes derived from the * Function class that describe actual functions. This is rather * a collection of classes that we have needed for our own programs - * once and thought they might be useful to others as well at some + * once and thought might be useful to others as well at some * point. + * + * @ingroup functions */ namespace Functions { @@ -37,6 +39,7 @@ namespace Functions * * Together with the function, its derivatives and Laplacian are defined. * + * @ingroup functions * @author: Guido Kanschat, 1999 */ template @@ -89,6 +92,7 @@ namespace Functions * The function xy. This function serves as an example for * a vanishing Laplacian. * + * @ingroup functions * @author: Guido Kanschat, 2000 */ template @@ -149,6 +153,7 @@ namespace Functions * * Together with the function, its derivatives and Laplacian are defined. * + * @ingroup functions * @author: Guido Kanschat, 1999 */ template @@ -210,6 +215,8 @@ namespace Functions * Cosine-shaped pillow function. * This is another function with zero boundary values on $[-1,1]^d$. In the interior * it is the product of $\cos(\pi/2 x_i)$. + * + * @ingroup functions * @author Guido Kanschat, 1999 */ template @@ -275,6 +282,8 @@ namespace Functions /** * Product of exponential functions in each coordinate direction. + * + * @ingroup functions * @author Guido Kanschat, 1999 */ template @@ -326,6 +335,7 @@ namespace Functions /** * Singularity on the L-shaped domain in 2D. * + * @ingroup functions * @author Guido Kanschat, 1999 */ class LSingularityFunction : public Function<2> @@ -376,6 +386,7 @@ namespace Functions /** * Singularity on the slit domain in 2D. * + * @ingroup functions * @author Guido Kanschat, 1999 */ class SlitSingularityFunction : public Function<2> @@ -425,6 +436,7 @@ namespace Functions /** * Singularity on the slit domain with one Neumann boundary in 2D. * + * @ingroup functions * @author Guido Kanschat, 2002 */ class SlitHyperSingularityFunction : public Function<2> @@ -469,6 +481,7 @@ namespace Functions std::vector &values, const unsigned int component = 0) const; }; + /** @@ -483,6 +496,7 @@ namespace Functions * * Together with the function, its derivatives and Laplacian are defined. * + * @ingroup functions * @author: Guido Kanschat, 2000 */ template @@ -594,6 +608,7 @@ namespace Functions * The class has its name from the fact that it resembles one * component of a Fourier cosine decomposition. * + * @ingroup functions * @author Wolfgang Bangerth, 2001 */ template @@ -653,6 +668,7 @@ namespace Functions * The class has its name from the fact that it resembles one * component of a Fourier sine decomposition. * + * @ingroup functions * @author Wolfgang Bangerth, 2001 */ template @@ -709,6 +725,7 @@ namespace Functions * function is then recovered as * $f(x) = \sum_j w_j sin(\sum_i k_i x_i) = Im(\sum_j w_j \exp(i k.x))$. * + * @ingroup functions * @author Wolfgang Bangerth, 2001 */ template @@ -769,6 +786,7 @@ namespace Functions * function is then recovered as * $f(x) = \sum_j w_j cos(\sum_i k_i x_i) = Re(\sum_j w_j \exp(i k.x))$. * + * @ingroup functions * @author Wolfgang Bangerth, 2001 */ template @@ -828,6 +846,7 @@ namespace Functions * also stores the number of the non-zero component, if the function * is vector-valued. * + * @ingroup functions * @author Guido Kanschat, 2002 */ template @@ -901,6 +920,7 @@ namespace Functions * If vector valued, it can be restricted * to a single component. * + * @ingroup functions * @author Guido Kanschat, 2001, 2002 */ template @@ -950,6 +970,7 @@ namespace Functions * maximum value is 1. If vector valued, it can be restricted * to a single component. * + * @ingroup functions * @author Guido Kanschat, 2001, 2002 */ template @@ -1000,6 +1021,7 @@ namespace Functions * distance to the center, and $s$ is the radius of the sphere. If * vector valued, it can be restricted to a single component. * + * @ingroup functions * @author Guido Kanschat, 2001, 2002 */ template diff --git a/deal.II/base/include/base/function_parser.h b/deal.II/base/include/base/function_parser.h index 9e9ed55b19..caf8cda593 100644 --- a/deal.II/base/include/base/function_parser.h +++ b/deal.II/base/include/base/function_parser.h @@ -246,6 +246,7 @@ template class Vector; @endverbatim * * + * @ingroup functions * @author Luca Heltai, 2005 */ template diff --git a/deal.II/base/include/base/function_time.h b/deal.II/base/include/base/function_time.h index 43989bb034..aa9066aa80 100644 --- a/deal.II/base/include/base/function_time.h +++ b/deal.II/base/include/base/function_time.h @@ -56,6 +56,7 @@ * purpose than the intended one! This will inevitably lead to confusion. * * + * @ingroup functions * @author Wolfgang Bangerth, Guido Kanschat, 1998, 1999 */ class FunctionTime @@ -101,11 +102,14 @@ class FunctionTime /*------------------------------ Inline functions ------------------------------*/ +#ifndef DOXYGEN + inline double FunctionTime::get_time () const { return time; } +#endif #endif diff --git a/deal.II/base/include/base/memory_consumption.h b/deal.II/base/include/base/memory_consumption.h index 601b426bc6..21e09cda8c 100644 --- a/deal.II/base/include/base/memory_consumption.h +++ b/deal.II/base/include/base/memory_consumption.h @@ -80,6 +80,7 @@ * maps, lists, etc. If you need such functions feel free to implement * them and send them to us for inclusion. * + * @ingroup memory * @author Wolfgang Bangerth, 2000 */ namespace MemoryConsumption diff --git a/deal.II/base/include/base/multithread_info.h b/deal.II/base/include/base/multithread_info.h index c606af2539..d61cbe562b 100644 --- a/deal.II/base/include/base/multithread_info.h +++ b/deal.II/base/include/base/multithread_info.h @@ -29,7 +29,8 @@ * n_default_threads is set to the number of CPUs by default, but * can be adjusted by the user to fit the requirements. * - * @author Thomas Richter, 2000 + * @ingroup threads + * @author Thomas Richter, Wolfgang Bangerth, 2000 */ class MultithreadInfo { @@ -115,8 +116,10 @@ class MultithreadInfo /** * Global variable of type MultithreadInfo which you may ask for the - * number of CPUs in you system, as well as for the default number of + * number of CPUs in your system, as well as for the default number of * threads that multithreaded functions shall use. + * + * @ingroup threads */ extern MultithreadInfo multithread_info; diff --git a/deal.II/base/include/base/polynomial_space.h b/deal.II/base/include/base/polynomial_space.h index af46c6d734..ce65921f4c 100644 --- a/deal.II/base/include/base/polynomial_space.h +++ b/deal.II/base/include/base/polynomial_space.h @@ -76,6 +76,8 @@ * x0y0zn * * + * + * @ingroup Polynomials * @author Guido Kanschat, Wolfgang Bangerth, Ralf Hartmann 2002, 2003, 2004, 2005 */ template diff --git a/deal.II/base/include/base/polynomials_bdm.h b/deal.II/base/include/base/polynomials_bdm.h index 51ac49c109..866a43d595 100644 --- a/deal.II/base/include/base/polynomials_bdm.h +++ b/deal.II/base/include/base/polynomials_bdm.h @@ -31,8 +31,6 @@ */ /** - * @brief The set of BDM polynomials on tensor product cells - * * This class implements the Hdiv-conforming, * vector-valued Brezzi-Douglas-Marini polynomials as described in the * book by Brezzi and Fortin. diff --git a/deal.II/base/include/base/quadrature_selector.h b/deal.II/base/include/base/quadrature_selector.h index d4c0b7e8f9..f914512ccb 100644 --- a/deal.II/base/include/base/quadrature_selector.h +++ b/deal.II/base/include/base/quadrature_selector.h @@ -30,7 +30,8 @@ * This class is useful if you want to use flexible quadrature rules, * that are read from a parameter file (see ParameterHandler for * this). - * + * + * @ingroup Quadrature * @author Ralf Schulz, 2003 */ template diff --git a/deal.II/base/include/base/smartpointer.h b/deal.II/base/include/base/smartpointer.h index b0b545b559..71bbc69a95 100644 --- a/deal.II/base/include/base/smartpointer.h +++ b/deal.II/base/include/base/smartpointer.h @@ -48,6 +48,7 @@ * a constant object (disallowing write access when dereferenced), while * SmartPointer is a mutable pointer. * + * @ingroup memory * @author Guido Kanschat, Wolfgang Bangerth, 1998 - 2005 */ template diff --git a/deal.II/base/include/base/subscriptor.h b/deal.II/base/include/base/subscriptor.h index e30324b273..ad0c3c1722 100644 --- a/deal.II/base/include/base/subscriptor.h +++ b/deal.II/base/include/base/subscriptor.h @@ -21,6 +21,7 @@ #include #include + /** * Handling of subscriptions. * @@ -45,6 +46,7 @@ * @note Due to a problem with volatile declarations, this * additional feature is switched of if multithreading is used. * + * @ingroup memory * @author Guido Kanschat, 1998 - 2005 */ class Subscriptor diff --git a/deal.II/base/include/base/thread_management.h b/deal.II/base/include/base/thread_management.h index 26efad95a1..8f73456d28 100644 --- a/deal.II/base/include/base/thread_management.h +++ b/deal.II/base/include/base/thread_management.h @@ -39,6 +39,8 @@ * deal.II. Most of the content of this namespace is discussed in * detail in one of the reports linked to from the documentation page * of deal.II. + * + * @ingroup threads */ namespace Threads { diff --git a/deal.II/doc/doxygen/headers/functions.h b/deal.II/doc/doxygen/headers/functions.h new file mode 100644 index 0000000000..f77f113cb5 --- /dev/null +++ b/deal.II/doc/doxygen/headers/functions.h @@ -0,0 +1,57 @@ +//------------------------------------------------------------------------- +// $Id$ +// Version: $Name$ +// +// Copyright (C) 2006 by the deal.II authors +// +// This file is subject to QPL and may not be distributed +// without copyright and license information. Please refer +// to the file deal.II/doc/license.html for the text and +// further information on this license. +// +//------------------------------------------------------------------------- + +/** + * @defgroup functions Functions + * + * Functions are used in various places in deal.II, for example to + * describe boundary conditions, coefficients in equations, forcing + * terms, or exact solutions. Since closed form expressions for + * equations are often hard to pass along as function arguments, + * deal.II uses the Function base class to describe these + * objects. Essentially, the interface of this base class requires + * derived classes to implement the ability to return the value of a + * function at one or a list of particular locations, and possibly (if + * needed) of gradients or second derivatives of the function. With + * this, function objects can then be used by algorithms like + * VectorTools::interpolate, VectorTools::project_boundary_values, and + * other functions. + * + * Some functions are needed again and again, and are therefore + * already provided in deal.II. This includes a function with a + * constant value; a function that is zero everywhere, or a + * vector-valued function for which only one vector component has a + * particular value and all other components are zero. Some more + * specialized functions are also defined in the Functions namespace. + * + * For time dependent computations, boundary conditions and/or right + * hand side functions may also change with time. Since at a given + * time step one is usually only interested in the spatial dependence + * of a function, it would be awkward if one had to pass a value for + * the time variable to all methods that use function objects. For + * example, the VectorTools::interpolate_boundary_values function + * would have to take a time argument which it can use when it wants + * to query the value of the boundary function at a given time + * step. However, it would also have to do so if we are considering a + * stationary problem, for which there is nothing like a time + * variable. + * + * To circumvent this problem, function objects are always considered + * spatial functions only. However, the Function class is derived from + * the FunctionTime base class that stores a value for a time + * variable, if so necessary. This way, one can define a function + * object that acts as a spatial function but can do so internally by + * referencing a particular time. In above example, one would set the + * time of the function object to the present time step before handing + * it off to the VectorTools::interpolate_boundary_values method. + */ diff --git a/deal.II/doc/doxygen/headers/memory.h b/deal.II/doc/doxygen/headers/memory.h new file mode 100644 index 0000000000..c0bed1cc8b --- /dev/null +++ b/deal.II/doc/doxygen/headers/memory.h @@ -0,0 +1,35 @@ +//------------------------------------------------------------------------- +// $Id$ +// Version: $Name$ +// +// Copyright (C) 2006 by the deal.II authors +// +// This file is subject to QPL and may not be distributed +// without copyright and license information. Please refer +// to the file deal.II/doc/license.html for the text and +// further information on this license. +// +//------------------------------------------------------------------------- + +/** + * @defgroup memory Memory handling + * + * This group has some basic classes and namespaces for memory + * handling. The Subscriptor and SmartPointer classes are used for + * counted memory handling, i.e. whenever a SmartPointer is set to + * point to an object, it increases a counter in that object; when the + * pointer is set to point elsewhere, it decreases it again. This way, + * one always knows how many users of an object there still are. While + * this is rarely useful in itself, it is used to generate an + * exception if an object is destroyed while a pointer somewhere is + * still pointing to it, as any access through that pointer at a later + * time would otherwise lead to access of invalid memory regions. + * + * In contrast to this, the MemoryConsumption namespace provides + * functions that can be used to determine the memory consumption of + * objects. For some simple classes, like the STL containers, it + * directly determines how much memory they need (or at least gives an + * estimate). For deal.II classes, it uses the + * memory_consumption member function that most classes + * have. + */ diff --git a/deal.II/doc/doxygen/headers/multithreading.h b/deal.II/doc/doxygen/headers/multithreading.h new file mode 100644 index 0000000000..5e2644c4e4 --- /dev/null +++ b/deal.II/doc/doxygen/headers/multithreading.h @@ -0,0 +1,46 @@ +//------------------------------------------------------------------------- +// $Id$ +// Version: $Name$ +// +// Copyright (C) 2006 by the deal.II authors +// +// This file is subject to QPL and may not be distributed +// without copyright and license information. Please refer +// to the file deal.II/doc/license.html for the text and +// further information on this license. +// +//------------------------------------------------------------------------- + +/** + * @defgroup threads Multithreading + * + * On machines with more than one processor (or multicore processors), + * it is often profitable to run several parts of the computations in + * parallel. For example, one could have several threads running in + * parallel, each of which assembles the cell matrices of a subset of + * the triangulation and then writes them into the global + * matrix. Since assembling matrices is often an expensive operation, + * this frequently leads to significant savings in compute time on + * multiprocessor machines. + * + * In a similar way, it is often also profitable to use multiple + * threads on a single-CPU system if a significant amount of input or + * output tasks has to be performed. In such cases, the program + * usually has to wait for disks or network storages to provide the + * requested data, or to flush buffers. If this is done on a separate + * thread, other threads of the program can continue to do other, more + * interesting things at the same time, using the CPU downtime. + * + * Support for this model of computations, i.e. using multiple threads + * on a shared-memory machine (SMP machine) is provided mainly through + * the Threads namespace that offers functions to create new threads + * as well as synchronisation primitives. The MultithreadInfo class + * allows to query certain properties of the system, such as the + * number of CPUs. The use of these classes is explained in the + * step-9, step-13 and step-14 tutorial programs. + * + * On the other hand, programs running on distributed memory machines + * (i.e. clusters) need a different programming model built on top of + * MPI and PETSc that is described in the step-17 and later example + * programs. + */ diff --git a/deal.II/doc/doxygen/headers/quadrature.h b/deal.II/doc/doxygen/headers/quadrature.h index 6750e13ef0..8c30fe0b32 100644 --- a/deal.II/doc/doxygen/headers/quadrature.h +++ b/deal.II/doc/doxygen/headers/quadrature.h @@ -87,4 +87,12 @@ * * All other classes in this module actually implement quadrature * rules of different order and other characteristics. + * + * + *

QuadratureSelector

+ * + * This class is used to generate a quadrature object based on a + * string that identifies the quadrature formula. This is useful in + * cases where one wants to specify a certain quadrature formula in an + * input file, rather than hardcode it in the program. */ -- 2.39.5